dbfunct.h

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

 * This can happen if several items with identical host are in
 * the database. A mismatch will result in a challenge containing
 * the correct realm and the correct credentials can be found.
 *
 * '*credentials' is a pointer to the corresponding credentials.
 * This is a pointer to the database item and not to a copy and
 * and may not be freed. 
 *
 * The host of 'url' and 'realm' are text strings and are matched
 * agaist the database case insensitivily.
 *
 * Return TRUE if found a match.
 */
BOOL checkHostAuth(BYTE* url, BYTE* realm, BYTE* *credentials);


/*
 * DELETE HOST CREDENTIALS
 *
 *	Remove all host authentication data.
 */
void deleteHostAuth(void);


/*
    --------------------
    Proxy authentication
    --------------------
*/

/*
 *	STORE PROXY CREDENTIALS
 *
 *	Store 'address' and 'portNumber' together with 'credentials'.
 * If already cfg_wae_wspif_AuthenticationItems are present, the
 * least recently added element is replaced by the new one.
 * 
 * If 'adress' and 'portNumber' matches an item, then the
 * credentials are uppdated to 'credentials'. 'address' can
 * contain any data and is only an exact match counts when
 * comparing addresses.
 *
 * 'address' can contain any data and is only an exact match counts
 * when comparing addresses.
 *
 * Return TRUE if successfull.
 */
BOOL storeProxyAuth(BYTE* address, UINT8 addressLength, UINT16 portNbr,
                    BYTE* credentials, UINT8 credLength);


/*
 * CHECK PROXY CREDENTIALS
 *
 * Search the database and return the credentials connected to
 * the host of 'url' and 'realm'.
 *
 * '*credentials' is a pointer to the corresponding credentials.
 * This is a pointer to the database item and not to a copy and
 * and may not be freed. 
 *
 * 'address' can contain any data and is only an exact match counts
 * when comparing addresses.
 *
 *	Return TRUE if found a match.
 */
BOOL checkProxyAuth(BYTE* address, UINT8 addressLength, UINT16 portNbr, BYTE* *credentials);


/*
 * DELETE PROXY CREDENTIALS
 *
 * Remove all proxy authentication data.
 */
void deleteProxyAuth(void);


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

/*
 * SET PERSISTENT STATUS
 *
 * Turn on or off persistent status for host or proxy 
 * authentication. 'hostNotProxy' is TRUE for host and FALSE
 * for proxy. 'status' is
 * 0 - no persistent save
 * 1 - backup
 * 2 - write-through
 *
 * Return error code.
 */
UINT8 setPersistentAuthStatus (BOOL hostNotProxy, int status);

/*
 * INIT/TERMINATE
 *
 * To be called at start-up or close-down. Call init after dbInit
 * and call terminate before dbTerminate.
 */
void authenticateInit(void);
void authenticateTerminate(void);





/*************************************************************/
/**********************     Cookies    ***********************/
/*************************************************************/


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

/*
    -------------------
    Access functions
    -------------------
*/

/*
 *	STORE COOKIE
 *
 * Stores a cookie composed of the given inparameters:
 *  - name,    c-string; mandatory
 *  - value,   c-string; mandatory with one exception, see below
 *  - domain,  c-string, either an explicit domain which starts with '.'
 *             or host, e.g. x.y.com; optional;
 *  - path,    c-string, path, may be empty, must not end with '/'
 *             optional
 *  - expires, unsgined integer in secs after 1970;
 *             expires is time when received + Max_Age; optional
 *  - version, unsigned integer; mandatory
 *
 * The url inparameter must be non-NULL and well formed containing the domain 
 * and optionally the path.
 *
 * If no domain is given (i.e. NULL is passed in), the storeCookie function
 * will set a default value for the cookie domain before storing the cookie. 
 * The default value used is the domain (host) part of the passed in url
 * inparameter.
 *
 * If no path is given, the storeCookie function will set the default value
 * which is the path part up to the rightmost but not including '/' of the
 * url.
 *
 * Next, this function checks that the passed in parameter url, the domain 
 * and path follows the rules as defined in rfc2109 chapter 4.3.2. I.e. it 
 * checks if a cookie received in a response should be rejected. The 
 * following rules apply:
 *  - the url domain part is domain matched against the cookie domain,
 *    domains are case insensitive
 *  - the cookie path must be a prefix of the url path part,
 *    paths are case sensitive
 *  - the cookie domain must not be a top domain, i.e. it must start with a 
 *    dot or contain embedded dots
 *  - a url host of the form HD must not contain any dots in H where D is
 *    the value of the cookie domain.
 *
 * If the check fails, the cookie is rejected.
 *
 * A missing value (NULL) for expires will be interpreted as keeping the
 * cookie until the next time the database is closed down, i.e the
 * next time cookiesTerminate() is called.
 *
 * For mandatory values, NULL must not be passed in, except when a zero
 * expire value is given, see below.
 *
 * A cookie is identified by the components domain, path and name.
 *
 * If already cfg_wae_wspif_CookieItems are present, the
 * least reasently used element is replaced by the new one.
 *
 * Trying to store a cookie that already exists updates the existing cookie.
 * The exception is when a zero expires value is given. This is 
 * interpreted as immediate expiration and any cookie matching the cookie
 * beeing passed in will be deleted. In either case, a cookie with
 * an expires value 0 will not be stored.
 *
 * When a zero expire value is given, the value parameter may be NULL.
 *
 * The cookie is stored in ram. However, when closing the database
 * cookies will be stored on persistent media, see cookiesTerminate().
 *
 * When a cookie is updated or created, all input parameters are copied
 * and stored.
 *
 * Returns TRUE if successfull.
 */
