pidb.h

mini http server,可以集成嵌入到程序中,实现简单的web功能

/*____________________________________________________________________________*\
 *

 Copyright (c) 1997-2003 John Roy, Holger Zimmermann. All rights reserved.

 These sources, libraries and applications are
 FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
 as long as the following conditions are adhered to.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer. 

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.

 3. The name of the author may not be used to endorse or promote products
    derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.

 *____________________________________________________________________________*|
 *
 * $Source: /cvsroot/pi3web/Pi3Web_200/Source/Pi2API/PIDB.h,v $
 * $Date: 2003/05/13 18:42:08 $
 *
 Description:
	Definition of interface to program database class.
\*____________________________________________________________________________*/
/* $HeaderTop:$ */

#ifndef PIDB_H_
#define PIDB_H_

/*____________________________________________________________________________*\
 *
 Decription:
	Definitions and function prototypes for the program database.
\*____________________________________________________________________________*/
typedef struct _PIDB PIDB;
typedef struct _PIDBIterator PIDBIterator;
typedef struct UserDBType PIUserType;

/* ---
These are the builtin types defined in every DB tree.
--- */
#define PIDBTYPE_INVALID				-1
#define PIDBTYPE_TREE					0
#define PIDBTYPE_STRING					1
#define PIDBTYPE_RFC822					2
#define PIDBTYPE_OPAQUE					3
#define PIDBTYPE_USER					4

/* --- this should always be the value of the last builtin type --- */
#define PIDBTYPE_LAST					4	

#define PIDBTYPE_BUILTINSIZE			(PIDBTYPE_LAST+1)

/* --- Flags --- */
#define PIDBFLAG_NONE					0x0000
#define PIDBFLAG_PROPAGATEUP			0x0001
#define PIDBFLAG_NOCALLBACK				0x0002
#define PIDBFLAG_FASTKEY				0x0004

/* --- text encoding of DB types and flags, for persistence --- */
#define PIDBTYPE_TEXT_TREE				"TREE"
#define PIDBTYPE_TEXT_STRING			"STRING"
#define PIDBTYPE_TEXT_RFC822			"RFC822"
#define PIDBTYPE_TEXT_OPAQUE			"OPAQUE"
#define PIDBTYPE_TEXT_USER				"USER"

#define PIDBFLAG_TEXT_PROPAGATEUP		"PROPAGATEUP"
#define PIDBFLAG_TEXT_NOCALLBACK		"NOCALLBACK"
#define PIDBFLAG_TEXT_FASTKEY			"FASTKEY"

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_new

 Synopsis:
	PIDB *PIDB_new( PIDB *pParent, const char *pName )
	
 Description:
	Creates a new PIDB tree under the specified parent node with the 
	specified name. If pParent is NULL, then the generated node will
	be the root of a new PIDB tree hierarchy.

	If a new child tree is successfully generated it is automatically 
	added into the parent tree's list of child nodes with a type of
	PIDBTYPE_TREE and a key of pName.

	If pParent is NULL then a new root tree node is generated. This tree
	should be free'd with PIDB_delete() when it is no longer needed.

 Notes:
	If memory cannot be allocated for the new tree, a special handler
	will be invoked in a method specific to the build and configuration
	of the server library. For more information see the specific notes
	for the library release.

 Return Values:
	Returns a pointer to the new child PIDB tree, or NULL if insufficent
	memory was available.

 Errors:
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIDB *PIDB_new( PIDB *pParent, const char *pName );

