connection.c File Reference

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include "libdali.h"
#include "portable.h"

Include dependency graph for connection.c:


Functions

DLCPdl_newdlcp (char *address, char *progname)
 Create a new DataLink Connection Parameter (DLCP) structure.
void dl_freedlcp (DLCP *dlconn)
 Free a DataLink Connection Parameter (DLCP) structure.
int dl_exchangeIDs (DLCP *dlconn, int parseresp)
 Send the ID command to the DataLink server and parse response.
int64_t dl_position (DLCP *dlconn, int64_t pktid, dltime_t pkttime)
 Position the client read position.
int64_t dl_position_after (DLCP *dlconn, dltime_t datatime)
 Position the client read position based on data time.
int64_t dl_match (DLCP *dlconn, char *matchpattern)
 Set the packet match parameters for a connection.
int64_t dl_reject (DLCP *dlconn, char *rejectpattern)
 Set the packet reject parameters for a connection.
int64_t dl_write (DLCP *dlconn, void *packet, int packetlen, char *streamid, dltime_t datastart, dltime_t dataend, int ack)
 Send a packet to the DataLink server.
int dl_read (DLCP *dlconn, int64_t pktid, DLPacket *packet, void *packetdata, size_t maxdatasize)
 Request a packet from the DataLink server.
int dl_getinfo (DLCP *dlconn, const char *infotype, char *infomatch, char **infodata, size_t maxinfosize)
 Request information from the DataLink server.
int dl_collect (DLCP *dlconn, DLPacket *packet, void *packetdata, size_t maxdatasize, int8_t endflag)
 Collect packets streaming from the DataLink server.
int dl_collect_nb (DLCP *dlconn, DLPacket *packet, void *packetdata, size_t maxdatasize, int8_t endflag)
 Collect packets streaming from the DataLink server without blocking.
int dl_handlereply (DLCP *dlconn, void *buffer, int buflen, int64_t *value)
 Handle the server reply to a command.
void dl_terminate (DLCP *dlconn)
 Set the terminate parameter of a DataLink connection.

Detailed Description

Routines for managing a connection with a DataLink server.

Author:
Chad Trabant, IRIS Data Management Center
modified: 2008.256

Function Documentation

int dl_collect ( DLCP dlconn,
DLPacket packet,
void *  packetdata,
size_t  maxdatasize,
int8_t  endflag 
)

Collect packets streaming from the DataLink server.

Collect packets streaming from the DataLink server. If the connection is not already in streaming mode the STREAM command will first be sent. This routine will block until a packet is received sending keepalive packets to the server based on the DLCP.keepalive parameter.

Designed to run in a tight loop at the heart of a client program, this function will return every time a packet is received. On successfully receiving a packet dlpack will be populated and the packet data will be copied into packetdata.

If the endflag is true the ENDSTREAM command is sent which instructs the server to stop streaming packets; a client must continue collecting packets until DLENDED is returned in order to get any packets that were in-the-air when ENDSTREAM was requested. The stream ending sequence must be completed if the connection is to be used after streaming mode.

Return values:
DLPACKET when a packet is received.
DLENDED when the stream ending sequence was completed or the connection was shut down.
DLERROR when an error occurred.

int dl_collect_nb ( DLCP dlconn,
DLPacket packet,
void *  packetdata,
size_t  maxdatasize,
int8_t  endflag 
)

Collect packets streaming from the DataLink server without blocking.

Collect packets streaming from the DataLink server. If the connection is not already in streaming mode the STREAM command will first be sent. This routine is a non-blocking version of dl_collect() and will return quickly whether data is received or not. Keep alive packets are sent to the server based on the DLCP.keepalive parameter.

Designed to run in a tight loop at the heart of a client program, this function will return every time a packet is received. On successfully receiving a packet dlpack will be populated and the packet data will be copied into packetdata.

If the endflag is true the ENDSTREAM command is sent which instructs the server to stop streaming packets; a client must continue collecting packets until DLENDED is returned in order to get any packets that were in-the-air when ENDSTREAM was requested. The stream ending sequence must be completed if the connection is to be used after streaming mode.

Return values:
DLPACKET A packet is received.
DLNOPACKET No packet is received.
DLENDED when the stream ending sequence was completed or the connection was shut down.
DLERROR when an error occurred.

int dl_exchangeIDs ( DLCP dlconn,
int  parseresp 
)

Send the ID command to the DataLink server and parse response.

Send the ID command including the client ID and optionally parse the capability flags from the server response. This routine is always called when a connection is first made using dl_connect() and shouldn't normally need to be called again.

Parameters:
dlconn DataLink Connection Parameters
parseresp Flag to control parsing of server response.
Returns:
-1 on errors, 0 on success.

void dl_freedlcp ( DLCP dlconn  ) 

Free a DataLink Connection Parameter (DLCP) structure.

Free all memory associated with a DLCP struct.

Parameters:
dlconn DLCP to free

int dl_getinfo ( DLCP dlconn,
const char *  infotype,
char *  infomatch,
char **  infodata,
size_t  maxinfosize 
)

Request information from the DataLink server.

Request and receive information from the server using the DataLink INFO command. The INFO response is placed in the supplied infodata buffer. All DataLink INFO responses are returned as XML.

