home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIDB.H < prev    next >
C/C++ Source or Header  |  1997-10-19  |  22KB  |  698 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: PIDB.h$
  43.  * $Date: Sun Aug 10 06:42:18 1997$
  44.  *
  45.  Description:
  46.     Definition of interface to program database class.
  47. \*____________________________________________________________________________*/
  48. /* $HeaderTop:$ */
  49.  
  50. #ifndef PIDB_H_
  51. #define PIDB_H_
  52.  
  53. /*____________________________________________________________________________*\
  54.  *
  55.  Decription:
  56.     Definitions and function prototypes for the program database.
  57. \*____________________________________________________________________________*/
  58. typedef struct _PIDB PIDB;
  59. typedef struct _PIDBIterator PIDBIterator;
  60. typedef struct UserDBType PIUserType;
  61.  
  62. /* ---
  63. These are the builtin types defined in every DB tree.
  64. --- */
  65. #define PIDBTYPE_INVALID                -1
  66. #define PIDBTYPE_TREE                    0
  67. #define PIDBTYPE_STRING                    1
  68. #define PIDBTYPE_RFC822                    2
  69. #define PIDBTYPE_OPAQUE                    3
  70. #define PIDBTYPE_USER                    4
  71.  
  72. /* --- this should always be the value of the last builtin type --- */
  73. #define PIDBTYPE_LAST                    4    
  74.  
  75. #define PIDBTYPE_BUILTINSIZE            (PIDBTYPE_LAST+1)
  76.  
  77. /* --- Flags --- */
  78. #define PIDBFLAG_NONE                    0x0000
  79. #define PIDBFLAG_PROPAGATEUP            0x0001
  80. #define PIDBFLAG_NOCALLBACK                0x0002
  81. #define PIDBFLAG_FASTKEY                0x0004
  82.  
  83. /* --- text encoding of DB types and flags, for persistence --- */
  84. #define PIDBTYPE_TEXT_TREE                "TREE"
  85. #define PIDBTYPE_TEXT_STRING            "STRING"
  86. #define PIDBTYPE_TEXT_RFC822            "RFC822"
  87. #define PIDBTYPE_TEXT_OPAQUE            "OPAQUE"
  88. #define PIDBTYPE_TEXT_USER                "USER"
  89.  
  90. #define PIDBFLAG_TEXT_PROPAGATEUP        "PROPAGATEUP"
  91. #define PIDBFLAG_TEXT_NOCALLBACK        "NOCALLBACK"
  92. #define PIDBFLAG_TEXT_FASTKEY            "FASTKEY"
  93.  
  94. /*____________________________________________________________________________*\
  95.  *
  96.  Name:
  97.     PIDB_new
  98.  
  99.  Synopsis:
  100.     PIDB *PIDB_new( PIDB *pParent, const char *pName )
  101.     
  102.  Description:
  103.     Creates a new PIDB tree under the specified parent node with the 
  104.     specified name. If pParent is NULL, then the generated node will
  105.     be the root of a new PIDB tree hierarchy.
  106.  
  107.     If a new child tree is successfully generated it is automatically 
  108.     added into the parent tree's list of child nodes with a type of
  109.     PIDBTYPE_TREE and a key of pName.
  110.  
  111.     If pParent is NULL then a new root tree node is generated. This tree
  112.     should be free'd with PIDB_delete() when it is no longer needed.
  113.  
  114.  Notes:
  115.     If memory cannot be allocated for the new tree, a special handler
  116.     will be invoked in a method specific to the build and configuration
  117.     of the server library. For more information see the specific notes
  118.     for the library release.
  119.  
  120.  Return Values:
  121.     Returns a pointer to the new child PIDB tree, or NULL if insufficent
  122.     memory was available.
  123.  
  124.  Errors:
  125.  See Also:
  126. \*____________________________________________________________________________*/
  127. PUBLIC_PIAPI PIDB *PIDB_new( PIDB *pParent, const char *pName );
  128.  
  129. /*____________________________________________________________________________*\
  130.  *
  131.  Name:
  132.     PIDBEx_new
  133.  
  134.  Synopsis:
  135.     PIDB *PIDBEx_new( PIDB *pParent, const char *pName,
  136.         void *(* fnLookup)( PIDB *, int, const char *, int ) )
  137.     
  138.  Description:
  139.     Creates a new PIDB of extended type PIDBEx. This tree supports a 
  140.     lookup callback where lookups on the tree will invoke the user 
  141.     supplied lookup function.
  142.  
  143.  Notes:
  144.     Use of this callback function on instances of this extended tree
  145.     type can be overriden by adding the PIDBFLAG_NOCALLBACK flag to the
  146.     flags passed to PIDB_lookup() or PIDB_getIterator().
  147.  
  148.  Return Values:
  149.     Returns a pointer to the new child PIDB tree on success.
  150.  
  151.  Errors:
  152.     Returns NULL if fnLookup is NULL.
  153.  
  154.  See Also:
  155. \*____________________________________________________________________________*/
  156. PUBLIC_PIAPI PIDB *PIDBEx_new( PIDB *pParent, const char *pName,
  157.         void *(* fnLookup)( PIDB *, int, const char *, int ) );
  158.  
  159. /*____________________________________________________________________________*\
  160.  *
  161.  Name:
  162.     PIDB_getParent
  163.  
  164.  Synopsis:
  165.     PIDB *PIDB_getParent( PIDB *pTree )
  166.     
  167.  Description:
  168.     Returns the parent tree of the specified PIDB tree.
  169.  
  170.  Notes:
  171.  Return Values:
  172.     Returns a pointer to the parent tree or NULL if the specified tree
  173.     is the top of the tree hierarchy.
  174.  
  175.  Errors:
  176.     NULL if pTree is NULL
  177.  
  178.  See Also:
  179. \*____________________________________________________________________________*/
  180. PUBLIC_PIAPI PIDB *PIDB_getParent( PIDB *pThis );
  181.  
  182. /*____________________________________________________________________________*\
  183.  *
  184.  Name:
  185.     PIDB_add
  186.  
  187.  Synopsis:
  188.     int PIDB_add( PIDB *pTree, int iType, const char *pKey, void *pValue,
  189.         int iFlags )
  190.     
  191.  Description:
  192.     Adds a child element into a PIDB tree. The action performed on the
  193.     opaque pointer pValue depends on the value of iType.
  194. <UL>
  195. <ITEM><B>PIDBTYPE_TREE</B><P>
  196.                 pValue must be a pointer to a valid PIDB tree. This tree
  197.             is in specified tree as a child node. Note that child trees are
  198.             automatically placed in thier parents tree when they are created,
  199.             explicitly adding them a second time may cause serious problems
  200.             when the tree is recursively free'd with PIDB_delete(). Use this
  201.             only to attach a child tree which was created with a NULL value
  202.             for parameter pParent in the call to PIDB_new().
  203.             
  204. <ITEM><B>PIDBTYPE_STRING</B><P>
  205.                 pValue must be a pointer to a null terminated character
  206.             array. A copy of the string is generated and stored in the 
  207.             current tree.
  208.  
  209. <ITEM><B>PIDBTYPE_RFC822</B><P>
  210.                 This type is created, maintained and used in the same
  211.             way as type PIDBTYPE_STRING. The important difference between
  212.             PIDBTYPE_STRING and PIDBTYPE_RFC822 is that PIDBTYPE_STRING is
  213.             in all repects case sensitive, whereas PIDBTYPE_RFC822 is in all
  214.             respects case in-sensitive.
  215.  
  216. <ITEM><B>PIDBTYPE_OPAQUE</B><P>
  217.                 pValue is stored in the tree as an unknown pointer. Note
  218.             that the user is responsible for free'ing memory allocated
  219.             at pValue, if any. This is different from other tree types 
  220.             where the object referenced by pValue will be cleaned up 
  221.             and memory free'd when the tree is destroyed.
  222.  
  223. <ITEM>PIDBTYPE_USER</B><P>
  224.                 This type requires that pValue is an object of a type
  225.             not specified in this interface. Pending this specification
  226.             this type is for internal use only.    
  227. </UL>
  228.     
  229.     The value iFlags is formed by OR'ing together the following values
  230. <P>
  231. <UL>
  232.  
  233. <ITEM><B>PIDBFLAG_FASTKEY</B><P>     The value pKey is assumed to be a symbol
  234.                             table entry so PIDB_add() skips the hashing
  235.                             and offset logic. This improves performance on 
  236.                             repeated DB actions at the cost of initial setup
  237.                             using PIDB_getFastKey().
  238. </UL>
  239.  
  240.  Notes:
  241.     The type PIDBTYPE_USER is under development and its behaviour
  242.     is subject to change.
  243.  
  244.  Return Values:
  245.     On success PIDB_add returns zero (PIAPI_COMPLETED). Otherwise
  246.     an error occured as described below.
  247.  
  248.  Errors:
  249.     PIAPI_EINVAL    An invalid value for iType was used or pTree was NULL
  250.     PIAPI_EXHAUSTED    Memory could not be allocated to complete the function.
  251.  
  252.  See Also:
  253. \*____________________________________________________________________________*/
  254. PUBLIC_PIAPI int PIDB_add( PIDB *pTree, int iType, const char *pKey, void *pV,
  255.         int iFlags );
  256.  
  257. /*____________________________________________________________________________*\
  258.  *
  259.  Name:
  260.     PIDB_replace
  261.  
  262.  Synopsis:
  263.     int PIDB_replace( PIDB *pTree, int iType, const char *pKey, void *pValue,
  264.         int iFlags )
  265.     
  266.  Description:
  267.     Replaces the first instance of the value corresponding to pKey in the
  268.     DB pTree. The new entry will be created even if a previous entry could
  269.     not be found. PIDB_add() describes the parameters iType and iFlags.
  270.     
  271.     Additionally iFlags may have the following flag set 
  272.         
  273.         PIDBFLAG_PROPAGATEUP    Search upwards from the current tree to
  274.                                 parent trees to find a match.
  275.  
  276.  Notes:
  277.  
  278.  Return Values:
  279.     On success PIDB_replace returns zero (PIAPI_COMPLETED). Otherwise
  280.     an error occured as described below.
  281.  
  282.  Errors:
  283.     PIAPI_EINVAL    An invalid value for iType was used or pTree was NULL
  284.     PIAPI_EXHAUSTED    Memory could not be allocated to complete the function.
  285.  
  286.  See Also:
  287. \*____________________________________________________________________________*/
  288. PUBLIC_PIAPI int PIDB_replace( PIDB *pTree, int iType, const char *pKey,
  289.         void *pV, int iFlags );
  290.  
  291. /*____________________________________________________________________________*\
  292.  *
  293.  Name:
  294.     PIDB_lookup
  295.  
  296.  Synopsis:
  297.     void *PIDB_lookup( PIDB *pTree, int iType, const char *pKey, int iFlags )
  298.     
  299.  Description:
  300.     Searches the PIDB tree for the first occurence of the an element which
  301.     matches the key. If pKey is NULL then the first element of the specified
  302.     type will be returned. See PIDB_getIterator() for the use of the parameter
  303.     iFlags.
  304.         
  305.  Notes:
  306.     This function cannot be used to distinguish between an unsuccessful
  307.     search and a successful search where the value of the matched element
  308.     is NULL. In these cases an PIDBIterator object should be used to
  309.     scan the tree, see PIDB_getIterator.
  310.  
  311.  Return Values:
  312.     On success the reference of the first element is returned. The type of 
  313.     the value depends on the specified value of iType. See PIDB_add for
  314.     a full description of possible types. See PIDBIterator_current for
  315.     a description of appropriate PIDBTYPE to C typecast mappings.
  316.     NULL is returned if no match was found.
  317.  
  318.  Errors:
  319.     If pTree is NULL or iType is out of range then PIDB_lookup() returns
  320.     NULL.
  321.  
  322.  See Also:
  323. \*____________________________________________________________________________*/
  324. PUBLIC_PIAPI void *PIDB_lookup( PIDB *pTree, int iType, const char *pKey,
  325.     int iFlags );
  326.  
  327. /*____________________________________________________________________________*\
  328.  *
  329.  Name:
  330.     PIDB_getFastKey
  331.  
  332.  Synopsis:
  333.     const char *PIDB_getFastKey( const char *pKey, int iType )
  334.     
  335.  Description:
  336.     Returns a pointer to a symbol table entry for the key pKey and
  337.     PIDB type iType. This symbol table entry then then be used in calls
  338.     to PIDB_lookup() and PIDB_getIterator() with the PIDBFLAG_FASTKEY to
  339.     avoid the overhead of hashing and symbol table lookup.
  340.         
  341.  Notes:
  342.     This function is useful where a key is used multiple times. The
  343.     fast key can be generated once and reused across all invocations
  344.     of PIDB_lookup() and PIDB_getIterator(). This significantly improves
  345.     performance.
  346.  
  347.  Return Values:
  348.     On success PIDB_getFastKey() returns a new key. Returns NULL on
  349.     failure.
  350.  
  351.  Errors:
  352.     Returns NULL if pKey is NULL or no memory space is available.
  353.  
  354.  See Also:
  355. \*____________________________________________________________________________*/
  356. PUBLIC_PIAPI const char *PIDB_getFastKey( const char *pKey, int iType );
  357.  
  358. /*____________________________________________________________________________*\
  359.  *
  360.  Name:
  361.     PIDB_pidbtypeNameToNumber
  362.  
  363.  Synopsis:
  364.     int PIDB_pidbtypeNameToNumber( const char *pType )
  365.     
  366.  Description:
  367.     Returns the integer value of the name pType, effectively mapping, the
  368.     string pType to return values as follows:-
  369. <CENTER>
  370. <TABLE BORDER=1>
  371. <TH>pType<TH>Return code
  372. <TR><TD>"TREE"<TD>PIDBTYPE_TREE
  373. <TR><TD>"STRING"<TD>PIDBTYPE_STRING
  374. <TR><TD>"RFC822"<TD>PIDBTYPE_RFC822
  375. <TR><TD>"OPAQUE"<TD>PIDBTYPE_OPAQUE
  376. <TR><TD>"USER"<TD>PIDBTYPE_USER
  377. </TABLE>
  378. </CENTER>
  379.     Comparision in not case sensitive.
  380.         
  381.  Notes:
  382.  Return Values:
  383.     If the string pType could not be matched PIDB_pidbtypeNameToNumber()
  384.     returns PIDBTYPE_INVALID.
  385.  
  386.  Errors:
  387.     On error PIDB_pidbtypeNameToNumber() returns PIDBTYPE_INVALID.
  388.  
  389.  See Also:
  390.     PIDB_pidbflagsNameToNumber()
  391. \*____________________________________________________________________________*/
  392. PUBLIC_PIAPI int PIDB_pidbtypeNameToNumber( const char *pType );
  393.  
  394. /*____________________________________________________________________________*\
  395.  *
  396.  Name:
  397.     PIDB_pidbflagsNameToNumber
  398.  
  399.  Synopsis:
  400.     int PIDB_pidbflagsNameToNumber( const char *pFlags )
  401.     
  402.  Description:
  403.     Returns the integer value of the flags represented by the string pFlags.
  404.     The string pFlags may contain many flags seperated by the pipe ('|')
  405.     character.
  406. <CENTER>
  407. <TABLE BORDER=1>
  408. <TH>pType<TH>Return code
  409. <TR><TD>"PROPAGATEUP"<TD>PIDBFLAG_TREE
  410. <TR><TD>"NOCALLBACK"<TD>PIDBFLAG_NOCALLBACK
  411. <TR><TD>"FASTKEY"<TD>PIDBFLAG_FASTKEY
  412. </TABLE>
  413. </CENTER>
  414.     Comparision in not case sensitive.
  415.         
  416.  Notes:
  417.     Whitespace in the string pFlags is allowed and will be ignored in 
  418.     matching the flags.
  419.  
  420.     The flags PIDBFLAG_NOCALLBACK and PIDBTYPE_FASTKEY have little use
  421.     in the context of persistence and are included only for
  422.     completeness.
  423.  
  424.  Return Values:
  425.     Returns the value formed by bitwise OR'ing the flags together. If
  426.     no flags are matched or the value pFlags is NULL,
  427.     PIDB_pidbflagsNameToNumber returns zero (PIDBFLAG_NONE).
  428.  
  429.  Errors:
  430.     This function does not generate an error. Unrecognised flags are
  431.     ignored.
  432.  
  433.  See Also:
  434.     PIDB_pidbtypeNameToNumber().
  435. \*____________________________________________________________________________*/
  436. PUBLIC_PIAPI int PIDB_pidbflagsNameToNumber( const char *pFlags );
  437.  
  438. /*____________________________________________________________________________*\
  439.  *
  440.  Name:
  441.     PIDB_getIterator
  442.  
  443.  Synopsis:
  444.     PIDBIterator *PIDB_getIterator( PIDB *pTree, int iType, const char *pKey,
  445.             int iFlags )
  446.     
  447.  Description:
  448.     Returns a pointer to an PIDBIterator object which to traverse the specified
  449.     tree for elements of type iType which match the key pKey. If pKey is
  450.     NULL all objects with type iType will be matched. The following flags
  451.     may be OR'ed together to form the value iFlags:
  452.  
  453.     PIDBFLAGS_PROPAGATEUP
  454.                 The current tree will first be searched and then the parent
  455.         tree. The recursively search all trees up the tree hierarchy to
  456.         the root node.
  457.  
  458.     PIDBFLAG_NOCALLBACK
  459.                 This flag disables use the the callback functions in
  460.     DB tree's created with callback hook functions via PIDBEx_new().
  461.     This flag is typically used in the implementation of callback
  462.     functions for PIDBEx when PIDB_lookup() or PIDB_getIterator() would
  463.     cause a recursive invokation of the callback function.
  464.  
  465.     PIDBFLAG_FASTKEY
  466.                 This flag indicates that the key pKey is an optimized
  467.     key generated by PIDB_getFastKey(). 
  468.  
  469.  Notes:
  470.     The iterator object should be free'd with PIDBIterator_delete() when
  471.     it is no longer needed.
  472.  
  473.  Return Values:
  474.     On success a pointer to an PIDBIterator object is returned. The
  475.     functions PIDBIterator_atValidElement(), PIDBIterator_current(), 
  476.     PIDBIterator_next() and PIDBIterator_delete() are used to access and
  477.     manipulate the iterator.
  478.     
  479.  Errors:
  480.     NULL is returned if pTree is NULL, iType invalid or memory
  481.     could not be allocated for the PIDBIterator object.
  482.  
  483.  See Also:
  484. \*____________________________________________________________________________*/
  485. PUBLIC_PIAPI PIDBIterator *PIDB_getIterator( PIDB *pTree, int iType,
  486.     const char *pKey, int iFlags );
  487.  
  488. /*____________________________________________________________________________*\
  489.  *
  490.  Name:
  491.     PIDB_delete
  492.  
  493.  Synopsis:
  494.     int PIDB_delete( PIDB *pTree )
  495.     
  496.  Description:
  497.     Destructs a root PIDB tree created by PIDB_new( NULL ). 
  498.  
  499.  Notes:
  500.  
  501.  Return Values:
  502.     On success PIDB_delete returns zero (PIAPI_COMPLETED).
  503.     
  504.  Errors:
  505.     PIAPI_EINVAL is returned if pTree is NULL. If pTree is a child
  506.     node of another tree then PIAPI_ERROR is returned.
  507.  
  508.  See Also:
  509. \*____________________________________________________________________________*/
  510. PUBLIC_PIAPI int PIDB_delete( PIDB *pTree );
  511.  
  512. /*____________________________________________________________________________*\
  513.  *
  514.  Name:
  515.     PIDB_getRoot
  516.  
  517.  Synopsis:
  518.     int PIDB_getRoot( PIDB *pTree )
  519.     
  520.  Description:
  521.     Returns the root node of a PIDB tree hierarchy.
  522.  
  523.  Notes:
  524.  
  525.  Return Values:
  526.     On success PIDB_getRoot() returns the root node of the PIDB tree
  527.     hierarchy.
  528.     
  529.  Errors:
  530.     If pTree is NULL PIDB_getRoot() returns NULL.
  531.  
  532.  See Also:
  533. \*____________________________________________________________________________*/
  534. PUBLIC_PIAPI PIDB *PIDB_getRoot( PIDB *pTree );
  535.  
  536. /*____________________________________________________________________________*\
  537.  *
  538.  Name:
  539.     PIDBIterator_atValidElement
  540.  
  541.  Synopsis:
  542.     int PIDBIterator_atValidElement( PIDBIterator *pIter )
  543.     
  544.  Description:
  545.     Returns a boolean result indicating whether not the PIDBIterator_current()
  546.     may be used to retrieve an element from the iterator.
  547.  
  548.  Notes:
  549.  Return Values:
  550.     Returns non-zero (PIAPI_TRUE) if an element may be read, otherwise zero
  551.     (PIAPI_FALSE) the iterator has exhausted matching elements.
  552.     
  553.  Errors:
  554.     Returns PIAPI_FALSE if pIter is NULL.
  555.  
  556.  See Also:
  557. \*____________________________________________________________________________*/
  558. PUBLIC_PIAPI int PIDBIterator_atValidElement( PIDBIterator *pIter );
  559.  
  560. /*____________________________________________________________________________*\
  561.  *
  562.  Name:
  563.     PIDBIterator_current
  564.  
  565.  Synopsis:
  566.     void *PIDBIterator_current( PIDBIterator *pIter, const char **ppKey )
  567.     
  568.  Description:
  569.     Returns the value of the current element of the iterator. If ppKey is
  570.     not NULL it will be set to point to the key of the retrieved element.
  571.  
  572.  Notes:
  573.     The results are undefined if the iterator does not point at a valid
  574.     element. The function PIDBIterator_atValidElement can be used to 
  575.     verify the status of the iterator object.
  576.  
  577.     In general the iterator object return elements in no particular order.
  578.     However, elements with the exact same key will be retrieved in the
  579.     order in which they were placed in the tree.
  580.     
  581.  Return Values:
  582.     Returns the current object from the iterator. The type of the object
  583.     depends on the value of iType. The pointer should be cast to a 
  584.     pointer of the appropriate type, typically the typecasts would be as
  585.     follows
  586.  
  587.     PIDBTYPE_TREE            PIDB *            a tree node
  588.     PIDBTYPE_STRING            const char *    character array
  589.     PIDBTYPE_S_RFC822         const char *    character array
  590.     PIDBTYPE_C_RFC822        const char *    character array
  591.     PIDBTYPE_OPAQUE            void *            generic pointer
  592.     PIDBTYPE_USER            void            not defined
  593.     
  594.  Errors:
  595.     Returns NULL is pIter is NULL.
  596.  
  597.  See Also:
  598. \*____________________________________________________________________________*/
  599. PUBLIC_PIAPI void *PIDBIterator_current( PIDBIterator *pIter,
  600.     const char **ppKey );
  601.  
  602. /*____________________________________________________________________________*\
  603.  *
  604.  Name:
  605.     PIDBIterator_next
  606.  
  607.  Synopsis:
  608.     int PIDBIterator_next( PIDBIterator *pIter )
  609.     
  610.  Description:
  611.     Increments an iterator objects internal pointers to point at the
  612.     next valid PIDB element.
  613.  
  614.  Notes:
  615.     The results are undefined if the iterator does not point at a valid
  616.     element. The function PIDBIterator_atValidElement should be used
  617.     at PIIterator_next and before PIDBIterator_next to verify that the
  618.     iterator points at a valid PIDB element.
  619.  
  620.  Return Values:
  621.     On success PIDBIterator_next() returns zero (PIAPI_COMPLETED).
  622.  
  623.  Errors:
  624.     PIAPI_EINVAL        if pIter is NULL
  625.  
  626.  See Also:
  627. \*____________________________________________________________________________*/
  628. PUBLIC_PIAPI int PIDBIterator_next( PIDBIterator *pIter );
  629.  
  630. /*____________________________________________________________________________*\
  631.  *
  632.  Name:
  633.     PIDBIterator_removeCurrent
  634.  
  635.  Synopsis:
  636.     int PIDBIterator_removeCurrent( PIDBIterator *pIter )
  637.     
  638.  Description:
  639.     Remove and destroy the current element of the iterator pIter.
  640.  
  641.  Notes:
  642.  Return Values:
  643.     On success PIDBIterator_removeCurrent() returns zero (PIAPI_COMPLETED).
  644.  
  645.  Errors:
  646.     PIAPI_EINVAL        if pIter is NULL
  647.  
  648.  See Also:
  649. \*____________________________________________________________________________*/
  650. PUBLIC_PIAPI int PIDBIterator_removeCurrent( PIDBIterator *pIter );
  651.  
  652. /*____________________________________________________________________________*\
  653.  *
  654.  Name:
  655.     PIDBIterator_delete
  656.  
  657.  Synopsis:
  658.     int PIDBIterator_delete( PIDBIterator *pIter )
  659.     
  660.  Description:
  661.     Destroys the iterator object and frees any associated memory.
  662.  
  663.  Notes:
  664.  Return Values:
  665.     On success PIDBIterator_delete() returns zero (PIAPI_COMPLETED).
  666.  
  667.  Errors:
  668.     PIAPI_EINVAL        if pIter is NULL
  669.  
  670.  See Also:
  671. \*____________________________________________________________________________*/
  672. PUBLIC_PIAPI int PIDBIterator_delete( PIDBIterator *pIter );
  673.  
  674. /*____________________________________________________________________________*\
  675.  *
  676.  Name:
  677.     PIUserType_getValue
  678.  
  679.  Synopsis:
  680.     void *PIUserType_getValue( PIUserType *pUserType )
  681.     
  682.  Description:
  683.     Returns the value associated with a PIUserType data structure.
  684.  
  685.  Notes:
  686.  Return Values:
  687.     On success PIUserType_getValue returns the value associated with
  688.     the PIUserType data structure. Returns NULL if pUserType is not
  689.     valid.
  690.  
  691.  Errors:
  692.  See Also:
  693. \*____________________________________________________________________________*/
  694. PUBLIC_PIAPI void *PIUserType_getValue( PIUserType *pUserType );
  695.  
  696. #endif    /* PIDB_H_ */
  697.  
  698.