wipdb.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.
 */
/*
 * wipdb.h
 *
 * Simple database system.
 *
 *
 * Created by Niclas Kellgren 000606.
 *
 * Revision history:
 *   000703  NKE  first version
 *   000728  NKE  data channel handling added
 *   000804  NKE  data channel api updated 
 *   000809  NKE  minor changes to data channel api
 *   000906  NKE  addHost, deletHost interfaces changed
 *   000914  NKE  data channel handling moved to dbFunct.h
 *   001018  NKE  added persistent memory handling
 *   010219  NKE  added db prefix to functions
 *   010220  NKE  added db_getElementData	and changed db_getInt/Str/Mem/Ptr to macros
 *   010309  NKE  added db_createStr and db_createMem
 *   010404  NKE  added DB_GET_MEM_START and DB_GET_MEM_LEN
 *   010514  NKE  added db_moveRecord	and some enhancements to handle backup/write-through
 *                conflicts generated by the new function.
 */

#ifndef _WIPDB_H
#define _WIPDB_H

#include "cmmnrsrc.h"
#include "confvars.h"
#include "aapimem.h"
#include "storage.h"
#include "wapcvt.h"


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

/* Error codes returned from functions in this module. */
enum {
	DB_err_success             = 0,  /* Successful operation.                                   */
	DB_err_nullValue           = 1,  /* Null pointer as parameter.                              */
	DB_err_record              = 2,  /* Couldn't find record.                                   */
	DB_err_field               = 3,  /* Couldn't find field.                                    */
	DB_err_outOfRefs           = 4,  /* Out of unique references.                               */
	DB_err_wrongType           = 5,  /* Tried to do a get/set on an element of a different type.*/
	DB_err_setError            = 6,  /* Unable to set data in element.                          */
	DB_err_exists              = 7,  /* Element with given key does already exist.              */
	DB_err_tooLongKey          = 8,  /* The key is too long.                                    */
	DB_err_noKeyGiven          = 9,  /* No key was given and the source record was nameless.    */
	DB_err_objectNotFound      = 10, /* Object not found.                                       */
	DB_err_noDefaultChannel    = 11, /* No channel set as default.                              */
	DB_err_persistentTypeError = 12, /* Pointer elements cannot be save on persistent memory.   */
	DB_err_outOfMemory         = 13, /* Out of memory. Can normaly not occur.                   */

	DB_err_noPersistentSave    = 20  /* Warning: created element, failed to save it persitently.*/
};

/* Flags to be used as inparameters to functions. */
enum {
	DB_null = 0,                     /* Not an element.                                         */
	DB_root = 65535u-31,             /* Reference to root element. Root hash to zero.           */

	DB_rec              = 0x00,      /* Normal record.                                          */
	DB_set              = 0x01,      /* Elements in record are nameless.                        */
	DB_int              = 0x02,      /* Integer element                                         */
	DB_str              = 0x03,      /* String element                                          */
	DB_mem              = 0x04,      /* Memory block element                                    */
	DB_ptr              = 0x05,      /* Pointer element                                         */
	
	DB_backup           = 0x10,      /* Backup element and its data/sub elements at closedown.  */
	DB_writeThrough     = 0x20,      /* Backup element as soon it is changed.                   */
	DB_noPersistentSave = 0x00       /* Do not backup this element                              */
};


/*********
 * Types *
 *********/

typedef UINT16 DB_ref;


typedef union {
	UINT32                i;
	void*                 p;
	BYTE*                 s;
} DB_elementData;


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

/*
    ----------------
    Element handling
    ----------------

 * Four types of data is handled: 32 bits unsigned integers,
 * strings, memory blocks and pointers. A memory block is a block
 * where its first 16 bits are used for telling the size of the
 * block in octets, the first two inclusive. To avoid endian 
 * problems, access the size by *(UINT16 *) p, where p is a
 * pointer to the block. All strings must be null terminated.
 *
 * Pointers are used to point out a structure outside the data-
 * base. Data belonging to the other three types are saved inside
 * the database, are owned by the data base and deallocated when
 * needed.
 *
 * All strings and memory blocks must be allocated by WIPAlloc()
 * and so are copies recieved from the database.
 *
 * All records have a reference of the DB_ref type. Null references
 * are DB_null and the root element has the reference DB_root.
 * 
 * A record can be of two types: record or set. A set is a record
 * with two restriction:
 * 1. The elements in a set do not have a key and can therefore
 *    not be fetched with any of the get operations.
 * 2. A record or set cannot be a field in a set.
 *
 * Error codes are defined in the constants section.
 */


/*
 * GET
 * 
 * Return requested data. Str and mem functions return a copy
 * interna data. Can only be done on a field of the same type
 * as requested. And exeption is getPtr, which can be applied
 * on a string, memory block och pointer element. It returns 
 * a pointer to internal or external object.
 *
 * The db_getInt/Str/Mem/Ptr functions are defined as macros and
 * use db_getElementData.
 *
 * If 'del' is true, the element is deleted together with its
 * data. Deleting the element when calling db_getPtr only removes
 * the field, not its data even if it is a string or memory 
 * block element.
*/
/*
INT32  db_getInt (DB_ref record, const BYTE* key, BOOL del, UINT8* errorCode);
BYTE*  db_getStr (DB_ref record, const BYTE* key, BOOL del, UINT8* errorCode);
BYTE*  db_getMem (DB_ref record, const BYTE* key, BOOL del, UINT8* errorCode);
void*  db_getPtr (DB_ref record, const BYTE* key, BOOL del, UINT8* errorCode);
*/
DB_ref db_getRef (DB_ref record, const BYTE* key, UINT8* errorCode);
UINT8  db_getType(DB_ref record, const BYTE* key, UINT8* errorCode);


