ESR_Session API functions


Detailed Description

Manages ESR session information.


Data Structures

struct  ESR_SessionSingleton

Functions

ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionCreate (const LCHAR *filename)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetProperty (const LCHAR *name, void **value, VariableTypes type)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetInt (const LCHAR *name, int *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetUint16_t (const LCHAR *name, asr_uint16_t *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetSize_t (const LCHAR *name, size_t *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetFloat (const LCHAR *name, float *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetBool (const LCHAR *name, ESR_BOOL *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetLCHAR (const LCHAR *name, LCHAR *value, size_t *len)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionContains (const LCHAR *name, ESR_BOOL *exists)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetProperty (const LCHAR *name, void *value, VariableTypes type)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetInt (const LCHAR *name, int value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetUint16_t (const LCHAR *name, asr_uint16_t value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetSize_t (const LCHAR *name, size_t value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetFloat (const LCHAR *name, float value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetBool (const LCHAR *name, ESR_BOOL value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetLCHAR (const LCHAR *name, LCHAR *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetIntIfEmpty (const LCHAR *name, int value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetUint16_tIfEmpty (const LCHAR *name, asr_uint16_t value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetSize_tIfEmpty (const LCHAR *name, size_t value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetFloatIfEmpty (const LCHAR *name, float value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetBoolIfEmpty (const LCHAR *name, ESR_BOOL value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionSetLCHARIfEmpty (const LCHAR *name, LCHAR *value)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionRemoveProperty (const LCHAR *name)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionRemoveAndFreeProperty (const LCHAR *name)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionDestroy (void)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionImportCommandLine (int argc, LCHAR *argv[])
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetSize (size_t *size)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetKeyAtIndex (size_t index, LCHAR **key)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionConvertToInt (const LCHAR *key)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionConvertToUint16_t (const LCHAR *key)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionConvertToSize_t (const LCHAR *key)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionConvertToFloat (const LCHAR *key)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionConvertToBool (const LCHAR *key)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionGetPropertyType (const LCHAR *name, VariableTypes *type)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionImportParFile (const LCHAR *filename)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionExists (ESR_BOOL *val)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionPrefixWithBaseDirectory (LCHAR *path, size_t *len)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionAddListener (ESR_SessionType *self, ESR_SessionTypeListenerPair *listener)
ESR_SHARED_API
ESR_ReturnCode 
ESR_SessionRemoveListener (ESR_SessionType *self, ESR_SessionTypeListenerPair *listener)


Function Documentation

ESR_SHARED_API ESR_ReturnCode ESR_SessionAddListener ( ESR_SessionType self,
ESR_SessionTypeListenerPair listener 
)

Adds an event-listener.

Parameters:
self ESR_SessionType handle
listener The event-listener to add
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionContains ( const LCHAR name,
ESR_BOOL *  exists 
)

Indicates if key exists in the session.

Parameters:
name Property name
exists True if key exists, false otherwise
Returns:
ESR_SUCCESS

ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToBool ( const LCHAR key  ) 

Convert the specified argument to bool.

Parameters:
key Property name
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_ARGUMENT if property cannot be converted to bool

ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToFloat ( const LCHAR key  ) 

Convert the specified argument to float.

Parameters:
key Property name
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_ARGUMENT if property cannot be converted to float

ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToInt ( const LCHAR key  ) 

Convert the specified argument to int.

Parameters:
key Property name
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_ARGUMENT if property cannot be converted to int

ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToSize_t ( const LCHAR key  ) 

Convert the specified argument to size_t.

Parameters:
key Property name
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_ARGUMENT if property cannot be converted to size_t

ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToUint16_t ( const LCHAR key  ) 

Convert the specified argument to int.

Parameters:
key Property name
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_ARGUMENT if property cannot be converted to asr_uint16_t

ESR_SHARED_API ESR_ReturnCode ESR_SessionCreate ( const LCHAR filename  ) 

Initializes the system session.

Parameters:
filename File to read session information from
Returns:
ESR_OPEN_ERROR if file cannot be opened; ESR_READ_ERROR if file cannot be read; ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionDestroy ( void   ) 

Destroys the system session.

Returns:
ESR_SUCCESS

ESR_SHARED_API ESR_ReturnCode ESR_SessionExists ( ESR_BOOL *  val  ) 

Sets val to true if a session object exists (non-null), FALSE otherwise.

Parameters:
val True if session is non-null, false otherwise
Returns:
ESR_SUCCESS

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetBool ( const LCHAR name,
ESR_BOOL *  value 
)

Returns copy of session property value.

Parameters:
name Property name
value Property value
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a bool

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetFloat ( const LCHAR name,
float *  value 
)

Returns copy of session property value.

Parameters:
name Property name
value Property value
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a float

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetInt ( const LCHAR name,
int *  value 
)

Returns copy of session property value.

Parameters:
name Property name
value Property value
Returns:
ESR_INVALID_RESULT_TYPE if the property is not an int

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetKeyAtIndex ( size_t  index,
LCHAR **  key 
)

Returns the key associated with the specified index.

Parameters:
index Element index
key [out] Key name
Returns:
ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetLCHAR ( const LCHAR name,
LCHAR value,
size_t *  len 
)

Returns copy of session property value.

Parameters:
name Property name
value Property value
len Length of value argument. If the return code is ESR_BUFFER_OVERFLOW, the required length is returned in this variable.
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetProperty ( const LCHAR name,
void **  value,
VariableTypes  type 
)

Returns session property value.

Parameters:
name Property name
value Property value
type Expected variable type (for strong-typing purposes)
Returns:
ESR_INVALID_RESULT_TYPE if the property is not of the specified type

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetPropertyType ( const LCHAR name,
VariableTypes *  type 
)

Returns the type of a property value.

Parameters:
name Property name
type [out] Value type
Returns:
ESR_INVALID_ARGUMENT if property cannot be found

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetSize ( size_t *  size  ) 

Returns the number of elements in the session.

Parameters:
size [out] Session size
Returns:
ESR_SUCCESS

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetSize_t ( const LCHAR name,
size_t *  value 
)

Returns copy of session property value.

Parameters:
name Property name
value Property value
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a size_t

ESR_SHARED_API ESR_ReturnCode ESR_SessionGetUint16_t ( const LCHAR name,
asr_uint16_t value 
)

Returns copy of session property value.

Parameters:
name Property name
value Property value
Returns:
ESR_INVALID_RESULT_TYPE if the property is not a asr_uint16_t

ESR_SHARED_API ESR_ReturnCode ESR_SessionImportCommandLine ( int  argc,
LCHAR argv[] 
)

Imports commandline arguments into the system session.

Keys are imported as "cmdline.[name]" where [name] is the name of the command-line argument Values are set in char* format.

For example, given the argument "-timer=5", the following key will be added to the session: ["cmdline.timer", "5"]

Validation is left up to the application.

If the session contains a key that is clobbered by the parser, the old [key, value] pair will be deallocated. For example, if the session contained ["cmdline.timer", "value"] before the aforementioned example occured, then the old [key, value] pair will be allocated by the parser.

Parameters:
argc Number of arguments
argv Argument values
Returns:
ESR_OUT_OF_MEMORY if the system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionImportParFile ( const LCHAR filename  ) 

Import PAR file into session.

Parameters:
filename File to read session from
Returns:
ESR_OPEN_ERROR if file cannot be opened; ESR_READ_ERROR if file cannot be read; ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionPrefixWithBaseDirectory ( LCHAR path,
size_t *  len 
)

Prefixes relative paths with the PAR-file base directory. If the path is not relative, it is not changed.

Parameters:
path Path to be prefixed
len Length of path argument. If the return code is ESR_BUFFER_OVERFLOW, the required length is returned in this variable.
Returns:
ESR_INVALID_ARGUMENT if path is null; ESR_NO_MATCH_ERROR if session property "parFile.baseDirectory" is undefined

ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveAndFreeProperty ( const LCHAR name  ) 

Removes and deallocates property from session.

Parameters:
name Property name
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveListener ( ESR_SessionType self,
ESR_SessionTypeListenerPair listener 
)

Removes an event-listener.

Parameters:
self ESR_SessionType handle
listener The event-listener to remove
Returns:
ESR_SUCCESS

ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveProperty ( const LCHAR name  ) 

Removes property from session.

Parameters:
name Property name
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetBool ( const LCHAR name,
ESR_BOOL  value 
)

Sets session property value, storing a copy of the value.

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetBoolIfEmpty ( const LCHAR name,
ESR_BOOL  value 
)

If the key does not exist in the session, calls SessionSetBool().

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetFloat ( const LCHAR name,
float  value 
)

Sets session property value, storing a copy of the value.

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetFloatIfEmpty ( const LCHAR name,
float  value 
)

If the key does not exist in the session, calls SessionSetFloat().

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetInt ( const LCHAR name,
int  value 
)

Sets session property value, storing a copy of the value.

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetIntIfEmpty ( const LCHAR name,
int  value 
)

If the key does not exist in the session, calls SessionSetInt().

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetLCHAR ( const LCHAR name,
LCHAR value 
)

Sets session property value, storing a copy of the value.

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetLCHARIfEmpty ( const LCHAR name,
LCHAR value 
)

If the key does not exist in the session, calls SessionSetLCHAR().

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetProperty ( const LCHAR name,
void *  value,
VariableTypes  type 
)

Sets session property value.

Parameters:
name Property name
value Property value
type Type of value being set
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetSize_t ( const LCHAR name,
size_t  value 
)

Sets session property value, storing a copy of the value.

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetSize_tIfEmpty ( const LCHAR name,
size_t  value 
)

If the key does not exist in the session, calls SessionSetSize_t().

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetUint16_t ( const LCHAR name,
asr_uint16_t  value 
)

Sets session property value, storing a copy of the value.

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory

ESR_SHARED_API ESR_ReturnCode ESR_SessionSetUint16_tIfEmpty ( const LCHAR name,
asr_uint16_t  value 
)

If the key does not exist in the session, calls SessionSetSize_t().

Parameters:
name Property name
value Property value
Returns:
ESR_OUT_OF_MEMORY if system is out of memory


Generated on Thu May 1 15:37:26 2008 for SREC by  doxygen 1.5.3