/*******************************************************************************
*                              Openwave Systems.                               *
*                            Device Products Group                             *
*                          Redwood City,  CALIFORNIA                           *
****************************************************************************//**
   @file
   This is the public API for the V6 Openwave Mobile Browser extension.


*//*
   REVISION HISTORY:
   Date:       Who:               Email:
      - Details:
--------------------------------------------------------------------------------
   20 Sep 2004 Richard Willis     richard.willis@openwave.com
      - Initial version

*******************************************************************************/
/*******************************************************************************
*                  Copyright (c) Openwave Systems 1995-2004                    *
*                            All rights reserved.                              *
*                                                                              *
*     THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF Openwave Systems Inc.     *
*               The copyright notice above does not evidence any               *
*              actual or intended publication of such source code.             *
*******************************************************************************/

#ifndef _IOMBV6_H
#define _IOMBV6_H


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

	INCLUDES

==============================================================================*/
#ifndef PREPROCESSING_ONLY //don't include these if we're only preprocessing & not compiling
#include "aee.h"	// for size_t, etc
#include "aeestdlib.h"	// for size_t, etc
#include "aeeinterface.h"
#endif //ndef PREPROCESSING_ONLY


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

	DEFINES

==============================================================================*/
/**@ingroup grp_utils
This is the maximum length of a URL, not including the NULL terminator.  This
may be used when sizing a buffer for the IOMBV6_wGetCurrentUrl() function.
*/
#define miIOMBV6_MAX_URL_LEN 1024


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

	TYPES

==============================================================================*/
/**@ingroup grp_cache
 This is the list of items that can be selectively erased from the browser
 persistent memory store.
*/
typedef enum
{
   keIOMBV6_CI_PagesPictures  = 0x01, ///< Deletes the pages and pictures from the browser cache.
   keIOMBV6_CI_History        = 0x02, ///< Deletes the URL history list from the browser cache.
   keIOMBV6_CI_Cookies        = 0x04, ///< Deletes all cookies from the browser cache.
}teIOMBV6_CacheItem;

/**@ingroup grp_config
 These are used for various items in the #tsIOMBV6_Config structure.
 Details may be found there.
*/
typedef enum
{
   keIOMBV6_BS_Unchanged,  ///< Don't alter the current setting.
   keIOMBV6_BS_Disable,    ///< Disable, or make FALSE, this item.
   keIOMBV6_BS_Enable      ///< Enable, or make TRUE, this item.
} teIOMBV6_BooleanSet;

/**@ingroup grp_config
 These are used for various items in the #tsIOMBV6_Config structure.
 Details may be found there.
*/
typedef enum
{
   keIOMBV6_SS_Unchanged,  ///< Don't alter the current setting.
   keIOMBV6_SS_Slow,       ///< Set the speed to slow, or longest.
   keIOMBV6_SS_Medium,     ///< Set the speed to medium.
   keIOMBV6_SS_Fast        ///< Set the speed to fast, or shortest.
} teIOMBV6_SpeedSet;

/**@ingroup grp_config
 These allow adjustment of the HTTP timeout period.
 This is the time to wait before reporting a failure to download a page or other
 object.
*/
typedef enum
{
   keIOMBV6_HTTPTime_Unchanged,     ///< Don't alter the current setting.
   keIOMBV6_HTTPTime_HttpTimeout1,  ///< kHttpTimeout1 as defined by the browser library.
   keIOMBV6_HTTPTime_HttpTimeout2   ///< kHttpTimeout2 as defined by the browser library.
}teIOMBV6_HTTPTimeoutSet;

/**@ingroup grp_config
 This configuration structure is passed to the IOMBV6_oConfigInternalSettings()
 to allow adjustment of these parameters during run time.  You should call
 IOMBV6_vInitStructure() to initialise this structure first, then simply fill in
 the elements that should be changed and leave the other's untouched.
*/
typedef struct
{
   teIOMBV6_HTTPTimeoutSet sHTTPTimeout;           ///< Choose between one of 2 timeout periods.  This is the time to wait before reporting a failure to download a page or other object.
   teIOMBV6_BooleanSet     eDownload;              ///< ENABLE to allow embedded pictures, sounds & other objects to be downloaded when viewing a page, DISABLE to download the page with no other objects (to reduce data charges).
   teIOMBV6_BooleanSet     eTitleRegion;           ///< ENABLE to display the title region, DISABLE not to.
   teIOMBV6_BooleanSet     eTitleWrap;             ///< ENABLE to wrap long text strings in the title bar (uncommon), DISABLE to let it horizontally scroll when it has the focus (common choice).
   teIOMBV6_SpeedSet       eKeyPressTimeoutSpeed;  ///< This sets the amount of time to wait before accepting a character choice when entering text in multitap mode.
   teIOMBV6_BooleanSet     eSmoothScroll;          ///< ENABLE for smooth scrolling (best for faster CPU handsets), DISABLE for block scrolling (better for slow CPU handsets).
   teIOMBV6_SpeedSet       eScrollSpeed;           ///< This controls the page scroll speed when the navigation key is held down.
} tsIOMBV6_Config;


