Next: 5. Examples
Up: Status Server Client C
Previous: 3. API Primer
Contents
Subsections
Before any other API calls are made to view, create, update, remove, or monitor information within the Status Server, this routine must be called to establish a connection. Once a connection is established to the Status Server, from the client perspective it remains persistent until the client chooses to disconnect from the Status Server.
If the Status Server itself is halted or the network connection between the client and Status Server is broken, the client API will enter into a blocking wait and retry process. As a result, it is not necessary for the client to check whether a connection failure occured following a successful connection. This approach is very similar to an NFS client-server interaction.
PASSFAIL ssLogon(const char *name)
- name - Name of the client program. This should correspond to argv[0] within the main loop of the client.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_SYNTAX_ERROR - Either the name of the client program is set to NULL, or an invalid hostname:port string is specified in the STATSERV environment variable.
- SS_NOT_CONNECTED_TO_SERVER - If the sockio library was not able to establish a connection to the Status Server host.
The connection between the client and Status Server will remain persistent until the client calls the ssLogoff() function to disconnect.
void ssLogoff(void)
Whenever an error occured on a Status Server API call, the enumerated value for the error code can be retrieved using this function call. This is very similar to what can be done at a system level with the external integer errno.
ss_errno_t ssGetError(void)
This function will return the value of the enumerated type ss_errno_t. The possible enumerated type possibilities are:
- SS_NO_ERROR -
- SS_SYNTAX_ERROR - A request was received by the Status Server which does not have the correct syntax.
- SS_INTERNAL_ERROR - An internal error was detected in the Status Server.
- SS_OBJ_DOES_NOT_EXIST - The object does not exist.
- SS_DIR_DOES_NOT_EXIST - The directory does not exist.
- SS_NODE_DOES_NOT_EXIST - Neither an object or directory exists in the Status Server at the requested location.
- SS_MON_DOES_NOT_EXIST - The requested monitor does not exist.
- SS_TOUCH_DOES_NOT_EXIST - A previous touch by this client does not exist.
- SS_OBJ_ALREADY_EXISTS - An object of the same name already exists.
- SS_DIR_ALREADY_EXISTS - A directory of the same name already exists.
- SS_NO_MONITORS_DEFINED - No monitors are defined.
- SS_DIR_CONTAINS_SUBDIR - The directory contains subdirectories.
- SS_DIR_CONTAINS_HIDDEN_OBJ - The directory contains hidden objects.
- SS_DIR_HAS_DEPENDENCIES - The directory has dependencies.
- SS_INT_CONVERT_ERROR - Unable to convert a string to an Integer.
- SS_DBL_CONVERT_ERROR - Unable to convert a string to a double precision floating point number.
- SS_BOOL_CONVERT_ERROR - Unable to convert a string to a boolean.
- SS_NOT_DEFINED_STATE - An object has not been initialized.
- SS_EXPIRED_STATE - The object has expired.
- SS_NOT_CONNECTED_TO_SERVER - If the sockio library was not able to establish a connection to the Status Server host.
- SS_UNKNOWN_ERROR - An unknown error has been encountered.
- SS_OBJ_HAS_DEPENDENCIES - An object has dependencies.
- SS_NODE_NOT_FOUND - The referenced object or directory can not be found.
- SS_READ_ONLY_MIRROR - Requesting an update to a read-only mirrored Status Server.
This routine will return back a pointer to a string containing descriptive text of the last error which occured on a Status Server API call. Please see the previous section for more details regarding the possible errors. This is very similar to what can be done at a system level with the call strerror(errno).
const char *ssGetStrError(void)
Descriptive string containing error details.
This routine allows a client the ability to register a callback function which will be called whenever the client is disconnected from the Status Server. If the user wishes to remove a previously defined callback routine, this routine can be called with the callback function set to NULL.
It is important to note that this callback function will not be called if a client invokes the ssLogoff() routine.
void ssDisconnectCallback(ss_callback_fn callback)
This routine allows a client the ability to register a callback function which will be called whenever the client is re-connected to the Status Server. If the user wishes to remove a previously defined callback routine, this routine can be called with the callback function set to NULL.
It is important to note that this callback function will not be called if a client invokes the ssLogoff() routine.
void ssReconnectCallback(ss_callback_fn callback)
Prior to either updating or removing an object within the Status Server, the client must perform a ``touch'' on the object. The touch enables a client to specify the intent to update or modify a value in the Status Server. If the data object does not exist before this call is made, it will be created with a state indicating that the object value is undefined.
This routine must also be used if a client wishes to change either the comment associated with an object or the lifetime.
Once a touch is placed on an object, it cannot be completely removed from the Status Server until the use counts for the object are zero. This means that no clients currently have an outstanding touch, monitor, or directory listing on the object. As a result, once a client performs a touch on an object, it is guaranteed to be available for updating.
There are four different API calls which can be used to perform a touch on an object. Each of the different API calls is described in the following sections.
This function call can be used if you don't wish to modify modify the current lifetime associated with an object. If the object does not yet exist when this call is made, it will be created with an unlimited lifetime.
PASSFAIL ssTouchObject(const char *name,
const char *comment)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than the maximum length of SS_MAX_NAME_SIZE defined in ss_define.h.
- comment - Description of the data object. If you do not wish to specify a comment, or don't want to modify the current comment, this must be set to NULL.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_ALREADY_EXISTS - A directory of the same name already exists.
- SS_PERMISSION_DENIED - If an attempt was made to perform a touch on a system object. For example, it is not possible to perform a touch on any objects within the /proc directory path.
- SS_SYNTAX_ERROR - The name specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine performs the same functionality as the ssTouchObject() call with the additional benefit of setting the lifetime of the object.
PASSFAIL ssTouchObjectWithLifetime(const char *name,
const char *comment,
time_t lifetime)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than the maximum length of SS_MAX_NAME_SIZE defined in ss_define.h.
- comment - Description of the data object. If you do not wish to specify a comment, or don't want to modify the current comment, this must be set to NULL.
- lifetime - An integer number, expressed in seconds, which identifies the amount of time the data object will be considered valid following a modification. If the lifetime is to be unlimited (i.e. no expiration date), this parameter must be set to zero.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_ALREADY_EXISTS - A directory of the same name already exists.
- SS_PERMISSION_DENIED - If an attempt was made to perform a touch on a system object. For example, it is not possible to perform a touch on any objects within the /proc directory path.
- SS_SYNTAX_ERROR - The name specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This function performs a touch on an object with the lifetime based on the duration of the client socket connection. For example, if you use this function and update an object in the Status Server, it will be considered valid until your client connection to the Status Server is broken at which point the object will change state to EXPIRED.
PASSFAIL ssTouchObjectWithAutoExpire(const char *name,
const char *comment)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than the maximum length of SS_MAX_NAME_SIZE defined in ss_define.h.
- comment - Description of the data object. If you do not wish to specify a comment, or don't want to modify the current comment, this must be set to NULL.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_ALREADY_EXISTS - A directory of the same name already exists.
- SS_PERMISSION_DENIED - If an attempt was made to perform a touch on a system object. For example, it is not possible to perform a touch on any objects within the /proc directory path.
- SS_SYNTAX_ERROR - The name specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This function will initiate a touch on an object in the Status Server and immediately change the value to be EXPIRED.
PASSFAIL ssTouchObjectExpire(const char *name,
const char *comment)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than the maximum length of SS_MAX_NAME_SIZE defined in ss_define.h.
- comment - Description of the data object. If you do not wish to specify a comment, or don't want to modify the current comment, this must be set to NULL.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_ALREADY_EXISTS - A directory of the same name already exists.
- SS_PERMISSION_DENIED - If an attempt was made to perform a touch on a system object. For example, it is not possible to perform a touch on any objects within the /proc directory path.
- SS_SYNTAX_ERROR - The name specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
The call serves two main purposes. First, it allow for a directory to be created if it doesn't already exists. Secondly, it can allow a client to register the intent to remove a directory from the Status Server. If the directory does not exist before this call is made, it will be created with an update count value of ``1''.
This routine must also be used if a client wishes to change the comment associated with a directory.
Once a touch is placed on the directory, it cannot be completely removed from the Status Server until the use counts for the directory are zero. This means that no clients currently have an outstanding touch, monitor, or directory listing on the directory. As a result, once a client performs a touch on a directory, it is guaranteed to remain persistent until an ``untouch'' is performed.
PASSFAIL ssTouchDir(const char *path,
const char *comment)
- path - Name of the directory path. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- comment - Description of the directory. If you do not wish to specify a comment, or don't want to modify the current comment, this must be set to NULL.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_ALREADY_EXISTS - A data object of the same name already exists.
- SS_PERMISSION_DENIED - If an attempt was made to perform a touch on a system directory. For example, it is not possible to perform a touch on the ``/proc'' system directory.
- SS_SYNTAX_ERROR - The path specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Once a touch is placed on an object or directory, it cannot be completely removed from the Status Server until the use counts for the object or directory are zero. This means that no clients currently have an outstanding touch, monitor, or directory listing on the object or directory. As a result, if a client creates an object or directory by performing a touch or touchdir and another client is responsible for removing the object or directory, the first client must ``untouch'' the object or directory before it can be completely removed by the second client.
PASSFAIL ssUntouch(const char *name)
- name - Name of the directory or data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NODE_DOES_NOT_EXIST - Directory or data object does not exist.
- SS_TOUCH_DOES_NOT_EXIST - A previous touch by this client does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Once a successful touch has been performed on an object, it is possible for the client to initiate an update request. The update request causes the value associated with the object to be modified. The client can update a Status Server object with either string, integer, double, or boolean data.
PASSFAIL ssPutString(const char *name,
const char *value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - New string for the data object. The string must be less than SS_MAX_VALUE_SIZE which is defined in ss_define.h. The string must be NULL terminated and can contain both printable and non-printable 8-bit characters.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the object, or an attempt was made to update a system object.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssPutInt(const char *name,
long value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - New integer value for the data object.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the object, or an attempt was made to update a system object.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssPutDouble(const char *name,
double value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - New double-precision floating point value for the data object.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the object, or an attempt was made to update a system object.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssPutBoolean(const char *name,
BOOLEAN value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - New boolean value for the data object.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the object, or an attempt was made to update a system object.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssPutPrintf(const char *name,
const char *fmt, ...)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- fmt - Character string that describes the format to be used.
- ... - Variable number of arguments depending on the number of items being printed.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the object, or an attempt was made to update a system object.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Since the Status Server is an open repository without permissions, any client has the ability to retrieve an object from the Status Server. Within the Status Server itself, values are stored as strings. The API provides the ability to extract information from the Status Server as either a string, integer, double or boolean value.
The information within the Status Server is stored in a modified URL encoded format. This routine will unencode the string and store it within a string specified by the user. The client will receive all the Status Server data up to the maximum length specified by the client. If length of the Status Server string is larger than the amount of room specified by the client, the string will be truncated.
PASSFAIL ssGetString(const char *name,
char *value,
size_t max_len)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- max_len - Maximum size of the buffer pre-allocated by the client. This length must include space for the NULL terminating character. If the client specified string length is less than SS_MAX_VALUE_SIZE, it is possible for the client to receive truncated data.
- value - Buffer where the contents of the data object will be stored.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_NOT_DEFINED_STATE - Data object has been created, but has not been initialized with a valid value.
- SS_EXPIRED_STATE - Data object exceeded its specified lifetime and is expired.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssGetInt(const char *name,
long *value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - Address where the integer value of the data object will be stored.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_NOT_DEFINED_STATE - Data object has been created, but has not been initialized with a valid value.
- SS_EXPIRED_STATE - Data object exceeded its specified lifetime and is expired.
- SS_INT_CONVERT_ERROR - Data object could not be converted to an integer.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssGetDouble(const char *name,
double *value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - Address where the double-precision floating point value of the data object will be stored.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_NOT_DEFINED_STATE - Data object has been created, but has not been initialized with a valid value.
- SS_EXPIRED_STATE - Data object exceeded its specified lifetime and is expired.
- SS_DBL_CONVERT_ERROR - Data object could not be converted to a double-precision floating point value.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
PASSFAIL ssGetBoolean(const char *name,
BOOLEAN *value)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - Address where the boolean value of the data object will be stored.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_NOT_DEFINED_STATE - Data object has been created, but has not been initialized with a valid value.
- SS_EXPIRED_STATE - Data object exceeded its specified lifetime and is expired.
- SS_BOOL_CONVERT_ERROR - Data object could not be converted to a boolean value.
- SS_SYNTAX_ERROR - Either the name or value specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Once a successful touch has been performed on an object, it is possible for the client to initiate a removal request of the object within the Status Server.
The data object cannot be completely removed from the Status Server until the use counts for the object are zero. This means that no clients currently have an outstanding touch, monitor, or directory listing on the object. If the use counts are greater than zero, the object will be put in a state of ``NONEXISTENT'' and will be removed completely whenever the use counts do go to zero. In the meantime, any request to ``get'' or ``stat'' the object will return an indication that the object does not exist as if it was completely removed from the Status Server.
PASSFAIL ssRemove(const char *name)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NODE_DOES_NOT_EXIST - Data object does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the object, or an attempt was made to remove a system object.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This function will check whether a specific data object exists in the Status Server and if so, return its status.
PASSFAIL ssStat(const char *name,
ss_stat_t *status)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- status - Enumerated type indicating whether the data object is valid, undefined, expired, or nonexistent.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine will return all the important attributes associated with a data object or directory. The information return is the same information as what is returned as part of a directory listing.
const ss_dirent_t *ssGetAttributes(const char *name)
- name - Name of the directory or data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
This function will either return a populated ss_dirent_t data structure, or NULL. If the function should return NULL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NODE_DOES_NOT_EXIST - Directory or data object does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
The client has the option of placing a monitor on any object with an optional deadband value. If a deadband are not desired, it can be set to 0. This indicates the client would like to monitor each change to an object value.
Once a monitor is placed on an object, the client must use the ssPoll() or ssWait() routine to retrieve updated monitor information.
Monitor changes to object can then be handled one of two ways. The client can specify a callback function to be called whenever the object changes, or the client can specify memory locations where the object value and value status will be updated. The value status enables the client to know when the state of an object changes, since an object can be valid, expired, undefined, or deleted. When a callback function is used, the updated value is always returned as a string.
Following an ssPoll() or ssWait() API call, if the value of a data object changes on the Status Server beyond the deadband threshold, the new value and status will be passed to a user callback function, along with the arbitrary 'userptr' provided by the user.
PASSFAIL ssMonitorCallback(const char *name,
double deadband,
ssMonitorCallbackFunc userfunc,
void *userptr)
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Following an ssPoll() or ssWait() API call, if the value of a data object changes on the Status Server, a new string value will be stored in the string buffer specified by the user. The string buffer specified by the client will be populated with the Status Server data up to the maximum length specified by the client. If length of the Status Server string is larger than the amount of room specified by the client, the string will be truncated.
PASSFAIL ssMonitorString(const char *name,
size_t max_len,
char *value,
ss_stat_t *value_status)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- max_len - Maximum size of the buffer pre-allocated by the client. This length must include space for the NULL terminating character. If the client specified string length is less than SS_MAX_VALUE_SIZE, it is possible for the client to receive truncated data.
- value - Buffer where the contents of the data object will be stored.
- value_status - Enumerated type which indicates the status of the value returned. Possible values include SS_VALID, SS_NONEXISTENT, SS_NOTDEFINED, SS_EXPIRED, and SS_TYPE_CAST_EXCEPTION. The value field should only be used if the value_status has a state of SS_VALID. In this case, the client should never receive an SS_TYPE_CAST_EXCEPTION since the value is stored as a string in the Status Server, so a type cast is not being performed.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Following an ssPoll() API call, if the value of a data object changes on the Status Server beyond the deadband threshold specified, a new integer value will be stored at the integer memory address specified by the user.
PASSFAIL ssMonitorInt(const char *name,
long deadband,
long *value,
ss_stat_t *value_status)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- deadband - Amount the Status Server data object must change by before the client is informed of a change in value. If this is set to 0, the client will be informed of all possible changes.
- value - Address where the integer value of the data object will be stored.
- value_status - Enumerated type which indicates the status of the value returned. Possible values include SS_VALID, SS_NONEXISTENT, SS_NOTDEFINED, SS_EXPIRED, and SS_TYPE_CAST_EXCEPTION. The value field should only be used if the value_status has a state of SS_VALID. It is possible for the client to receive a status of SS_TYPE_CAST_EXCEPTION if it is not possible to convert the string stored on the Status Server to an integer.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Following an ssPoll() API call, if the value of a data object changes on the Status Server beyond the deadband threshold specified, a new double-precision floating point number value will be stored at the memory address specified by the user.
PASSFAIL ssMonitorDouble(const char *name,
double deadband,
double *value,
ss_stat_t *value_status)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- deadband - Amount the Status Server data object must change by before the client is informed of a change in value. If this is set to 0, the client will be informed of all possible changes.
- value - Address where the integer value of the data object will be stored.
- value_status - Enumerated type which indicates the status of the value returned. Possible values include SS_VALID, SS_NONEXISTENT, SS_NOTDEFINED, SS_EXPIRED, and SS_TYPE_CAST_EXCEPTION. The value field should only be used if the value_status has a state of SS_VALID. It is possible for the client to receive a status of SS_TYPE_CAST_EXCEPTION if it is not possible to convert the string stored on the Status Server to a double-precision floating point number.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Following an ssPoll() API call, if the value of a data object changes on the Status Server, a new boolean value will be stored at the memory address specified by the user.
PASSFAIL ssMonitorBoolean(const char *name,
BOOLEAN *value,
ss_stat_t *value_status)
- name - Name of the data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- deadband - Amount the Status Server data object must change by before the client is informed of a change in value. If this is set to 0, the client will be informed of all possible changes.
- value - Address where the integer value of the data object will be stored.
- value_status - Enumerated type which indicates the status of the value returned. Possible values include SS_VALID, SS_NONEXISTENT, SS_NOTDEFINED, SS_EXPIRED, and SS_TYPE_CAST_EXCEPTION. The value field should only be used if the value_status has a state of SS_VALID. It is possible for the client to receive a status of SS_TYPE_CAST_EXCEPTION if it is not possible to convert the string stored on the Status Server to a boolean.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_OBJ_DOES_NOT_EXIST - Data object does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
The client has the option of placing a monitor on any directory. Within the Status Server, an update counter is maintained with each directory. This counter is incremented any time the value of a data object within that directory is modified. As a result, a client could place a monitor on a directory and perform a directory listing to get the new values of a directory following a change. One potential application where this could be useful is if a directory is used to store the values within a GUI drop-down list. If a new data object is added or removed, the client could place a monitor on the directory and update the possible options within the drop-down list dynamically.
It is possible to specify a deadband in order to limit the notifications of directory updates. In most cases, it will probably be desirable to be notified of all directory updates, in which case the deadband value must be set to 0.
Once a monitor is placed on a directory, the client must use the ssPoll() or ssWait() routine to retrieve updated monitor information.
Monitor changes to a directory can be handled one of two ways. The client can specify a callback function to be called whenever the contents of a directory change, or the client can specify memory locations where the directory count and value status will be updated. The value status enables the client to know when the state of a directory changes, since a directory can be either be valid or deleted. When a callback function is used, the updated value is always returned as a string
Following an ssPoll() or ssWait() API call, if the contents of a directory change, the new value and status will be passed to a user callback function, along with the arbitrary 'userptr' provided by the user.
PASSFAIL ssMonitorDirCallback(const char *path,
ssMonitorCallbackFunc userfunc,
void *userptr)
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_DOES_NOT_EXIST - Directory does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Following an ssPoll() or ssWait() API call, if the contents of a directory change, the client can specify a memory location to hold the new directory count and value status.
PASSFAIL ssMonitorDir(const char *path,
long *value,
ss_stat_t *status)
- path - Name of the directory path. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
- value - Address where the update count value of the directory will be stored.
- value_status - Enumerated type which indicates the status of the value returned. Since it is not possible for a directory to become expired or undefined, the only possible values the client should see are SS_VALID or SS_NONEXISTENT.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_DOES_NOT_EXIST - Directory does not exist.
- SS_SYNTAX_ERROR - The name specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine will remove a monitor from a data object or directory currently monitored by the client.
PASSFAIL ssUnmonitor(const char *name)
- name - Name of the directory or data object. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NODE_DOES_NOT_EXIST - Directory or data object does not exist.
- SS_MON_DOES_NOT_EXIST - The client has not previously placed a monitor on this directory or data object.
- SS_SYNTAX_ERROR - The name specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine will initiate a check whether any monitored information is available for retrieval by the C API and, if so, retrieve the monitored data from the Status Server and either call the client registered callback function or store the information in the memory locations whhich were previously defined during the setup of the monitor.
If a monitor request was made to monitor as an Integer, floating point, or boolean data types, a conversion will be performed from the string format received over the interface to the monitor requested data type. Any errors detected, either during the conversion process or from the data response sent by the Status Server, will be stored in the previously allocated memory location for return code information.
PASSFAIL ssPoll(void)
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine is identical to the ssPoll() except it allow for a timeout to be supplied which indicates how long the timeout should be on a select() when waiting for activity to occur on a socket. If activity occurs on the socket, it will initiate a check whether any monitored information is available for retrieval by the C API and, if so, retrieve the monitored data from the Status Server and either call the client registered callback function or store the information in the memory locations whhich were previously defined during the setup of the monitor.
If a monitor request was made to monitor as an Integer, floating point, or boolean data types, a conversion will be performed from the string format received over the interface to the monitor requested data type. Any errors detected, either during the conversion process or from the data response sent by the Status Server, will be stored in the previously allocated memory location for return code information.
PASSFAIL ssWait(int timeout_hundredths)
- timeout_hundredths - Time in hundredths of a second to wait for activity on the socket.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This function will force mailbox retrieval message to be sent to the Status Server and will wait for a response from the Status Server. It is useful to call this after setting up a set of new monitors. If monitored information is available for retrieval, it will retrieve the monitored data from the Status Server and either call the client registered callback function or store the information in the memory locations whhich were previously defined during the setup of the monitor.
If a monitor request was made to monitor as an Integer, floating point, or boolean data types, a conversion will be performed from the string format received over the interface to the monitor requested data type. Any errors detected, either during the conversion process or from the data response sent by the Status Server, will be stored in the previously allocated memory location for return code information.
PASSFAIL ssSync(void)
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine will retrieve the current working directory path for the client from the Status Server. The default path used by a client upon connection to the Status Server is ``/''. This will be the path returned by this routine unless the client has explicitly change the working path through a call to ssChdir().
const char *ssPwd(void)
This function will either return the current working directory path or NULL in case of an error. If the function should return NULL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine will change the current working directory for the client on the Status Server. The default path used by a client upon connection to the Status Server is ``/''.
PASSFAIL ssChdir(const char *path)
- path - Name of the directory path. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_DIR_DOES_NOT_EXIST - Directory does not exist.
- SS_SYNTAX_ERROR - The path specified is either NULL, or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Once a successful touch has been performed on a directory, it is possible for the client to request the removal of the directory from the Status Server.
The directory cannot be completely removed from the Status Server until the use counts for the directory are zero. This means that no clients currently have an outstanding touch, monitor, or directory listing on the directory. If the use counts are greater than zero, the object will be put in a state of ``NONEXISTENT'' and will be removed whenever the use counts become zero.
PASSFAIL ssRmdir(const char *path)
- path - Name of the directory path. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NODE_DOES_NOT_EXIST - Directory does not exist.
- SS_PERMISSION_DENIED - Either the client did not perform a previous touch on the directory, or an attempt was made to remove a system directory.
- SS_SYNTAX_ERROR - The path specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
When performing a directory listing, a Status Server directory must first be opened for reading. If the directory can be successfully opened, all the underlying contents can be retrieved by making successive calls to ssReaddir. Information from multiple directories can be retrieved by using the same regular expression matching rules used by the UNIX ``ls'' command.
PASSFAIL ssOpenDir(const char *path)
- path - Name of the directory path. The name can be specified with a fully-qualified absolute directory path, or as a name containing a relative directory path. Absolute references must be prefixed by a leading '/'. Relative path references may be prefixed with either a ``./'' or ``../''. Please note that upon the initial connection to the Status Server, the current path for the client will be ``/''. The name must be less than SS_MAX_NAME_SIZE which is defined in ss_define.h. In addition, the same regular expression matching rules used by the UNIX ``ls'' command can be included in the directory path.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NODE_DOES_NOT_EXIST - Directory does not exist.
- SS_SYNTAX_ERROR - The path specified is either NULL or invalid.
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine will retrieve the next directory line if a directory has previously been opened for reading. Upon successful completion a populated ss_dirent_t will be returned back to the client.
const ss_dirent_t *ssReadDir(void)
This function will either return a populated ss_dirent_t data structure, or NULL. If the function should return NULL, there are two reasons why this could occur. First, there are no more directory lines to be read. Secondly, an error occured. If the function should return NULL, the ssGetError() function must be called to determine if an error occured. If ssGetError() returns SS_NO_ERROR, the directory contents specified in the ssOpendir() function have all been retrieved. If ssGetError() is not SS_NO_ERROR, these are the possible error conditions why this routine may fail:
- SS_DIR_DOES_NOT_EXIST - This call was made before having called the ssOpendir() routine.
This routine will return back the file descriptor used for socket communication with the Status Server. As a result, the client could use the file descriptor within a select loop in order to be informed when the Status Server sends something to the client. This is particularly useful for a client which has placed monitors on Status Server variables.
Caution must be used when using the file descriptor. If it is used incorrectly, the socket communications between the client and Status Server may be adversely affected.
PASSFAIL ssGetFileDescriptor(int *fd)
- value - Address where the file descriptor value will be stored.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine turns on the tracing of all Status Server activity on the server itself. Please be VERY CAREFUL when using this option, since tracing will seriously affect the performance of the Status Server and could flood the CFHT_LOG.
Also, once tracing is turned off, it will stay on until it is turned off with the ssTraceOff() function call. It will not be turned off automatically when the client who requested it disconnects from the Status Server.
PASSFAIL ssTraceOn(void)
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine turns off the tracing of all Status Server activity on the server itself. The client which initiated the trace with the ssTraceOn function call does not need to be the client which requests the tracing to be turned off.
PASSFAIL ssTraceOff(void)
This routine will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine triggers a serialization of the Status Server data contents to a text file. The location of where the serialization text file is stored can be found by looking at the value of ``/proc/serialize/filename''. A serialization of the Status Server is also performed periodically at the interval specified by ``/proc/serialize/interval''.
PASSFAIL ssAutosave(void)
This routine will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
This routine allows for a timeout to be supplied which indicates how long the timeout interval should be on a select() call when waiting for activity to occur on a socket. If activity occurs on the socket, it will initiate a check whether any mirroring information is available for retrieval by the C API. If so, the mirroring data will be retrieved and the client registered callback function will be invoked.
PASSFAIL ssMirrorWait(int timeout_hundredths)
- timeout_hundredths - Time in hundredths of a second to wait for activity on the socket.
This function will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Following an ssMirrorWait() API call, if an object or directory changes on the Status Server, a mirror update transaction will be passed to a user callback function.
PASSFAIL ssMirrorCallback(ssMonitorCallbackFunc userfunc),
This function should always return PASS when called via the client API. If a failure should happen to be returned, this should be considered an internal error within the Status Server API library. At this point, the client API library will initiate an abort() causing a segmentation fault to occur.
This routine will initiate a serialization of the Status Server data followed by a shutdown of the server itself. This is a disruptive operation and will affect all clients currently connected to the Status Server. As a result, the utmost discretion must be used to determine when the routine should be used.
PASSFAIL ssShutdown(void)
This routine will return either PASS or FAIL. If the function should return FAIL, the reason for the error will be an enumerated type returned by the ssGetError() function. The error types which are possible when calling this routine are:
- SS_NOT_CONNECTED_TO_SERVER - This error should only if the client has never called ssLogon() or if the initial ssLogon() failed. Otherwise, a retry mechanism is in place to handle a temporary loss of connection. As a result, if a client has successfully logged on to the Status Server, it should not need to check for this return value.
Next: 5. Examples
Up: Status Server Client C
Previous: 3. API Primer
Contents
Tom Vermeulen
2008-02-07