dbfunct.h

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

/*
 * Copyright (C) Ericsson Mobile Communications AB, 2000, 2001.
 * 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.
 */
/*
 * dbFunct.h
 *
 * Data channel handling.
 * Store and find authentication information in database.
 * Store and find cookies.
 *
 * This file contains various functions with two things in common:
 * they both use wipdb database and they access internal
 * structures in the database.
 *
 *
 * Created by Niclas Kellgren 000904.
 *
 * Revision history:
 *   000914, NKE: data channel code moved from wipdb.h
 *   001004, NKE: host and proxy authentication added
 *   001019, NKE: host and proxy api changed
 *   001117, NKE: documentation
 *   010122, NKE: added constants for configuration variable names
 *   010123, NKE: adding missing symbolic constant CREDENTIALS
 *   010130, NKE: changed the declaration of addHost and deleteHost 
 *   010130, NKE: added getFirstConfiguredObject
 *   010208, RMZ: added functions for cookies
 *   010315, NKE: added COOKIES_ENABLED constant
 *   010410, IPN: added MASTER_GW, STARTPAGE, PROXY_PROVIDER_ID constants
 *   010514, NKE: added setPersistentAuthStatus
 */

#ifndef _DBFUNCT_H
#define _DBFUNCT_H

#include "tapimmi.h"
#include "aapiclnt.h"
#include "cmmnrsrc.h"
#include "wipdb.h"


/*
 * DATA CHANNEL HANDLING
 *
 * This file contains among other things a collection of functions
 * handling data channels. Always use specialized function if 
 * available. I.e. deleting a object record with deleteItem instead
 * of	deleteObject may cause a corrupt database and a system crash!
 *
 *
 * HOST AND PROXY AUTHENTICATION
 *
 * The authentication functions do not use external structures, but
 * is dependent on pointers to elements. The database records
 * created by the code must not be deleted or manipulated by 
 * ordinary database operations.
 *
 * The structures are saved to persistent memory. This makes
 * operations that change data slow. Searching though, is done
 * entirely in RAM menory and is fast.
 */



 
/*************************************************************/
/******************  data channel handling  ******************/
/*************************************************************/


/*************
 * Constants *
 *************/

#define HISTORY_SIZE         "hstSz"
#define CACHE_AGE            "cAge"
#define CACHE_MODE           "cMode"
#define DISPLAY_IMAGES       "dsplI"
#define UPDATE_IMAGES        "updtI"
#define PUSH_SECURITY_LEVEL  "pshSL"
#define WSP_LANGUAGE         "wsp l"
#define PROFILE              "profl"
#define PROFILE_DIFF         "pDiff"
#define USER_AGENT           "ua"
#define ACCESS_TYPE          "accTp"
#define ONLINE               "onln"
#define CLIENT_LOCAL_PORT    "cltLP"
#define USSD_GW_TYPE         "usdGT"
#define TIMEOUT              "tmout"
#define STACKMODE            "stckm"
#define CHANNEL_EXPIRES      "cExp"
#define MASTER_GW            "mast"
#define STARTPAGE            "stPa"
#define PROXY_PROVIDER_ID    "prPrI"
#define ALLOW_WTLS_CLASS_1   "wtls1"
#define UDP_IP_SRC           "udpIS"
#define UDP_IP_GW            "udpIG"
#define SMS_C                "smsC"
#define SMS_GW               "smsGW"
#define USSD_C               "usdC"
#define USSD_GW              "usdGW"
#define CREDENTIALS          "cred"
#define COOKIES_ENABLED      "cEnbl"

/* cookie component keys */
#define COOKIE_LIST          "coo"
#define COOKIE_NAME          "name"
#define COOKIE_VALUE         "val"
#define COOKIE_DOMAIN        "dom"
#define COOKIE_PATH          "path"
#define COOKIE_EXPIRES       "exp"
#define COOKIE_VERSION       "ver"


/* 
 * Default values for fields automatically added can be found in
 * addDataChannel() or dchInit().
 */

enum {
	DB_maxNbrOfObjects = 10 + 1, /* Upper limit for number of concurrent objects plus one template */
	DB_maxNbrOfDataChannels = 7  /* Upper limit for number of concurrent data channels */
};


/*************
 * Functions *
 *************/

/*
 * GET REFERENCE
 *
 * Return a reference to the record associated with 'object'
 * and 'channel'.
*/
DB_ref getObjectRef(UINT8 object);
DB_ref getChannelRef(UINT8 object, UINT8 channel);


/*
 * ADD/DELETE OBJECT
 *
 * addObject adds an object with number 'object' if it does not
 * exist. The function returns a reference to the new object
 * record.
 *
 * removeObject removes an object with number 'object' and all
 * its data.
 */
DB_ref addObject(INT8 object);
void   deleteObject(UINT8 object);


