libdali  1.6
 All Classes Files Functions Variables Typedefs Macros Pages
Classes | Macros | Typedefs | Functions
libdali.h File Reference
#include "portable.h"

Go to the source code of this file.

Classes

struct  DLLog_s
 
struct  DLCP_s
 
struct  DLPacket_s
 
struct  DLstrlist_s
 

Macros

#define LIBDALI_VERSION   "1.6"
 
#define LIBDALI_RELEASE   "2013.210"
 
#define MAXPACKETSIZE   16384
 
#define MAXREGEXSIZE   16384
 
#define MAX_LOG_MSG_LENGTH   200
 
#define LIBDALI_POSITION_EARLIEST   -2
 
#define LIBDALI_POSITION_LATEST   -3
 
#define MAXSTREAMID   60
 
#define DLERROR   -1
 
#define DLENDED   0
 
#define DLPACKET   1
 
#define DLNOPACKET   2
 
#define DLTMODULUS   1000000
 
#define DLTERROR   -2145916800000000LL
 
#define DL_EPOCH2DLTIME(X)   X * (dltime_t) DLTMODULUS
 
#define DL_DLTIME2EPOCH(X)   X / DLTMODULUS
 

Typedefs

typedef int64_t dltime_t
 
typedef struct DLLog_s DLLog
 
typedef struct DLCP_s DLCP
 
typedef struct DLPacket_s DLPacket
 
typedef struct DLstrlist_s DLstrlist
 

Functions

DLCPdl_newdlcp (char *address, char *progname)
 Create a new DataLink Connection Parameter (DLCP) structure. More...
 
void dl_freedlcp (DLCP *dlconn)
 Free a DataLink Connection Parameter (DLCP) structure. More...
 
int dl_exchangeIDs (DLCP *dlconn, int parseresp)
 Send the ID command to the DataLink server and parse response. More...
 
int64_t dl_position (DLCP *dlconn, int64_t pktid, dltime_t pkttime)
 Position the client read position. More...
 
int64_t dl_position_after (DLCP *dlconn, dltime_t datatime)
 Position the client read position based on data time. More...
 
int64_t dl_match (DLCP *dlconn, char *matchpattern)
 Set the packet match parameters for a connection. More...
 
int64_t dl_reject (DLCP *dlconn, char *rejectpattern)
 Set the packet reject parameters for a connection. More...
 
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. More...
 
int dl_read (DLCP *dlconn, int64_t pktid, DLPacket *packet, void *packetdata, size_t maxdatasize)
 Request a packet from the DataLink server. More...
 
int dl_getinfo (DLCP *dlconn, const char *infotype, char *infomatch, char **infodata, size_t maxinfosize)
 Request information from the DataLink server. More...
 
int dl_collect (DLCP *dlconn, DLPacket *packet, void *packetdata, size_t maxdatasize, int8_t endflag)
 Collect packets streaming from the DataLink server. More...
 
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. More...
 
int dl_handlereply (DLCP *dlconn, void *buffer, int buflen, int64_t *value)
 Handle the server reply to a command. More...
 
void dl_terminate (DLCP *dlconn)
 Set the terminate parameter of a DataLink connection. More...
 
char * dl_read_streamlist (DLCP *dlconn, const char *streamfile)
 Create a compound regular expression from a list in a file. More...
 
int dl_connect (DLCP *dlconn)
 Connect to a DataLink server. More...
 
void dl_disconnect (DLCP *dlconn)
 Disconnect a DataLink connection. More...
 
int dl_senddata (DLCP *dlconn, void *buffer, size_t sendlen)
 Send arbitrary data to a DataLink server. More...
 
int dl_sendpacket (DLCP *dlconn, void *headerbuf, size_t headerlen, void *databuf, size_t datalen, void *respbuf, int resplen)
 Create and send a DataLink packet. More...
 
