Functions to communicate using LLRP messages over a socket. More...

#include <assert.h>
#include <poll.h>
#include <unistd.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/tcp.h>
#include <arpa/inet.h>
#include <netdb.h>
#include <fcntl.h>
#include <time.h>
#include "ltkc_platform.h"
#include "ltkc_base.h"
#include "ltkc_frame.h"
#include "ltkc_connection.h"

Include dependency graph for ltkc_connection.c:

Go to the source code of this file.

Defines
#define	LLRP1_TCP_PORT (5084u)
Functions
static time_t	calculateTimeLimit (int nMaxMS)
	Internal routine to calculate time limit.
int	LLRP_Conn_closeConnectionToReader (LLRP_tSConnection *pConn)
	Close connection to reader, allow reuse of instance.
LLRP_tSConnection *	LLRP_Conn_construct (const LLRP_tSTypeRegistry *pTypeRegistry, unsigned int nBufferSize)
	Construct a new LLRP connection instance.
void	LLRP_Conn_destruct (LLRP_tSConnection *pConn)
	Destruct a LLRP connection instance.
const char *	LLRP_Conn_getConnectError (LLRP_tSConnection *pConn)
	Get the string that explains LLRP_Conn_openReaderConnection() error.
const LLRP_tSErrorDetails *	LLRP_Conn_getRecvError (LLRP_tSConnection *pConn)
	Get the details that explains LLRP_Conn_recvMessage() or LLRP_Conn_recvResponse() error.
const LLRP_tSErrorDetails *	LLRP_Conn_getSendError (LLRP_tSConnection *pConn)
	Get the details that explains LLRP_Conn_sendMessage() error.
const LLRP_tSErrorDetails *	LLRP_Conn_getTransactError (LLRP_tSConnection *pConn)
	Get the details that explains LLRP_Conn_transact() error.
int	LLRP_Conn_openConnectionToReader (LLRP_tSConnection pConn, const char pReaderHostName)
	Open the connection to the reader.
LLRP_tSMessage *	LLRP_Conn_recvMessage (LLRP_tSConnection *pConn, int nMaxMS)
	Receive a message from a connection.
LLRP_tSMessage *	LLRP_Conn_recvResponse (LLRP_tSConnection pConn, int nMaxMS, const LLRP_tSTypeDescriptor pResponseType, llrp_u32_t ResponseMessageID)
	Receive a specific message from a connection.
LLRP_tResultCode	LLRP_Conn_sendMessage (LLRP_tSConnection pConn, LLRP_tSMessage pMessage)
	Send a LLRP message to a connection.
LLRP_tSMessage *	LLRP_Conn_transact (LLRP_tSConnection pConn, LLRP_tSMessage pSendMessage, int nMaxMS)
	Transact a LLRP request and response to a connection.
static LLRP_tResultCode	recvAdvance (LLRP_tSConnection *pConn, int nMaxMS, time_t timeLimit)
	Internal routine to advance receiver.

Detailed Description

Functions to communicate using LLRP messages over a socket.

This provides a simple interface to send and receive LLRP messages using a network socket.

This is simplified. It is possible, even likely, that some applications could require much more sophistication. To that end this source file serves as an example to illustrate how framing, encoding, decoding, and response matching are done.

Definition in file ltkc_connection.c.

Define Documentation

#define LLRP1_TCP_PORT (5084u)

Definition at line 60 of file ltkc_connection.c.

Function Documentation

static time_t calculateTimeLimit ( int nMaxMS ) [static]

Internal routine to calculate time limit.

Based on nMaxMS, the subscriber specified max time to await receipt of a (specific) message, determine the last time() to try.

The timeLimit prevents "spinning". See LLRP_Conn_recvResponse() above.

Parameters:

[in] nMaxMS -1 => block indefinitely 0 => just peek at input queue and socket queue, return immediately no matter what >0 => ms to await complete frame

Returns:: timeLimit 0 => never stop >0 => latest time() to try

Definition at line 1183 of file ltkc_connection.c.