/*____________________________________________________________________________*\
 *
 Name:
	PIDBEx_new

 Synopsis:
	PIDB *PIDBEx_new( PIDB *pParent, const char *pName,
		void *(* fnLookup)( PIDB *, int, const char *, int ) )
	
 Description:
	Creates a new PIDB of extended type PIDBEx. This tree supports a 
	lookup callback where lookups on the tree will invoke the user 
	supplied lookup function.

 Notes:
	Use of this callback function on instances of this extended tree
	type can be overriden by adding the PIDBFLAG_NOCALLBACK flag to the
	flags passed to PIDB_lookup() or PIDB_getIterator().

 Return Values:
	Returns a pointer to the new child PIDB tree on success.

 Errors:
	Returns NULL if fnLookup is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIDB *PIDBEx_new( PIDB *pParent, const char *pName,
		void *(* fnLookup)( PIDB *, int, const char *, int ) );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_getParent

 Synopsis:
	PIDB *PIDB_getParent( PIDB *pTree )
	
 Description:
	Returns the parent tree of the specified PIDB tree.

 Notes:
 Return Values:
	Returns a pointer to the parent tree or NULL if the specified tree
	is the top of the tree hierarchy.

 Errors:
	NULL if pTree is NULL

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIDB *PIDB_getParent( PIDB *pThis );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_add

 Synopsis:
	int PIDB_add( PIDB *pTree, int iType, const char *pKey, void *pValue,
		int iFlags )
	
 Description:
	Adds a child element into a PIDB tree. The action performed on the
	opaque pointer pValue depends on the value of iType.
<DL>
<DT><B>PIDBTYPE_TREE</B><DD>
	pValue must be a pointer to a valid PIDB tree. This tree
	is in specified tree as a child node. Note that child trees are
	automatically placed in thier parents tree when they are created,
	explicitly adding them a second time may cause serious problems
	when the tree is recursively free'd with PIDB_delete(). Use this
	only to attach a child tree which was created with a NULL value
	for parameter pParent in the call to PIDB_new().
			
<DT><B>PIDBTYPE_STRING</B><DD>
	pValue must be a pointer to a null terminated character
	array. A copy of the string is generated and stored in the 
	current tree.

<DT><B>PIDBTYPE_RFC822</B><DD>
	This type is created, maintained and used in the same
	way as type PIDBTYPE_STRING. The important difference between
	PIDBTYPE_STRING and PIDBTYPE_RFC822 is that PIDBTYPE_STRING is
	in all repects case sensitive, whereas PIDBTYPE_RFC822 is in all
	respects case in-sensitive.

<DT><B>PIDBTYPE_OPAQUE</B><DD>
	pValue is stored in the tree as an unknown pointer. Note
	that the user is responsible for free'ing memory allocated
	at pValue, if any. This is different from other tree types 
	where the object referenced by pValue will be cleaned up 
	and memory free'd when the tree is destroyed.

<DT><B>PIDBTYPE_USER</B><DD>
	This type requires that pValue is an object of a type
	not specified in this interface. Pending this specification
	this type is for internal use only.	
</DL>

	The value iFlags is formed by OR'ing together the following values
<P>

<DL>
<DT><B>PIDBFLAG_FASTKEY</B><DD>
 	The value pKey is assumed to be a symbol
	table entry so PIDB_add() skips the hashing
	and offset logic. This improves performance on 
	repeated DB actions at the cost of initial setup
	using PIDB_getFastKey().
</DL>

 Notes:
	The type PIDBTYPE_USER is under development and its behaviour
	is subject to change.

 Return Values:
	On success PIDB_add returns zero (PIAPI_COMPLETED). Otherwise
	an error occured as described below.

 Errors:
	PIAPI_EINVAL	An invalid value for iType was used or pTree was NULL
	PIAPI_EXHAUSTED	Memory could not be allocated to complete the function.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDB_add( PIDB *pTree, int iType, const char *pKey, void *pV,
		int iFlags );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_replace

 Synopsis:
	int PIDB_replace( PIDB *pTree, int iType, const char *pKey, void *pValue,
		int iFlags )
	
 Description:
	Replaces the first instance of the value corresponding to pKey in the
	DB pTree. The new entry will be created even if a previous entry could
	not be found. PIDB_add() describes the parameters iType and iFlags.
	
	Additionally iFlags may have the following flag set 
		
		PIDBFLAG_PROPAGATEUP	Search upwards from the current tree to
								parent trees to find a match.

 Notes:

 Return Values:
	On success PIDB_replace returns zero (PIAPI_COMPLETED). Otherwise
	an error occured as described below.

 Errors:
	PIAPI_EINVAL	An invalid value for iType was used or pTree was NULL
	PIAPI_EXHAUSTED	Memory could not be allocated to complete the function.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDB_replace( PIDB *pTree, int iType, const char *pKey,
		void *pV, int iFlags );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_lookup

 Synopsis:
	void *PIDB_lookup( PIDB *pTree, int iType, const char *pKey, int iFlags )
	
 Description:
	Searches the PIDB tree for the first occurence of the an element which
	matches the key. If pKey is NULL then the first element of the specified
	type will be returned. See PIDB_getIterator() for the use of the parameter
	iFlags.
		
 Notes:
	This function cannot be used to distinguish between an unsuccessful
	search and a successful search where the value of the matched element
	is NULL. In these cases an PIDBIterator object should be used to
	scan the tree, see PIDB_getIterator.

 Return Values:
	On success the reference of the first element is returned. The type of 
	the value depends on the specified value of iType. See PIDB_add for
	a full description of possible types. See PIDBIterator_current for
	a description of appropriate PIDBTYPE to C typecast mappings.
	NULL is returned if no match was found.

 Errors:
	If pTree is NULL or iType is out of range then PIDB_lookup() returns
	NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI void *PIDB_lookup( PIDB *pTree, int iType, const char *pKey,
	int iFlags );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_getFastKey

 Synopsis:
	const char *PIDB_getFastKey( const char *pKey, int iType )
	
 Description:
	Returns a pointer to a symbol table entry for the key pKey and
	PIDB type iType. This symbol table entry then then be used in calls
	to PIDB_lookup() and PIDB_getIterator() with the PIDBFLAG_FASTKEY to
	avoid the overhead of hashing and symbol table lookup.
		
 Notes:
	This function is useful where a key is used multiple times. The
	fast key can be generated once and reused across all invocations
	of PIDB_lookup() and PIDB_getIterator(). This significantly improves
	performance.

 Return Values:
	On success PIDB_getFastKey() returns a new key. Returns NULL on
	failure.

 Errors:
	Returns NULL if pKey is NULL or no memory space is available.