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:
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.
This module is part of the socloc API and needs to be linked with the following modules:
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.
This module depends on the following header files:
Prototype : int sloc_initialize(void) Returns : socloc code
This function will attempt to initialize the socloc interface by:
The socloc startup file must exist and be in the same directory as the binary/executable.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Prototype : static int sloc_failover(void) Returns : socloc code
This private function will failover to another socloc server if one is available.
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.
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.
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.