int dl_recvdata (DLCP *dlconn, void *buffer, size_t readlen, uint8_t blockflag)
 Receive arbitrary data from a DataLink server. More...
 
int dl_recvheader (DLCP *dlconn, void *buffer, size_t buflen, uint8_t blockflag)
 Receive DataLink packet header. More...
 
int dl_doy2md (int year, int jday, int *month, int *mday)
 Compute the month and day-of-month from day-of-year. More...
 
int dl_md2doy (int year, int month, int mday, int *jday)
 Compute the day-of-year from year, month and day-of-month. More...
 
char * dl_dltime2isotimestr (dltime_t dltime, char *isotimestr, int8_t subseconds)
 Generate an ISO time string from a dltime_t. More...
 
char * dl_dltime2mdtimestr (dltime_t dltime, char *mdtimestr, int8_t subseconds)
 Generate an time string in month-day format from a dltime_t. More...
 
char * dl_dltime2seedtimestr (dltime_t dltime, char *seedtimestr, int8_t subseconds)
 Generate an time string in SEED format from a dltime_t. More...
 
dltime_t dl_time2dltime (int year, int day, int hour, int min, int sec, int usec)
 Convert specified time values to a dltime_t value. More...
 
dltime_t dl_seedtimestr2dltime (char *seedtimestr)
 Convert a SEED time string to a dltime_t value. More...
 
dltime_t dl_timestr2dltime (char *timestr)
 Convert a time string to a dltime_t value. More...
 
int dl_splitstreamid (char *streamid, char *w, char *x, char *y, char *z, char *type)
 Split a stream ID into separate components: "W_X_Y_Z/TYPE". More...
 
int dl_bigendianhost (void)
 Determine byte order of host machine. More...
 
double dl_dabs (double value)
 Return absolute value of double value. More...
 
int dl_readline (int fd, char *buffer, int buflen)
 Read a line from a file stream. More...
 
int dl_log (int level, int verb,...)
 Log a message using the global logging parameters. More...
 
int dl_log_r (const DLCP *dlconn, int level, int verb,...)
 Log a message using the log parameters from a DLCP. More...
 
int dl_log_rl (DLLog *log, int level, int verb,...)
 Log a message using the log parameters from a DLCP. More...
 
void dl_loginit (int verbosity, void(*log_print)(char *), const char *logprefix, void(*diag_print)(char *), const char *errprefix)
 Initialize global logging system parameters. More...
 
void dl_loginit_r (DLCP *dlconn, int verbosity, void(*log_print)(char *), const char *logprefix, void(*diag_print)(char *), const char *errprefix)
 Initialize logging parameters specific to a DLCP. More...
 
DLLogdl_loginit_rl (DLLog *log, int verbosity, void(*log_print)(char *), const char *logprefix, void(*diag_print)(char *), const char *errprefix)
 Initialize logging parameters for a specific DLLog. More...
 
int dl_recoverstate (DLCP *dlconn, const char *statefile)
 Recover DataLink connection state from a file. More...
 
int dl_savestate (DLCP *dlconn, const char *statefile)
 Save a DataLink connection state to a file. More...
 
int dl_strparse (const char *string, const char *delim, DLstrlist **list)
 Parse/split a string on a specified delimiter. More...
 
int dl_strncpclean (char *dest, const char *source, int length)
 Copy a string while removing space charaters. More...
 
int dl_addtostring (char **string, char *add, char *delim, int maxlen)
 Concatinate one string to another growing the destination as needed. More...
 

Detailed Description

Interface declarations for the DataLink library (libdali).

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License (GNU-LGPL) for more details. The GNU-LGPL and further information can be found here: http://www.gnu.org/

Author
Chad Trabant, IRIS Data Management Center

modified: 2011.003

Macro Definition Documentation

#define DL_DLTIME2EPOCH (   X)    X / DLTMODULUS

Macro to scale a high precision time to a Unix/POSIX epoch time