DB_elementData db_getElementData(DB_ref record, const BYTE* key, BOOL del, UINT16 type, UINT8* errorCode);

#define db_getInt(record, key, del, errorCode) \
db_getElementData((record), (key), (del), DB_int, (errorCode)).i

#define db_getStr(record, key, del, errorCode) \
db_getElementData((record), (key), (del), DB_str, (errorCode)).s

#define db_getMem(record, key, del, errorCode) \
db_getElementData((record), (key), (del), DB_mem, (errorCode)).s

#define db_getPtr(record, key, del, errorCode) \
db_getElementData((record), (key), (del), DB_ptr, (errorCode)).p


/*
 * SET
 *
 * Set field to specified value. If the field does not exist,
 * it is created. If it does exist, it has be of the same
 * type as the the operation. Its data is updated and in the
 * str and mem case, its old data is freed.
 *
 * An error code is returned.
 */
UINT8 db_setInt(DB_ref record, const BYTE* key, INT32 value);
UINT8 db_setStr(DB_ref record, const BYTE* key, BYTE* value);
UINT8 db_setMem(DB_ref record, const BYTE* key, BYTE* value);
UINT8 db_setPtr(DB_ref record, const BYTE* key, void* value);


/*
 * CREATE
 *
 * Create a new empty record. 'flags' can be of two types, DB_rec
 * means record and DB_set creates a set.
 * 
 * If a field with the same name exists, an error will be generated,
 * except when the parent record is a set.
 *
 * 'errorCode' returns the status of the function. DB_err_success
 * when the operation i successfully completed.
 *
 * If 'key' is NULL, the key of the new record will be an empty
 * string.
 */
DB_ref db_createRecord(DB_ref record, const BYTE* key, UINT16 flags, UINT8* errorCode);


/*
 * COPY
 *
 * Duplicates a record tree 'from' and inserts it at the record
 * 'to' as a field. It is legal to insert the copy into source
 * tree.
 *
 * 'key' is the name of the copy. If 'key' is NULL, the original
 * name will be used.
 *
 * 'flags' can be set to DB_writeThrough or DB_backup, but this
 * parameter can only be used if the destination 'to' is DB_root.
 * Otherwise the persistent state is inherited from the parent,
 * i.e. form the 'to' record. Use DB_noPersistentSave when no
 * persistent save is wanted.
 *
 * If an error occurs, all work is undone and a correct
 * structrure is maintained.
 *
 * A reference to the new record is returned.
 */
DB_ref db_copyRecord(DB_ref from, DB_ref to, BYTE* key, UINT16 flags, UINT8 *errorCode);

/*
 * MOVE
 *
 * Move a record to a new destination. The element order is
 * preserved.
 *
 * Even if the original is write through or backup, the copy
 * may or may not be. Instead 'flags' can be set to DB_writeThrough
 * or DB_backup to indicate the new persistent state. This
 * parameter is only used when the destination 'to' is DB_root.
 * Otherwise the persistent state is inherited from the parent,
 * i.e. from the 'to' record. Use DB_noPersistentSave when no
 * persistent save is wanted.
 *
 * If an error occurs, all work is undone and a correct
 * structrure is maintained.
 *
 * A record moved into itself, it is deleted and the reference
 * returned is not valid. 
 *
 * A moved record gets a new reference and it is returned.
 */
DB_ref db_moveRecord (DB_ref from, DB_ref fromParent, DB_ref to, UINT16 flags, UINT8 *errorCode);

/*
 * DELETE
 *
 * db_deleteItem removes the specified item. If it is a string or 
 * memory block, associated data is freed. For records and sets,
 * the entire subtree is deleted.
 *
 * db_clearRecord removes all fields connected to 'record'. The 
 * entire subtree is deleted. Works on both records and sets.
 *
 * An error code is returned.
 */
UINT8 db_deleteItem(DB_ref record, const BYTE* key);
UINT8 db_clearRecord(DB_ref record);



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

/*
 * INIT/TERMINATE
 *
 * To be called at start-up or close-down.
 *
 * Remove of all non-database structures connected to the
 * database before calling dbTerminate. 
 *
 * If HAS_SETJMP is not set, when out of memory, the system
 * does not restart until the control has been returned to the
 * event loop. In this case, it is not legal to call any database
 * functions between dbInit and returning to the event loop.
 *
 * An error code is returned, telling the what went wrong.
 */
UINT16 db_dbInit(void);
UINT16 db_dbTerminate(void);



/*
 * COPY STRING/MEMORY BLOCK
 *
 * 'p' points to the area to be copied. db_createStr copies length-1
 * bytes and adds a '\0'. db_createMem saves 'length' in two bytes
 * and appends a copy of 'length' bytes.
 */
BYTE* db_createStr(const char* p, UINT16 length);
BYTE* db_createMem(const char* p, UINT16 length);


/*
 * MEM FUNCTIONS
 *
 * DB_GET_MEM_LEN gives the length of a memory block.
 *
 * DB_GET_MEM_START gives the pointer to the first data byte in
 * a memory block. The result is a pointer to a BYTE.
 */
#define DB_GET_MEM_LEN(p) (*(UINT16*) (p))
#define DB_GET_MEM_START(p) ((BYTE*) (p) + sizeof(UINT16))

#endif