home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIObject.h < prev    next >
C/C++ Source or Header  |  1997-10-19  |  12KB  |  437 lines
  1. /*____________________________________________________________________________*\
  2.  *
  3.  
  4.  Copyright (c) 1997 John Roy. All rights reserved.
  5.  
  6.  These sources, libraries and applications are
  7.  FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
  8.  as long as the following conditions are adhered to.
  9.  
  10.  Redistribution and use in source and binary forms, with or without
  11.  modification, are permitted provided that the following conditions
  12.  are met:
  13.  
  14.  1. Redistributions of source code must retain the above copyright
  15.     notice, this list of conditions and the following disclaimer. 
  16.  
  17.  2. Redistributions in binary form must reproduce the above copyright
  18.     notice, this list of conditions and the following disclaimer in
  19.     the documentation and/or other materials provided with the
  20.     distribution.
  21.  
  22.  3. Redistributions of any form whatsoever and all advertising materials 
  23.     mentioning features must contain the following
  24.     acknowledgment:
  25.     "This product includes software developed by John Roy
  26.     (http://www.johnroy.com/pi3/)."
  27.  
  28.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  29.  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30.  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  31.  IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  32.  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33.  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34.  GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35.  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36.  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37.  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  38.  OF THE POSSIBILITY OF SUCH DAMAGE.
  39.  
  40.  *____________________________________________________________________________*|
  41.  *
  42.  * $Source: PIObject.h$
  43.  * $Date: Sun Aug 10 06:42:19 1997$
  44.  *
  45.  Description:
  46.     Definition of generic interface to objects.
  47. \*____________________________________________________________________________*/
  48. /* $HeaderTop:$ */
  49.  
  50. #ifndef PIOBJECT_H_
  51. #define PIOBJECT_H_
  52.  
  53. #include "PIClass.h"
  54. #include "PIDB.h"
  55.  
  56. /*____________________________________________________________________________*\
  57.  *
  58. Typedefs and function prototypes
  59. \*____________________________________________________________________________*/
  60. typedef struct _PIObject PIObject;
  61.  
  62. /*____________________________________________________________________________*\
  63.  *
  64.  Name:
  65.     PIObject_load
  66.  
  67.  Synopsis:
  68.     PIObject *PIObject_load( PIDB *pDB, PIConfig *pConfig,
  69.         const char *pName, int iArgc, const char *ppArgv[] )
  70.     
  71.  Description:
  72.     Create an instance of an object from a class reference and the 
  73.     parsed configuration tree pConfigDB.
  74.  
  75.     If pConfigDB is NULL then the DB tree hierarchy will be searched
  76.     upwards from pDB to find a tree whose key is PIDBKEY_CONFIGURATION.
  77.  
  78.     If the class of the object is not known the function
  79.     PIClass_lookupOrLoad() will be invoked to attempt to load the class.
  80.  
  81.     The constructor function of the object's classes is invoked on the
  82.     new object with the arguments iArgc and ppArgv before it is returned
  83.     from this function.
  84.  
  85.  Notes:
  86.     The configuration file reference to an object is of the form
  87.         <Object>
  88.         Name=<object name>
  89.         Class=<class name>
  90.         ...
  91.         ...
  92.         </Object>
  93.  
  94.  Return Values:
  95.     Returns a pointer to the new object, or NULL if an error occurred.
  96.  
  97.  Errors:
  98.  See Also:
  99. \*____________________________________________________________________________*/
  100. PUBLIC_PIAPI PIObject *PIObject_load( PIDB *pDB, PIConfig *pConfig,
  101.     const char *pName, int iArgc, const char *ppArgv[] );
  102.  
  103. /*____________________________________________________________________________*\
  104.  *
  105.  Name:
  106.     PIObject_loadFromLine
  107.  
  108.  Synopsis:
  109.     PIObject *PIObject_loadFromLine( PIDB *pDB, PIConfig *pConfig,
  110.         const char *pObjectLine )
  111.     
  112.  Description:
  113.     This function is not yet documented.
  114.  
  115.  Notes:
  116.  Return Values:
  117.  Errors:
  118.  See Also:
  119. \*____________________________________________________________________________*/
  120. PUBLIC_PIAPI PIObject *PIObject_loadFromLine( PIDB *pDB, PIConfig *pConfig,
  121.     const char *pObjectLine );
  122.  
  123. /*____________________________________________________________________________*\
  124.  *
  125.  Name:
  126.     PIObject_loadEx
  127.  
  128.  Synopsis:
  129.     PIObject *PIObject_loadEx( const PIObject *pParent, const char *pObjectKey)
  130.     
  131.  Description:
  132.     This function is not yet documented.
  133.  
  134.  Notes:
  135.  Return Values:
  136.  Errors:
  137.  See Also:
  138. \*____________________________________________________________________________*/
  139. PUBLIC_PIAPI PIObject *PIObject_loadEx( const PIObject *pParent,
  140.     const char *pObjectKey );
  141.  
  142. /*____________________________________________________________________________*\
  143.  *
  144.  Name:
  145.     PIObject_readParameters
  146.  
  147.  Synopsis:
  148.     int PIObject_readParameters(
  149.         PIObject *pParent,
  150.         int iArgc,
  151.         const char *ppArgv[],
  152.         int (* fnParameter)( const char *, const char *, const char * ),
  153.         void *pParam
  154.         )
  155.     
  156.  Description:
  157.     This function is not yet documented.
  158.  
  159.  Notes:
  160.  Return Values:
  161.     Returns non-zero on success, zero on failure.
  162.  Errors:
  163.  See Also:
  164. \*____________________________________________________________________________*/
  165. PUBLIC_PIAPI int PIObject_readParameters(
  166.     PIObject *pParent,
  167.     int iArgc,
  168.     const char *ppArgv[],
  169.     int (* fnParameters)( void *, const char *, const char *, const char *),
  170.     void *pParam
  171.     );
  172.  
  173. /*____________________________________________________________________________*\
  174.  *
  175.  Name:
  176.     PIObject_copy
  177.  
  178.  Synopsis:
  179.     PIObject *PIObject_copy( PIObject *pObject, int iArgc,
  180.         const char *ppArgv[] )
  181.     
  182.  Description:
  183.     Make an exact copy of an object.
  184.  
  185.     The new objects constructor function will be invoked with the
  186.     arguments iArgc and ppArgv.
  187.  
  188.  Notes:
  189.  Return Values:
  190.     Returns a pointer to the new object, or NULL if an error occurred.
  191.  
  192.  Errors:
  193.     Returns NULL if pObject is NULL or memory could not be 
  194.     allocated for the copy operation.
  195.  
  196.  See Also:
  197. \*____________________________________________________________________________*/
  198. PUBLIC_PIAPI PIObject *PIObject_copy( const PIObject *pObject,
  199.     int iArgc, const char *ppArgv[] );
  200.  
  201. /*____________________________________________________________________________*\
  202.  *
  203.  Name:
  204.     PIObject_new
  205.  
  206.  Synopsis:
  207.     PIObject *PIObject_new( const PIClass *pClass, PIDB *pDB, PIConfig *pConfig,
  208.         const char *pName, int iArgc, const char *ppArgv[] )
  209.     
  210.  Description:
  211.     Create an instance of an object from a class directly without using a 
  212.     parsed configuration tree.
  213.  
  214.     The object will be created with class pClass, DB pDB, ConfigDB pConfig,
  215.     and name pName.
  216.  
  217.     The object's constructor function will be invoked with the parameters
  218.     iArgc and ppArgv.
  219.  
  220.  Notes:
  221.  Return Values:
  222.     Returns a pointer to the new object, or NULL if an error occurred.
  223.  
  224.  Errors:
  225.  See Also:
  226. \*____________________________________________________________________________*/
  227. PUBLIC_PIAPI PIObject *PIObject_new( const PIClass *pClass, PIDB *pDB,
  228.     PIConfig *pConfig, const char *pName, int iArgc, const char *ppArgv[] );
  229.  
  230. /*____________________________________________________________________________*\
  231.  *
  232.  Name:
  233.     PIObject_getName
  234.  
  235.  Synopsis:
  236.     const char *PIObject_getName( const PIObject *pObj )
  237.     
  238.  Description:
  239.     Returns an objects name.
  240.  
  241.  Notes:
  242.  Return Values:
  243.     Returns the object's name.
  244.  
  245.  Errors:
  246.     Returns NULL is pObj is NULL.
  247.  See Also:
  248. \*____________________________________________________________________________*/
  249. PUBLIC_PIAPI const char *PIObject_getName( const PIObject *pObj );
  250.  
  251. /*____________________________________________________________________________*\
  252.  *
  253.  Name:
  254.     PIObject_getDB
  255.  
  256.  Synopsis:
  257.     PIDB *PIObject_getDB( const PIObject *pObj )
  258.     
  259.  Description:
  260.     Returns the DB associated with this object.
  261.  
  262.  Notes:
  263.  Return Values:
  264.     Returns the DB associcated with this object.
  265.  
  266.  Errors:
  267.  See Also:
  268. \*____________________________________________________________________________*/
  269. PUBLIC_PIAPI PIDB *PIObject_getDB( const PIObject *pObj );
  270.  
  271. /*____________________________________________________________________________*\
  272.  *
  273.  Name:
  274.     PIObject_setDB
  275.  
  276.  Synopsis:
  277.     int PIObject_setDB( PIObject *pObj, PIDB *pDB )
  278.     
  279.  Description:
  280.     Sets the DB associated with this object.
  281.  
  282.  Notes:
  283.  Return Values:
  284.     PIObject_setDB() returns zero (PIAPI_COMPLETED) on success.
  285.  
  286.  Errors:
  287.     PIAPI_EINVAL is pObj is NULL.
  288.  
  289.  See Also:
  290. \*____________________________________________________________________________*/
  291. PUBLIC_PIAPI int PIObject_setDB( PIObject *pObj, PIDB *pDB );
  292.  
  293. /*____________________________________________________________________________*\
  294.  *
  295.  Name:
  296.     PIObject_getConfigurationDB
  297.  
  298.  Synopsis:
  299.     PIConfig *PIObject_getConfigurationDB( const PIObject *pObj )
  300.     
  301.  Description:
  302.     Returns the configuration DB associated with an object.
  303.  
  304.  Notes:
  305.  Return Values:
  306.     Returns the configuration DB associated with this object.
  307.  
  308.  Errors:
  309.     Returns NULL is pObj is NULL.
  310.  
  311.  See Also:
  312. \*____________________________________________________________________________*/
  313. PUBLIC_PIAPI PIConfig *PIObject_getConfigurationDB( const PIObject *pObj );
  314.  
  315. /*____________________________________________________________________________*\
  316.  *
  317.  Name:
  318.     PIObject_setConfigurationDB
  319.  
  320.  Synopsis:
  321.     int PIObject_setConfigurationDB( PIObject *pObj, PIConfig *pConfig )
  322.     
  323.  Description:
  324.     Sets the configuration DB of the associated object.
  325.  
  326.  Notes:
  327.  Return Values:
  328.     On success PIObject_setConfigurationDB() returns zero (PIAPI_COMPLETED).
  329.  
  330.  Errors:
  331.     If either of pObj or pConfig are NULL, PIObject_setConfigurationDB()
  332.     returns PIAPI_EINVAL.
  333.  
  334.  See Also:
  335. \*____________________________________________________________________________*/
  336. PUBLIC_PIAPI int PIObject_setConfigurationDB( PIObject *pObj,
  337.     PIConfig *pConfig );
  338.  
  339. /*____________________________________________________________________________*\
  340.  *
  341.  Name:
  342.     PIObject_getClass
  343.  
  344.  Synopsis:
  345.     const PIClass *PIObject_getClass( const PIObject *pObj )
  346.     
  347.  Description:
  348.     Returns a reference to the class object of this object.
  349.  
  350.  Notes:
  351.  Return Values:
  352.     Returns a reference to the class object of this object.
  353.  
  354.  Errors:
  355.     Returns NULL is pObj is NULL.
  356.  
  357.  See Also:
  358. \*____________________________________________________________________________*/
  359. PUBLIC_PIAPI const PIClass *PIObject_getClass( const PIObject *pObj );
  360.  
  361. /*____________________________________________________________________________*\
  362.  *
  363.  Name:
  364.     PIObject_getUserData
  365.  
  366.  Synopsis:
  367.     void *PIObject_getUserData( const PIObject *pObj )
  368.     
  369.  Description:
  370.     Return the value previously set for this object by PIObject_setUserData().
  371.  
  372.  Notes:
  373.     The user data field is NULL initialized when the object instance is
  374.     created.
  375.  
  376.  Return Values:
  377.     Returns user defined value for this object.
  378.  
  379.  Errors:
  380.     Returns NULL is pObj is NULL.
  381.  
  382.  See Also:
  383. \*____________________________________________________________________________*/
  384. PUBLIC_PIAPI void *PIObject_getUserData( const PIObject *pObj );
  385.  
  386. /*____________________________________________________________________________*\
  387.  *
  388.  Name:
  389.     PIObject_setUserData
  390.  
  391.  Synopsis:
  392.     int PIObject_setUserData( PIObject *pObj, void *pNewValue )
  393.     
  394.  Description:
  395.     Sets the user data field in the object to pNewValue. This value
  396.     can be retrieved later with a call to PIObject_getUserData().
  397.  
  398.  Notes:
  399.  Return Values:
  400.     On success PIObject_setUserData() returns zero (PIAPI_COMPLETED).
  401.  
  402.  Errors:
  403.     If pObj is NULL PIObject_setUserData() returns PIAPI_EINVAL.
  404.  
  405.  See Also:
  406. \*____________________________________________________________________________*/
  407. PUBLIC_PIAPI int PIObject_setUserData( PIObject *pObj, void *pData );
  408.  
  409. /*____________________________________________________________________________*\
  410.  *
  411.  Name:
  412.     PIObject_delete
  413.  
  414.  Synopsis:
  415.     int PIObject_delete( PIObject *pObj, int iArgc, const char *ppArgv[] )
  416.     
  417.  Description:
  418.     Destroy and free memory associated with the object pObj.
  419.  
  420.     The objects destructor function will be passed the parameters
  421.     iArgc and ppArgv.
  422.  
  423.  Notes:
  424.  Return Values:
  425.      On success PIObject_delete() returns zero (PIAPI_COMPLETED).
  426.  
  427.  Errors:
  428.     PIAPI_EINVAL is returned if pObj is NULL.
  429.  
  430.  See Also:
  431. \*____________________________________________________________________________*/
  432. PUBLIC_PIAPI int PIObject_delete( PIObject *pObj, int iArgc,
  433.     const char *ppArgv[] );
  434.  
  435. #endif    /* PIOBJECT_H_ */
  436.  
  437.