#define DL_EPOCH2DLTIME (   X)    X * (dltime_t) DLTMODULUS

Macro to scale a Unix/POSIX epoch time to a high precision time

#define DLENDED   0

Connection terminated

#define DLERROR   -1

Error occurred

#define DLNOPACKET   2

No packet for non-blocking dl_collect_nb()

#define DLPACKET   1

Packet returned

#define DLTERROR   -2145916800000000LL

Error code for routines that normally return a high precision time. The time value corresponds to '1902/1/1 00:00:00.000000' with the default DLTMODULUS

#define DLTMODULUS   1000000

High precision time tick interval as 1/modulus seconds * Default modulus of 1000000 defines tick interval as a microsecond

#define LIBDALI_POSITION_EARLIEST   -2

Earliest position in the buffer

#define LIBDALI_POSITION_LATEST   -3

Latest position in the buffer

#define LIBDALI_RELEASE   "2013.210"

libdali release date

#define LIBDALI_VERSION   "1.6"

libdali version

#define MAX_LOG_MSG_LENGTH   200

Maximum length of log messages

#define MAXPACKETSIZE   16384

Maximum packet size for libdali

#define MAXREGEXSIZE   16384

Maximum regex pattern size

#define MAXSTREAMID   60

Maximium stream ID string length

Typedef Documentation

typedef struct DLCP_s DLCP

DataLink connection parameters

typedef struct DLLog_s DLLog

Logging parameters

typedef struct DLPacket_s DLPacket

DataLink packet

typedef int64_t dltime_t

Data type for high-precision time values. Require a large (>= 64-bit) integer type

Function Documentation

int dl_addtostring ( char **  string,
char *  add,
char *  delim,
int  maxlen 
)

Concatinate one string to another growing the destination as needed.

Concatinate one string to another with a delimiter in-between growing the destination string as needed up to a maximum length.

Parameters
stringDestination string to be added to
addString to add to string
delimOptional delimiter between added strings (cannot be NULL, but can be an empty string)
maxlenMaximum number of bytes to grow string
Returns
0 on success, -1 on memory allocation error and -2 when string would grow beyond maximum length.
int dl_bigendianhost ( void  )

Determine byte order of host machine.

Determine the byte order of the host machine. Due to the lack of portable defines to determine host byte order this run-time test is provided. The code actually tests for little-endianess, the only other alternative is assumed to be big endian.

Returns
0 if the host is little endian, otherwise 1.
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
DLPACKETwhen a packet is received.
DLENDEDwhen the stream ending sequence was completed or the connection was shut down.
DLERRORwhen 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
DLPACKETA packet is received.
DLNOPACKETNo packet is received.
DLENDEDwhen the stream ending sequence was completed or the connection was shut down.
DLERRORwhen an error occurred.
int dl_connect ( DLCP dlconn)

Connect to a DataLink server.

Open a network socket connection to a Datalink server and set 'dlconn->link' to the new descriptor. Expects 'dlconn->addr' to be in 'host:port' format. Either the host, port or both are optional, if the host is not specified 'localhost' is assumed, if the port is not specified '16000' is assumed, if neither is specified (only a colon) then 'localhost' and port '16000' are assumed.

If a permanent error is detected (invalid port specified) the dlconn->terminate flag will be set so the dl_collect() family of routines will not continue trying to connect.

Parameters
dlconnDataLink Connection Parameters
Returns
the socket descriptor created.
Return values
-1on errors
double dl_dabs ( double  value)

Return absolute value of double value.

Determine the absolute value of an input double, actually just test if the input double is positive multiplying by -1.0 if not and return it.

Returns
Positive value of input double.
void dl_disconnect ( DLCP dlconn)

Disconnect a DataLink connection.

Close the network socket associated with connection and set 'dlconn->link' to -1.

Parameters
dlconnDataLink Connection Parameters
char* dl_dltime2isotimestr ( dltime_t  dltime,
char *  isotimestr,
int8_t  subseconds 
)

