Server IPC API Library Module

The server IPC API library module has the file name ipcsrv.c. Any mention of QNX in this document refers to the QNX 4.x OS.

This module provides a high level interface for a TCP or QNX message passing connection oriented iterative server application. The Unix version of this API uses the TCP Berkeley sockets (BSD) interprocess communication method. The Windows version of this API uses the Winsock interprocess communication method. The QNX version of this API uses the QNX message passing IPC method. This module contains global server data depending on the platform.

Here is a list of functions in the server IPC API library module:

- ipc_init
- ipc_server_wait
- ipc_recv_data
- ipc_send_data
- ipc_close_client
- ipc_close
- ipc_trans_num
- ipc_connect_num
- ipc_display_client

Starting in GPL package version 1.33, the TCP variant of this API has been re-written using select function. The client socket is no longer closed once per transaction. Once the client connects, the socket is left open until a socket communication error or the client closes the socket. The model for this API taken from pages 162-167, section 6.8 of Unix Network Programming Volume 1, Networking API's: Sockets and XTI second edition by W. Richard Stevens. The select function is completely supported by WinSock, the only difference is that WinSock does not require or use the first parameter to select which is the depth of the fd_set. Along with the select function, a set of socket descriptors is managed using the fd_set data type and the FD_ macros which are completely portable within both Unix and Windows. TCP servers using this API are limited to the maximum number of simultaneous client socket connections defined by FD_SETSIZE (in the OS socket include file).

This API has been re-structured so that the function ipc_server_wait is now an infinite loop and should only be called once by the main server code (TCP only). When a request is sent by the client, ipc_server_wait will call the server function process_request to read the request data, process the request and send the reply back. Your server must supply this function which must return zero normally, one upon valid request of server termination and -1 upon some sort of socket communication error (refer to socloc.c, sys_log.c and dbsrv.c for good server examples of how to use this API).

This API has also been modified to keep track of the current number of transactions processed and the current number of client connections (functions ipc_trans_num and ipc_connect_num). The server transaction count feature is support by all IPC methods, the connection count is supported by TCP IPC method only.

# Module Dependencies

The following modules are required along with this module:

- ipcomm.c (except QNX)
- ipconfig.c (optional for use with TCP config files [now obsolete])

Just make sure you compile and link this module along with the other required modules.

# Module Header Files

This module requires the header files:

- stdhead.h
- flsocket.h
- ipcomm.h (except QNX)
- ipcsrv.h

# Module Functions

## ipc_init

    TCP Proto  : int ipc_init(char *host_name, int port_number)
    QNX Proto  : int ipc_init(char *host_name)
    Parameters :
          Name : host_name
    Description: host name of server (returned) (TCP), nameloc name (QNX)

          Name : port_number
    Description: port number of server

    Returns    : TRUE upon success, FALSE otherwise

This function will initialize the server by attempting to resolve the server host name by using a gethostname function call, prepare the server socket, bind the socket and listen to the port (TCP only). The QNX message passing variant will call the function qnx_name_attach to register the service name with nameloc. Note that QNX> does not have the concept of a port number.

## ipc_server_wait

    TCP Proto  : void ipc_server_wait(void)

This function uses the select I/O function call to wait for a client connection and then calls the accept socket function call to accept each client connection. Note that the server program will block/wait for a connection. This function applies to TCP IPC method only.

## ipc_recv_data

    TCP Proto  : int ipc_recv_data(char *buf)
    QNX Proto  : int ipc_recv_data(char *buf, int size_buf)
    Parameters :
          Name : buf
    Description: receive data buffer

          Name : size_buf
    Description: size (in bytes) of the receive buffer

    Returns    : number of bytes received upon success, zero otherwise

This function will receive data from the client and place the data into the receive data buffer. The data is actually received by calling the low level TCP socket function ipc_recv (TCP only).

The QNX message passing variant will read block in this function waiting for a virtual circuit connection.

## ipc_send_data

    Prototype  : int ipc_send_data(char *buf)
    Parameters :
          Name : buf
    Description: send data buffer

    Returns    : number of bytes sent upon success, zero otherwise

This function will send data through the client socket. The data is actually sent by calling the low level TCP socket function ipc_send (TCP only).

## ipc_close_client

    TCP Proto  : int ipc_close_client(void)

    Returns    : TRUE upon success, FALSE otherwise

This function will close the client socket. This function applies to the TCP IPC only.

## ipc_close

    Protoype   : int ipc_close(void)

    Returns    : TRUE upon success, FALSE otherwise

This function will cause the server to stop listening.

## ipc_trans_num

    TCP Proto  : long ipc_trans_num(void)

    Returns    : server transaction count

This TCP only function will return the current server transaction count. This function applies to the TCP IPC method only.

## ipc_connect_num

    TCP Proto  : int ipc_connect_num(void)

    Returns    : server connection count

This TCP only function will return the current server connection count. This function applies to the TCP IPC method only.

## ipc_display_client

    Prototype  : void ipc_display_client(void)

This function will display the client socket pointer address. The function is used for debugging. This function applies to TCP IPC method only.

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

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