si_sq.h

是一个手机功能的模拟程序

/*
 * Copyright (C) Ericsson Mobile Communications AB, 2000.
 * Licensed to AU-System AB.
 * All rights reserved.
 *
 * This software is covered by the license agreement between
 * the end user and AU-System AB, and may be used and copied
 * only in accordance with the terms of the said agreement.
 *
 * Neither Ericsson Mobile Communications AB nor AU-System AB
 * assumes any responsibility or liability for any errors or inaccuracies in
 * this software, or any consequential, incidental or indirect damage arising
 * out of the use of the Generic WAP Client software.
 */

/***********************
File: si_sq.h + c
Author: Klas Hermodsson (KHN)

Description:
SQ stands for Script Queue. This module encapsulates the script interpreter (SI) 
(see the si_si files). It can handle several independent script invokations. The SQ functions as a 
dispatcher and makes sure the invokations are queues and executed properly. 
The SQ can execute an invokation until it is done before letting another invokation execute. 
It can also let the invokations take turn and execute them pseudo-simulataneously. 
This mode is called round robin. Which mode the SQ will execute scripts in is determined 
when calling the SQ_Init function.

The SQ manages a queue of invoke heads (see structInvokeHead below). There will be one
invoke head per script invokation. When an invokation is finished executing the SQ will
remove the invoke head and its subcomponents.

Each invoke head holds a stack of BP elements (structBPElement). 
There will be a BP element in the stack per script file involved in the invokation. 
The BP element holds a WMLScript file in its encoded form (sometimes referred to 
as bytecode package or BP) and its corresponding script interpreter (SI).

The SQ is the component that SDL interfaces with to run scripts. The actual low level
interface between SDL and C is found in the si_sdl files.

The central functions to the SQ are SQ_InvokeScript and SQ_Exec.
SQ_InvokeScript takes care of an incoming invokation.
SQ_Exec is the main script handling thread function and that the SDL that 
encapsulates WMLS calls in the following mannor (simplified):

while (WAP client alive)
{
	SQ_Exec()
	<handle incoming signals>
}


Example of SQ operation: 
When a script invokation reaches the SQ an invoke head is created and put in the queue. 
The invoke head has itself createf a BP element which now points to the script file.
The next time SQ_Exec is called a SI is created for the script file. If everything went ok
the SI is executed for one time slice (see si_si files). If the script file calls an external
function in another script file the invoke head is put in a wait state and the SQ_Exec returns
with a return value that says that an external file is needed. The SDL must then call 
SQ_GetExternalCallParams to get the URL to the new script file. If SQ_Exec is called and 
the new script file has not been loaded yet (and no other invokations exist) the function
will return directly signaling that has nothing to process for the moment. When the 
WAP client has successfully loaded the new script file it calls SQ_LoadDoneReceived.
The next time SQ_Exec is called a SI is created for the new file and is executed for a 
time slice. And so on.
When a script file is done executing the result of the script (there is always a return value)
is given back to the caller (either another script file or the component that invoked the script).

************************/

#ifndef _SI_SQ_H
#define _SI_SQ_H


#include "cmmnrsrc.h"
#include "si_si.h"
#include "wmldef.h"
#include "confvars.h"

#ifdef USE_PROPRIETARY_WMLS_LIBS
	#include "aapiclnt.h"
    #include "tapiclnt.h"
#endif


typedef struct BPElement {
	BYTE									*BP;								/* A pointer to the encoded WMLS file */
	UINT32								BPlen;							/* the length in number of bytes */
	INT16									IANAcharset;				/* header field from WSP for the BP file. Is used to determine string encoding of WMLS strings in the BP file */
	WCHAR									*callURL;						/* The absolute URL to this WMLS file */
	BOOL									isInitialBPInvoked;	/*	TRUE: the callURL includes funcName and args. 
																								FALSE the funcName and args can be fetched from next SI  */
	pstructSI							theSI;							/* The interpreter that handles this WMLS file */
	struct BPElement			*next;							/* the next in this stack of BP elements */

} structBPElement, *pstructBPElement;



