wmlif.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: WMLIF.h
  
	Source file for the interface between WAE and the WML-structure.
	Includes function to initiate the parse of a WML-deck and using
	the structure created during the parse.

	Rev history:
		980728	JPR		Created
		990208	JPR		Corrections
		990315	JPR		Major changes. Handles the WML-specific parts 
						of the startup and closing down of the parser.
		990316	JPR		Variable handling moved here from WMLElm.h
		990406	JPR		Corrections
		990423	JPR		Corrections in History functions
		990514	JPR		WML/WBXML Version handling updated.
		990528	JPR		Function WML_IsPEmpty added
		990531	JPR		Navigation corrections (setvar element)
		990610	JPR		Trim text functions updated.
		990826	JPR		Function WML_NewContext added.
		991124	JPR		History functions moved to History.h

		991207	JPR		Changes to support new generic WBXML-decoder
		010125	NKE		Removed WML_ParseNextElement. Functionality
						included in the new decoder WBXML_Decode(),
						WML_CreateElement, WML_StartParser and WML_ModifyParse.
==========================================================================*/

#ifndef _INTERFACEH
#define _INTERFACEH

#include "wmldef.h"

typedef struct tNUMBERSTRUCT
{
	UINT16 iIndex;
	struct tNUMBERSTRUCT *pNext;
} NUMBERSTRUCT, *pNUMBERSTRUCT;


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

	Functions for decoding wmlc-content

=========================================================================

	Functions used to parse a WML-deck. The functions uses the general 
	WBXML-decoder (WBXMLDec) and for the WML-specific parts it uses 
	WMLParse.

	The functions must be used in the following manner:

	1. An user agent is created with the WML_CreateUserAgent function. 
	   The user agent contains information of the wml-context and is used 
	   until it is terminated.

	2. For each wml-deck to be parsed, the function WML_StartParser is 
	   called initially. If it returns TRUE step 3 should be executed. 
	   Otherwise, step 4 should be executed.

	3. The function WML_ParseNextElement is called repeatedly until NULL 
	   is returned which indicates that the whole deck has been parsed.

	4. The function WML_EndParser is called if step (3) is completed. The 
	   function returns TRUE if the  parse was successful, FALSE otherwise. 
	   If step (3) is interrupted earlier, the function WML_AbortParser 
	   must be called instead.
	
	5. The functions WML_EmptyDECK, WML_EmptyVarTable, DeleteHostList may 
	   be called to alter the context of the user agent.

	6. Repeat step (2-5) for each new deck to be parsed.

    7. Delete the user agent with the function WML_DeleteUserAgent. The 
	   function also removes the variable table, the current deck, the 
	   history list, the decode struct, the HostList, and the URL Base.

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

/*========================================================================
	WML_CreateUserAgent
==========================================================================
	Creates an User Agent and sets the attributes to their default values.
	
	Input: -
	Output: Pointer to UA, NULL if error
==========================================================================*/
pUA WML_CreateUserAgent (void);


/*========================================================================
	WML_DeleteUserAgent
==========================================================================
	Deletes an User Agent and removes the attributes pbURLBase, 
	pVisitedHosts, the variable table, the string table, the decode struct 
	and the current deck.
	
	Input: **UA
	Output: -
==========================================================================*/
void WML_DeleteUserAgent (pUA *ppUser);


/*========================================================================
	WML_StartParser
==========================================================================
    Starts up the parser. Parses the prolog and builds the string table. 
	During this phase the version number (WBXML) is also verified. 
	
	Input: User Agent, pointer to bytestream, the number of bytes in the 
		   bytestream, the content type and content level.
	Output: TRUE if OK, FALSE otherwise.
==========================================================================*/
BOOL WML_StartParser (pUA pUser, BYTE *pbStream, UINT32 iNbrOfBytes,
					  BYTE bContentType, UINT8 iContentLevel); 


/*========================================================================
	WML_EndParser
==========================================================================
    Finishes the parse of a deck. Removes the temporary variables. Stores 
	all not overridden TEMPLATE DO elements in the cards. If the parse
	was successful TRUE is returned, otherwise FALSE is returned. 

	If the function returns FALSE, the string table and the deck are 
	deleted.
	
	Input: User Agent
	Output: TRUE if OK, FALSE otherwise.
==========================================================================*/
BOOL WML_EndParser (pUA pUser);


/*========================================================================
	WML_AbortParser
==========================================================================
    Aborts the parse of a deck. Removes the temporary variables, and the 
	string table.
	
	Input: User Agent
	Output: -
==========================================================================*/
void WML_AbortParser (pUA pUser);


/*========================================================================
	WML_EmptyDECK
==========================================================================
	Deletes the WML deck and the string table in the specified User Agent
	
	Input: User Agent
	Output: -
==========================================================================*/
void WML_EmptyDECK (pUA pUser);




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

	VARIABLE TABLE FUNCTIONS

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

