piobject.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/PIObject.h,v $
 * $Date: 2003/05/13 18:42:09 $
 *
 Description:
	Definition of generic interface to objects.
\*____________________________________________________________________________*/
/* $HeaderTop:$ */

#ifndef PIOBJECT_H_
#define PIOBJECT_H_

#include "PIClass.h"
#include "PIDB.h"

/*____________________________________________________________________________*\
 *
Typedefs and function prototypes
\*____________________________________________________________________________*/
typedef struct _PIObject PIObject;

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_load

 Synopsis:
	PIObject *PIObject_load( PIDB *pDB, PIConfig *pConfig,
		const char *pName, int iArgc, const char *ppArgv[] )
	
 Description:
	Create an instance of an object from a class reference and the 
	parsed configuration tree <B>pConfigDB</B>.

	If <B>pConfigDB</B> is NULL then the DB tree hierarchy will be searched
	upwards from pDB to find a tree whose key is PIDBKEY_CONFIGURATION.

	If the class of the object is not known the function
	PIClass_lookupOrLoad() will be invoked to attempt to load the class.

	The constructor function of the object's classes is invoked on the
	new object with the arguments iArgc and ppArgv before it is returned
	from this function.

 Notes:
	The configuration file reference to an object is of the form
	<pre>
		&lt;Object&gt;
		Name=[object name]
		Class=[class name]
		...
		...
		&lt;/Object&gt;
	</pre>

 Return Values:
	Returns a pointer to the new object, or NULL if an error occurred.

 Errors:
 See Also:
	PIObject_loadEx, PIObject_loadFromLine
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIObject *PIObject_load( PIDB *pDB, PIConfig *pConfig,
	const char *pName, int iArgc, const char *ppArgv[] );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_loadFromLine

 Synopsis:
	PIObject *PIObject_loadFromLine( PIDB *pDB, PIConfig *pConfig,
		const char *pObjectLine )
	
 Description:
	Create an instance of an object from a class reference and the 
	parsed configuration tree <B>pConfigDB</B> and the given object
	line.

	The parameter <B>pObjectLine</B> is tokenized and the result is handed
	over to PIObject_load to construct the object finally.

 Notes:
	The string <B>pObjectLine</B> contains the object name in the leading
	position and the constructor arguments all separated by whitespaces.

 Return Values:
	Returns a pointer to the new object, or NULL if an error occurred.

 Errors:
 See Also:
	PIObject_load, PIObject_loadEx
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIObject *PIObject_loadFromLine( PIDB *pDB, PIConfig *pConfig,
	const char *pObjectLine );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_loadEx

 Synopsis:
	PIObject *PIObject_loadEx( const PIObject *pParent, const char *pObjectKey)
	
 Description:
	Create an instance of an object from a parent object reference.

	The configuration tree of the parent will be used to lookup the
	object line by the given object key.

	PIObject_loadFromLine will be used to load the object.

 Notes:
 Return Values:
	Returns a pointer to the new object, or NULL if an error occurred.
 Errors:
 See Also:
	PIObject_load, PIObject_loadFromLine
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIObject *PIObject_loadEx( const PIObject *pParent,
	const char *pObjectKey );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_readParameters

 Synopsis:
	int PIObject_readParameters(
		PIObject *pParent,
		int iArgc,
		const char *ppArgv[],
		int (* fnParameters)( void *, const char *, const char *, const char * ),
		void *pParam
		)
	
 Description:
	Read in the configuration parameters of an object during construction.

	This function will loop over all parameters passed in <B>ppArgv</B>,
	and hand over the pre-processed parameters together with <B>pParam</B>
	to the callback function fnParameters.

 Notes:
	The parameter line will be tokenized and de-quoted, i.e. the parameters are
	of the general form
	<pre>
		key1="value1"
		key2="value2"
		...
	</pre>
 Return Values:
	Returns non-zero on success, zero on failure.
 Errors:
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIObject_readParameters(
	PIObject *pParent,
	int iArgc,
	const char *ppArgv[],
	int (* fnParameters)( void *, const char *, const char *, const char *),
	void *pParam
	);

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_copy

 Synopsis:
	PIObject *PIObject_copy( PIObject *pObject, int iArgc,
		const char *ppArgv[] )
	
 Description:
	Make an exact copy of an object.

	The new objects constructor function will be invoked with the
	arguments iArgc and ppArgv.

 Notes:
 Return Values:
	Returns a pointer to the new object, or NULL if an error occurred.

 Errors:
	Returns NULL if pObject is NULL or memory could not be 
	allocated for the copy operation.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIObject *PIObject_copy( const PIObject *pObject,
	int iArgc, const char *ppArgv[] );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_new

 Synopsis:
	PIObject *PIObject_new( const PIClass *pClass, PIDB *pDB, PIConfig *pConfig,
		const char *pName, int iArgc, const char *ppArgv[] )
	
 Description:
	Create an instance of an object from a class directly without using a 
	parsed configuration tree.

	The object will be created with class pClass, DB pDB, ConfigDB pConfig,
	and name pName.

	The object's constructor function will be invoked with the parameters
	iArgc and ppArgv.

 Notes:
 Return Values:
	Returns a pointer to the new object, or NULL if an error occurred.

 Errors:
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIObject *PIObject_new( const PIClass *pClass, PIDB *pDB,
	PIConfig *pConfig, const char *pName, int iArgc, const char *ppArgv[] );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_getName

 Synopsis:
	const char *PIObject_getName( const PIObject *pObj )
	
 Description:
	Returns an objects name.

 Notes:
 Return Values:
	Returns the object's name.

 Errors:
	Returns NULL is pObj is NULL.
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI const char *PIObject_getName( const PIObject *pObj );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_getDB

 Synopsis:
	PIDB *PIObject_getDB( const PIObject *pObj )
	
 Description:
	Returns the DB associated with this object.

 Notes:
 Return Values:
	Returns the DB associcated with this object.

 Errors:
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIDB *PIObject_getDB( const PIObject *pObj );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_setDB

 Synopsis:
	int PIObject_setDB( PIObject *pObj, PIDB *pDB )
	
 Description:
	Sets the DB associated with this object.

 Notes:
 Return Values:
	PIObject_setDB() returns zero (PIAPI_COMPLETED) on success.

 Errors:
	PIAPI_EINVAL is pObj is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIObject_setDB( PIObject *pObj, PIDB *pDB );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_getConfigurationDB

 Synopsis:
	PIConfig *PIObject_getConfigurationDB( const PIObject *pObj )
	
 Description:
	Returns the configuration DB associated with an object.

 Notes:
 Return Values:
	Returns the configuration DB associated with this object.

 Errors:
	Returns NULL is pObj is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIConfig *PIObject_getConfigurationDB( const PIObject *pObj );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_setConfigurationDB

 Synopsis:
	int PIObject_setConfigurationDB( PIObject *pObj, PIConfig *pConfig )
	
 Description:
	Sets the configuration DB of the associated object.

 Notes:
 Return Values:
	On success PIObject_setConfigurationDB() returns zero (PIAPI_COMPLETED).

 Errors:
	If either of pObj or pConfig are NULL, PIObject_setConfigurationDB()
	returns PIAPI_EINVAL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIObject_setConfigurationDB( PIObject *pObj,
	PIConfig *pConfig );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_getClass

 Synopsis:
	const PIClass *PIObject_getClass( const PIObject *pObj )
	
 Description:
	Returns a reference to the class object of this object.

 Notes:
 Return Values:
	Returns a reference to the class object of this object.

 Errors:
	Returns NULL is pObj is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI const PIClass *PIObject_getClass( const PIObject *pObj );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_getUserData

 Synopsis:
	void *PIObject_getUserData( const PIObject *pObj )
	
 Description:
	Return the value previously set for this object by PIObject_setUserData().

 Notes:
	The user data field is NULL initialized when the object instance is
	created.

 Return Values:
	Returns user defined value for this object.

 Errors:
	Returns NULL is pObj is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI void *PIObject_getUserData( const PIObject *pObj );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_setUserData

 Synopsis:
	int PIObject_setUserData( PIObject *pObj, void *pNewValue )
	
 Description:
	Sets the user data field in the object to pNewValue. This value
	can be retrieved later with a call to PIObject_getUserData().

 Notes:
 Return Values:
	On success PIObject_setUserData() returns zero (PIAPI_COMPLETED).

 Errors:
	If pObj is NULL PIObject_setUserData() returns PIAPI_EINVAL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIObject_setUserData( PIObject *pObj, void *pData );

/*____________________________________________________________________________*\
 *
 Name:
	PIObject_delete

 Synopsis:
	int PIObject_delete( PIObject *pObj, int iArgc, const char *ppArgv[] )
	
 Description:
	Destroy and free memory associated with the object pObj.

	The objects destructor function will be passed the parameters
	iArgc and ppArgv.

 Notes:
 Return Values:
 	On success PIObject_delete() returns zero (PIAPI_COMPLETED).

 Errors:
	PIAPI_EINVAL is returned if pObj is NULL.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIObject_delete( PIObject *pObj, int iArgc,
	const char *ppArgv[] );

#endif	/* PIOBJECT_H_ */