typedef struct DLCP_s { char addr[100]; char clientid[200]; int keepalive; int iotimeout; int link; float serverproto; int32_t maxpktsize; int8_t writeperm; int64_t pktid; dltime_t pkttime; int8_t keepalive_trig; dltime_t keepalive_time; int8_t terminate; int8_t streaming; DLLog *log; } DLCP;
sladdr | The address of the DataLink server to connect to in 'host:port' format. example: "st27.gfz-potsdam.de:18000". The host or port specifications are both optional, they will default to 'localhost' and '16000' respectively. | |
clientid | Client identification sent to the server during initial handshake. This ID is populated in a call to dl_newdlcp(). Normally this takes the form of: "progname:username:pid:arch", for example: "dalitool:rt:6055:SunOS-5.10" | |
keepalive | Interval in seconds to send keepalive packets to the server when no data is being received with either dl_collect() or dl_collect_nb(). Default interval is 600 seconds, 0 to disable. | |
iotimeout | Network I/O timeout in seconds. Send and receive operations will be interrupted after this timeout to avoid hung socket connections. Default timeout is 60 seconds, 0 to disable. |
link | This is the file descriptor associated with the connected network socket. This value will be -1 when not connected to a server. | |
serverproto | The DataLink protocol version of the connected server. This is set during connection handshake and will be 0.0 if it was not supplied by the server. | |
maxpktsize | The maximum packet size supported by the connected server. This is set during connection handshake and will be 0 if it was not supplied by the server. | |
writeperm | A flag indicating if the server has granted the client write permission. This is set during connection handshake and will be 1 if write permission is granted and 0 otherwise. | |
pktid | Packet ID of the last packet received. A packet ID is a large integer uniquely identifying a packet in a DataLink server instance. | |
pkttime | Packet time of the last packet received. Each DataLink packet has an associated packet creation time which, when combined with the pktid, can be used to uniquely identify a packet in a DataLink server instance. | |
keepalive_trig | ||
keepalive_time | These are used to trigger and track the sending of keep- alive packets. | |
terminate | Used internally to indicate connection termination. | |
streaming | Used to indicate status of streaming mode, set to either true (1) or false (0). Streaming mode is activated when either dl_collect() or dl_collect_nb() is initially called, a specific call to those functions will deactivate streaming. When a connection is in streaming mode most server query functions will not work. | |
log | Logging parameters specific to this connection. |
dl_newdlcp() : Allocate and initialize a DLCP struct with default values.
dl_freedlcp() : Free all memory associated with a DLCP struct.
dl_position() : Position the connection to a specific packet in the DataLink server based on packet ID and packet time.
dl_position_after() : Position the connection to a specific packet in DataLink server based on data time.
dl_match() : Send a new regular expression matching pattern to the DataLink server. Used to limit packets to specific stream IDs for packet transfer or stream listing.
dl_reject() : Send a new regular expression rejecting pattern to the DataLink server, the antithesis of the matching pattern.
dl_write() : Write a supplied packet to a DataLink server.
dl_getinfo() : Submit an INFO request to and collect the response from a DataLink server. Responses are in XML. Request types include STATUS, STREAMS and CONNECTIONS.
dl_collect() : Collect and return a packet each time called. Keepalive packets are sent at the keepalive interval when no packets are being sent from the server. If a connection is not currently configured in streaming mode, the first call to dl_collect() will turn this mode on. Designed to run in a tight loop at the heart of a client program this routine blocks until a packet is received.
dl_collect_nb() : This is a non-blocking version of dl_collect(), it will always return whether a packet is received or not.
dl_terminate() : Set the terminate flag in the connection parameters. This will cause dl_collect()/dl_collect_nb() to return DLENDED. This is commonly used in a signal handler to smoothly exit from a packet collection loop.
dl_savestate() : Save current packet ID and time to a file.
dl_recoverstate() : Recover packet ID and time from a file.
dl_loginit() : initialize the verbosity level of the library functions, also set the functions and prefixes used for log, diagnostic and error messages.
dl_log() : the central logging facility. Behavior is controlled by the settings specified with dl_loginit().
The default destination for log messages is standard output (stdout), while all diagnostic (including error) messages go to standard error (stderr). Most of the internal messages emmited by the library are considered diagnostic and will, by default, go to standard error.
The default prefix for log and diagnostic messages is nothing. The default prefix for diagnostic error messages is "error: ".
There are reentrant versions of these functions that operation either on the logging parameters in a DLCP struct or directly on a logging parameter DLLog struct. They are intended for use in threaded programs or where a complex logging scheme is desired. See the man pages for more details.