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:
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.
The following modules are required along with this module:
Just make sure you compile and link this module along with the other required modules.
This module requires the header files:
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.
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.
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.
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).
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.
Protoype : int ipc_close(void) Returns : TRUE upon success, FALSE otherwise
This function will cause the server to stop listening.
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.
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.
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.