Generate an ISO time string from a dltime_t.

Build a time string in ISO recommended format from a high precision epoch time, dltime_t, value.

The provided isostimestr must have enough room for the resulting time string of 27 characters, i.e. '2001-07-29T12:38:00.000000' + NULL.

The 'subseconds' flag controls whenther the sub second portion of the time is included or not.

Parameters
dltimeThe dltime_t time value
isotimestrReturned ISO time string, must have room for 27 characters
subsecondsFlag to control the inclusion of subseconds
Returns
A pointer to the resulting string or NULL on error.
char* dl_dltime2mdtimestr ( dltime_t  dltime,
char *  mdtimestr,
int8_t  subseconds 
)

Generate an time string in month-day format from a dltime_t.

Build a time string in month-day format from a high precision epoch time.

The provided mdtimestr must have enough room for the resulting time string of 27 characters, i.e. '2001-07-29 12:38:00.000000' + NULL.

The 'subseconds' flag controls whenther the sub second portion of the time is included or not.

Parameters
dltimeThe dltime_t time value
mdtimestrReturned time string, must have room for 27 characters
subsecondsFlag to control the inclusion of subseconds
Returns
A pointer to the resulting string or NULL on error.
char* dl_dltime2seedtimestr ( dltime_t  dltime,
char *  seedtimestr,
int8_t  subseconds 
)

Generate an time string in SEED format from a dltime_t.

Build a SEED (day-of-year) time string from a high precision epoch time.

The provided seedtimestr must have enough room for the resulting time string of 25 characters, i.e. '2001,195,12:38:00.000000
'.

The 'subseconds' flag controls whenther the sub second portion of the time is included or not.

Parameters
dltimeThe dltime_t time value
seedtimestrReturned time string, must have room for 25 characters
subsecondsFlag to control the inclusion of subseconds
Returns
A pointer to the resulting string or NULL on error.
int dl_doy2md ( int  year,
int  jday,
int *  month,
int *  mday 
)

Compute the month and day-of-month from day-of-year.

Compute the month and day-of-month from a year and day-of-year.

Year is expected to be in the range 1900-2100, jday is expected to be in the range 1-366, month will be in the range 1-12 and mday will be in the range 1-31.

Parameters
yearYear (1900 - 2100)
jdayDay-of-year, "Julian" day (1 - 366)
monthReturned month (1 - 12)
mdayReturned day-of-month (1 - 31)
Returns
0 on success and -1 on error.
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
dlconnDataLink Connection Parameters
parserespFlag 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
dlconnDLCP 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
dlconnDataLink Connection Parameters
infotypeThe INFO type to request
infomatchAn optional match pattern
infodataBuffer to place the INFO response into
maxinfosizeMaximum 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
-1Error
0"OK" received
1"ERROR" received
int dl_log ( int  level,
int  verb,
  ... 
)

Log a message using the global logging parameters.

A wrapper to dl_log_main() that uses the global logging parameters.

Parameters
levelLevel at which to log the message (1, 2 or 3)
verbVerbosity threshold at which to log the message
...Message format and optional arguments in printf style
Returns
See dl_log_main() description for return values.
int dl_log_r ( const DLCP dlconn,
int  level,
int  verb,
  ... 
)

Log a message using the log parameters from a DLCP.

A wrapper to dl_log_main() that uses the logging parameters in a supplied DLCP. If the supplied pointer is NULL the global logging parameters will be used.

Parameters
dlconnDataLink Connection Parameters with associated logging paramters
levelLevel at which to log the message (1, 2 or 3)
verbVerbosity threshold at which to log the message
...Message format and optional arguments in printf style
Returns
See dl_log_main() description for return values.
int dl_log_rl ( DLLog log,
int  level,
int  verb,
  ... 
)

Log a message using the log parameters from a DLCP.

