/* @(#)96    1.7  src/examples/type_mgr/server_object_db.h, examples.src, os2dce21.dss, 960602a.1  6/10/94  18:39:29 */
/*
 * COMPONENT_NAME:  examples.src
 *
 * FUNCTIONS:
 *
 * ORIGINS: 27
 *
 * (C) COPYRIGHT International Business Machines Corp. 1992, 1994
 * All Rights Reserved
 * Licensed Materials - Property of IBM
 *
 * US Government Users Restricted Rights - Use, duplication or
 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 *
 */

/*********************************************************************
 *  File      :  server_object_db.h 
 *********************************************************************
 *                                                                   *
 *  Functions :  utilities to manage the server's object database.
 *                                                                   *
 *  Comments  :  These routines are called by the server at startup  *
 *		 time and by the tm_admin manager.                   *
 *                                                                   *
 *********************************************************************/

/*
 *  Make the context handle for the object database operations an
 *  opaque structure.  The caller is not conerned with what is in
 *  the context handle.
 */

typedef void *object_db_handle_t;


/*********************************************************************
 *   Function    :  PUBLIC object_db_init
 *********************************************************************
 *
 *   Description :  Initializes object database.  If this is the 
 *		    first invocation of the server, the database is
 *		    created. If the server already exists (e.g. it 
 *		    is being brought back online) this routine 
 *		    restarts the database.
 *
 *   Returns     :  OBJECT_DB_CREATED / OBJECT_DB_RESTARTED / 
 *		    OBJECT_DB_INIT_UNDERWAY / FAILURE
 *
 *   Comments    :  This routine ensures one-time initialization
 *		    of the database in the presence of multiple
 *		    calls (including concurrent calls by the same
 *		    or different threads) to this routine.
 *	
 *		    OBJECT_DB_INIT_UNDERWAY is returned only if
 *		    a thread recursively calls this routine and 
 *		    that thread is the thread (internally) performing
 *		    the initialization.  Any other thread finding
 *		    the database in this state will automatically
 *		    block until initialization is complete (success
 *		    or failure) and then return the status set by
 *		    initializing thread.
 *
 *		    Any thread calling the routine subsequent to the 
 *		    initialization end, will simply return the status
 *		    set by the initializing thread.
 *		    
 *********************************************************************/

extern unsigned32 
object_db_init( void );


/*********************************************************************
 *   Function    :  object_db_entry_add
 *********************************************************************
 *
 *   Description :  Adds an (object_name, type_name) tuple to the
 *		    object database.
 *
 *   Returns     :  SUCCESS / FAILURE / OBJECT_ALREADY_EXISTS / 
 *		    CODING_ERROR
 *
 *   Comments    :  CODING_ERROR is returned if this API is called 
 *		    prior to successful initialization of the database.
 *
 *********************************************************************/

extern unsigned32 
object_db_entry_add( char    	*object_name,
		     char 	*type_name );


/*********************************************************************
 *   Function    :  PUBLIC object_db_entry_delete
 *********************************************************************
 *
 *   Description :  Remove the named object entry from the server's 
 *		    object database.
 *
 *   Returns     :  SUCCESS / FAILURE / NO_MATCH / CODING_ERROR
 *
 *   Comments    :  CODING_ERROR is returned if this API is called 
 *		    prior to successful initialization of the database.
 *
 *********************************************************************/

extern unsigned32 
object_db_entry_delete( char *object_name );


/*********************************************************************
 *   Function    :  PUBLIC object_db_entry_inq_begin
 *********************************************************************
 *
 *   Description :  Sets up an inquiry context into the object table 
 *
 *   Returns     :  SUCCESS / FAILURE/ CODING_ERROR
 *
 *   Comments	 :  Initializes the context handle passed in.  
 *		    NOTE: The caller must allocate the storage
 *		    for the object_db_handle_t and pass in the 
 *		    the address of it.
 *
 *   		    CODING_ERROR is returned if this API is called 
 *		    prior to successful initialization of the database.
 *
 *********************************************************************/

extern unsigned32
object_db_entry_inq_begin( object_db_handle_t	*context );


/*********************************************************************
 *   Function    :  PUBLIC object_db_entry_inq_next
 *********************************************************************
 *
 *   Description :  Returns the object name and type index of an
 *		    object database entry.  
 *
 *   Returns     :  SUCCESS / NO_MORE_ENTRIES / CODING_ERROR / FAILURE
 *
 *   Comments	 :  The inquiry context is an opaque reference to an 
 *		    entry in the object database.  A reference count 
 *		    for each  entry reflects the number of contexts 
 *		    referencing it.
 *
 *		    The first call to this routine for a particular
 *		    context (after the requisite call to  
 *		    object_db_entry_inq_begin) establishes a 
 *		    reference to the  first entry of the database.
 *		    Subsequent calls increment the context through the 
 *		    table.  When the end of the table is reached, this
 *		    routine returns NO_MORE_ENTRIES and the context is 
 *		    no longer valid.  When the caller is through with a 
 *		    context (handle), the routine object_entry_inq_done
 *		    must be called.
 *		    
 *		    This routine allocates storage for the returned
 *		    arguments and assigns it to the (char *) arguments
 *		    passed in.
 *
 *		    The caller is responsible for freeing the storage
 *		    allocated by this routine.
 *
 *		    If an argument is NULL, nothing is returned for that
 *		    argument.
 *
 *   		    CODING_ERROR is returned if this API is called 
 *		    prior to successful initialization of the database,
 *		    or a detectably invalid context handle was passed
 *		    in.
 *
 *********************************************************************/

extern unsigned32
object_db_entry_inq_next( object_db_handle_t *context,
			  char 	 **object_name_p,
			  char	 **type_name_p );



/*********************************************************************
 *   Function    :  PUBLIC object_db_entry_inq_done
 *********************************************************************
 *
 *   Description :  Frees the context pointed to by the context
 *		    handle.
 *
 *   Returns     :  SUCCESS / FAILURE / CODING_ERROR
 *
 *   Comments	 :  If the context is valid, the reference count
 *		    of the entry is decremented.
 *
 *  		    CODING_ERROR is returned if this API is called 
 *		    prior to successful initialization of the database,
 *		    or a detectably invalid context handle was passed
 *		    in.
 *
 *********************************************************************/

extern unsigned32
object_db_entry_inq_done( object_db_handle_t *context );


/*********************************************************************
 *   Function    :  PUBLIC object_db_entry_query_type
 *********************************************************************
 *
 *   Description :  Search for an object in the server's in-memory   
 *                  object table.                                    
 *
 *   Returns     :  SUCCESS / FAILURE  / NO_MATCH
 *
 *   Comments	 :  This routine allocates storage for the returned
 *		    type_name argument and points *type_name to it.
 *		    The caller is responsible for freeing the
 *		    storage when finished with it.
 *
 *		    Setting the type_name argument to NULL results in
 *	 	    no value returned for the argument.  This allows
 *		    the routine be used to query the object database
 *		    for a particular object name.
 *
 *   		    CODING_ERROR is returned if this API is called 
 *		    prior to successful initialization of the database.
 *
 *********************************************************************/

extern unsigned32 
object_db_entry_query_type( char	*object_name,
 			    char 	**type_name_p );

/* server_object_db.h */
