Socloc Configuration API

This configuration socloc API module has the file name slconfig.c. This callable API will manage the local application copy of the socloc config link list. This local copy could be used by a client, socket server or socloc server application. This API module does not contain any socket calls. This API module contains only public functions. Note that there is no DOS or QNX version of this API.

Here is a list of functions in this module:

- sl_config_read
- sl_config_get_first
- sl_config_get_nentries
- sl_config_get_nth
- sl_config_find
- sl_config_add
- sl_config_port_exist
- sl_config_host_exist
- sl_config_delete
- sl_config_delete_all
- sl_config_get_list
- sl_config_put_list
- sl_config_write_file
- sl_config_get_ils
- sl_config_set_ils
- sl_config_list
- sl_config_debug

# Module Global Data

This socloc API contains the following global data:

       struct sl_config_entry *sl_base = SL_NULL;

This single pointer is the base pointer to the config link list. The definition of the config link list is contained in the header file slconfig.h

# 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
- sloc.c
- sliocode.c
- sconnect.c

In the Linux or Unix platform, this module is compiled along with the other socloc modules as part of the script csocloc. A good example of a Unix 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
- socloc.h
- slconfig.h

# Module Functions

## sl_config_read

    Prototype   : int sl_config_read(char *fname)
    Parameters  :
          Name  : fname
    Description : socloc startup file name

    Returns     : socloc code

This function will attempt to read and parse the socloc startup file fname. Upon success, the contents of the startup file will be placed into the config link list.

## sl_config_get_first

    Prototype   : int sl_config_get_first(char *hn, int *port, char *ip)
    Parameters  :
          Name  : hn
    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 get the details of the first entry in the config link list. The server entry is not tested to see if the socloc server is responding. If the running application is a socloc server, the config link list entry referring to itself will be ignored. All parameters are required to be not null pointers except ip. String pointers are required to point to already allocated storage of sufficient size to hold the returned string.

## sl_config_get_nentries

    Prototype   : int sl_config_get_nentries(int *nentries)
    Parameters  :
          Name  : nentries
    Description : returned number of entries

    Returns     : socloc code

This function will attempt to get the number of entries in the config link list. If the running application is a socloc server, the config link list entry referring to itself will be ignored (not counted). Nentries is required to be not null.

## sl_config_get_nth

    Prototype   : int sl_config_get_nth(int pos, char *hn, int *port, char *ip)
    Parameters  :
          Name  : pos
    Description : config link list position

          Name  : hn
    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 get the details of the pos entry in the config link list. The server entry is not tested to see if the socloc server is responding. If the running application is a socloc server, the config link list entry referring to itself will be ignored (not counted). All parameters are required to be not null pointers except ip. String pointers are required to point to already allocated storage of sufficient size to hold the returned string.

## sl_config_find

    Prototype   : int sl_config_find(char *hn, int *port, char *ip)
    Parameters  :

          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 specific socloc server. Function will use any of the supplied hn, port or ip to locate the server entry in the config link list. Any of the three input parameters may be a null pointer. At least one parameter value must be present. Upon a successful match, the server details missing will be loaded from the config link list information. Any parameter that is null upon entry will indicate that the return value is not desired. Note that this function will only search the application local config link list.

## sl_config_add

    Prototype   : int sl_config_add(char *hn, int port, char *ip)
    Parameters  :
          Name  : hn
    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 application local config link list. All pointer parameters except the IP address are required to be not null. Port is required to be a positive integer. Function works by first checking for a duplicate TCP port in use by calling the function sl_config_port_exist. Since there is also a requirement that no more than one socloc server may be run on a single machine, this function will then check for a duplicate host name by calling the function sl_config_host_exist. Once these two tests have been passed, the entry is added to the end of the application local config link list.

## sl_config_port_exist

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

    Returns     : socloc code

This function will check the supplied port against all ports in use in the application local config link list. If the supplied port already exists in the application local config link list, the function will return SL_PORT_EXIST as defined in the header file socloc.h.

## sl_config_host_exist

    Prototype   : int sl_config_host_exist(char *hname)
    Parameters  :
          Name  : hname
    Description : host name

    Returns     : socloc code

This function will check the supplied hname against all host names in use in the application local config link list. If the supplied host name already exists in the application local config link list, the function will return SL_CONFIG_HOST_EXIST as defined in the header file socloc.h. Note that only the application local config link list will be checked.

## sl_config_delete

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

    Returns     : socloc code

This function will delete a socloc server entry from the application local config link list.

## sl_config_delete_all

    Prototype   : int sl_config_delete_all(void)

    Returns     : socloc code

This function will delete the entire application local config link list. The base pointer to this link list ( sl_base is also set to null).

## sl_config_get_list

    Prototype   : int sl_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 listed in the application local config link list. 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 present in the link list entry.

## sl_config_put_list

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

    Returns     : socloc code

This function will replace the current application local config link list with list_in which 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.

## sl_config_write_file

    Prototype   : int sl_config_write_file(void)

    Returns     : socloc code

This function will write the entire application local config link list to the socloc startup file.

## sl_config_get_ils

    Prototype   : int sl_config_get_ils(int port, int *ils_flag)
    Parameters  :
          Name  : port
    Description : TCP port number

          Name  : ils_flag
    Description : returned ils_flag

    Returns     : socloc code

This function will get the value of the is_local_server flag for the port entry in the application local config link list. A socloc server will set this flag in the entry describing itself. All parameters are required and ils_flag is required to be not null.

## sl_config_set_ils

    Prototype   : int sl_config_set_ils(int port, int ils_flag)
    Parameters  :
          Name  : port
    Description : TCP port number

          Name  : ils_flag
    Description : is_local_server flag

    Returns     : socloc code

This function will set the value of the is_local_server flag for the port entry to ils_flag in the application local config link list. The ils_flag parameter must be zero (0) or one (1). A socloc server will set this flag in the entry describing itself. All parameters are required.

## sl_config_list

    Prototype   : void sl_config_list(void)

This function will display the contents of the application local config link list. If logging is off, the list will be displayed to the screen only. If logging is on, the list will be displayed on the screen and sent to the log file by calling the function sl_config_debug.

## sl_config_debug

    Prototype   : void sl_config_debug(void)

This function will display and log the contents of the application local config link list. If lodgging is off, no output will appear. The list lines are logged by calling the function log_file_date.

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

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