Timesync Main API Module

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.

# What is Timesync and How Does It Work

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:

- timesync_init
- timesync_get_datime
- timesync_status
- timesync_stop
- timesync_log_off
- timesync_log_on
- timesync_log_status
- timesync_service_name
- timesync_version
- timesync_get_active
- timesync_trans_num
- timesync_connect_num
- timesync_end
- ts_sr_code
- ts_sr_char
- ts_failover
- ts_lsr_code
- ts_lsr_char
- ts_client_connect
- ts_header

# Module Dependencies

This module also requires the modules parse.c and logger.c.

# Module Header Files

This module requires the header files:

- stdhead.h
- flsocket.h
- timesync.h

# Module Functions

## timesync_init

    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.

## timesync_get_datime

    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.

## timesync_status

    Prototype  : int timesync_status(void)

    Returns    : timesync code

This function will get the running status of the current timesync server.

## timesync_stop

    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.

## timesync_log_off

    Prototype  : int timesync_log_off(void)

    Returns    : timesync code

This function will turn off server logging.

## timesync_log_on

    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.

## timesync_log_status

    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).

## timesync_service_name

    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.

## timesync_version

    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.

## timesync_get_active

    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.

## timesync_trans_num

    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.

## timesync_connect_num

    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.

## timesync_end

    Prototype   : void timesync_end(void)

This function will shutdown this API.

## ts_sr_code

    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).

## ts_sr_char

    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.

## ts_failover

    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.

## ts_lsr_code

    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.

## ts_lsr_char

    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.

## ts_client_connect

    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.

## ts_header

    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.

Goto Top | GPL Software Overview | GPL Library
Future Lab Home | Contact Webmaster | Feedback

Copyright © 2002-2006 Future Lab, Last Updated Jun 30, 2006