Socloc Main API

This main socloc API module has the file name sloc.c. This callable API will communicate with a socloc server All platforms use the TCP socket interface to communicate to the socloc server. This API module contains public and private functions. Unless otherwise indicated, a function is assumed to be public. Note that there is no DOS or QNX version of this API. Any mention of QNX> in this documentation refers to the QNX> 4.x OS.

Automatic failover is built into this API. If a socloc server is found to be not responding, functions in this API will cause a failover to another socloc server.

Starting in GPL package version 1.33, this module has been re-written to connect once and keep the socket open until closed or upon a socket communication error.

Here is a list of functions in this module:

# Public Functions

- sloc_initialize
- sloc_end
- sloc_log_off
- sloc_log_on
- sloc_log_status
- sloc_add
- sloc_config_add
- sloc_config_delete
- sloc_status
- sloc_service_name
- sloc_version
- sloc_delete
- sloc_find
- sloc_config_find
- sloc_find_list
- sloc_ll_find
- sloc_ll_find_list
- sloc_get_list
- sloc_put_list
- sloc_config_update
- sloc_config_get_list
- sloc_config_put_list
- sloc_dump_debug
- sloc_config_dump_debug
- sloc_terminate
- sloc_get_active_socloc
- sloc_set_active_socloc
- sloc_is_init
- sloc_trans_num
- sloc_connect_num
- sloc_term_api

# Private Functions

- sloc_connect
- sloc_ll_status
- sloc_sr_int
- sloc_lsr_int
- sloc_sr_long
- sloc_lsr_long
- sloc_sr_code
- sloc_lsr_code
- sloc_sr_char
- sloc_lsr_char
- sloc_failover
- sloc_reload_config_list
- sloc_client_connect
- sloc_ll_client_connect

# Module Global Data

This socloc API contains the following global data:

    #ifdef OS_WIN32
    SOCKET slclientSocket;        // client socket
    SOCKADDR_IN slsockClientAddr; // client address structure
    LPHOSTENT lpHostEnt;          // host info structure
    #endif

    #ifdef OS_UNIX
    int slclientSocket;
    struct sockaddr_in slsockClientAddr;
    struct hostent *lpHostEnt;
    #endif

    char sloc_hostname[128];      // host name of 'socloc' server
    int sloc_port = 0;            // port 'socloc' is using

The current socloc server details are stored in sloc_hostname and sloc_port. These connection specs are trusted. If the server is found to be not responding, this API module will attempt to automatically failover to another socloc server.

Note that the link list of socloc servers (the config list) is actually stored in the socloc API configuration module.

Starting in GPL package version 1.33, this API is no longer bound to the socloc server. The socloc server now has its own API that performs communication between the server and other socloc servers as well as other socket servers.

# Module Dependencies

This module is part of the socloc API and needs to be linked with the following modules:

- fio.c
- parse.c
- logger.c
- ipcomm.c
- slconfig.c
- sliocode.c
- sconnect.c

In the Linux and Unix platform, this module is compiled along with the other socloc modules as part of the script csocloc. A good example of a shell script for a client application that uses this API is mksockc.

# Module Header Files

This module depends on the following header files:

- stdhead.h
- flsocket.h
- ipcomm.h
- sloc.h
- socloc.h
- slconfig.h
- sconnect.h
- sliocode.h

# Module Functions

## sloc_initialize

    Prototype   : int sloc_initialize(void)

    Returns     : socloc code

This function will attempt to initialize the socloc interface by:

- reading the socloc startup file
- attempt to connect to a socloc server

The socloc startup file must exist and be in the same directory as the binary/executable.

## sloc_end

    Prototype   : void sloc_end(void)

This function will stop communication with a socloc server. The client socket is closed and the global details are wiped.

## sloc_log_off

    Prototype   : int sloc_log_off(void)

    Returns     : socloc code

This function will attempt to turn off socloc server logging. If server logging is already off, the function will return SL_LOG_ALREADY_OFF as defined in socloc.h.

## sloc_log_on

    Prototype   : int sloc_log_on(char *lname)
    Parameters  :
          Name  : lname
    Description : log file name

    Returns     : socloc code

