home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIConfig.h < prev    next >
C/C++ Source or Header  |  1997-10-19  |  8KB  |  254 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: PIConfig.h$
  43.  * $Date: Sun Aug 10 06:42:17 1997$
  44.  *
  45.  Description:
  46.     Definition of interface to configuration files and parsed 
  47.     configuration trees.
  48. \*____________________________________________________________________________*/
  49. /* $HeaderTop:$ */
  50.  
  51. #ifndef PICONFIG_H_
  52. #define PICONFIG_H_
  53.  
  54. #include "PIDB.h"
  55.  
  56. /*____________________________________________________________________________*\
  57.  *
  58.  Decription:
  59.     Definitions and function prototypes for the program database.
  60. \*____________________________________________________________________________*/
  61. typedef struct PIConfigDBString PIConfigString;
  62. typedef struct PIConfigDB PIConfig;
  63.  
  64. /*____________________________________________________________________________*\
  65.  *
  66.  Name:
  67.     PIConfig_loadConfigurationFile
  68.  
  69.  Synopsis:
  70.     int PIConfig_loadConfigurationFile( PIDB *pDB, const char *pFileName,
  71.         PIConfig **ppConfigDB )
  72.     
  73.  Description:
  74.     Parse the configuration file pFileName and place the parsed     
  75.     contents in a new DB tree under the specified tree pDB, with the key
  76.     PIDBKEY_CONFIGURATION.
  77.  
  78.     If ppConfigDB is non-NULL and a configuration tree is created
  79.     the pointer to the new configuration tree will be placed in ppConfigDB.
  80.  
  81.  Notes:
  82.     In all cases where pDB and pFileName are non-NULL a new child DB tree
  83.     with the key PIDBKEY_CONFIGURATION will be added under the tree pDB.
  84.     
  85.  Return Values:
  86.     On complete success PIConfig_loadConfigurationFile() will return zero
  87.     (PIAPI_COMPLETED). Other errors may be returned as described below.
  88.  
  89.  Errors:
  90.     PIAPI_EINVAL    if pDB or pFileName is NULL.
  91.     PIAPI_ERROR        if an error occurred while parsing the configuration file.
  92.     [PIAPI_WARNING]    this error code may be returned if a warning was generated
  93.                         while parsing the configuraton file. Currently 
  94.                         PIAPI_COMPLETED will be returned when a configuration
  95.                         file is loaded with only warnings.
  96.  See Also:
  97. \*____________________________________________________________________________*/
  98. PUBLIC_PIAPI int PIConfig_loadConfigurationFile( PIDB *pDB,
  99.     const char *pFileName, PIConfig **ppConfigDB );
  100.  
  101. /*____________________________________________________________________________*\
  102.  *
  103.  Name:
  104.     PIConfig_findConfiguration
  105.  
  106.  Synopsis:
  107.     PIConfig *PIConfig_findConfiguration( PIDB *pDB )
  108.     
  109.  Description:
  110.     Search under the PIDB tree node pDB for another tree with the key
  111.     PIDBKEY_CONFIGURATION.
  112.  
  113.     The tree hierarchy is search recusively upwards from the node pDB 
  114.     until the configuration tree is found or the root node is reached
  115.     with no match.
  116.  
  117.  Notes:
  118.     This function is implemented as
  119.         
  120.         PIConfig *PIDB_Lookup( pDB, <internal type>, PIDBKEY_CONFIGURATION,
  121.             PIDBFLAG_PROPAGATEUP )
  122.         
  123.  Return Values:
  124.     Returns a pointer to the configuration tree or NULL if it was not
  125.     found.
  126.  
  127.  Errors:
  128.     Returns NULL is pDB is NULL.
  129.  
  130.  See Also:
  131. \*____________________________________________________________________________*/
  132. PUBLIC_PIAPI PIConfig *PIConfig_findConfiguration( PIDB *pDB );
  133.  
  134. /*____________________________________________________________________________*\
  135.  *
  136.  Name:
  137.     PIConfig_lookupValue
  138.  
  139.  Synopsis:
  140.     const char *PIConfig_lookupValue( PIConfig *pConfig, const char *pKey,
  141.         char *pInfoBuffer, int iLen )
  142.     
  143.  Description:
  144.     Lookup a value within the specified configuration tree.
  145.  
  146.     If the value is found and pInfoBuffer is non-NULL a description of the
  147.     location where the value was defined will be written into it, up to iLen
  148.     characters. 
  149.  
  150.  Notes:
  151.     A configuration file definition line is of the form
  152.  
  153.         Key=<value> <addition values>
  154.  
  155.     The exact format of the description placed in pInfoBuffer is subject to
  156.     change but may include the following information:-
  157.     
  158.         <UL>
  159.         <LI>The filename from which the value was read.
  160.         <LI>The line number within the file where the value was found.
  161.         </UL>
  162.  
  163.     If multiple definitions for a key are found within pConfig then the first
  164.     will be returned.
  165.  
  166.  Return Values:
  167.     Returns a pointer to the value for the key pKey under the configuration
  168.     tree. PIConfig_lookupValue() returns NULL if no match is found.
  169.  
  170.  Errors:
  171.     Returns NULL if pConfig is NULL.
  172.  
  173.  See Also:
  174. \*____________________________________________________________________________*/
  175. PUBLIC_PIAPI const char *PIConfig_lookupValue( PIConfig *pConfig,
  176.     const char *pKey, char *pInfoBuffer, int iLen );
  177.  
  178. /*____________________________________________________________________________*\
  179.  *
  180.  Name:
  181.     PIConfig_lookupTree
  182.  
  183.  Synopsis:
  184.     PIConfig *PIConfig_lookupTree( PIConfig *pConfig, const char *pKey,
  185.         char *pInfoBuffer, int iLen )
  186.     
  187.  Description:
  188.     Lookup the configuration tree with the key pKey in pConfig.
  189.  
  190.     If the definition is found and pInfoBuffer is non-NULL a description of the
  191.     location where the tree was defined will be written into it, up to iLen
  192.     characters. 
  193.  
  194.  Notes:
  195.     A configuration file tree is of the following form
  196.  
  197.         <Key>
  198.             ...
  199.             ...
  200.         </Key>
  201.  
  202.     The exact format of the description placed in pInfoBuffer is subject to
  203.     change but may include the following information:-
  204.     
  205.         - The filename from which the value was read.
  206.         - The line number within the file where the value was found.
  207.         - The character position within the line where the key definition was
  208.             found. For configuration files with
  209.             content-type x-pi-internal/x-scl1.0 (.conf or .scl) this will
  210.             be the length of the line.
  211.  
  212.     If multiple defintions for a key are found within pConfig
  213.     then the first will be returned.
  214.  
  215.  Return Values:
  216.     Returns a PIConfig structure. The functions PIConfig_lookupValue()
  217.     and PIConfig_lookupTree() can be used to find definitions and trees
  218.     within this tree.
  219.  
  220.  Errors:
  221.     Returns NULL if a tree with the specified key was not found within
  222.     this key.
  223.  
  224.  See Also:
  225. \*____________________________________________________________________________*/
  226. PUBLIC_PIAPI PIConfig *PIConfig_lookupTree( PIConfig *pConfig,
  227.     const char *pKey, char *pInfoBuffer, int iLen );
  228.  
  229. /*____________________________________________________________________________*\
  230.  *
  231.  Name:
  232.     PIConfigString_getString
  233.  
  234.  Synopsis:
  235.     const char *PIConfigString_getString( PIConfigString *pString )
  236.     
  237.  Description:
  238.     Returns the string value of a given PIConfigString data structure.
  239.  
  240.  Notes:
  241.  Return Values:
  242.     Returns a pointer to the string of the given PIConfigString data
  243.     structure. 
  244.  
  245.  Errors:
  246.     On error PIConfigString_getString() returns NULL.
  247.  
  248.  See Also:
  249. \*____________________________________________________________________________*/
  250. PUBLIC_PIAPI const char *PIConfigString_getString( PIConfigString *pString );
  251.  
  252. #endif    /* PICONFIG_H_ */
  253.  
  254.