/**@ingroup grp_config
 This configuration structure is passed to the IOMBV6_oConfigInetInfoSettings()
 to allow to set WAP-ESF info up during run time.
*/
typedef struct
{
   const uint8 *kpbProxyAddress;       ///< WAP-ESF's IP address (MMC:"browser:proxy..0.address")
   uint16 wProxyAddressLen;            ///< The number of bytes for IP address
   const uint8 *kpbProxyHomepage;      ///< Top page URL (MMC:"browser:proxy..0.homepage.url")
   uint16 wProxyHomepageLen;           ///< The number of bytes for Top page URL
   const uint8 *kpbProxyPort;          ///< WAP-ESF's default port number (MMC:"browser:proxy..0.port")
   uint16 wProxyPortLen;               ///< The number of bytes for default port number
   const uint8 *kpbProxyE2Eport;       ///< WAP-ESF's secure e2e port number (MMC:"browser:proxy..0.e2eport")
   uint16 wProxyE2EportLen;            ///< The number of bytes for secure e2e port number
   const uint8 *kpbProxyLxLport;       ///< WAP-ESF's secure lxl port number (MMC:"browser:proxy..0.lxlport")
   uint16 wProxyLxLportLen;            ///< The number of bytes for secure lxl port number
   const uint8 *kpbProxyAuthUsername;  ///< WAP-ESF's user ID (MMC:"browser:proxy..0.auth.username")
   uint16 wProxyAuthUsernameLen;       ///< The number of bytes for user ID
   const uint8 *kpbProxyAuthPassword;  ///< WAP-ESF's password (MMC:"browser:proxy..0.auth.password")
   uint16 wProxyAuthPasswordLen;       ///< The number of bytes for password
} tsIOMBV6_InetInfo;

/**@ingroup grp_utils
 This root certificate information structure is passed to the IOMBV6_oGetRootCertInfo()
 to get the root certificate information corresponding to the specified index during run time.

 Issuer and Subject should have some following OID names:
 - /CN	Common name
 - /C	Country name
 - /L	Locality name
 - /ST	State Or Province name
 - /O	Organization name
 - /OU	Organizational Unit name
 - /G	Given name
 - /S	Surname
 - /SN	Serial number
 - /I	Initials
 - /T	Title


*/
typedef struct
{
   const byte *kpcVersion; 	                      ///< Version             (Binary: 1byte)
   const char *kpczSerialNumber; 	              ///< Serial number       (C strings)
   const char *kpczSignatureAlgorithm;	          ///< Signature algorithm (C strings)
   const char *kpczIssuer; 	                      ///< Issuer              (C strings: "/C=../O=../OU=..")
   const char *kpczValidFrom; 	                  ///< Issued date         (C strings: "MM/DD/YY hh:mm:ss")
   const char *kpczValidTo; 	                  ///< Expiration date     (C strings: "MM/DD/YY hh:mm:ss")
   const char *kpczSubject; 	                  ///< Subject             (C strings: "/C=../O=../OU=..")
   const char *kpczPublicKey; 	                  ///< Public key          (C strings)
} tsIOMBV6_RootCertInfo;


/**@ingroup grp_http_request_manager
@DESCRIPTION
 Callback function that is called by the browser to receive the head response
 received from the remote HTTP server for an IOMBV6_lwHTTP_RequestStart()
 request.
@PARAMETERS
 @param[in] lwHandle The handle that was returned in the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] lwUserHandle Optional user specific handle that was passed in to the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] *pvUser Optional user specific data that was passed in to the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] wStatus An integer specifying the HTTP Status-Code provided in the
   Status-Line of the response, as defined in RFC 2616, section 6.1.1.
 @param[in] kpczUrl A pointer to the response URL - if included in the response -
   as a null-terminated string.\n
   In most cases, url is the value of the Content-Location entity-header field
   included in the response. However, for redirection responses (HTTP 301, 302,
   303, 307), url is the value of the Location response-header field.\n
   The device may use the value of url as a base URL for interpreting any
   relative URLs that might be defined in the response.
 @param[in] kpczHeaders A pointer to a null-terminated string that contains a
   blank-line (CRLF) terminated block of headers that were included in the
   response.
@RETURNS
 TRUE to continue the transaction.  Otherwise FALSE to stop it and force the 
 browser to cancel the request and deallocate resources associated with it, 
 without calling the #tpfvEndNotify callback.
*/
typedef boolean (*tpfoStartNotify)( uint32 lwHandle, uint32 lwUserHandle, void *pvUser, uint16 wStatus, const char *kpczUrl, const char *kpczHeaders );

