pidb.h

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

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI const char *PIDB_getFastKey( const char *pKey, int iType );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_pidbtypeNameToNumber

 Synopsis:
	int PIDB_pidbtypeNameToNumber( const char *pType )
	
 Description:
	Returns the integer value of the name pType, effectively mapping, the
	string pType to return values as follows:-
<CENTER>
<TABLE BORDER=1>
<TH>pType<TH>Return code
<TR><TD>"TREE"<TD>PIDBTYPE_TREE
<TR><TD>"STRING"<TD>PIDBTYPE_STRING
<TR><TD>"RFC822"<TD>PIDBTYPE_RFC822
<TR><TD>"OPAQUE"<TD>PIDBTYPE_OPAQUE
<TR><TD>"USER"<TD>PIDBTYPE_USER
</TABLE>
</CENTER>
	Comparision in not case sensitive.
		
 Notes:
 Return Values:
	If the string pType could not be matched PIDB_pidbtypeNameToNumber()
	returns PIDBTYPE_INVALID.

 Errors:
	On error PIDB_pidbtypeNameToNumber() returns PIDBTYPE_INVALID.

 See Also:
	PIDB_pidbflagsNameToNumber()
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDB_pidbtypeNameToNumber( const char *pType );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_pidbflagsNameToNumber

 Synopsis:
	int PIDB_pidbflagsNameToNumber( const char *pFlags )
	
 Description:
	Returns the integer value of the flags represented by the string pFlags.
	The string pFlags may contain many flags seperated by the pipe ('|')
	character.
<CENTER>
<TABLE BORDER=1>
<TH>pType<TH>Return code
<TR><TD>"PROPAGATEUP"<TD>PIDBFLAG_TREE
<TR><TD>"NOCALLBACK"<TD>PIDBFLAG_NOCALLBACK
<TR><TD>"FASTKEY"<TD>PIDBFLAG_FASTKEY
</TABLE>
</CENTER>
	Comparision in not case sensitive.
		
 Notes:
	Whitespace in the string pFlags is allowed and will be ignored in 
	matching the flags.

	The flags PIDBFLAG_NOCALLBACK and PIDBTYPE_FASTKEY have little use
	in the context of persistence and are included only for
	completeness.

 Return Values:
	Returns the value formed by bitwise OR'ing the flags together. If
	no flags are matched or the value pFlags is NULL,
	PIDB_pidbflagsNameToNumber returns zero (PIDBFLAG_NONE).

 Errors:
	This function does not generate an error. Unrecognised flags are
	ignored.

 See Also:
	PIDB_pidbtypeNameToNumber().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDB_pidbflagsNameToNumber( const char *pFlags );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_getIterator

 Synopsis:
	PIDBIterator *PIDB_getIterator( PIDB *pTree, int iType, const char *pKey,
			int iFlags )
	
 Description:
	Returns a pointer to an PIDBIterator object which to traverse the specified
	tree for elements of type iType which match the key pKey. If pKey is
	NULL all objects with type iType will be matched. The following flags
	may be OR'ed together to form the value iFlags:

	PIDBFLAG_PROPAGATEUP
				The current tree will first be searched and then the parent
		tree. The recursively search all trees up the tree hierarchy to
		the root node.

	PIDBFLAG_NOCALLBACK
				This flag disables use the the callback functions in
	DB tree's created with callback hook functions via PIDBEx_new().
	This flag is typically used in the implementation of callback
	functions for PIDBEx when PIDB_lookup() or PIDB_getIterator() would
	cause a recursive invokation of the callback function.

	PIDBFLAG_FASTKEY
				This flag indicates that the key pKey is an optimized
	key generated by PIDB_getFastKey(). 

 Notes:
	The iterator object should be free'd with PIDBIterator_delete() when
	it is no longer needed.

 Return Values:
	On success a pointer to an PIDBIterator object is returned. The
	functions PIDBIterator_atValidElement(), PIDBIterator_current(), 
	PIDBIterator_next() and PIDBIterator_delete() are used to access and
	manipulate the iterator.
	
 Errors:
	NULL is returned if pTree is NULL, iType invalid or memory
	could not be allocated for the PIDBIterator object.

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

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_delete

 Synopsis:
	int PIDB_delete( PIDB *pTree )
	
 Description:
	Destructs a root PIDB tree created by PIDB_new( NULL ). 

 Notes:

 Return Values:
	On success PIDB_delete returns zero (PIAPI_COMPLETED).
	
 Errors:
	PIAPI_EINVAL is returned if pTree is NULL. If pTree is a child
	node of another tree then PIAPI_ERROR is returned.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDB_delete( PIDB *pTree );