This function will attempt to turn on socloc server logging. The log file name lname is optional. If the log file name is given, it must be valid and the socloc server must be able to write to this file. If no file name is given, the socloc server will use SL_LOG_FILE as defined in socloc.c. If server logging is already on, the function will return SL_LOG_ALREADY_ON as defined in socloc.h.

## sloc_log_status

    Prototype   : int sloc_log_status(int *lflag, char *lfname)
    Parameters  :
          Name  : lflag
    Description : returned log flag (1=on,0=off)

          Name  : lfname
    Description : returned log file name

    Returns     : socloc code

This function will attempt to get the status of socloc server logging. The log status will be in the returned log flag and the current log file name will be in the returned log file name which must be already allocated to sufficient size.

## sloc_add

    Prototype   : int sloc_add(char *sname, char *hname, int port, char *ip)
    Parameters  :
          Name  : sname
    Description : service name

          Name  : hname
    Description : host name

          Name  : port
    Description : TCP port number

          Name  : ip
    Description : IP address

    Returns     : socloc code

This function will attempt to add a socket server to the list of available socket servers. All parameters are required except ip which may be a null pointer. If ip is not a null pointer, a valid IP address (IP v4 dotted notation) is required. The port is required to be unique across all socket and socloc servers.

## sloc_config_add

    Prototype   : int sloc_config_add(char *hname, int port, char *ip)
    Parameters  :
          Name  : hname
    Description : host name

          Name  : port
    Description : TCP port number

          Name  : ip
    Description : IP address

    Returns     : socloc code

This function will attempt to add a socloc server to the list of available socloc servers. All parameters are required except ip which may be a null pointer. If ip is not a null pointer, a valid IP address (IP v4 dotted notation) is required. The port is required to be unique across all socket and socloc servers.

## sloc_config_delete

    Prototype   : int sloc_config_delete(int port)
    Parameters  :
          Name  : port
    Description : TCP port number

    Returns     : socloc code

This function will attempt to delete a socloc server from the list of available socloc servers. Since all TCP/IP ports are required to be unique, all socloc delete API functions use the TCP port as the delete key.

## sloc_status

    Prototype   : int sloc_status(void)

    Returns     : socloc code

This function will attempt to get the status of the socloc server. If the server is operational, the typical response is SL_OK as defined in socloc.h.

## sloc_service_name

    Prototype   : int sloc_service_name(char *sname)
    Parameters  :
          Name  : sname
    Description : returned service name

    Returns     : socloc code

This function will attempt to get the service name of a socloc server. Sname is required to be not null and already allocated to sufficient size for the returned service name. This function is kind of silly because the returned service name should always be socloc. It is included for completeness and compatibility with all other socket servers. The socloc server is required to be able to interpret the common socket send code SOCKET_SEND_SERVICE_NAME as defined in flsocket.h.

## sloc_version

    Prototype   : int sloc_version(char *version)
    Parameters  :
          Name  : version
    Description : returned version

    Returns     : socloc code

This function will attempt to get the version string of a socloc server. Version is required to be not null and already allocated to sufficient size for the returned version string. The socloc server is required to be able to interpret the common socket send code SOCKET_SEND_VERSION as defined in flsocket.h.

## sloc_connect

    Prototype   : static int sloc_connect(char *hname, int port)
    Parameters  :
          Name  : hname
    Description : host name

          Name  : port
    Description : TCP port number

    Returns     : socloc code

This private function will attempt to connect to a specific socloc server. All parameters are required. A socket connection will be attempted verified by acquiring the service name of the server using the function sloc_service_name. This service name must match the socloc service name defined as SL_SERVICE_NAME in socloc.h.

## sloc_delete

    Prototype   : int sloc_delete(int port)
    Parameters  :
          Name  : port
    Description : TCP port number

    Returns     : socloc code

This function will attempt to delete a socket server from the list of available socket servers. Since all TCP ports are required to be unique, all socloc delete API functions use the TCP port as the delete key.

## sloc_find

    Prototype   : int sloc_find(char *sname, char *hname, int *port, char *ip)
    Parameters  :
          Name  : sname
    Description : service name

          Name  : hname
    Description : returned host name

          Name  : port
    Description : returned TCP port number

          Name  : ip
    Description : returned IP address

    Returns     : socloc code