/**@ingroup grp_http_request_manager
@DESCRIPTION
 Callback function that is called by the browser to receive the a chunk of a
 response entity data for an IOMBV6_lwHTTP_RequestStart() request.
@PARAMETERS
 @param[in] lwHandle The handle that was returned in the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] lwUserHandle Optional user specific handle that was passed in to the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] *pvUser Optional user specific data that was passed in to the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] kpbData A pointer to a buffer containing a chunk of the response
   entity.
 @param[in] liDataSize Amount of data in bytes.
@RETURNS
 TRUE to continue the transaction.  Otherwise FALSE to stop it and force the 
 browser to cancel the request and deallocate resources associated with it, 
 without calling the #tpfvEndNotify callback.
*/
typedef boolean (*tpfoDataNotify)( uint32 lwHandle, uint32 lwUserHandle, void *pvUser, const uint8 *kpbData, int32 liDataSize );

/**@ingroup grp_http_request_manager
@DESCRIPTION
 Callback function that is called by the browser when a
 IOMBV6_lwHTTP_RequestStart() transaction has finished.
@PARAMETERS
 @param[in] lwHandle The handle that was returned in the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] lwUserHandle Optional user specific handle that was passed in to the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] *pvUser Optional user specific data that was passed in to the call to
   IOMBV6_lwHTTP_RequestStart().
 @param[in] oComplete TRUE if the transaction was successful and all data was
   received.  FALSE if there was an error and data is missing.
@RETURNS
 Nil.
*/
typedef void (*tpfvEndNotify)( uint32 lwHandle, uint32 lwUserHandle, void *pvUser, boolean oComplete );


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

	INTERFACE

==============================================================================*/
/**@ingroup grp_lifecycle
 This is the interface to the Openwave Mobile Browser V6 extension.  It is
 returned when the extension is created with a call to ISHELL_CreateInstance
 with a class ID of @ref AEECLSID_IOMBV6.  This structure is the first parameter
 that is passed into all the functions of this class as it refers to a unique
 instance of the class.  Rather than creating multiple instances of this class
 for each transaction, an application may simply make multiple requests and track
 each request via the handle that is returned from IOMBV6_lwHTTP_RequestStart(). */
typedef struct stIOMBV6 IOMBV6;

#ifndef DOXYGEN_SHOULD_SKIP_THIS //make doxygen ignore this block of code
//This is the definition of the virtual function structure
AEEINTERFACE( IOMBV6 )
{
   //declare our virtual functions using macro expansion
   #define FUNCTION( RETURNS, NAME )   RETURNS (*NAME)(
   #define NO_PARAM                    void
   #define FIRST_PARAM( TYPE, NAME )   TYPE NAME
   #define NEXT_PARAM( TYPE, NAME )    , TYPE NAME
   #define END_FUNCTION                );
   #include "iombv6.m"
};
#endif //DOXYGEN_SHOULD_SKIP_THIS


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

	VIRTUAL FUNCTION ACCESSORS

==============================================================================*/
///@ingroup grp_lifecycle
///Wrapper for the lwAddRefPub() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_lwAddRef( psIOMBV6 ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->lwAddRefPub( psIOMBV6 )

///@ingroup grp_lifecycle
///Wrapper for the lwReleasePub() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_lwRelease( psIOMBV6 ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->lwReleasePub( psIOMBV6 )

///@ingroup grp_http_request_manager
///Wrapper for the vHTTPREQ_RegisterCallbacks() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_vHTTP_RegisterCallbacks( psIOMBV6, pfoStartNotify, pfoDataNotify, pfvEndNotify ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->vHTTPREQ_RegisterCallbacks( psIOMBV6, pfoStartNotify, pfoDataNotify, pfvEndNotify )

///@ingroup grp_http_request_manager
///Wrapper for the lwHTTPREQ_RequestStart() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_lwHTTP_RequestStart( psIOMBV6, kpczMethod, kpczUrl, kpczHeaders, kpbEntity, liEntitySize, oStreaming, lwUserHandle, pvUser ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->lwHTTPREQ_RequestStart( psIOMBV6, kpczMethod, kpczUrl, kpczHeaders, kpbEntity, liEntitySize, oStreaming, lwUserHandle, pvUser )

///@ingroup grp_http_request_manager
///Wrapper for the vHTTPREQ_RequestCancel() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_vHTTPRequestCancel( psIOMBV6, lwHandle ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->vHTTPREQ_RequestCancel( psIOMBV6, lwHandle )

