The timesync main API library module has the file name timesapi.c. This module provides the programmer with a callable API that will access the timesync server. The QNX platform version of this API uses QNX message passing as the interprocess communication (IPC) method. All other platforms use the TCP socket interface to communicate to the timesync server. Note that there is no DOS version of this API. Any mention of QNX in this documentation refers to the QNX 4.x OS.
The TCP socket version of this API requires/uses the socloc API to communicate with a socloc server. The TCP details of the timesync server are obtained from the socloc server.
Timesync consists of an API (with two C modules) and server which can synchronize the date/time clock on many different platforms. A computer that is (either part time or full time) connected to the Internet will run the timesync server and one of the many available atomic time applications. The clock on this machine will automatically be updated by the atomic time application. All other computers in the environment will obtain the correct date/time by using this API to contact the timesync server.
Under TCP IPC method only, failover of a socloc server is provided in the socloc API and failover of a timesync server is provided in this API.
The functions defined in this API return a timesync code. These return codes are defined in the API header file timesync.h.
This method of operation is very simple and compatible with most OS's.
Here is a list of functions in the timesync main API module:
This module also requires the modules parse.c and logger.c.
This module requires the header files:
Prototype : int timesync_init(void) Returns : timesync code
This function should be called before attempting to communicate with the timesync server. This function will attempt to find a running timesync server by using the socloc API. A check is made to make sure that the socloc interface has already been initialized. Note that socloc is used only in TCP IPC.
Prototype : int timesync_get_datime(int *year, int *month, int *day,
int *hour, int *min, int *sec)
Parameters :
Name : year
Description : returned year
Name : month
Description : returned month
Name : day
Description : returned day of month
Name : hour
Description : returned hour
Name : min
Description : returned minute
Name : sec
Description : returned second
Returns : timesync code
This function will obtain the date and time from the timesync server.
Prototype : int timesync_status(void) Returns : timesync code
This function will get the running status of the current timesync server.
Prototype : int timesync_stop(char *passwd)
Parameters :
Name : passwd
Description : server termination password
Returns : timesync code
This function will attempt to halt the current timesync server. The server termination password is required and is case sensitive.
Prototype : int timesync_log_off(void) Returns : timesync code
This function will turn off server logging.
Prototype : int timesync_log_on(char *lfname)
Parameters :
Name : lfname
Description : path and file name of server log
Returns : timesync code
This function will activate server logging using the supplied path and file name of server log.
Prototype : int timesync_log_status(int *lflag, char *lfname)
Parameters :
Name : lflag
Description : returned log flag
Name : lfname
Description : returned log path and file name
Returns : timesync code
This function will obtain the timesync server log flag and log file name. Upon success, the log flag will be returned in the returned log flag and the server log file name will be returned in the returned log path and file name (which must be allocated to sufficient size by the caller).
Prototype : int timesync_service_name(char *sname)
Parameters :
Name : sname
Description : returned service name
Returns : timesync code
This function will obtain and return the timesync server service name into the returned service name which must be allocated to sufficient size by the caller. The TCP socket service name is always timesync. The QNX message passing service name is always /timesync.
Prototype : int timesync_version(char *ver)
Parameters :
Name : ver
Description : returned version
Returns : timesync code
This function will obtain and return the timesync server version ID string into the returned version which must be allocated to sufficient size by the caller.
Prototype : void timesync_get_active(char *hname, int *port)
Parameters :
Name : hname
Description : returned host name
Name : port
Description : returned port
This function will obtain the current timesync server TCP host name and port number. This function applies to TCP IPC method only. Upon success, the server host name will be returned in the returned host name which must be allocated by the caller to sufficient size and the server TCP port number will be returned in the returned port.
Prototype : int timesync_trans_num(long *transout)
Parameters :
Name : transout
Description : returned transaction count
Returns : timesync code
This function will get the timesync server transaction count. Upon success the transaction count will be loaded into the returned transaction count.
Prototype : int timesync_connect_num(int *connectout)
Parameters :
Name : connectout
Description : returned connection count
Returns : timesync code
This function will get the timesync server connection count. Upon success the connection count will be loaded into the returned connection count.
Prototype : void timesync_end(void)
This function will shutdown this API.
Prototype : static int ts_sr_code(int typ, char *parm)
Parameters :
Name : typ
Description : send code
Name : parm
Description : command parameters
Returns : timesync code
This private function will send and receive a message to the timesync server (using the low level function ts_lsr_code) that returns only a code. Function will failover to another timesync server (if one is available) upon a socket communication error (TCP only).
Prototype : static int ts_sr_char(int typ, char *parm, char *char_out)
Parameters :
Name : typ
Description : send code
Name : parm
Description : command parameters
Name : char_out
Description : returned reply
Returns : timesync code
This private function will send and receive a message to the timesync server that returns a string in addition to the return code (using the low level function ts_lsr_char). Function will failover to another timesync server (if one is available) upon a socket communication error (TCP only). The returned reply must be allocated by the caller to sufficient size.
Prototype : static int ts_failover(int dflag)
Parameters :
Name : dflag
Description : socloc delete flag
Returns : timesync code
This private function will failover to another timesync server if one is available. The socloc delete flag is used to indicate whether the socloc server should delete the current server entry. Function applies to TCP IPC method only.
Prototype : static int ts_lsr_code(int typ, char *parm)
Parameters :
Name : typ
Description : send code
Name : parm
Description : command parameters
Returns : timesync code
This private function will send and receive a message to the timesync server that returns only a code. The command parameters may be NULL or empty.
Prototype : static int ts_lsr_char(int typ, char *parm, char *char_out)
Parameters :
Name : typ
Description : send code
Name : parm
Description : command parameters
Name : char_out
Description : returned reply
Returns : timesync code
This private function will send and receive a message to the timesync server that returns a string in addition to the return code. The returned reply must be allocated by the caller to sufficient size. The command parameters may be NULL or empty.
Prototype : static int ts_client_connect(void) Returns : timesync code
This private function will attempt to connect to the currently defined timesync server. Applies to TCP IPC method only.
Prototype : static void ts_header(char *mname)
Parameters :
Name : mname
Description : function name
This private function will create a log entry (if enabled) to indicate entry into a timesync function.