BOOL storeCookie(BYTE* url, BYTE* name, BYTE* value, BYTE* domain,
                 BYTE* path, UINT32* expires, UINT32 version);


/*
 * CHECK COOKIES
 *
 * Searches the database for all cookies valid for the passed in url.
 * To retrieve the result of the search, call getNextCookie repeatedly
 * unitl false is returned.
 *
 * This function is intended to be called before a http request.
 * The url inparameter must be non-NULL and well formed containing the domain
 * and optionally the path.
 *
 * A match as defined in rfc2109 is:
 *  - the url domain part is domain matched against the cookie domain,
 *    domains are case insensitive
 *  - the cookie path must be a prefix of the url path part,
 *    paths are case sensitive
 *
 * All matched cookies will be stored internally. Calling 
 * getNextCookie retrieves cookies from the stored search result.
 *
 * Calling storeCookie, checkCookie or deleteAllCookies
 * invalidates the internally stored search result from the previous
 * checkCookie call.
 *
 * Side effect: during the search, the expires date is checked and
 *              if a cookie is expired it will be removed from the database.
 *
 * Returns TRUE if one or more cookies matched.
 */
BOOL checkCookies(BYTE* url);


/*
 * GET NEXT COOKIE
 *
 * Retrieves the next cookie from the set of matched cookies found
 * in a previous checkCookies() call.
 *
 * This function should be called repeatedly after a checkCookies call
 * until getNextCookie returns false.
 *
 * Cookies are returned in the following order:
 *  - more specific paths precedes less specific paths,
 *
 * getNextCookie returns the cookie components as out-paramameters, except
 * expires. The out-parameters are not copied out, so the database owns
 * (has delete responsibility of) the memory pointed to.
 *
 * If the caller is not interested in an out-parameter, NULL can be 
 * passed in instead, e.g. when passing in NULL for the path parameter, 
 * the path component won't be returned.
 *
 * Of the returned out-params, only the path, i.e. *path, may be NULL.
 * All other pointer out-params has non-NULL values.
 *
 * Returns TRUE when a cookie was retrieved in which case there might
 * be cookies left in the search result set to retrieve.
 * When FALSE is returned, no cookie was retrieved, the out-parameters are
 * not valid and also there are no more cookies left to retrieve from
 * the search result.
 */
BOOL getNextCookie(BYTE** name, BYTE** value, BYTE** domain, BYTE** path,
                   UINT32* version);


/*
 * RESET COOKIE ITERATION
 *
 *	Resets the iteration done via getNextCookie to the first cookie in
 * the set of matched cookies if any. That is, after this function
 * has been called, a call to getNextCookie will return the first
 * matched cookie if any.
 * If the search result is invalidated, nothing is done in this function.
 */
void resetCookieIter(void);


/*
 * DELETE ALL COOKIES
 *
 *	Removes all cookies.
 * At present, cookies are just removed from RAM,
 * not from persistent memory.
 */
void deleteAllCookies(void);



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

/*
 * INIT/TERMINATE
 *
 * To be called at start-up or close-down. Call init after dbInit
 * and call terminate before dbTerminate.
 *
 * When terminating, cookies with missing expires component will be deleted.
 * All remaining non-expired cookies will be stored on persistent media
 * on close-down.
 * 
 */
void cookiesInit(void);
void cookiesTerminate(void);



#endif