int LLRP_Conn_closeConnectionToReader ( LLRP_tSConnection * pConn )

Close connection to reader, allow reuse of instance.

Parameters:

[in] pConn Pointer to the connection instance.

Returns:: ==0 Connected OK, ready for business !=0 Error, check getConnectError() for reason

Definition at line 380 of file ltkc_connection.c.

LLRP_tSConnection* LLRP_Conn_construct	(	const LLRP_tSTypeRegistry *	pTypeRegistry,
		unsigned int	nBufferSize
	)

Construct a new LLRP connection instance.

Parameters:

[in]	pTypeRegistry	The LLRP registry of known message/parameter types. Includes standard and custom. Used during decode.
[in]	nBufferSize	Size of each the receive and send buffers. Use size larger than the largest frame you expect. 0 selects a default value.

Returns:: !=NULL Pointer to connection instance ==NULL Error, always an allocation failure most likely nBufferSize is weird

Definition at line 95 of file ltkc_connection.c.

void LLRP_Conn_destruct ( LLRP_tSConnection * pConn )

Destruct a LLRP connection instance.

Parameters:

[in] pConn Pointer to the connection instance.

Returns:: void

Definition at line 175 of file ltkc_connection.c.

const char* LLRP_Conn_getConnectError ( LLRP_tSConnection * pConn )

Get the string that explains LLRP_Conn_openReaderConnection() error.

Parameters:

[in] pConn Pointer to the connection instance.

Returns:: ==NULL No error !=NULL Short string description of error

Definition at line 360 of file ltkc_connection.c.

const LLRP_tSErrorDetails* LLRP_Conn_getRecvError ( LLRP_tSConnection * pConn )

Get the details that explains LLRP_Conn_recvMessage() or LLRP_Conn_recvResponse() error.

Parameters:

[in] pConn Pointer to the connection instance.

Returns:: Pointer to const error details

Definition at line 716 of file ltkc_connection.c.

const LLRP_tSErrorDetails* LLRP_Conn_getSendError ( LLRP_tSConnection * pConn )

Get the details that explains LLRP_Conn_sendMessage() error.

Parameters:

[in] pConn Pointer to the connection instance.

Returns:: Pointer to const error details

Definition at line 625 of file ltkc_connection.c.

const LLRP_tSErrorDetails* LLRP_Conn_getTransactError ( LLRP_tSConnection * pConn )

Get the details that explains LLRP_Conn_transact() error.

This is not 100% reliable. It looks at the send error and if that seems OK it uses the recv error. Uses of LLRP_Conn_sendMessage(), LLRP_Conn_recvMessage() or LLRP_CONN_recvResponse() since LLRP_Conn_transact() will distort the error.

Returns:: Pointer to const error details

Definition at line 490 of file ltkc_connection.c.

int LLRP_Conn_openConnectionToReader	(	LLRP_tSConnection *	pConn,
		const char *	pReaderHostName
	)

Open the connection to the reader.

The steps:

Look up the host name
Create a socket
Connect to the host address
Condition the socket (set options)

Parameters:

[in]	pConn	Pointer to the connection instance.
[in]	pReaderHostName	String containing the reader host name

Returns:: ==0 Connected OK, ready for business !=0 Error, check LLRP_Conn_getConnectError() for reason

Definition at line 245 of file ltkc_connection.c.

LLRP_tSMessage* LLRP_Conn_recvMessage	(	LLRP_tSConnection *	pConn,
		int	nMaxMS
	)

Receive a message from a connection.

The message could have already arrived and be pending on the input queue.

Parameters:

[in]	pConn	Pointer to the connection instance.
[in]	nMaxMS	-1 => block indefinitely 0 => just peek at input queue and socket queue, return immediately no matter what >0 => ms to await complete frame

Returns:: ==NULL No message available per parameters. Check LLRP_Conn_getRecvErrot() for why !=NULL Input message

Definition at line 654 of file ltkc_connection.c.

