# 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
DLCP * | dl_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.
DLLog * | dl_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 |  | ) | 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_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.