typedef struct InvokeHead {
	UINT8									invokeID;				/* the ID for an invokation so that when SQ_Exec returns one can find which invokation was executed */
	UINT32								UApidAsInt;			/* the SDL process ID of the user agent that invoked the script. Used to send signals about script execution back to the caller. */
	pUA										theUAStruct;		/* A pointer to the user agent. must NOT be deallocated when InvokeHead is deleted. It is used for some scriptlib functions */
	BOOL									isDone;					/* TRUE: this invoke thread is done and is waiting for someone to collect the result 
																							FALSE: not done */
	BOOL									isInWaitState;	/* TRUE if waiting for external resources. FALSE: if ready to run */
	enumErrorCode					errorCode;			/* if error occurs the whole thread is deallocated and the errCode is stored here */
	pstructVar						theResult;			/* when the script is done, the call list is deallocated and the result i stored in this attribute. */
	BOOL									browserPrev;		/* TRUE if a WMLBrowser.prev is to be performed when the script call is done */
	WCHAR									*browserGoUrl;	/* if a WMLBrowser.go is to be performed when the script call is done the URL is stored here */
	pstructBPElement			BPcallList;			/* actually a call stack of WMLS files. I.e the first script file of the call will be in the "bottom" of the stack */
	struct InvokeHead			*next;					/* next in this list of invoke heads */

} structInvokeHead, *pstructInvokeHead;


typedef struct SQ {
	UINT16								timeSlice;					/* the config param to be used for all created SIs. (see si_si files) */
	UINT8									nextInvokeID;				/* this is so that one knows which invokeID to give to the next Invoke */
	BOOL									doRoundRobinScheduling;
	BOOL									onlyOneScriptPerUA;
	BOOL									handlesTopPriorityREQ;	
		/* if the SQ handles top priority requests: a top priority request gets the benifit of getting its 
		invokation first in line and will start executing next time SQ_Exec is called. Another top priority req 
		will do the same thing so top priority req can interrupt each other*/
	pstructInvokeHead			currentInvoke;	/* steps through the InvokeHead elements if round robin scheduling is used otherwise it will be the first in the invokeList. */
	pstructInvokeHead			invokeList;		/* the queue of script invokes */

} structSQ, *pstructSQ;



/* enumScriptStatus is the return type from a SQ_Exec call.
It tells about the script thread it executed for its time slice. */
typedef enum {
	eSs_more = 1,		/* There is more to process in the invoke queue */
	eSs_done,				/* a script thread is done. Th ereturn value should now be collected. */
	eSs_done_prev,	/* done (see above) and the UA should perform a PREV action */
	eSS_done_go,		/* done and the UA should perform a GO action with a url found in si->goURL */
	eSs_error,			/* the script thread resulted in an error */
	eSs_extFunc,		/* the script thread calls an external script file that has to be fetched */
	eSs_lib					/* the script thread calls a type of scriptlib function that has to be handled in SDL */
} enumScriptStatus;






/*==========================================
	SQ_Init
============================================

---Purpose: 
To create a new SQ.

---Params:
timeSlice					the amount of time units an SI will execute the most at a timne.
roundRobin				TRUE: the script invokes will share execution time evenly in round robin fashion.
										FALSE: The invoke first in the queue will execute til it's done. Then a new 
										invoke will start to execute.
oneScriptPerUA		TRUE: Only one script invoke per user agent is allowed.
										FALSE: multiple script invokes per user agent is allowed.
handlesTopPrio		TRUE: a script with top priority (see SQ_InvokeScript) will be put first in the 
										invoke queue and will start executing next SQ_exec is called.
	
---Return:
The newly created SQ.

------------------------------------------------------------------------*/
pstructSQ SQ_Init( UINT16 timeSlice, BOOL roundRobin, BOOL oneScriptPerUA, BOOL handlesTopPrio );


/*==========================================
	SQ_Terminate
============================================

---Purpose: 
To deallocate an SQ and all of its components.

---Params:
pThis			The SQ to be terminated. The pointer will be set to NULL when the termination is done.
	
---Return:
-

------------------------------------------------------------------------*/
VOID SQ_Terminate( pstructSQ *pThis );


/*==========================================
	SQ_InvokeScript
============================================

---Purpose: 
To put a new invoke in the script queue.

---Params:
thisx						The SQ that manages the scripts.
UApidIndex			The index into the array (kept in SDL) that holds the process ID (pID) 
									to the SDL user agent that invokes this script.
theUA						User agent struct that holds some information needed when performing 
									some of the script lib functions.
pBP							The compiled script file to be executed.
									NOTE: The SQ will take care of deallocation of this parameter.
BPlen						The length of the BP in bytes.
IANAcharset			The IANA charset code that WSP sent as a header for this script.
									Tells how some string constants are encoded.
pCallURL				The absolute URL that was used to load this script file. 
									Includes fragment with function name and parameters.
									NOTE: The SQ will take care of deallocation of this parameter.
isTopPriority		If TRUE this script wants to be executed ASAP. See SQ_Init for 
									how these are handled.
	
---Return:
>0:	The invoke ID that will be used to identify the script thread caused by this invokation. 
			E.g. SQ_Exec will return such an id so it's possible to tell what script thread was executed.
0:	Something went wrong and the invokation was not queued. E.g. a user agent tries to have 
			two scripts running when the config param oneScriptPerUA has been set to TRUE.

------------------------------------------------------------------------*/
UINT8 SQ_InvokeScript( pstructSQ thisx, UINT32 UApidInt, pUA theUA, BYTE **pBP, UINT32 BPlen, INT16 IANAcharset, WCHAR **pCallURL, 
											 BOOL isTopPriority );