If maxinfosize argument is 0 memory will be allocated as needed for the INFO data result and the infodata pointer will be set to this new buffer; it is up to the caller to free this memory. If an infomatch string is supplied it will be appended to the INFO request sent to the server.

Parameters:
dlconn DataLink Connection Parameters
infotype The INFO type to request
infomatch An optional match pattern
infodata Buffer to place the INFO response into
maxinfosize Maximum number of bytes to write to infodata buffer
Returns:
The length of the INFO response in bytes on success and -1 on error.

int dl_handlereply ( DLCP dlconn,
void *  buffer,
int  buflen,
int64_t *  value 
)

Handle the server reply to a command.

Handle the server reply to a command. This routine is used by other library routines to process replies from the server.

Server replies are of the form:

"OK|ERROR value size"

followed by an optional server message of size bytes. If size is greater than zero it will be read from the connection and placed into buffer. The server message, if included, will always be a NULL-terminated string.

Return values:
-1 Error
0 "OK" received
1 "ERROR" received

int64_t dl_match ( DLCP dlconn,
char *  matchpattern 
)

Set the packet match parameters for a connection.

Send new match pattern to server or reset matching. If matchpattern is NULL a zero length pattern command is sent to the server which resets the client matching setting.

The packet match pattern limits which packets are sent to the client in streaming mode, this is the mode used for dl_collect() and dl_collect_nb() requests.

Parameters:
dlconn DataLink Connection Parameters
matchpattern Match regular expression
Returns:
the count of currently matched streams on success and -1 on error.

DLCP* dl_newdlcp ( char *  address,
char *  progname 
)

Create a new DataLink Connection Parameter (DLCP) structure.

Allocate, initialze and return a pointer to a new DLCP struct.

Parameters:
address Address of DataLink server in "host:port" format
progname Name of program, usually argv[0]
Returns:
allocated DLCP struct on success, NULL on error.

int64_t dl_position ( DLCP dlconn,
int64_t  pktid,
dltime_t  pkttime 
)

Position the client read position.

Set the client read position to a specified packet ID and packet time. A packet ID and time together uniquely identify a packet in a DataLink server. The packet time must match the packet ID current in the server's buffer or the positioning request will fail.

Parameters:
dlconn DataLink Connection Parameters
pktid Packet ID to set position to
pkttime Packet time cooresponding to pktid
Returns:
A positive packet ID on success and -1 on error.

int64_t dl_position_after ( DLCP dlconn,
dltime_t  datatime 
)

Position the client read position based on data time.

Set the client read position to the first packet with a data end time after a reference datatime. The reference time must be specified as a dltime_t value, see dl_time2dltime() and friends to generate these time values.

Parameters:
dlconn DataLink Connection Parameters
datatime Reference data time as a dltime_t value
Returns:
A positive packet ID on success and -1 on error.

int dl_read ( DLCP dlconn,
int64_t  pktid,
DLPacket packet,
void *  packetdata,
size_t  maxdatasize 
)

Request a packet from the DataLink server.

Request a specific packet from the server.

A maximum of maxdatasize will be written to packetdata. If the packet data is larger than this maximum size an error will be logged and 0 will be returned; the packet data will be recv'd and discarded in order to leave the connection in a usable state.

If this routine returns -1 the connection should be considered to be in a bad state and should be shut down.

Parameters:
dlconn DataLink Connection Parameters
pktid Packet ID to request
packet Pointer to a DLPacket struct for the received packet header information
packetdata Pointer to a buffer for received packet data
maxdatasize Maximum data size to write to packetdata
Returns:
Number of bytes of packet data received on success and -1 on error.

int64_t dl_reject ( DLCP dlconn,
char *  rejectpattern 
)

Set the packet reject parameters for a connection.

Send new reject pattern to server or reset rejecting. If rejectpattern is NULL a zero length pattern command is sent to the server which resets the client rejecting setting.

The packet reject pattern limits which packets are sent to the client in streaming mode, this is the mode used for dl_collect() and dl_collect_nb() requests.

Parameters:
dlconn DataLink Connection Parameters
rejectpattern Reject regular expression
Returns:
the count of currently rejected streams on success and -1 on error.

void dl_terminate ( DLCP dlconn  ) 

Set the terminate parameter of a DataLink connection.

Set the terminate parameter/flag in the DLCP and log a diagnostic message indicating that the connection is terminating. Some of the library routines watch the terminate parameter as an indication that the client program is requesting a shut down. This routine is typically used in a signal handler.

int64_t dl_write ( DLCP dlconn,
void *  packet,
int  packetlen,
char *  streamid,
dltime_t  datastart,
dltime_t  dataend,
int  ack 
)

Send a packet to the DataLink server.

Send a packet to the server and optionally request and process an acknowledgement from the server. An appropriate DataLink packet header is created from the supplied parameters and sent with the packet data.

When an acknowledgement from the server has been requested this routine will receive the response from the server and parse it, a successful acknowledgement is indicated by the return value.

Parameters:
dlconn DataLink Connection Parameters
packet Packet data buffer to send
packetlen Length of data in bytes to send from packet
streamid Stream ID of packet
datastart Data start time for packet
dataend Data end time for packet
ack Acknowledgement flag, if true request acknowledgement
Returns:
-1 on error and 0 on success when no acknowledgement is requested and a positive packet ID on success when acknowledgement is requested.


Generated on Fri Sep 12 15:38:53 2008 for libdali by  doxygen 1.5.6