This section outlines the available functions within the C API for clients to interact with the Status Server. More details regarding the functionality provided by the client API is provided in the subsequent API Reference section.
The client will initiate a connection request to the Status Server. For traceability purposes, the Client API will send a subsequent message with the UNIX Process ID and program name. When a client chooses to establish a connection with the Status Server, it must decide whether the Client API should automatically try to re-establish a connection to the Status Server if the connection is broken and whether a socket timeout threshold is desired.
A predefined socket timeout threshold will be defined as part of the Client API. This threshold can be modified by setting a new timeout value via the timeout parameter. If this parameter is less than or equal to 0, the system default will be used. Otherwise, the new value will be used for the socket timeout. The timeout must be specified in seconds.
It is possible for the socket connection between the Client API and Status Server to go down unexpectedly. The Client API will provide the option to retry until the connection is re-established. If the retry option is used, the client program will be blocked until the socket connection is re-established. Any time the Client API retries the connection, it will resend all ``touch'', ``touchdir'' and ``monitor'' commands prior to processing the current API call. When the retry_pause parameter is set to a value greater than or equal to 0, automatic reconnection is turned on. If this value is less than 0, automatic reconnection is turned off. In addition, the retry_pause indicates the number of seconds the Client API will wait to initiate another connection to the Status Server.
The return value from the API call will indicate whether the operation was successful. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssLogon(const char *program_name,
const int timeout,
const int retry_pause)
In addition, the client has the option of setting up client callback functions with the C API for the case where a timeout of the socket occurs or when the socket connection between the Client API and Status Server goes down unexpectedly. If automatic reconnection is enabled, the client callback for disconnection should never be called. Instead a function within the the Client API will be called to initiate a retry.
void ssRetryCallback(ss_callback_func retry_fn)
void ssDiscCallback(ss_disc_func disc_fn)
The C API will disconnect from the Status Server by closing the socket. As part of the disconnect, the Client API must clean up internal resources associated with the Status Server connection. This is also true for the case where the client detects that the client connection with the Status Server has been broken. When using the C API, a disconnect request should not fail unless a client connection isn't available. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
If the client makes a call to ssLogoff, this will not cause the automatic retry mechanism to trigger. A connection to the Status Server must be subsequently established with another call to ssLogon.
PASSFAIL ssLogoff(void)
The client must specify the name of the object and optionally specify a comment or lifetime. If a lifetime is not specified, the value of the object will not expire. When using the C API, there should not be any cases where a touch would fail.
void ssTouchObject(const char *name,
const char *comment,
const int *lifetime)
The client has the ability to update Status Server objects of the following types:
Clients using a telnet session will send all data as strings across the socket interface. This is the same way data is sent to the Status Server by the Client API. In order to support the ability to handle 8 bit ASCII characters within a string, the string is encoded into 7 bit ASCII printable characters by the Client API prior to being sent across the interface. In addition, boolean, floating point, and integer data is converted to a string prior to being sent to the Status Server. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssPutInt(const char *name,
const int value)
PASSFAIL ssPutDouble(const char *name,
const double value)
PASSFAIL ssPutString(const char *name,
const char *value)
PASSFAIL ssPutBoolean(const char *name,
const BOOLEAN value)
The client will make a request to retrieve the value of an object. If the request is successful, the value of the Status Server object will be converted from it's encoded string format to the type requested via the C API call. This value will then be stored in the address specified by the user. If the request is not successful, the details regarding the error will be stored in cfht_errno.
PASSFAIL ssGetInt(const char *name,
int *value)
PASSFAIL ssGetDouble(const char *name,
double *value)
PASSFAIL ssGetString(const char *name,
char *value)
PASSFAIL ssGetBoolean(const char *name,
BOOLEAN *value)
For clients using the C API, the status of the object will be stored in a memory location specified by the user. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssStat(const char *name,
ss_stat_t *status)
The client has the option of placing a monitor on any object with optional age and deadband values. If deadband and/or deadband are not desired, it can be set to 0. This indicates the client would like to monitor each change to an object value. When monitors are applied using the C API library, an address must be supplied for both the monitored object value as well as the return code. The return code enables the server to notify a client whenever the state of an object changes. As a result, the client can be informed when an object becomes expired, NULL, or removed.
Once the client is informed that a monitor was successfully applied, the Client API will store an association between the name of the object and the value and return value addresses for the object. The Client API can then process monitor update notification messages and store the value and return codes in the proper memory locations for subsequent use by the client. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssMonitorInt(const char *name,
const int deadband,
const int age,
int *value,
ss_ret_t *value_status)
PASSFAIL ssMonitorDouble(const char *name,
const double deadband,
const int age,
double *value,
ss_ret_t *value_status)
PASSFAIL ssMonitorString(const char *name,
const size_t max_length,
const int age,
char *value,
ss_ret_t *value_status)
PASSFAIL ssMonitorBoolean(const char *name,
const int age,
BOOLEAN *value,
ss_ret_t *value_status)
The client will initiate the object removal request and should process the return value. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
ss_ret_t ssKillMonitor(const char *name)
The client will initiate the monitor retrieval request and must be prepared to process the return information sent by the Status Server. The client will process each line of data until it receives the end-of-transaction indicator.
For clients using the C API, each line of monitored data will be converted and stored in the memory location which was previously defined during the setup of the monitor. Integer, floating point, and boolean data types will be converted 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. From the C API point of view, this call should not fail unless a client connection is not available. When using the C API, there should not be any cases where a ``poll'' would fail.
void ssPoll(void)
The client will initiate the removal request and should check the return value to determine whether the operation was successful. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssRemove(const char *name)
The client will initiate the current directory request and receive a pointer to a string containing the directory path. When using the C API, there should not be any cases where a request to retrieve the current directory path would fail.
char *ssPwd(void)
The client will initiate the change current directory request and should check the return value to determine whether the operation was successful. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssChdir(const char *path)
Prior to removing a directory and its contents the client must perform a ``touchdir'' on the directory. The ``touchdir'' also enables a client to create the directory if it doesn't already exist and to alter the comment associated with a directory. When using the C API, there should not be any cases where a touchdir would fail.
void ssTouchDir(const char *path,
const char *comment)
The client will initiate the directory removal request and should check the return value to determine whether the operation was successful. If the call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssRmdir(const char *path)
The client will initiate the directory content retrieval request and must be prepared to process the return information sent by the Status Server. The client will process each line of data until it receives the end of message indicator.
When using the C API, the client will first make a request to open the directory. The directory can be opened with a recursive option indicating that all underlying contents will be returned as part of the request. The return value from the ssOpendir call will indicate whether the directory could successfully be opened. The client must then call ssReaddir until it receives a NULL indicating that all the directory contents have been returned. Directory contents will be returned in an Object Name=Value and Dir=Name format. For example, /i/cfh12k/etype=''FLAT''. If the ssOpendir call should happen to fail, more details regarding the failure will be available in cfht_errno.
PASSFAIL ssOpendir(const char *path)
char *ssReaddir(void)
The client can initiate a trace on all Status Server activity. When using the C API, there should not be any cases where a trace initiation request would fail.
void ssTraceOn(void)
A client can stop a trace currently running in the Status Server. When using the C API, there should not be any cases where a request to stop a trace would fail. If a trace was not running and a request was made to stop a trace, the Status Server will still send back a positive response.
void ssTraceOff(void)
A client can request that the Status Server serialize itself to a file. When using the C API, there should not be any cases where a serialization request would fail. It is possible that the serialization itself might fail, but the Status Server does not send a response back to the client once the Serialization is completed. Instead, it sends back a response once it receives a request to initiate serialization.
void ssAutosave(void)
The client can request a shutdown of the Status Server. This function will return once the message is sent to the Status Server.
void ssShutdown(void)