LLRP_tSMessage* LLRP_Conn_recvResponse	(	LLRP_tSConnection *	pConn,
		int	nMaxMS,
		const LLRP_tSTypeDescriptor *	pResponseType,
		llrp_u32_t	ResponseMessageID
	)

Receive a specific message from a connection.

The message is identified by type and message ID.

This is used to receive a response to a request, but could be used for other things, too. A message matches and is returned if the type matches AND if the message ID matches. Either or both can be wildcards.

The sought message could have already arrived and be pending on the input queue. While we are looking for the response notifications might arrive. They are held in the input queue while we continue to look for the sought message.

About timeLimit.... The timeLimit is the last time() we'll try to receive the sought message and prevents "spinning". It is conceivable that a steady stream of messages other than the one sought could arrive, and the time between those messages could be smaller the nMaxMS. When that happens, recvAdvance() would not time out during its poll/select. It could "spin". The time out must be detected by other means and that's the purpose of timeLimit.

Parameters:

[in]	pConn	Pointer to the connection instance.
[in]	nMaxMS	-1 => block indefinitely 0 => just peek at input queue and socket queue, return immediately no matter what >0 => ms to await complete frame
[in]	pResponseType	The type descriptor of the sought or NULL to match all messages. If not NULL, ERROR_MESSAGE will also match.
[in]	ResponseMessageID	The MessageID of sought message or 0 to match all messages.

Returns:: ==NULL No message available per parameters. Check LLRP_Conn_getRecvErrot() for why !=NULL Input message

Definition at line 771 of file ltkc_connection.c.

LLRP_tResultCode LLRP_Conn_sendMessage	(	LLRP_tSConnection *	pConn,
		LLRP_tSMessage *	pMessage
	)

Send a LLRP message to a connection.

Parameters:

[in]	pConn	Pointer to the connection instance.
[in]	pMessage	Pointer to the LLRP message to send.

Returns:: LLRP_RC_OK Frame sent LLRP_RC_SendIOError I/O error in write(). Probably means fd is bad. LLRP_RC_... Encoder error. Check LLRP_Conn_getSendError() for why.

Definition at line 522 of file ltkc_connection.c.

LLRP_tSMessage* LLRP_Conn_transact	(	LLRP_tSConnection *	pConn,
		LLRP_tSMessage *	pSendMessage,
		int	nMaxMS
	)

Transact a LLRP request and response to a connection.

This is a combination of LLRP_Conn_sendMessage() and LLRP_Conn_recvResponse(). The MessageID is taken from the outgoing messages. It's best to not use MessageID 0. The expected response type is also taken from the outgoing message. ERROR_MESSAGE is also deemed a response;

Parameters:

[in]	pConn	Pointer to the connection instance.
[in]	pSendMessage	Pointer to the LLRP message to send.
[in]	nMaxMS	-1 => block indefinitely 0 => just peek at input queue and socket queue, return immediately no matter what >0 => ms to await complete frame

Returns:: ==NULL Something failed. Use LLRP_Conn_getTransactError() for best guess at what went wrong. !=NULL Response message

Definition at line 424 of file ltkc_connection.c.

static LLRP_tResultCode recvAdvance	(	LLRP_tSConnection *	pConn,
		int	nMaxMS,
		time_t	timeLimit
	)		`[static]`

Internal routine to advance receiver.

Parameters:

[in]	pConn	Pointer to the connection instance.
[in]	nMaxMS	-1 => block indefinitely 0 => just peek at input queue and socket queue, return immediately no matter what >0 => ms to await complete frame

Returns:: LLRP_RC_OK Frame received LLRP_RC_RecvEOF End-of-file condition on fd LLRP_RC_RecvIOError I/O error in poll() or read(). Probably means fd is bad. LLRP_RC_RecvFramingError LLRP_FrameExtract() detected an impossible situation. Recovery unlikely. LLRP_RC_RecvTimeout Frame didn't complete within allowed time LLRP_RC_... Decoder error.

Definition at line 900 of file ltkc_connection.c.

Defines

Functions

Detailed Description

Define Documentation

Function Documentation