si_si.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_si.h + c
Author: Klas Hermodsson (KHN)

Description:
NOTE: This description assumes knowledge of the purpose and tasks
of the WMLScript interpreter described in the WMLS specification.
The comments found here are more of an explanation of the design and 
implementation of this interpreter.

The script interpreter (SI) is the component that handles and interprets 
a single script file. When a script file calls an function residing in 
another script file the SI signals this to the Script Queue (see si_sq files) 
which manages the SIs.

A very important component of the SI is the runtime environment (RE, see si_re files).
The RE keeps track of such things as the binary script file itself (BP), 
instruction pointer (IP), operand stack (OpS) and so on.

SI creation
To create the SI it needs the binary script file and the calling information 
(function name and call parameters). There are two different cases when 
a SI needs to be created: a user agent call a script function or another script file
calls a function in the new script file. 
If it is a user agent initiated call then function name and parameters are in the
fragment of the call URL. (SI_NewWithArgString)
If the call came from another script file then the function 
name is separated and the parameters are passed as an operand stack 
just containg those parameter values. (SI_NewWithArgOpS)

SI and "external resources"
Since the SI only handles one script file, a call to an external script function 
will result in a new SI being created. This is one case of needing 
an external resource. When the SI coes upon the external call it stores the
external call data in the returnParams struct. The data stored is
URL, function name and parameters to the external function.

The other case is when a script library function is not entirely 
coded in C but needs help from SDL to complete the task.
In this case the data stored in the returnParams struct is
the library and function index of the function to be completed.

The data saved in the returnParams struct is in time fetched
by the WMLS SDL process and taken care of.
The following functions are used for fetching this data:
SI_GetLibCalllParams,
SI_GetExtCalllParams_URL,
SI_GetExtCalllParams_rest

From the moment that the external resource is needed until 
the result is returned, the SI is in a wait state.
The result is returned via the functions:
SI_ReceiveReturnVal,
SI_LoadStringDone,
SI_ReceiveCalledSIReturnVal

The GO and PREV actions
The library functions WMLBrowser.go and prev are special in the
way that they do not take effect until the whole script invoke is done.
This means that these parameters must be passed back to the caller.
The GO and PREV functions overwrite each other which means that if
there first is a GO call and then a PREV call, the PREV action
overrides all former GO or PREV actions. This means that
if a script file is done and returns a GO or PREV action to the
script that called it, this action overrides the stored GO or PREV
action (if any). Confusing, eh?

How the SI works
When the SI is created, a runtime envrionment (RE) is created (see si_re files).
The central functions of the SI are the constructors and the SI_ExecBlock function.
The SI_ExecBlock function interprets a number of instructions until it reaches the
timeslice (explained below) maximum or an external resource is needed in which case 
the SI is put in a waut state.
The SI_ExecBlock has a return value which signals if the script is done or if
the ExecBlock function needs to be called further. It also signals if an 
external resource is needed.

Each instruction and script library function has been given a time cost.
This is to indicate how much time units it takes to interpret the instruction/lib function.
Timeslice is then a number of time units for which the SI is allowed to interpret 
the script file before returning control to the caller of SI_ExecBlock.
By doing this, the SI doesn't run until it's done but can instead easily
be run "pseudo simultaneously" with other tasks of the WAP client.
The timeslice parameter is configurable and is part of the porting parameters
found in confvars.h.

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

#ifndef _SI_SI_H
#define _SI_SI_H


#include "cmmnrsrc.h"
#include "si_re.h"
#include "si_ops.h"

#include "wmldef.h"
	/* def..h is for the pUA type */

#ifdef CAN_SIGN_TEXT
	#include "si_crpto.h"
#endif


typedef enum { 
	SI_RETURN_DONE,					/* The SI is done */
	SI_RETURN_MORE,					/* The SI is not done */
	SI_RETURN_EXTERNAL,			/* The SI will need external resources (extended info will be found in a 
															structSIReturnParams) */
	SI_RETURN_EXTERNAL_NO_PARAMS	/* The SI is waiting for an external result. 
																		No params need to be transferred. The result will later come to the WMLS SDL
																		process and then a C function (depends on what external operation was performed) 
																		will be called. */
} enumSIReturn;