This function will attempt to find the details of a socket server using only the service name (sname). All parameters are required except ip which may be a null pointer. The contents of hname, port and ip upon entry will be cleared by this function. The host name, port number and (optionally) the IP address of the first responding server with the matching sname will be loaded into the returned parameters upon success. The input sname is converted to a connect string to be parsed by the socloc server. If you need to locate a socket server by more than the service name, use the function sloc_ll_find instead.

## sloc_config_find

    Prototype   : int sloc_config_find(char *hname, int *port, char *ip)
    Parameters  :
          Name  : hname
    Description : (returned) host name

          Name  : port
    Description : (returned) TCP port number

          Name  : ip
    Description : (returned) IP address

    Returns     : socloc code

This function will attempt to find the details of a socloc server based on the provided information. Each parameter must not be null except for the ip address. If a parameter contains a value (non-empty string or non-zero integer) when the function is called, that detail will be used to attempt to find a matching socloc server. At least one parameter value is required. The non-empty/zero input values are converted to a connect string to be parsed by the socloc server. When a match is found, the missing details (parameters that are zero or empty) will be loaded with the information on the matched socloc server.

## sloc_find_list

    Prototype   : int sloc_find_list(char *sname, char *list_out)
    Parameters  :
          Name  : sname
    Description : service name

          Name  : list_out
    Description : returned
    server list

    Returns     : socloc code

This function will attempt to find the details of one or more socket servers using only the service name (sname). All parameters are required. The input sname is converted to a connect string to be parsed by the socloc server. The returned list uses SL_LIST_DELIM (as defined in socloc.h) to delimit each server entry. Each returned entry is in the following format:

       sname hname port [ip]

Any returned value that contains spaces will be quoted. The TCP/IP address will only be present if it was registered with the socloc server. If you wish to obtain a list of socket servers by more than the service name, use the function sloc_ll_find_list instead.

## sloc_ll_find

    Prototype   : int sloc_ll_find(char *sn, char *hn, int *port, char *ip)
    Parameters  :
          Name  : sn
    Description : service name

          Name  : hn
    Description : host name

          Name  : port
    Description : TCP port number

          Name  : ip
    Description : IP address

    Returns     : socloc code

This function will attempt to find the details of a socket server using any supplied parameter(s). All parameters are required to be not a null pointer except ip. The function will convert the supplied input parameters into a connect string to be parsed by the socloc server. If a socket server match is found, any empty or zero parameter will be filled in with the matched socket server detail. If you wish to locate a socket server by only the service name, use the function sloc_find instead.

## sloc_ll_find_list

    Prototype   : int sloc_ll_find_list(char *sn, char *hn, int *pt, char *ip,
                                        char *list_out)
    Parameters  :
          Name  : sn
    Description : service name

          Name  : hn
    Description : host name

          Name  : pt
    Description : TCP port number

          Name  : ip
    Description : IP address

          Name  : list_out
    Description : returned server list

    Returns     : socloc code

This function will attempt to find the details of one or more socket servers using all supplied parameter(s). All parameters are required to be not null pointers. At least one parameter must contain valid data (not a empty string or zero integer value). All input parameter(s) that are not empty strings or zero values are converted to a connect string to be parsed by the socloc server. The returned list uses SL_LIST_DELIM (as defined in socloc.h) to delimit each server entry. Each returned entry is in the following format:

       sname hname port [ip]

Any returned value that contains spaces will be quoted. The IP address will only be present if it was registered with the socloc server. If you wish to obtain a list of socket servers by just the service name, use the function sloc_find_list instead.

## sloc_get_list

    Prototype   : int sloc_get_list(char *list_out)
    Parameters  :
          Name  : list_out
    Description : returned
    server list

    Returns     : socloc code

This function will attempt to get the details of all socket servers known to socloc. The returned list uses SL_LIST_DELIM (as defined in socloc.h) to delimit each server entry. Each returned entry is in the following format:

       sname hname port [ip]

Any returned value that contains spaces will be quoted. The IP address will only be present if it was registered with the socloc server.

## sloc_put_list

    Prototype   : int sloc_put_list(char *list_in)
    Parameters  :
          Name  : list_in
    Description :
    socket server list

    Returns     : socloc code