///@ingroup grp_http_request_manager
///Wrapper for the vHTTPREQ_RequestCancelUser() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_vHTTPRequestCancelUser( psIOMBV6, pvUser ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->vHTTPREQ_RequestCancelUser( psIOMBV6, pvUser )

///@ingroup grp_config
///Wrapper for the vCFG_InitStructure() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_vInitStructure( psIOMBV6, psConfig ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->vCFG_InitStructure( psIOMBV6, psConfig )

///@ingroup grp_config
///Wrapper for the oCFG_ConfigInternalSettings() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oConfigInternalSettings( psIOMBV6, kpsConfig ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oCFG_ConfigInternalSettings( psIOMBV6, kpsConfig )

///@ingroup grp_config
///Wrapper for the oCFG_RestoreInternalDefaults() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oRestoreInternalDefaults( psIOMBV6 ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oCFG_RestoreInternalDefaults( psIOMBV6 )

///@ingroup grp_cache
///Wrapper for the vCFG_ClearCache() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_vClearCache( psIOMBV6, eItem ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->vCFG_ClearCache( psIOMBV6, eItem )

///@ingroup grp_snapshot
///Wrapper for the oSNAP_DeleteAllSnapshots() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oDeleteAllSnapshots( psIOMBV6 ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oSNAP_DeleteAllSnapshots( psIOMBV6 )
 
///@ingroup grp_object
///Wrapper for the oMMC_GetObject() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oGetObject( psIOMBV6, kpczObjectName, pbBuffer, plwNofBytes ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oMMC_GetObject( psIOMBV6, kpczObjectName, pbBuffer, plwNofBytes )

///@ingroup grp_object
///Wrapper for the oMMC_SetObject() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oSetObject( psIOMBV6, kpczObjectName, kpbBuffer, wNofBytes ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oMMC_SetObject( psIOMBV6, kpczObjectName, kpbBuffer, wNofBytes )

///@ingroup grp_utils
///Wrapper for the oPUBUTIL_IsHomeDomain() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oIsHomeDomain( psIOMBV6, kpczURL ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oPUBUTIL_IsHomeDomain( psIOMBV6, kpczURL )

///@ingroup grp_utils
///Wrapper for the wPUBUTIL_GetCurrentURL() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_wGetCurrentUrl( psIOMBV6, pczCurrentURL, wBufferSize ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->wPUBUTIL_GetCurrentURL( pczCurrentURL, wBufferSize )

///@ingroup grp_utils
///Wrapper for the oPUBUTIL_GetRootCertInfo() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oGetRootCertInfo( psIOMBV6, lwIndex, psRootCertInfo ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oPUBUTIL_GetRootCertInfo( psIOMBV6, lwIndex, psRootCertInfo )

///@ingroup grp_config
///Wrapper for the oCFG_ConfigInetInfoSettings() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oConfigInetInfoSettings( psIOMBV6, psInetInfo ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oCFG_ConfigInetInfoSettings( psIOMBV6, psInetInfo )

///@ingroup grp_config
///Wrapper for the oCFG_ClearPersistentMemory() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_oClearPersistentMemory( psIOMBV6 ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->oCFG_ClearPersistentMemory( psIOMBV6 )

///@ingroup grp_utils
///Wrapper for the vPUBUTIL_AddTestRootCert() function.  This macro provides a
///convienient method for an application to call this function.
#define IOMBV6_vAddTestRootCert( psIOMBV6, kpbTestRootCert ) \
   AEEGETPVTBL( (psIOMBV6), IOMBV6 )->vPUBUTIL_AddTestRootCert( psIOMBV6, kpbTestRootCert )


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

	GLOBAL VARIABLE DECLARATIONS

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


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

	FUNCTION DECLARATIONS

==============================================================================*/
/**@ingroup grp_lifecycle
@DESCRIPTION
 This function is used by the BREW core to load an instance of the class.  It
 is never called directly by an application.  Instead, it is called by BREW when
 an application requests an instance of this class via ISHELL_CreateInstance().\n\n
 The OEM should add this function to the BREW class table to allow
 ISHELL_CreateInstance() to create an instance of this extension.
@PARAMETERS
 @param[in] psIShell Contains pointer to the IShell interface. 
 @param[in] lwClassID Specifies the ClassID of the applet which is being loaded
 @param[in] ppsMe On return, points to a valid instance of the class provided
   this function returns SUCCESS.  If an error occurs, this will return NULL.
@RETURNS
 SUCCESS if the extension initialised ok, otherwise an error explaining the
 reason for the initialisation failure.
*/
int Opwv_Ext_New( IShell *psIShell, AEECLSID lwClassID, void **ppsMe );


#endif /* _IOMBV6_H */