typedef struct
{
	BOOL				islibCall;	/* TRUE = lib call, FALSE = call to an extrenal function (in another BP) */
	pstructOpS	argOpS;			/* the arguments for the library/external function */
	/*------*/
	UINT16			libNbr;
	UINT8				libFuncIndex;
	/*------*/
	WCHAR*			bpUrl;			/* NULL terminated */
	BYTE*				funcName;		/* NULL terminated */

} structSIReturnParams, *pstructSIReturnParams;


typedef struct
{
		/* theUserAgent = the UA that started the script execution.
			This is needed when wanting to access WML variables. */
	pUA											theUserAgent; 	
	UINT8										invokeID; /* the invokeId of the invoke element. This is to have a trace back to where in the script Q the si is */
	pstructRuntimeEnv				RE;
	WCHAR										*baseURL;			/* the absolute url of this compilation */
	WCHAR										*refererURL;	/* the absolute url of the refering page/(script unit) */
	UINT16									timeSlice;
	UINT16									currTime;
	BOOL										inWaitState;	/* TRUE if the SI is waiting for external resources */
	enumSIReturn						returnInfo;
	pstructSIReturnParams		returnParams;
	BOOL										WMLBrowserActionInvoked;	/* TRUE if prev or go invoked */
	BOOL										WMLBrowser_prev;	/* TRUE if the UA should perform a PREV action upon return */
	WCHAR										*WMLBrowser_goURL;	/* if != NULL then the UA should perform the GO action with this URL  */

#ifdef CAN_SIGN_TEXT
	SignedContent						*sc; /* a struct needed when performing the WMLS library function Crypto.signText (see si_libs.c) */
#endif

} structSI, *pstructSI;




/*==========================================
	SI_NewWithArgString
============================================

---Purpose: 
To create a SI for the supplied script file. The called function and its parameter values is
inside the baseUrl parameter (see call URL syntax in the WMLS language spec).
This function is used when the caller is a user agent.

---Params:
BP					The binary script file.
BPlen				The length of BP in bytes.
IANAcharset	The WSP charset header. This might indicate
							the character set used for string constants.
userAgent		The user agent struct. Used for example to access
							WML variables.
baseUrl			The absolute URL of this script file and with a
							fragment which contains function name and parameter values.
refererUrl	The absolute URL to the referring file. Without the card fragment?
timeSlice		The number of time units maximum that SI_ExecBlock can
							run without interruption.
errCode			Returns an error code (see errcodes.h).
	
---Return:
pstructSI		The created SI.
NULL				Something went wrong.

------------------------------------------------------------------------*/
pstructSI SI_NewWithArgString( UINT8 invokeID, BYTE* BP, UINT32 BPlen, INT16 IANAcharset, pUA userAgent, WCHAR *baseUrl, /* this url includes funcname and arguments in the fragment */
															WCHAR *refererUrl, UINT16 timeSlice, enumErrorCode *errCode );


/*==========================================
	SI_NewWithArgOpS
============================================

---Purpose: 
To create a SI for the supplied script file. The function name and parameter values are 
supplied as two separate arguments to this function.
This function is used when the caller is another SI.

---Params:
BP					The binary script file.
BPlen				The length of BP in bytes.
IANAcharset	The WSP charset header. This might indicate
							the character set used for string constants.
userAgent		The user agent struct. Used for example to access
							WML variables.
pFuncName		The name of the function to be called.
pArgOpS			An operand stack containing the argument values to the function called.
baseUrl			The absolute URL of this script file and with a
							fragment which contains function name and parameter values.
refererUrl	The absolute URL to the referring file. Without the card fragment?
timeSlice		The number of time units maximum that SI_ExecBlock can
							run without interruption.
errCode			Returns an error code (see errcodes.h).
	
---Return:
pstructSI		The created SI.
NULL				Something went wrong.

------------------------------------------------------------------------*/
pstructSI SI_NewWithArgOpS( UINT8 invokeID, BYTE* BP, UINT32 BPlen, INT16 IANAcharset, pUA userAgent, BYTE **pFuncName, pstructOpS *pArgOpS,
														WCHAR *baseUrl, WCHAR* refererUrl, UINT16 timeSlice, enumErrorCode *errCode );


/*==========================================