This function will send a socket server list to a socloc server. The socloc server will then delete the existing socket server list and replace it with list_in. The input list is expected to be delimited by SL_LIST_DELIM (as defined in socloc.h). Each socket server entry is expected in the following format:

       sname hname port [ip]

Any value that contains spaces must be quoted. The IP address is optional.

## sloc_config_update

    Prototype   : int sloc_config_update(void)

    Returns     : socloc code

This function will update a socloc server or client application config list (the list of known socloc servers aka: the config list) and write this current list to the socloc startup file SL_CONFIG_FILE_NAME (as defined in slconfig.h). The file will be written to the current directory.

This function operates by calling sloc_config_get_list to acquire a copy of the current config list. This list is placed into memory and replacing the old list by calling the function sl_config_put_list. A new socloc startup file is then written replacing the old file by calling the function sl_config_write_file.

## sloc_config_get_list

    Prototype   : int sloc_config_get_list(char *list_out)
    Parameters  :
          Name  : list_out
    Description : returned socloc server list

    Returns     : socloc code

This function will attempt to get the details of all socloc servers known. The returned list uses SL_LIST_DELIM (as defined in socloc.h) to delimit each server entry. Each returned entry is in the following format:

       hname port [ip]

Any returned value that contains spaces will be quoted. The IP address will only be present if it was registered with the socloc server.

## sloc_config_put_list

    Prototype   : int sloc_config_put_list(char *list_in)
    Parameters  :
          Name  : list_in
    Description : socloc server list

    Returns     : socloc code

This function will send a socloc server list to the current socloc server. The socloc server will then delete the existing socloc server list and replace it with list_in. The input list is expected to be delimited by SL_LIST_DELIM (as defined in socloc.h). Each socloc server entry is expected in the following format:

       hname port [ip]

Any value that contains spaces must be quoted. The IP address is optional.

## sloc_dump_debug

    Prototype   : int sloc_dump_debug(void)

    Returns     : socloc code

This function will send a request to the socloc server to dump/display the contents of the current socket server link list.

## sloc_config_dump_debug

    Prototype   : int sloc_config_dump_debug(void)

    Returns     : socloc code

This function will send a request to the socloc server to dump/display the contents of the current socloc server link list.

## sloc_terminate

    Prototype   : int sloc_terminate(char *passwd)
    Parameters  :
          Name  : passwd
    Description : socloc server termination password

    Returns     : socloc code

This function will attempt to terminate the current socloc server. The passwd must match (including case sensitivity) the termination password SL_TERM_PASSWD as defined in the socloc server module socloc.c. Upon acceptance of the password, the socloc server will broadcast the socloc server termination to all other known socloc servers.

## sloc_get_active_socloc

    Prototype   : int sloc_get_active_socloc(char *hname, int *port)
    Parameters  :
          Name  : hname
    Description : returned host name

          Name  : port
    Description : returned TCP port number

    Returns     : socloc code

This function will retrieve the host name (hname) and TCP port number (port) of the current socloc server. Both parameter pointers must not be null and the host name must already be allocated to sufficient size for the returned host name.

## sloc_set_active_socloc

    Prototype   : int sloc_set_active_socloc(char *hname, int port)
    Parameters  :
          Name  : hname
    Description : host name

          Name  : port
    Description : TCP port number

    Returns     : socloc code

This function will attempt to set the current active socloc server. The server must be present in the socloc config list, must also be currently responding and the server must be a socloc server. This will be verified by calling the function sloc_connect which will in turn call the function sloc_service_name. Upon successful completion, the new server will become the current socloc server.

## sloc_is_init

    Prototype   : int sloc_is_init(void)

    Returns     : socloc code

This function will determine whether this API has been initialized. The API is considered initialized when there is an active host name in sloc_hostname and a positive port number in sloc_port. Function returns SL_OK if the API has been initialized, SL_NO_INIT otherwise.

## sloc_trans_num

    Prototype   : int sloc_trans_num(long *transout)
    Parameters  :
          Name  : transout
    Description : returned transaction count

    Returns     : socloc code

This function will get the socloc server transaction count. Upon success the transaction count will be loaded into the returned transaction count.

## sloc_connect_num

    Prototype   : int sloc_connect_num(int *connectout)
    Parameters  :
          Name  : connectout
    Description : returned connection count

    Returns     : socloc code

This function will get the socloc server connection count. Upon success the connection count will be loaded into the returned connection count.

