ltkc_win32/inc/ltkc_connection.h File Reference

Types and function prototypes for handling two-way LLRP message traffic. More...

Classes

struct  LLRP_SConnection
 Structure of an LLRP connection instance. More...

Functions

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.
int LLRP_Conn_openConnectionToReader (LLRP_tSConnection *pConn, const char *pReaderHostName)
 Open the connection to the reader.
int LLRP_Conn_closeConnectionToReader (LLRP_tSConnection *pConn)
 Close connection to reader, allow reuse of instance.
const char * LLRP_Conn_getConnectError (LLRP_tSConnection *pConn)
 Get the string that explains LLRP_Conn_openReaderConnection() error.
LLRP_tSMessage * LLRP_Conn_transact (LLRP_tSConnection *pConn, LLRP_tSMessage *pSendMessage, int nMaxMS)
 Transact a LLRP request and response to a connection.
const LLRP_tSErrorDetails * LLRP_Conn_getTransactError (LLRP_tSConnection *pConn)
 Get the details that explains LLRP_Conn_transact() error.
LLRP_tResultCode LLRP_Conn_sendMessage (LLRP_tSConnection *pConn, LLRP_tSMessage *pMessage)
 Send a LLRP message to a connection.
const LLRP_tSErrorDetails * LLRP_Conn_getSendError (LLRP_tSConnection *pConn)
 Get the details that explains LLRP_Conn_sendMessage() error.
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.
const LLRP_tSErrorDetails * LLRP_Conn_getRecvError (LLRP_tSConnection *pConn)
 Get the details that explains LLRP_Conn_recvMessage() or LLRP_Conn_recvResponse() error.

Detailed Description

Types and function prototypes for handling two-way LLRP message traffic.

Function Documentation

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
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
void LLRP_Conn_destruct ( LLRP_tSConnection *  pConn  ) 

Destruct a LLRP connection instance.

Parameters:
[in] pConn Pointer to the connection instance.
Returns:
void
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
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
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
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
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
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
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
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.
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
Generated on Thu Jul 27 11:09:23 2017 for Mercury C API by  doxygen 1.6.3