libdali.h File Reference

#include "portable.h"

Include dependency graph for libdali.h:

This graph shows which files directly or indirectly include this file:


Data Structures

struct  DLLog
struct  DLCP
struct  DLPacket
struct  DLstrlist

Defines

#define LIBDALI_H   1
#define LIBDALI_VERSION   "1.1"
#define LIBDALI_RELEASE   "2008.256"
#define MAXPACKETSIZE   16384
#define MAXREGEXSIZE   16384
#define MAX_LOG_MSG_LENGTH   200
#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

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.
char * dl_read_streamlist (DLCP *dlconn, const char *streamfile)
 Create a compound regular expression from a list in a file.
int dl_connect (DLCP *dlconn)
 Connect to a DataLink server.
void dl_disconnect (DLCP *dlconn)
 Disconnect a DataLink connection.
int dl_senddata (DLCP *dlconn, void *buffer, size_t sendlen)
 Send arbitrary data to a DataLink server.
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.
int dl_recvdata (DLCP *dlconn, void *buffer, size_t readlen, uint8_t blockflag)
 Receive arbitrary data from a DataLink server.
int dl_recvheader (DLCP *dlconn, void *buffer, size_t buflen, uint8_t blockflag)
 Receive DataLink packet header.
int dl_doy2md (int year, int jday, int *month, int *mday)
 Compute the month and day-of-month from day-of-year.
int dl_md2doy (int year, int month, int mday, int *jday)
 Compute the day-of-year from year, month and day-of-month.
char * dl_dltime2isotimestr (dltime_t dltime, char *isotimestr, int8_t subseconds)
 Generate an ISO time string from a dltime_t.
char * dl_dltime2mdtimestr (dltime_t dltime, char *mdtimestr, int8_t subseconds)
 Generate an time string in month-day format from a dltime_t.
char * dl_dltime2seedtimestr (dltime_t dltime, char *seedtimestr, int8_t subseconds)
 Generate an time string in SEED format from a dltime_t.
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.
dltime_t dl_seedtimestr2dltime (char *seedtimestr)
 Convert a SEED time string to a dltime_t value.
dltime_t dl_timestr2dltime (char *timestr)
 Convert a time string to a dltime_t value.
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".
int dl_bigendianhost (void)
 Determine byte order of host machine.
double dl_dabs (double value)
 Return absolute value of double value.
int dl_readline (int fd, char *buffer, int buflen)
 Read a line from a file stream.
int dl_log (int level, int verb,...)
 Log a message using the global logging parameters.
int dl_log_r (const DLCP *dlconn, int level, int verb,...)
 Log a message using the log parameters from a DLCP.
int dl_log_rl (DLLog *log, int level, int verb,...)
 Log a message using the log parameters from a DLCP.
void dl_loginit (int verbosity, void(*log_print)(char *), const char *logprefix, void(*diag_print)(char *), const char *errprefix)
 Initialize global logging system parameters.
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.
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.
int dl_recoverstate (DLCP *dlconn, const char *statefile)
 Recover DataLink connection state from a file.
int dl_savestate (DLCP *dlconn, const char *statefile)
 Save a DataLink connection state to a file.
int dl_strparse (const char *string, const char *delim, DLstrlist **list)
 Parse/split a string on a specified delimiter.
int dl_strncpclean (char *dest, const char *source, int length)
 Copy a string while removing space charaters.
int dl_addtostring (char **string, char *add, char *delim, int maxlen)
 Concatinate one string to another growing the destination as needed.

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: 2008.256

Define Documentation

#define DL_DLTIME2EPOCH (  )     X / DLTMODULUS

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

#define DL_EPOCH2DLTIME (  )     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_RELEASE   "2008.256"

libdali release date

#define LIBDALI_VERSION   "1.1"

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 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:
string Destination string to be added to
add String to add to string
delim Optional delimiter between added strings (cannot be NULL, but can be an empty string)
maxlen Maximum 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:
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_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:
dlconn DataLink Connection Parameters
Returns:
the socket descriptor created.
Return values:
-1 on 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:
dlconn DataLink 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:
dltime The dltime_t time value
isotimestr Returned ISO time string, must have room for 27 characters
subseconds Flag 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:
dltime The dltime_t time value
mdtimestr Returned time string, must have room for 27 characters
subseconds Flag 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:
dltime The dltime_t time value
seedtimestr Returned time string, must have room for 25 characters
subseconds Flag 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:
year Year (1900 - 2100)
jday Day-of-year, "Julian" day (1 - 366)
month Returned month (1 - 12)
mday Returned 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:
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

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:
level Level at which to log the message (1, 2 or 3)
verb Verbosity 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:
dlconn DataLink Connection Parameters with associated logging paramters
level Level at which to log the message (1, 2 or 3)
verb Verbosity 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:
log DLLog logging paramters
level Level at which to log the message (1, 2 or 3)
verb Verbosity 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:
dlconn DataLink Connection Parameters
matchpattern Match 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:
year Year (1900 - 2100)
month Month (1 - 12)
mday Day-of-month (1 - 31)
jday Returned 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:
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.

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:
dlconn DataLink Connection Parameters
statefile File to recover state from
Return values:
-1 Error
0 Completed successfully
1 File 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:
dlconn DataLink Connection Parameters
buffer Buffer for received data
readlen Number of bytes to read and place into buffer
blockflag Flag to control use of blocking versus non-blocking mode
Returns:
number of bytes read on success
Return values:
0 when no data available on non-blocking socket
-1 on connection shutdown
-2 on 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:
0 when no data available on non-blocking socket
-1 on connection shutdown
-2 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.

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:
dlconn DataLink Connection Parameters
statefile File to save state to
Return values:
-1 Error
0 Completed 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:
seedtimestr SEED 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:
dlconn DataLink Connection Parameters
buffer Buffer containing data to send
sendlen Number of bytes to send from buffer
Return values:
0 on success
-1 on 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:
dlconn DataLink Connection Parameters
headerbuf Buffer containing DataLink packet header
headerlen Length of header buffer to send
databuf Buffer containing DataLink packet data
datalen Length of data buffer to send
respbuf Buffer to place response from server
resplen Length of response buffer
Returns:
number of bytes of response received
Return values:
0 on success and respbuf is NULL
-1 on 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:
dest Destination string
source String to copy
length Copy 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:
string String to parse/split
delim Delimiter to split string on
list Returned 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:
year Year (1900 - 2100)
day Day (1 - 366)
hour Hour (0 - 23)
min Minute (0 - 59)
sec Second (0 - 60)
usec Microsecond (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:
timestr Time 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:
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