/*========================================================================
	WML_SetVariable 
==========================================================================
	Sets the value on the variable pchName to pchValue. STORES COPIES OF 
	THE STRINGS! If the variable does not exist, it is created. The Name 
	must be specified but the value may be NULL, in which the variable is 
	removed. The variable is set if there is enough memory and the name is 
	a valid variable name (consult WAP WML 1.2 section 10.3.1). If the 
	value is equal to the empty string it is stored as NULL, i.e. removed.

	If the fWTA-flag is set, WTA-event parameters are also allowed (i.e.,
	variables starting with '1' - '9', consult WTA specification for more
	information).
  
	Input: Name (WCHAR *) and Value (WCHAR *), User Agent and WTA-flag
	Output: TRUE if value is set, FALSE otherwise. 
==========================================================================*/
BOOL WML_SetVariable (pUA pUser, WCHAR *pchName, WCHAR *pchValue, BOOL fWTA);


/*========================================================================
	WML_GetVariable 
==========================================================================
	Returns a COPY of the value of the variable with the specified name.
	
	Input: Variable name and the User Agent
	Output: WCHAR *, NULL if not found
==========================================================================*/
WCHAR* WML_GetVariable (pUA pUser, WCHAR *pchName);


/*========================================================================
	WML_EmptyVarTable
==========================================================================
	Deletes the variable table in the specified User Agent.

	Input: User Agent
	Output: -
==========================================================================*/
void WML_EmptyVarTable (pUA pUser);


/*========================================================================
	WML_DeleteEventVariables
==========================================================================
	If a navigation fails, the variables specified in the setvar elements 
	in the task should not be set. These variables are stored temporary
	in a list in the user agent, that must be deleted. This function 
	removes that list. The function should be called whenever a task is
	failed.

	Input: User Agent
	Output: -
==========================================================================*/
void WML_DeleteEventVariables (pUA pUser);


/*========================================================================
	WML_AddEventVariablesToContext
==========================================================================
	This function transfers the variables set in the task, from the 
	temporary list in the user agent, to the variable list in the user 
	agent (part of the context). The function also removes the temporary 
	list.

	Input: User Agent
	Output: -
==========================================================================*/
void WML_AddEventVariablesToContext (pUA pUser);


/*========================================================================
	WML_CheckVariableSyntax
==========================================================================
	This function checks the syntax of the variable name. If the variable
	name is valid TRUE isr returned, otherwise FALSE is returned. (Consult 
	WAP WML 1.2 section 10.3.1 for more information.)

	If the fWTA-flag is set, WTA-event parameters are also allowed (i.e.,
	variables starting with '1' - '9', consult WTA specification for more
	information).

	Input: Variable name and WTA-flag
	Output: TRUE if OK, FALSE otherwise.	
==========================================================================*/
BOOL WML_CheckVariableSyntax (WCHAR *pchVariable, BOOL fWTA);




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

	SELECT ELEMENT FUNCTIONS

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

/*========================================================================
	WML_SetSelectDefault
==========================================================================
	Sets the default value for a SELECT element.

	Input: Element of type SELECT and User Agent.
	Output: True if OK, FALSE otherwise.
==========================================================================*/
BOOL WML_SetSelectDefault (pELEMENTTYPE pSelect, pUA pUser);


/*========================================================================
	WML_UpdateSelect
==========================================================================
	Updates the variables in a specified SELECT element according to the 
	option elements in the content of the SELECT element. 

	Input: Element of type SELECT and User Agent.
	Output: True if OK, FALSE otherwise.
==========================================================================*/
BOOL WML_UpdateSelect (pELEMENTTYPE pSelect, pUA pUser);


/*========================================================================
	WML_UpdateAllSelect
==========================================================================
	Updates all SELECT elements on a card.

	Input: Element of type CARD and User Agent.
	Output: True if OK, FALSE otherwise.
==========================================================================*/
BOOL WML_UpdateAllSelect (pELEMENTTYPE pCard, pUA pUser);


/*========================================================================
	WML_PreSelectOptions
==========================================================================
	Sets the 'SELECTED'-field in all the option elements indicated in the 
	NUMBERSTRUCT to TRUE, all other to FALSE. 

	Input: Element of type OPTION or OPTGROUP, a NUMBERSTRUCT (NULL to 
		   deselect all), two pointers to UINT16 (used internally, set
		   to 0). The ppDefaultOption pointer is also changed.
	Output: -
==========================================================================*/
void WML_PreSelectOptions(pELEMENTTYPE pElement, pNUMBERSTRUCT *ppDefaultOption,
						  UINT16 *piFindNbr, UINT16 *piThisNbr);