/*
 * SEARCH FOR CONFIGURED OBJECT
 *
 * Search for an object not connected to a push, WTA, template or
 * content user agent. The number of first one found with at least 
 * one configured data channel is returned. If no matching object
 * is found, '*errorCode' is set to DB_err_objectNotFound, else
 * DB_err_success.
 */
UINT8 getFirstConfiguredObject(UINT8 *errorCode);


/*
 * DATA CHANNEL
 *
 * addDataChannel creates a new channel record and an new object
 * record if nessesary.	It returns a reference to the new channel
 * record.
 *
 * deleteChannel removes the channel object if found. If the
 * default channel is deleted, then a call to getDataChannel
 * that does not result in a match will cause an error code to
 * be returned.
 *
 * getDataChannel searches through all host addresses connected
 * to the channels in an object. The channel number belonging
 * to the best matching host is returned. If there is no match,
 * then if set, the default channel number is returned, or else
 * an error occurs. Assumes the url to be well formatted, including
 * a scheme, host and optionally a path. The status of the
 * function at return is signaled through '*errorCode'.
 *
 * The host address connected to a channel contains a host name
 * which may be followed by a path name.
 *
 * getDataChannel matches url:s with host addresses as sepcified
 * in the WAP End to End Security Specification (section 10.3.1).
 * During getDataChannel it is checked if channels for the specified
 * object have expired. If any expired channels are found the outparam
 * expired is set, otherwise it is false. The id of any expired channels
 * for the object is remembered in an internal set (list). These channel
 * id:s may be retrieved by calling getNextExpired. Note, the internal set
 * of expired channel id:s is reset for each call of getDataChannel.
 *
 * setDefaultDataChannel changes the data channel to be used
 * when no host matches when calling getDataChannel. An object
 * and a data channel are created if either is missing.
 *
 * getNextExpired iterates on the internal set of expired channels.
 * The internal set is reset when calling getDataChannel. getNextExpired
 * returns TRUE if outparam channelId is valid, i.e. containing the next
 * channel id in the iteration. getNextExpired returns FALSE when the
 * iteration ends and then the outparam channelId is not valid.
 * The channelId param must not be NULL.
*/
DB_ref addDataChannel(UINT8 object, UINT8 channel);
void   deleteDataChannel(UINT8 object, UINT8 channel);
UINT8  getDataChannel(UINT8 object, const BYTE* url,
                      BOOL* expired, UINT8 *errorCode);
void   setDefaultDataChannel(UINT8 object, UINT8 channel);
BOOL   getNextExpired(UINT8* channelId);

/*
 * ADD/DELETE HOST
 *
 * Add/delete host address and optionally path. 
 *
 * When calling these functions, the string pointed out by 'host'
 * is not taken over by the database.
 *
 * The string pointed out by 'host' must include a host name which
 * may be followed by a path name. The first '/' delimits the host from
 * the path. The host name may be the empty string.
 *
 * 'length' is the length of host including any path but excluding an  
 * optional terminating EOL.
 *
 * Calling deleteHost, the 'host'
 * string must match the host and any path to be deleted.
 * When matching, the host part is compared case insensitively while any path
 * part is compared case sensitively.
 */
void addHost   (UINT8 object, UINT8 channel, const BYTE* host, UINT16 length);
void deleteHost(UINT8 object, UINT8 channel, const BYTE* host, UINT16 length);


/*
    --------------
    Administration
    --------------
*/

/*
 * INIT/TERMINATE
 *
 * To be called at start-up or close-down.
 */
void dataChannelInit(void);
void dataChannelTerminate(void);






/*************************************************************/
/**********************  authenticate  ***********************/
/*************************************************************/


/*************
 * Functions *
 *************/

/*
    -------------------
    Host authentication
    -------------------
*/

/*
 *	STORE HOST CREDENTIALS
 *
 * Store the host of 'url' together with 'realm' and 'credientials'.
 * If already cfg_wae_wspif_AuthenticationItems are present, the
 * least reasently used element is replaced by the new one.
 *
 * If host and 'realm' matches an item, then the credentials are
 * uppdated to 'credentials'. The host and 'realm' are text
 * strings and are matched agaist the database case insensitivily.
 *
 * Return TRUE if successfull.
 */
BOOL storeHostAuth(BYTE* url, BYTE* realm, BYTE*  credentials, UINT8 credLength);


/*
 * CHECK HOST CREDENTIALS
 *
 * Search the database and return the credentials connected to
 * the host of 'url' and 'realm'.
 *
 * This function is called in two cases: before a http request
 * and when a request results in a challange for authenification.
 * In the first case, checkHostAuth is called with 'realm' set
 * to NULL and the matching is done based on only the URL. Even
 * if the item exists in the database, a mismatch may occur.