Functions for network DataLink connections. More...

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

Detailed Description

Functions for network DataLink connections.

Function Documentation

◆ dl_connect()

SOCKET 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' or '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 separator) 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

◆ dl_disconnect()

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

◆ dl_senddata()

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.

◆ dl_sendpacket()

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

◆ dl_recvdata()

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.

◆ dl_recvheader()

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.