A wrapper to dl_log_main() that uses the logging parameters in a supplied DLLog. If the supplied pointer is NULL the global logging parameters will be used.

Parameters
logDLLog logging paramters
levelLevel at which to log the message (1, 2 or 3)
verbVerbosity threshold at which to log the message
...Message format and optional arguments in printf style
Returns
See dl_log_main() description for return values.
void dl_loginit ( int  verbosity,
void(*)(char *)  log_print,
const char *  logprefix,
void(*)(char *)  diag_print,
const char *  errprefix 
)

Initialize global logging system parameters.

Initialize the global logging parameters.

See dl_loginit_main() description for usage.

void dl_loginit_r ( DLCP dlconn,
int  verbosity,
void(*)(char *)  log_print,
const char *  logprefix,
void(*)(char *)  diag_print,
const char *  errprefix 
)

Initialize logging parameters specific to a DLCP.

Initialize DLCP specific logging parameters. If the logging parameters have not been initialized (dlconn->log == NULL) new parameter space will be allocated.

See dl_loginit_main() description for usage.

DLLog* dl_loginit_rl ( DLLog log,
int  verbosity,
void(*)(char *)  log_print,
const char *  logprefix,
void(*)(char *)  diag_print,
const char *  errprefix 
)

Initialize logging parameters for a specific DLLog.

Initialize DLLog specific logging parameters. If the logging parameters have not been initialized (log == NULL) new parameter space will be allocated.

See dl_loginit_main() description for usage.

Returns
A pointer to the created/re-initialized DLLog struct.
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
dlconnDataLink Connection Parameters
matchpatternMatch regular expression
Returns
the count of currently matched streams on success and -1 on error.
int dl_md2doy ( int  year,
int  month,
int  mday,
int *  jday 
)

Compute the day-of-year from year, month and day-of-month.

Compute the day-of-year from a year, month and day-of-month.

Year is expected to be in the range 1900-2100, month is expected to be in the range 1-12, mday is expected to be in the range 1-31 and jday will be in the range 1-366.

Parameters
yearYear (1900 - 2100)
monthMonth (1 - 12)
mdayDay-of-month (1 - 31)
jdayReturned day-of-year, "Julian" day (1 - 366)
Returns
0 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
addressAddress of DataLink server in "host:port" format
prognameName 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 currently in the server's buffer or the positioning request will fail.

As a special case pktid maybe be set to LIBDALI_POSITION_EARLIEST or LIBDALI_POSITION_LATEST to set the client read position to the earliest or latest packet. In both cases the pkttime value is ignored.

Parameters
dlconnDataLink Connection Parameters
pktidPacket ID to set position to
pkttimePacket time cooresponding to pktid
Returns
A positive packet ID on success, 0 when packet is not found 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
dlconnDataLink Connection Parameters
datatimeReference 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
dlconnDataLink Connection Parameters
pktidPacket ID to request
packetPointer to a DLPacket struct for the received packet header information
packetdataPointer to a buffer for received packet data
maxdatasizeMaximum data size to write to packetdata
Returns
Number of bytes of packet data received on success and -1 on error.
char* dl_read_streamlist ( DLCP dlconn,
const char *  streamfile 
)

Create a compound regular expression from a list in a file.

Read a list of stream regular expressions from a file and create a compound regular expression. The caller is responsible for free'ing the returned string.

Returns
A composite regex pattern on success and NULL on error.
int dl_readline ( int  fd,
char *  buffer,
int  buflen 
)

Read a line from a file stream.

Read characters from a stream (specified as a file descriptor) until a newline character '
' is read and place them into the supplied buffer. Reading stops when either a newline character is read or buflen-1 characters have been read. The buffer will always contain a NULL-terminated string.

Returns
The number of characters read on success and -1 on error.
int dl_recoverstate ( DLCP dlconn,
const char *  statefile 
)

Recover DataLink connection state from a file.

Recover connection state from a state file and set the state parameters in a given DataLink Connection Paramters.