## sloc_term_api

    Prototype   : void sloc_term_api(void)

This function will shutdown this API. Close the socket in use, wipe the globals indicating the server host name and port and delete the local socloc config link list.

## sloc_sr_int

    Prototype   : static int sloc_sr_int(int typ, char *parm, int *ival)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

          Name  : ival
    Description : returned integer value

    Returns     : socloc code

This private function will attempt to send a request to the current active socloc server that will return an integer value in addition to the socloc code. The parameter typ is required to be a valid send command code, parm may be a null pointer or an empty string if there are no command parameters, ival must not be a null integer pointer. Upon failure, this function will failover to another socloc server.

## sloc_lsr_int

    Prototype   : static int sloc_lsr_int(int typ, char *parm, int *ival)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

          Name  : ival
    Description : returned integer value

    Returns     : socloc code

This private function will send and receive a message to the socloc server that returns an integer as well as a return code. Its ok if parm is NULL or empty.

## sloc_sr_long

    Prototype   : static int sloc_sr_long(int typ, char *parm, long *lgval)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

          Name  : lgval
    Description : returned long integer value

    Returns     : socloc code

This private function will attempt to send a request to the current active socloc server that will return a long integer value in addition to the socloc code. The parameter typ is required to be a valid send command code, parm may be a null pointer or an empty string if there are no command parameters, lgval must not be a null long integer pointer. A current active socloc server must be found on entry. Upon failure, this function will failover to another socloc server.

## sloc_lsr_long

    Prototype   : static int sloc_lsr_long(int typ, char *parm, long *lgval)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

          Name  : lgval
    Description : returned long integer value

    Returns     : socloc code

This private function will send and receive a message to the socloc server that returns a long integer as well as a return code. Its ok if 'parm' is NULL or empty.

## sloc_sr_code

    Prototype   : static int sloc_sr_code(int typ, char *parm)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

    Returns     : socloc code

This private function will attempt to send a request to the current active socloc server that will return no other value except the socloc code. The parameter typ is required to be a valid send command code, parm may be a null pointer or an empty string if there are no command parameters. Upon failure, this function will failover to another socloc server.

## sloc_lsr_code

    Prototype   : static int sloc_lsr_code(int typ, char *parm)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

    Returns     : socloc code

This private function will send and receive a message to the socloc server that returns only a return code. Its ok if parm is NULL or empty.

## sloc_sr_char

    Prototype   : static int sloc_sr_char(int typ, char *parm, char *sval)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

          Name  : sval
    Description : returned string value

    Returns     : socloc code

This private function will attempt to send a request to the current active socloc server that will return a string in addition to the socloc code. The parameter typ is required to be a valid send command code, parm may be a null pointer or an empty string if there are no command parameters. The returned string value must already be allocated to sufficient size by the caller. A current active socloc server must be found on entry. Upon failure, this function will failover to another socloc server.

## sloc_lsr_char

    Prototype   : static int sloc_lsr_char(int typ, char *parm, char *sval)
    Parameters  :
          Name  : typ
    Description : send command code

          Name  : parm
    Description : command parameter(s)

          Name  : sval
    Description : returned string value

    Returns     : socloc code

This private function will send and receive a message to the socloc server that returns a string as well as a return code. The returned string value must already be allocated to sufficient size for the receiving string. Its ok if parm is NULL or empty.

## sloc_failover

    Prototype   : static int sloc_failover(void)

    Returns     : socloc code

This private function will failover to another socloc server if one is available.

## sloc_reload_config_list

    Prototype   : static int sloc_reload_config_list(void)

    Returns     : socloc code

This private function will get a fresh copy of the socloc config list from the current socloc server and place into memory.

## sloc_client_connect

    Prototype   : int sloc_client_connect(void)

    Returns     : socloc code

This private function will first attempt to connect to the current active socloc server (of which there must be one) using the function sloc_ll_client_connect.

## sloc_ll_client_connect

    Prototype   : int sloc_ll_client_connect(void)

    Returns     : socloc code

This private function will attempt to connect to the current active socloc server by opening a socket to the server. This function will not attempt a failover if the connection attempt fails.

Goto Top | Socloc Overview | Future Lab Home | Contact Webmaster | Feedback

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