# connection.c File Reference

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

Include dependency graph for connection.c:

## Functions
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.

## Detailed Description

Routines for managing a connection with a DataLink server.

Author:
  Chad Trabant, IRIS Data Management Center

modified: 2008.256

## Function Documentation

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

Collect packets streaming from the DataLink server.

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

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

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

Return values:

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

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

Collect packets streaming from the DataLink server without blocking.

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

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

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

Return values:

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

int dl_exchangeIDs | ( | DLCP * | dlconn,
|  | int | parseresp |
| ) |  |  |

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

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | parseresp | Flag to control parsing of server response.

Returns:
  -1 on errors, 0 on success.

void dl_freedlcp | ( | DLCP * | dlconn | ) |

Free a DataLink Connection Parameter (DLCP) structure.

Free all memory associated with a DLCP struct.

Parameters:

  | dlconn | DLCP to free

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

Request information from the DataLink server.

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

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | infotype | The INFO type to request
  | infomatch | An optional match pattern
  | infodata | Buffer to place the INFO response into
  | maxinfosize | Maximum number of bytes to write to infodata buffer

Returns:
  The length of the INFO response in bytes on success and -1 on error.

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

Handle the server reply to a command.

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

Server replies are of the form:

"OK|ERROR value size"

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

Return values:

  | -1 | Error
  | 0 | "OK" received
  | 1 | "ERROR" received

int64_t dl_match | ( | DLCP * | dlconn,
|  | char * | matchpattern |
| ) |  |  |

Set the packet match parameters for a connection.

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

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | matchpattern | Match regular expression

Returns:
  the count of currently matched streams on success and -1 on error.

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

Create a new DataLink Connection Parameter (DLCP) structure.

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

Parameters:

  | address | Address of DataLink server in "host:port" format
  | progname | Name of program, usually argv[0]

Returns:
  allocated DLCP struct on success, NULL on error.

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

Position the client read position.

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | pktid | Packet ID to set position to
  | pkttime | Packet time cooresponding to pktid

Returns:
  A positive packet ID on success and -1 on error.

int64_t dl_position_after | ( | DLCP * | dlconn,
|  | dltime_t | datatime |
| ) |  |  |

Position the client read position based on data time.

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | datatime | Reference data time as a dltime_t value

Returns:
  A positive packet ID on success and -1 on error.

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

Request a packet from the DataLink server.

Request a specific packet from the server.

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

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | pktid | Packet ID to request
  | packet | Pointer to a DLPacket struct for the received packet header information
  | packetdata | Pointer to a buffer for received packet data
  | maxdatasize | Maximum data size to write to packetdata

Returns:
  Number of bytes of packet data received on success and -1 on error.

int64_t dl_reject | ( | DLCP * | dlconn,
|  | char * | rejectpattern |
| ) |  |  |

Set the packet reject parameters for a connection.

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

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | rejectpattern | Reject regular expression

Returns:
  the count of currently rejected streams on success and -1 on error.

void dl_terminate | ( | DLCP * | dlconn | ) |

Set the terminate parameter of a DataLink connection.

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

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

Send a packet to the DataLink server.

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

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

Parameters:

  | dlconn | DataLink Connection Parameters
  | packet | Packet data buffer to send
  | packetlen | Length of data in bytes to send from packet
  | streamid | Stream ID of packet
  | datastart | Data start time for packet
  | dataend | Data end time for packet
  | ack | Acknowledgement flag, if true request acknowledgement

Returns:
  -1 on error and 0 on success when no acknowledgement is requested and a positive packet ID on success when acknowledgement is requested.