Parameters
dlconnDataLink Connection Parameters
statefileFile to recover state from
Return values
-1Error
0Completed successfully
1File could not be opened (probably not found)
int dl_recvdata ( DLCP dlconn,
void *  buffer,
size_t  readlen,
uint8_t  blockflag 
)

Receive arbitrary data from a DataLink server.

This fundamental routine is used by other library routines to receive data from a DataLink server. Up to readlen bytes of received data is placed into buffer.

If blockflag is true (1) this function will block until readlen bytes have been read. If blockflag is false (0) and no data is available for reading this function will immediately return. If blockflag is false and some initial data is received the function will block until readlen bytes have been read.

If a user specified network I/O timeout was not applied at the system socket level this routine will implement the timeout using an alarm timer to interrupt the blocked send.

Parameters
dlconnDataLink Connection Parameters
bufferBuffer for received data
readlenNumber of bytes to read and place into buffer
blockflagFlag to control use of blocking versus non-blocking mode
Returns
number of bytes read on success
Return values
0when no data available on non-blocking socket
-1on connection shutdown
-2on error.
int dl_recvheader ( DLCP dlconn,
void *  buffer,
size_t  buflen,
uint8_t  blockflag 
)

Receive DataLink packet header.

Receive a DataLink packet header and place it into buffer up to buflen bytes in length.

The header body returned in buffer will always be NULL terminated. The buffer must be at least 255 bytes in size. The maximum header length is effectively 254 bytes.

Returns
number of bytes read on success
Return values
0when no data available on non-blocking socket
-1on connection shutdown
-2on 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
dlconnDataLink Connection Parameters
rejectpatternReject regular expression
Returns
the count of currently rejected streams on success and -1 on error.
int dl_savestate ( DLCP dlconn,
const char *  statefile 
)

Save a DataLink connection state to a file.

Save the all the current the sequence numbers and time stamps into the given state file.

Parameters
dlconnDataLink Connection Parameters
statefileFile to save state to
Return values
-1Error
0Completed successfully
dltime_t dl_seedtimestr2dltime ( char *  seedtimestr)

Convert a SEED time string to a dltime_t value.

Convert a SEED time string to a high precision epoch time. SEED time format is "YYYY[,DDD,HH,MM,SS.FFFFFF]", the delimiter can be a comma [,], colon [:] or period [.] except for the fractional seconds which must start with a period [.].

The time string can be "short" in which case the omitted values are assumed to be zero (with the exception of DDD which is assumed to be 1): "YYYY,DDD,HH" assumes MM, SS and FFFF are 0. The year is required, otherwise there wouldn't be much for a date.

Ranges are checked for each time value.

Parameters
seedtimestrSEED time string to convert
Returns
dltime_t time value on success and DLTERROR on error.
int dl_senddata ( DLCP dlconn,
void *  buffer,
size_t  sendlen 
)

Send arbitrary data to a DataLink server.

This fundamental routine is used by other library routines to send data via a DataLink connection. Before data is sent the socket to set to blocking mode and back to non-blocking before returning unless there was an error in which case the socket should be disconnected.

If a user specified network I/O timeout was not applied at the system socket level this routine will implement the timeout using an alarm timer to interrupt the blocked send.

Parameters
dlconnDataLink Connection Parameters
bufferBuffer containing data to send
sendlenNumber of bytes to send from buffer
Return values
0on success
-1on error.
int dl_sendpacket ( DLCP dlconn,
void *  headerbuf,
size_t  headerlen,
void *  databuf,
size_t  datalen,
void *  respbuf,
int  resplen 
)

Create and send a DataLink packet.

Send a DataLink packet created by combining an appropriate preheader with headerbuf and, optionally, databuf.

The header length must be larger than 0 but the packet length can be 0 resulting in a header-only packet, commonly used for sending commands.

