Definitions and functions for DataLink connections. More...

Data Structures
struct	DLCP

struct	DLPacket

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_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.

Detailed Description

Definitions and functions for DataLink connections.

Data Structure Documentation

◆ DLCP

struct DLCP

◆ DLPacket

struct DLPacket

Function Documentation

◆ dl_newdlcp()

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.

◆ dl_freedlcp()

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

◆ dl_exchangeIDs()

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.

◆ dl_position()

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

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

Returns: A positive packet ID on success, 0 when packet is not found and -1 on error.

◆ dl_position_after()

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.

◆ dl_match()

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.

◆ dl_reject()

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.

◆ dl_write()

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.

◆ dl_read()

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.

◆ dl_getinfo()

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.

◆ dl_collect()

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.

◆ dl_collect_nb()

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.

◆ dl_handlereply()

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

◆ dl_terminate()

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.

◆ dl_read_streamlist()

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.

◆ dl_recoverstate()

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)

◆ dl_savestate()

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

Data Structures

Functions

Detailed Description

Data Structure Documentation

◆ DLCP

◆ DLPacket

Function Documentation

◆ dl_newdlcp()

◆ dl_freedlcp()

◆ dl_exchangeIDs()

◆ dl_position()

◆ dl_position_after()

◆ dl_match()

◆ dl_reject()

◆ dl_write()

◆ dl_read()

◆ dl_getinfo()

◆ dl_collect()

◆ dl_collect_nb()

◆ dl_handlereply()

◆ dl_terminate()

◆ dl_read_streamlist()

◆ dl_recoverstate()

◆ dl_savestate()