/*==========================================
	SQ_AbortScriptsForSpecificUA
============================================

---Purpose: 
Stops and deallocates all script threads invoked by a certain user agent
(There is no way to abort just a single script thread via its invokeID at this time).

---Params:
thisx				The SQ.
UApidIndex	The index into the SDL kept array of user agent process IDs. The
							index is also stored in each invoke head so its easy to decide
							which invoke heads to abort.
	
---Return:
-

------------------------------------------------------------------------*/
VOID SQ_AbortScriptsForSpecificUA( pstructSQ thisx, UINT32 UApidInt );


/*==========================================
	SQ_Exec
============================================

---Purpose: 
The central function of the SQ. This function is to be called regularly.
e.g:
while (running application)
{
	SQ_exec
	(take care of incoming signals etc.)
}

The function executes a script thread (one invoke head) for one time slice (max) 
and then returns. Which script thread depends on the mode of the SQ (see SQ_Init above).

---Params:
pInvokeIDThatExecuted		Returns the invoke ID of the script thread that was executed.
pUApidIndex							Returns the index into the SDL kept array of process
													IDs to the user agent which invoked the script thread
													that was executed.
	
---Return:
eSs_more				If this is returned and InvokeIDThatExecuted != 0 then there is more to process.
									If InvokeIDThatExecuted == 0 then SQ_exec is in a wait state so it is not
									necessary to call it again until the SQ receives any new input.
eSs_done				This is returned if a script thread is done and has a return value to be 
									retrieved by calling SQ_GetResult (see below).
eSs_done_prev		The same as eSs_done but the user agent should also perform a PREV action.
									Fetching of the PREV parameters must be done. This is done by calling
									SQ_GetPrevParams (this is done in addition to fetching the result).
eSS_done_go			The same as eSs_done but the user agent should also perform a GO action.
									Fetching of the GO parameters must be done. This is done by calling
									SQ_GetGoParams (this is done in addition to fetching the result).
eSs_error				An error ocurred in the script thread. The error code must be fetched
									and is done by calling SQ_GetError.
eSs_extFunc			The script thread is calling a function in another script file.
									Call SQ_GetExternalCallParams to get the URL of the file to be loaded.
									(see SQ_LoadDoneReceived and SQ_LoadErrorReceived for more info)
eSs_lib					The script thread is calling a script lib function that needs
									to communicate with the outside. Call SQ_GetLibCallParams to get 
									the data on which function needs help to finish.

------------------------------------------------------------------------*/
enumScriptStatus SQ_Exec( pstructSQ thisx, UINT8 *pInvokeIDThatExecuted, UINT32 *pUApidInt );

/*==========================================
	SQ_GetResult
============================================

---Purpose: 
To get the result from a script thread that is done executing.

---Params:
thisx				The SQ
invokeID		The id of the script thread (this was returned by SQ_Exec).
pResultStr	Returns the result of the script thread converted to a string.
							NOTE: The receiver is responsible for deallocating this parameter.
	
---Return:
TRUE:		Everything went ok. The script thread was done and had a return
					value that hadn't yet been collected.
FALSE:	Something went wrong. E.g. incorrect invokeID, the script thread
					is not done or the result has already been collected.

------------------------------------------------------------------------*/
BOOL SQ_GetResult( pstructSQ thisx, UINT8 invokeID,WCHAR **pResultStr );

/*==========================================
	SQ_GetGoParams
============================================

---Purpose: 
To get the URL to be used in the GO action commanded by the
script thread.

---Params:
thisx			The SQ.
invokeID	The id of the script thread (this was returned by SQ_Exec).
pGoUrl		Returns the URL.
						NOTE: The receiver is responsible for deallocating this parameter.
	
---Return:
TRUE:		Everything went ok.
FALSE:	Something went wrong. E.g. incorrect invokeID or the script thread
					is not done.

------------------------------------------------------------------------*/
BOOL SQ_GetGoParams( pstructSQ thisx, UINT8 invokeID, BYTE **pGoUrl );

/*==========================================
	SQ_GetPrevParams
============================================

---Purpose: 
Actually, this function is obsolete since no parameters
are provided by the WMLBrowser.go script lib function.