If the response buffer respbuf is not NULL then read up to resplen bytes into respbuf using dl_recvheader() after sending the packet. This is only designed for small pieces of data, specifically the server acknowledgement to a command, which are a header-only packets.

Parameters
dlconnDataLink Connection Parameters
headerbufBuffer containing DataLink packet header
headerlenLength of header buffer to send
databufBuffer containing DataLink packet data
datalenLength of data buffer to send
respbufBuffer to place response from server
resplenLength of response buffer
Returns
number of bytes of response received
Return values
0on success and respbuf is NULL
-1on error
int dl_splitstreamid ( char *  streamid,
char *  w,
char *  x,
char *  y,
char *  z,
char *  type 
)

Split a stream ID into separate components: "W_X_Y_Z/TYPE".

Split stream ID into separate components from the composite form: "W_X_Y_Z/TYPE" where the underscores and slash separate the components. Memory for each component must already be allocated. If a specific component is not desired set the appropriate argument to NULL.

While the stream name components are completely generic the (strongly) suggested form for geophysical data is "NET_STA_LOC_CHAN/TYPE" where NETwork, STAtion, LOCation and CHANnel follow the FDSN SEED conventions.

Returns
0 on success and -1 on error.
int dl_strncpclean ( char *  dest,
const char *  source,
int  length 
)

Copy a string while removing space charaters.

Copy length characters from source to dest while removing all spaces. The result is left justified and always null terminated. The source string must have at least length characters and the destination string must have enough room needed for the non-space characters within length and the null terminator.

Parameters
destDestination string
sourceString to copy
lengthCopy up to a maximum of this many characters to dest
Returns
The number of characters (not including the null terminator) in the destination string.
int dl_strparse ( const char *  string,
const char *  delim,
DLstrlist **  list 
)

Parse/split a string on a specified delimiter.

Splits a 'string' on 'delim' and puts each part into a linked list pointed to by 'list' (a pointer to a pointer). The last entry has it's 'next' set to 0. All elements are NULL terminated strings.

It is up to the caller to free the memory associated with the returned list. To facilitate freeing this special string list dl_strparse() can be called with both 'string' and 'delim' set to NULL and then the linked list is traversed and the memory used is free'd and the list pointer is set to NULL.

Parameters
stringString to parse/split
delimDelimiter to split string on
listReturned list of sub-strings.
Returns
The number of elements added to the list, or 0 when freeing the linked list.
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.

dltime_t dl_time2dltime ( int  year,
int  day,
int  hour,
int  min,
int  sec,
int  usec 
)

Convert specified time values to a dltime_t value.

Convert specified time values to a high precision epoch time, a dltime_t value. The routine will range check all the input parameters.

Parameters
yearYear (1900 - 2100)
dayDay (1 - 366)
hourHour (0 - 23)
minMinute (0 - 59)
secSecond (0 - 60)
usecMicrosecond (0 - 999999)
Returns
dltime_t time value on success and DLTERROR on error.
dltime_t dl_timestr2dltime ( char *  timestr)

Convert a time string to a dltime_t value.

Convert a generic time string to a high precision epoch time. SEED time format is "YYYY[/MM/DD HH:MM:SS.FFFF]", the delimiter can be a dash [-], slash [/], colon [:], or period [.] and between the date and time a 'T' or a space may be used. The fracttional seconds must begin with a period [.].

The time string can be "short" in which case the omitted values are assumed to be zero (with the exception of month and day which are assumed to be 1): "YYYY/MM/DD" assumes HH, MM, SS and FFFF are 0. The year is required, otherwise there wouldn't be much for a date.

Ranges are checked for each time value.

Parameters
timestrTime string to convert
Returns
dltime_t time value on success and DLTERROR on error.
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
dlconnDataLink Connection Parameters
packetPacket data buffer to send
packetlenLength of data in bytes to send from packet
streamidStream ID of packet
datastartData start time for packet
dataendData end time for packet
ackAcknowledgement 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.