Name:
PIClass_getLibrary
Synopsis:
const PIDLL *PIClass_getLibrary( const PIClass *pClass )
Description:
Return the library object associated with this class.
Notes:
Return Values:
Returns NULL on failure.
Errors:
PIAPI_EINVAL if pClass is NULL.
See Also:
Name:
PIClass_load
Synopsis:
const PIClass *PIClass_load( PIDB *pDB, PIConfig *pConfig,
const char *pClassName )
Description:
Attempts to load a class with name pClassName from a definition
in the parsed configuration DB pConfigDB.
If pConfigDB is NULL then PIConfig_findConfiguration() is used to
find the configuration DB from pDB.
Notes:
If the class library has not already been loaded PIClass_loadClass
will attempt to load it using PILibrary_load().
Return Values:
On success PIClass_load() returns a const pointer to the specified class.
Errors:
PIAPI_EINVAL if pDB or pClassName is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PIClass_lookup
Synopsis:
const PIClass *PIClass_lookup( PIDB *pDB, const char *pClassName );
Description:
Looks under the root node of pDB for a PIDB tree with a key of
PIDBKEY_LIBRARIES and then under that for a PIDB with a key of
PIDBKEY_CLASSES, then searches within this tree for an element
with key pClassName. If found this element is returned.
Notes:
Return Values:
On success PIClass_lookup() returns a const pointer to the specified class.
Errors:
PIAPI_EINVAL if pDB or pClassName is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PIClass_lookupOrLoad
Synopsis:
const PIClass *PIClass_lookupOrLoad( PIDB *pDB, PIConfig *pConfig,
const char *pClassName )
Description:
This function first attempts to find an existing class using
PIClass_lookup(). If that fails it attempts to load the class
from the parsed configuration DB pConfigDB using PIClass_load().
Notes:
See PIClass_lookup() and PIClass_load() for more details.
Return Values:
On success PIClass_lookup() returns a const pointer to the specified class.
Errors:
PIAPI_EINVAL if pDB or pClassName is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Synopsis:
const char *PIConfigString_getString( PIConfigString *pString )
Description:
Returns the string value of a given PIConfigString data structure.
Notes:
Return Values:
Returns a pointer to the string of the given PIConfigString data
structure.
Errors:
On error PIConfigString_getString() returns NULL.
See Also:
Name:
PIConfig_findConfiguration
Synopsis:
PIConfig *PIConfig_findConfiguration( PIDB *pDB )
Description:
Search under the PIDB tree node pDB for another tree with the key
PIDBKEY_CONFIGURATION.
The tree hierarchy is search recusively upwards from the node pDB
until the configuration tree is found or the root node is reached
with no match.
Notes:
This function is implemented as
PIConfig *PIDB_Lookup( pDB, <internal type>, PIDBKEY_CONFIGURATION,
PIDBFLAG_PROPAGATEUP )
Return Values:
Returns a pointer to the configuration tree or NULL if it was not
found.
Errors:
Returns NULL is pDB is NULL.
See Also:
Name:
PIConfig_loadConfigurationFile
Synopsis:
int PIConfig_loadConfigurationFile( PIDB *pDB, const char *pFileName,
PIConfig **ppConfigDB )
Description:
Parse the configuration file pFileName and place the parsed
contents in a new DB tree under the specified tree pDB, with the key
PIDBKEY_CONFIGURATION.
If ppConfigDB is non-NULL and a configuration tree is created
the pointer to the new configuration tree will be placed in ppConfigDB.
Notes:
In all cases where pDB and pFileName are non-NULL a new child DB tree
with the key PIDBKEY_CONFIGURATION will be added under the tree pDB.
Return Values:
On complete success PIConfig_loadConfigurationFile() will return zero
(PIAPI_COMPLETED). Other errors may be returned as described below.
Errors:
PIAPI_EINVAL if pDB or pFileName is NULL.
PIAPI_ERROR if an error occurred while parsing the configuration file.
[PIAPI_WARNING] this error code may be returned if a warning was generated
while parsing the configuraton file. Currently
PIAPI_COMPLETED will be returned when a configuration
file is loaded with only warnings.
See Also:
Name:
PIConfig_lookupTree
Synopsis:
PIConfig *PIConfig_lookupTree( PIConfig *pConfig, const char *pKey,
char *pInfoBuffer, int iLen )
Description:
Lookup the configuration tree with the key pKey in pConfig.
If the definition is found and pInfoBuffer is non-NULL a description of the
location where the tree was defined will be written into it, up to iLen
characters.
Notes:
A configuration file tree is of the following form
<key> ... ... </key>The exact format of the description placed in pInfoBuffer is subject to change but may include the following information:
Return Values:
Returns a PIConfig structure. The functions PIConfig_lookupValue()
and PIConfig_lookupTree() can be used to find definitions and trees
within this tree.
Errors:
Returns NULL if a tree with the specified key was not found within
this key.
See Also:
Name:
PIConfig_lookupValue
Synopsis:
const char *PIConfig_lookupValue( PIConfig *pConfig, const char *pKey,
char *pInfoBuffer, int iLen )
Description:
Lookup a value within the specified configuration tree.
If the value is found and pInfoBuffer is non-NULL a description of the
location where the value was defined will be written into it, up to iLen
characters.
Notes:
A configuration file definition line is of the form
<key>=<value> <additional values>The exact format of the description placed in pInfoBuffer is subject to change but may include the following information:
Return Values:
Returns a pointer to the value for the key pKey under the configuration
tree. PIConfig_lookupValue() returns NULL if no match is found.
Errors:
Returns NULL if pConfig is NULL.
See Also:
Name:
PIDBEx_new
Synopsis:
PIDB *PIDBEx_new( PIDB *pParent, const char *pName,
void *(* fnLookup)( PIDB *, int, const char *, int ) )
Description:
Creates a new PIDB of extended type PIDBEx. This tree supports a
lookup callback where lookups on the tree will invoke the user
supplied lookup function.
Notes:
Use of this callback function on instances of this extended tree
type can be overriden by adding the PIDBFLAG_NOCALLBACK flag to the
flags passed to PIDB_lookup() or PIDB_getIterator().
Return Values:
Returns a pointer to the new child PIDB tree on success.
Errors:
Returns NULL if fnLookup is NULL.
See Also:
Name:
PIDBIterator_atValidElement
Synopsis:
int PIDBIterator_atValidElement( PIDBIterator *pIter )
Description:
Returns a boolean result indicating whether not the PIDBIterator_current()
may be used to retrieve an element from the iterator.
Notes:
Return Values:
Returns non-zero (PIAPI_TRUE) if an element may be read, otherwise zero
(PIAPI_FALSE) the iterator has exhausted matching elements.
Errors:
Returns PIAPI_FALSE if pIter is NULL.
See Also:
Name:
PIDBIterator_current
Synopsis:
void *PIDBIterator_current( PIDBIterator *pIter, const char **ppKey )
Description:
Returns the value of the current element of the iterator. If ppKey is
not NULL it will be set to point to the key of the retrieved element.
Notes:
The results are undefined if the iterator does not point at a valid
element. The function PIDBIterator_atValidElement can be used to
verify the status of the iterator object.
In general the iterator object return elements in no particular order.
However, elements with the exact same key will be retrieved in the
order in which they were placed in the tree.
Return Values:
Returns the current object from the iterator. The type of the object
depends on the value of iType. The pointer should be cast to a
pointer of the appropriate type, typically the typecasts would be as
follows
iType | Cast | Remark |
---|---|---|
PIDBTYPE_TREE | PIDB * | a tree node |
PIDBTYPE_STRING | const char * | character array |
PIDBTYPE_RFC822 | const char * | character array |
PIDBTYPE_OPAQUE | void * | generic pointer |
PIDBTYPE_USER | void | not defined |
Errors:
Returns NULL is pIter is NULL.
See Also:
Name:
PIDBIterator_delete
Synopsis:
int PIDBIterator_delete( PIDBIterator *pIter )
Description:
Destroys the iterator object and frees any associated memory.
Notes:
Return Values:
On success PIDBIterator_delete() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if pIter is NULL
See Also:
Name:
PIDBIterator_next
Synopsis:
int PIDBIterator_next( PIDBIterator *pIter )
Description:
Increments an iterator objects internal pointers to point at The
next valid PIDB element.
Notes:
The results are undefined if the iterator does not point at a valid
element. The function PIDBIterator_atValidElement should be used
at PIIterator_next and before PIDBIterator_next to verify that the
iterator points at a valid PIDB element.
Return Values:
On success PIDBIterator_next() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if pIter is NULL
See Also:
Name:
PIDBIterator_removeCurrent
Synopsis:
int PIDBIterator_removeCurrent( PIDBIterator *pIter )
Description:
Remove and destroy the current element of the iterator pIter.
Notes:
Return Values:
On success PIDBIterator_removeCurrent() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if pIter is NULL
See Also:
Name:
PIDB_add
Synopsis:
int PIDB_add( PIDB *pTree, int iType, const char *pKey, void *pValue,
int iFlags )
Description:
Adds a child element into a PIDB tree. The action performed on the
opaque pointer pValue depends on the value of iType.
Notes:
The type PIDBTYPE_USER is under development and its behaviour
is subject to change.
Return Values:
On success PIDB_add returns zero (PIAPI_COMPLETED). Otherwise
an error occured as described below.
Errors:
PIAPI_EINVAL An invalid value for iType was used or pTree was NULL
PIAPI_EXHAUSTED Memory could not be allocated to complete the function.
See Also:
Name:
PIDB_delete
Synopsis:
int PIDB_delete( PIDB *pTree )
Description:
Destructs a root PIDB tree created by PIDB_new( NULL ).
Notes:
Return Values:
On success PIDB_delete returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL is returned if pTree is NULL. If pTree is a child
node of another tree then PIAPI_ERROR is returned.
See Also:
Name:
PIDB_getFastKey
Synopsis:
const char *PIDB_getFastKey( const char *pKey, int iType )
Description:
Returns a pointer to a symbol table entry for the key pKey and
PIDB type iType. This symbol table entry then then be used in calls
to PIDB_lookup() and PIDB_getIterator() with the PIDBFLAG_FASTKEY to
avoid the overhead of hashing and symbol table lookup.
Notes:
This function is useful where a key is used multiple times. The
fast key can be generated once and reused across all invocations
of PIDB_lookup() and PIDB_getIterator(). This significantly improves
performance.
Return Values:
On success PIDB_getFastKey() returns a new key. Returns NULL on
failure.
Errors:
Returns NULL if pKey is NULL or no memory space is available.
See Also:
Name:
PIDB_getIterator
Synopsis:
PIDBIterator *PIDB_getIterator( PIDB *pTree, int iType, const char *pKey,
int iFlags )
Description:
Returns a pointer to an PIDBIterator object which to traverse the specified
tree for elements of type iType which match the key pKey. If pKey is
NULL all objects with type iType will be matched. The following flags
may be OR'ed together to form the value iFlags:
PIDBFLAG_PROPAGATEUP
The current tree will first be searched and then the parent
tree. The recursively search all trees up the tree hierarchy to
the root node.
PIDBFLAG_NOCALLBACK
This flag disables use the the callback functions in
DB tree's created with callback hook functions via PIDBEx_new().
This flag is typically used in the implementation of callback
functions for PIDBEx when PIDB_lookup() or PIDB_getIterator() would
cause a recursive invokation of the callback function.
PIDBFLAG_FASTKEY
This flag indicates that the key pKey is an optimized
key generated by PIDB_getFastKey().
Notes:
The iterator object should be free'd with PIDBIterator_delete() when
it is no longer needed.
Return Values:
On success a pointer to an PIDBIterator object is returned. The
functions PIDBIterator_atValidElement(), PIDBIterator_current(),
PIDBIterator_next() and PIDBIterator_delete() are used to access and
manipulate the iterator.
Errors:
NULL is returned if pTree is NULL, iType invalid or memory
could not be allocated for the PIDBIterator object.
See Also:
Name:
PIDB_getParent
Synopsis:
PIDB *PIDB_getParent( PIDB *pTree )
Description:
Returns the parent tree of the specified PIDB tree.
Notes:
Return Values:
Returns a pointer to the parent tree or NULL if the specified tree
is the top of the tree hierarchy.
Errors:
NULL if pTree is NULL
See Also:
Name:
PIDB_getRoot
Synopsis:
int PIDB_getRoot( PIDB *pTree )
Description:
Returns the root node of a PIDB tree hierarchy.
Notes:
Return Values:
On success PIDB_getRoot() returns the root node of the PIDB tree
hierarchy.
Errors:
If pTree is NULL PIDB_getRoot() returns NULL.
See Also:
Name:
PIDB_lookup
Synopsis:
void *PIDB_lookup( PIDB *pTree, int iType, const char *pKey, int iFlags )
Description:
Searches the PIDB tree for the first occurence of the an element which
matches the key. If pKey is NULL then the first element of the specified
type will be returned. See PIDB_getIterator() for the use of the parameter
iFlags.
Notes:
This function cannot be used to distinguish between an unsuccessful
search and a successful search where the value of the matched element
is NULL. In these cases an PIDBIterator object should be used to
scan the tree, see PIDB_getIterator.
Return Values:
On success the reference of the first element is returned. The type of
the value depends on the specified value of iType. See PIDB_add for
a full description of possible types. See PIDBIterator_current for
a description of appropriate PIDBTYPE to C typecast mappings.
NULL is returned if no match was found.
Errors:
If pTree is NULL or iType is out of range then PIDB_lookup() returns
NULL.
See Also:
Name:
PIDB_new
Synopsis:
PIDB *PIDB_new( PIDB *pParent, const char *pName )
Description:
Creates a new PIDB tree under the specified parent node with the
specified name. If pParent is NULL, then the generated node will
be the root of a new PIDB tree hierarchy.
If a new child tree is successfully generated it is automatically
added into the parent tree's list of child nodes with a type of
PIDBTYPE_TREE and a key of pName.
If pParent is NULL then a new root tree node is generated. This tree
should be free'd with PIDB_delete() when it is no longer needed.
Notes:
If memory cannot be allocated for the new tree, a special handler
will be invoked in a method specific to the build and configuration
of the server library. For more information see the specific notes
for the library release.
Return Values:
Returns a pointer to the new child PIDB tree, or NULL if insufficent
memory was available.
Errors:
See Also:
Name:
PIDB_pidbflagsNameToNumber
Synopsis:
int PIDB_pidbflagsNameToNumber( const char *pFlags )
Description:
Returns the integer value of the flags represented by the string pFlags.
The string pFlags may contain many flags seperated by the pipe ('|')
character.
pType | Return code |
---|---|
"PROPAGATEUP" | PIDBFLAG_TREE |
"NOCALLBACK" | PIDBFLAG_NOCALLBACK |
"FASTKEY" | PIDBFLAG_FASTKEY |
Notes:
Whitespace in the string pFlags is allowed and will be ignored in
matching the flags.
The flags PIDBFLAG_NOCALLBACK and PIDBTYPE_FASTKEY have little use
in the context of persistence and are included only for
completeness.
Return Values:
Returns the value formed by bitwise OR'ing the flags together. If
no flags are matched or the value pFlags is NULL,
PIDB_pidbflagsNameToNumber returns zero (PIDBFLAG_NONE).
Errors:
This function does not generate an error. Unrecognised flags are
ignored.
See Also:
PIDB_pidbtypeNameToNumber
Name:
PIDB_pidbtypeNameToNumber
Synopsis:
int PIDB_pidbtypeNameToNumber( const char *pType )
Description:
Returns the integer value of the name pType, effectively mapping, the
string pType to return values as follows:-
pType | Return code |
---|---|
"TREE" | PIDBTYPE_TREE |
"STRING" | PIDBTYPE_STRING |
"RFC822" | PIDBTYPE_RFC822 |
"OPAQUE" | PIDBTYPE_OPAQUE |
"USER" | PIDBTYPE_USER |
Notes:
Return Values:
If the string pType could not be matched PIDB_pidbtypeNameToNumber()
returns PIDBTYPE_INVALID.
Errors:
On error PIDB_pidbtypeNameToNumber() returns PIDBTYPE_INVALID.
See Also:
PIDB_pidbflagsNameToNumber
Name:
PIDB_replace
Synopsis:
int PIDB_replace( PIDB *pTree, int iType, const char *pKey, void *pValue,
int iFlags )
Description:
Replaces the first instance of the value corresponding to pKey in the
DB pTree. The new entry will be created even if a previous entry could
not be found. PIDB_add() describes the parameters iType and iFlags.
Additionally iFlags may have the following flag set
PIDBFLAG_PROPAGATEUP Search upwards from the current tree to
parent trees to find a match.
Notes:
Return Values:
On success PIDB_replace returns zero (PIAPI_COMPLETED). Otherwise
an error occured as described below.
Errors:
PIAPI_EINVAL An invalid value for iType was used or pTree was NULL
PIAPI_EXHAUSTED Memory could not be allocated to complete the function.
See Also:
Name:
PIIO_in
Synopsis:
int PIIO_in( PIObject *pObj, void *pData, int iLen, int *piReceived,
int iArgc, const char *ppArgv[] )
Description:
Read a block of data from the IO object pObj into the buffer
pData. Up to
iLen bytes may be read. On success the number bytes read is written
to the integer pointer to by piReceived
Optional additional parameters may be passed to the IO object, the
parameters iArgc and ppArgv specify the number of elements in
an array of values and the array of values respectively.
Notes:
On normal channel close (gracefull socket or pipe close) PIAPI_COMPLETED
is returned and the value at piReceived set to zero.
Return Values:
On success PIAPI_COMPLETED is returned.
Errors:
On error PIAPI_ERROR is returned.
See Also:
PIIO_out
Name:
PIIO_out
Synopsis:
int PIIO_out( PIObject *pObj, void *pData, int iLen, int *piSent,
int iArgc, const char *ppArgv[] )
Description:
Send a block of data in buffer pData with length iLen into
the IO object pObj. On success the value at piSent is set
to the number of bytes written.
Optional additional parameters may be passed to the IO object, the
parameters iArgc and ppArgv specify the number of elements in
an array of values and the array of values respectively.
Notes:
Return Values:
On success PIAPI_COMPLETED is returned.
Errors:
On error PIAPI_ERROR is returned.
See Also:
PIIO_in
Name:
PILibrary_load
Synopsis:
const PILibrary *PILibrary_load( PIDB *pDB, PIConfig *pConfig,
const char *pLibraryName )
Description:
Attempts to load the library with name pLibraryName from the
parsed configuration file pConfigDB.
If pConfigDB is NULL then PIConfig_findConfiguration() is used to
find the configuration DB from pDB.
Notes:
Return Values:
On success PILibrary_load() returns a const pointer to the a new PILibrary
object.
Errors:
PIAPI_EINVAL if pDB or pLibraryName is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PILibrary_lookup
Synopsis:
const PILibrary *PILibrary_lookup( PIDB *pDB, const char *pLibraryName );
Description:
Looks under the root node of pDB for a PIDB tree with a key of
PIDBKEY_LIBRARIES, then searches within this tree for an element
with key pLibraryName. If found this element is returned.
Notes:
Return Values:
On success PILibrary_lookup() returns a const pointer to a new
PILibrary object.
Errors:
PIAPI_EINVAL if pDB or pLibraryName is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Synopsis:
const PILibrary *PILibrary_lookupOrLoad( PIDB *pDB, PIConfig *pConfig,
const char *pLibraryName )
Description:
This function first attempts to find an existing library using
PILibrary_lookup(). If that fails it attempts to load the library
from the parsed configuration DB pConfigDB using PILibrary_load().
Notes:
See PILibrary_lookup() and PILibrary_load() for more details.
Return Values:
On success PILibrary_lookup() returns a const pointer to the
specificed PILibrary object.
Errors:
PIAPI_EINVAL if pDB or pLibraryName is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PILog_addMessage
Synopsis:
int PILog_addMessage( PIDB *pDB, PIConfig *pConfig, int iType,
const char *pFormat, ... );
Description:
Log a message concerning initialization from a configuration file.
PILog_addMessage() will automatically include information from
parsed configuration DB pConfig.
pFormat is a printf() compatible format string. PILog_addMessage()
takes a variable number of arguments. The number and type of
arguments should be compatible with printf() directives.
The flag iType indicates whether the item should be logged as an
error or a warning, it may contain one of the following values:-
PILOG_ERROR
PILOG_WARNING
PILOG_ALL
Notes:
PILog_addMessage() looks under the root DB for a DB with a key of
PIDBKEY_DIAGNOSTICS.
Return Values:
On success PILog_addMessage() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if pDB or pFormat is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PILog_newSink
Synopsis:
int PILog_newSink( int iType, const char *pParam )
Description:
Sets a new sink for logged messages. Messages can be sent to the
main program DB (default), to a file (path to file is given by parameter
pParam), or to a standard stream.
The following flags for iType dictate the new sink.
Notes:
Current logging to a file via this mechanism is not implemented,
attempting to set the log sink to a file will result in an error
code of PIAPI_NOTSUPPORTED.
Return Values:
On success PILog_newSink() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if iType is PILOG_FILE and pParam is NULL.
PIAPI_ERROR if another error occurred.
PIAPI_NOTSUPPRTED as described under notes.
See Also:
Synopsis:
int PILog_writeDiagnostics( PIDB *pDB, int iFlags, const char *pFileName )
Description:
Write the contents of the diagnostics DB to the file pFileName. The
value iFlags is the inclusive-or of diagnostic types to write, the
macro PILOG_ALL can be used to specify all message types.
If pFileName is NULL the output will be written to the standard output.
Notes:
PILog_writeDiagnostics() looks under the root DB for a DB with a key of
PIDBKEY_DIAGNOSTICS.
Return Values:
On success PILog_writeDiagnostics() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if pDB is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PILogic_execute
Synopsis:
int PILogic_execute( PIObject *pObj, int iArgc, const char *ppArgv[] )
Description:
Execute the logic performed by the logic object pObj.
Optional additional parameters may be passed to the logic object, the
parameters iArgc and ppArgv specify the number of elements in
an array of values and the array of values respectively.
Notes:
Return Values:
On success PIAPI_COMPLETED is returned.
Errors:
On error PIAPI_ERROR or PIAPI_ABORT is returned.
See Also:
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:
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:
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:
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:
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:
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:
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:
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 pConfigDB.
If pConfigDB 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
<Object> Name=[object name] Class=[class name] ... ... </Object>
Return Values:
Returns a pointer to the new object, or NULL if an error occurred.
Errors:
See Also:
PIObject_loadEx PIObject_loadFromLine
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
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 pConfigDB and the given object
line.
The parameter pObjectLine is tokenized and the result is handed
over to PIObject_load to construct the object finally.
Notes:
The string pObjectLine 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
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:
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 ppArgv,
and hand over the pre-processed parameters together with pParam
to the callback function fnParameters.
Notes:
The parameter line will be tokenized and de-quoted, i.e. the parameters are
of the general form
key1="value1" key2="value2" ...
Return Values:
Returns non-zero on success, zero on failure.
Errors:
See Also:
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:
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:
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:
Name:
PIProgram_dbgDump
Synopsis:
int PIProgram_dbgDump( PIDB *pDB, const char *pDumpFile )
Description:
Dump the entire contents of the database referenced by pDB to the
file pDumpFile. The file is opened in write truncate mode.
If pDumpFile is NULL PIProgram_dbgDump will attempt to write data
to the standard output stream.
Notes:
PIProgram_dbgDump formats the data in a hierarchical tree
format.
Return Values:
On success PIProgram_dbgDump() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_EINVAL if pDB is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PIProgram_enter
Synopsis:
int PIProgram_enter( const char *pProgramName, int iVersion,
PIProgramFn fn )
Description:
Initializes the program database and platform facilities. If successful
it invokes the user supplied function fn.
Notes:
PIProgam_enter should be invoked with the value PIPROGRAM_VERSION_1_0
for parameter iVersion.
PIProgram_enter automatically invokes PIPlatform_enter with the
platform version PIPLATFORM_VERSION_1_0 to initialize multithreading
and custom memory management facilities.
The parameter pProgramName should be passed argv[0] from the main()
entry point to the program. This may be used by certain platform
implementations.
Return Values:
On success PIProgram_enter() returns zero (PIAPI_COMPLETED)
Errors:
PIAPI_EINVAL if iVersion is not supported or fn is NULL.
PIAPI_ERROR if another error occurred.
See Also:
Name:
PIUserType_getValue
Synopsis:
void *PIUserType_getValue( PIUserType *pUserType )
Description:
Returns the value associated with a PIUserType data structure.
Notes:
Return Values:
On success PIUserType_getValue returns the value associated with
the PIUserType data structure. Returns NULL if pUserType is not
valid.
Errors:
See Also: