COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
    

Creates an instance of the protocol stack - a communications endpoint. The type parameter determines the mode of communication. At present the following values are supported:

The cs_create function returns a null-pointer if a system error occurs. The blocking parameter should be '1' if you wish the association to operate in blocking mode, and '0' otherwise. The protocol field should be PROTO_Z3950 or PROTO_HTTP. Protocol PROTO_SR is no longer supported.

     void cs_close(COMSTACK handle);
    

Closes the connection (as elegantly as the lower layers will permit), and releases the resources pointed to by the handle parameter. The handle should not be referenced again after this call.

     int cs_put(COMSTACK handle, char *buf, int len);
    

Sends buf down the wire. In blocking mode, this function will return only when a full buffer has been written, or an error has occurred. In nonblocking mode, it's possible that the function will be unable to send the full buffer at once, which will be indicated by a return value of 1. The function will keep track of the number of octets already written; you should call it repeatedly with the same values of buf and len, until the buffer has been transmitted. When a full buffer has been sent, the function will return 0 for success. The return value -1 indicates an error condition (see below).

     int cs_get(COMSTACK handle, char **buf, int *size);
    

Receives a PDU or HTTP Response from the peer. Returns the number of bytes read. In nonblocking mode, it is possible that not all of the packet can be read at once. In this case, the function returns 1. To simplify the interface, the function is responsible for managing the size of the buffer. It will be reallocated if necessary to contain large packages, and will sometimes be moved around internally by the subsystem when partial packages are read. Before calling cs_get for the first time, the buffer can be initialized to the null pointer, and the length should also be set to 0 (cs_get will perform a malloc(2) on the buffer for you). When a full buffer has been read, the size of the package is returned (which will always be greater than 1). The return value -1 indicates an error condition.

See also the cs_more() function below.

     int cs_more(COMSTACK handle);
    

The cs_more() function should be used in conjunction with cs_get and select(2). The cs_get() function will sometimes (notably in the TCP/IP mode) read more than a single protocol package off the network. When this happens, the extra package is stored by the subsystem. After calling cs_get(), and before waiting for more input, You should always call cs_more() to check if there's a full protocol package already read. If cs_more() returns 1, cs_get() can be used to immediately fetch the new package. For the mOSI subsystem, the function should always return 0, but if you want your stuff to be protocol independent, you should use it.

     int cs_look(COMSTACK handle);
    

This function is useful when you're operating in nonblocking mode. Call it when select(2) tells you there's something happening on the line. It returns one of the following values:

     int cs_fileno(COMSTACK h);
    

returns the file descriptor of the association. Use this when file-level operations on the endpoint are required (select(2) operations, specifically).