/*____________________________________________________________________________*\
 *
 Name:
	PIDB_getRoot

 Synopsis:
	int PIDB_getRoot( PIDB *pTree )
	
 Description:
	Returns the root node of a PIDB tree hierarchy.

 Notes:

 Return Values:
	On success PIDB_getRoot() returns the root node of the PIDB tree
	hierarchy.
	
 Errors:
	If pTree is NULL PIDB_getRoot() returns NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIDB *PIDB_getRoot( PIDB *pTree );

/*____________________________________________________________________________*\
 *
 Name:
	PIDBIterator_atValidElement

 Synopsis:
	int PIDBIterator_atValidElement( PIDBIterator *pIter )
	
 Description:
	Returns a boolean result indicating whether not the PIDBIterator_current()
	may be used to retrieve an element from the iterator.

 Notes:
 Return Values:
	Returns non-zero (PIAPI_TRUE) if an element may be read, otherwise zero
	(PIAPI_FALSE) the iterator has exhausted matching elements.
	
 Errors:
	Returns PIAPI_FALSE if pIter is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDBIterator_atValidElement( PIDBIterator *pIter );

/*____________________________________________________________________________*\
 *
 Name:
	PIDBIterator_current

 Synopsis:
	void *PIDBIterator_current( PIDBIterator *pIter, const char **ppKey )
	
 Description:
	Returns the value of the current element of the iterator. If ppKey is
	not NULL it will be set to point to the key of the retrieved element.

 Notes:
	The results are undefined if the iterator does not point at a valid
	element. The function PIDBIterator_atValidElement can be used to 
	verify the status of the iterator object.

	In general the iterator object return elements in no particular order.
	However, elements with the exact same key will be retrieved in the
	order in which they were placed in the tree.
	
 Return Values:
	Returns the current object from the iterator. The type of the object
	depends on the value of iType. The pointer should be cast to a 
	pointer of the appropriate type, typically the typecasts would be as
	follows
	
<CENTER>
<TABLE BORDER=1>
<TR><TH>iType<TH>Cast<TH>Remark
<TR><TD>PIDBTYPE_TREE<TD>PIDB *<TD>a tree node
<TR><TD>PIDBTYPE_STRING<TD>const char *<TD>character array
<TR><TD>PIDBTYPE_RFC822<TD>const char *<TD>character array
<TR><TD>PIDBTYPE_OPAQUE<TD>void *<TD>generic pointer
<TR><TD>PIDBTYPE_USER<TD>void<TD>not defined
</TABLE>
</CENTER>
 Errors:
	Returns NULL is pIter is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI void *PIDBIterator_current( PIDBIterator *pIter,
	const char **ppKey );

/*____________________________________________________________________________*\
 *
 Name:
	PIDBIterator_next

 Synopsis:
	int PIDBIterator_next( PIDBIterator *pIter )
	
 Description:
	Increments an iterator objects internal pointers to point at The
	next valid PIDB element.

 Notes:
	The results are undefined if the iterator does not point at a valid
	element. The function PIDBIterator_atValidElement should be used
	at PIIterator_next and before PIDBIterator_next to verify that the
	iterator points at a valid PIDB element.

 Return Values:
	On success PIDBIterator_next() returns zero (PIAPI_COMPLETED).
 
 Errors:
	PIAPI_EINVAL		if pIter is NULL

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDBIterator_next( PIDBIterator *pIter );

/*____________________________________________________________________________*\
 *
 Name:
	PIDBIterator_removeCurrent

 Synopsis:
	int PIDBIterator_removeCurrent( PIDBIterator *pIter )
	
 Description:
	Remove and destroy the current element of the iterator pIter.

 Notes:
 Return Values:
	On success PIDBIterator_removeCurrent() returns zero (PIAPI_COMPLETED).
 
 Errors:
	PIAPI_EINVAL		if pIter is NULL

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDBIterator_removeCurrent( PIDBIterator *pIter );

/*____________________________________________________________________________*\
 *
 Name:
	PIDBIterator_delete

 Synopsis:
	int PIDBIterator_delete( PIDBIterator *pIter )
	
 Description:
	Destroys the iterator object and frees any associated memory.

 Notes:
 Return Values:
	On success PIDBIterator_delete() returns zero (PIAPI_COMPLETED).
 
 Errors:
	PIAPI_EINVAL		if pIter is NULL

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIDBIterator_delete( PIDBIterator *pIter );

/*____________________________________________________________________________*\
 *
 Name:
	PIUserType_getValue

 Synopsis:
	void *PIUserType_getValue( PIUserType *pUserType )
	
 Description:
	Returns the value associated with a PIUserType data structure.

 Notes:
 Return Values:
	On success PIUserType_getValue returns the value associated with
	the PIUserType data structure. Returns NULL if pUserType is not
	valid.
 
 Errors:
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI void *PIUserType_getValue( PIUserType *pUserType );

#endif	/* PIDB_H_ */