4.8.0.0R6
Software Development Kit
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules
ltrx_network_protocol Struct Reference

Represents a network protocol for registration. More...

Data Fields

unsigned int isClient: 1
 
unsigned int isServer: 1
 
unsigned int isTcpBased: 1
 
unsigned int isUdpBased: 1
 
bool(* optProtocolIsConnectionActive )(struct ltrx_network_protocol_handle *lnph)
 Is connection active? More...
 
enum ltrx_network_return(* optProtocolSendDataNonBlocking )(struct ltrx_network_protocol_handle *lnph, const void *data, size_t length, bool push, struct ltrx_trigger *sendTrigger)
 Send data non-blocking. More...
 
size_t(* protocolCanSend )(struct ltrx_network_protocol_handle *lnph)
 How much data can be sent? More...
 
bool(* protocolCloseConnection )(struct ltrx_network_protocol_handle *lnph)
 Close connection. More...
 
struct
ltrx_network_protocol_handle *(* 
protocolConstructor )(const struct ltrx_network_protocol *lnp, const char *optCredential)
 Constructor. More...
 
bool(* protocolCredentialHasChanged )(struct ltrx_network_protocol_handle *lnph, const char *currentCredential)
 Has the configured credential been changed? More...
 
void(* protocolDestructor )(struct ltrx_network_protocol_handle *lnph)
 Destructor. More...
 
bool(* protocolEstablishConnection )(struct ltrx_network_protocol_handle *lnph, struct ltrx_ip_socket *lis, const char *optionalHostname)
 Establish connection. More...
 
bool(* protocolIsDataAvailable )(struct ltrx_network_protocol_handle *lnph)
 Is data available? More...
 
bool(* protocolIsEndOfFile )(struct ltrx_network_protocol_handle *lnph)
 Is receive at end of file? More...
 
const char * protocolName
 
size_t(* protocolReceiveData )(struct ltrx_network_protocol_handle *lnph, const uint8_t **dataPointerLocation, size_t length)
 Receive data. More...
 
bool(* protocolSendData )(struct ltrx_network_protocol_handle *lnph, const void *data, size_t length, bool push)
 Send data. More...
 
void(* protocolShutdown )(struct ltrx_network_protocol_handle *lnph, enum ltrx_network_protocol_shutdown how)
 Protocol shutdown. More...
 
unsigned int requiresCredentials: 1
 

Detailed Description

Represents a network protocol for registration.

This struct designates the procedures to support a Network protocol. It it used with ltrx_network_register_protocol().

Note that your struct must persist, so you will typically declare it static const.

Field Documentation

unsigned int ltrx_network_protocol::isClient

1 if supports client role.

unsigned int ltrx_network_protocol::isServer

1 if supports server (listener) role.

unsigned int ltrx_network_protocol::isTcpBased

1 if layered over TCP.

unsigned int ltrx_network_protocol::isUdpBased

1 if layered over UDP.

bool(* ltrx_network_protocol::optProtocolIsConnectionActive)(struct ltrx_network_protocol_handle *lnph)

Is connection active?

Checks if a connection is currently active. This may be called after this protocol layer has been constructed.

Return values
trueConnection is active.
falseConnection is inactive.
Parameters
[in,out]lnphAbstract handle from constructor.
enum ltrx_network_return(* ltrx_network_protocol::optProtocolSendDataNonBlocking)(struct ltrx_network_protocol_handle *lnph, const void *data, size_t length, bool push, struct ltrx_trigger *sendTrigger)

Send data non-blocking.

A protocol implementation optionally supplies this function to support non-blocking calls. If not implemented, the protocol implementation sets this function pointer to NULL. Some applications may require non-blocking calls, so will not operate with a protocol implementation that does not supply it.

This is called after this protocol layer has been established.

The caller must retain the integrity of data if it sees a return code of LTRX_NETWORK_RETURN__WORKING. In this case the caller must periodically call again, with length of 0 and push unchanged or false, until it sees LTRX_NETWORK_RETURN__SUCCESS or LTRX_NETWORK_RETURN__FAILURE returned. The caller may use sendTrigger to expedite this periodic calling, but may not rely on being triggered (must also use a reasonable timeout).

Note that with push of false, a return code of LTRX_NETWORK_RETURN__SUCCESS does NOT imply that the data has been transmitted, but merely buffered. To transmit the data, you will need to either call this with push of true, or call protocolCloseConnection.

Return values
LTRX_NETWORK_RETURN__WORKINGOperation in progress.
LTRX_NETWORK_RETURN__SUCCESSSuccess.
LTRX_NETWORK_RETURN__FAILUREFailed.
Parameters
[in,out]lnphAbstract handle from constructor.
[in]dataData to send.
[in]lengthLength of data to send.
[in]pushIf true, force the protocol layer to forward data now, unless no data has been buffered.
[in]sendTriggerThis trigger may be signaled when the operation is complete.
size_t(* ltrx_network_protocol::protocolCanSend)(struct ltrx_network_protocol_handle *lnph)

How much data can be sent?

Checks how many bytes can now be accepted for sending. This may be called after this protocol layer has been established.

Returns
Number of bytes that may be sent.
Parameters
[in,out]lnphAbstract handle from constructor.
bool(* ltrx_network_protocol::protocolCloseConnection)(struct ltrx_network_protocol_handle *lnph)

Close connection.

Perform any necessary handshakes to gracefully close this protocol layer connection. This is called after this protocol layer has been established.

Caution: This function may block until it either succeeds or fails.

Return values
trueSuccess.
falseFailed.
Parameters
[in,out]lnphAbstract handle from constructor.
struct ltrx_network_protocol_handle*(* ltrx_network_protocol::protocolConstructor)(const struct ltrx_network_protocol *lnp, const char *optCredential)

Constructor.

This constructor function performs initialization, typically allocating necessary memory or other resources.

Returns
Abstract handle to be used with subsequent network functions.
Return values
NULLFailed.
Parameters
[in]lnpPointer to this structure.
[in]optCredentialName of credential if required, otherwise NULL.
bool(* ltrx_network_protocol::protocolCredentialHasChanged)(struct ltrx_network_protocol_handle *lnph, const char *currentCredential)

Has the configured credential been changed?

This may be called after this protocol layer has been established.

The application will call this to see if any changes have been made to the credential configuration, which it only knows by the credential name. Typically the application will close any current connections when it learns that a change has been made.

Parameters
[in,out]lnphAbstract handle from constructor.
[in]currentCredentialCurrent name of credential.
void(* ltrx_network_protocol::protocolDestructor)(struct ltrx_network_protocol_handle *lnph)

Destructor.

This destructor function performs shutdown, typically freeing any memory or resources allocated by the constructor.

Parameters
[in,out]lnphAbstract handle from constructor.
bool(* ltrx_network_protocol::protocolEstablishConnection)(struct ltrx_network_protocol_handle *lnph, struct ltrx_ip_socket *lis, const char *optionalHostname)

Establish connection.

Perform any necessary handshakes to establish this protocol layer connection. This is called after the underlying TCP or UDP layer is established.

Caution: This function may block until it either succeeds or fails.

Return values
trueSuccess.
falseFailed.
Parameters
[in,out]lnphAbstract handle from constructor.
[in,out]lisSocket with established connection.
[in]optionalHostnameHostname or NULL.
bool(* ltrx_network_protocol::protocolIsDataAvailable)(struct ltrx_network_protocol_handle *lnph)

Is data available?

Checks if any data is available for receive. This may be called after this protocol layer has been established.

Return values
trueOne or more bytes are available.
falseNo data is available.
Parameters
[in,out]lnphAbstract handle from constructor.
bool(* ltrx_network_protocol::protocolIsEndOfFile)(struct ltrx_network_protocol_handle *lnph)

Is receive at end of file?

Checks if all receive data has been read and a FIN has been received. This may be called after this protocol layer has been established.

Return values
trueNo more receive data will be available.
falseMore data might become available.
Parameters
[in,out]lnphAbstract handle from constructor.
const char* ltrx_network_protocol::protocolName

Name of this protocol as it will appear in configuration menu choices.

size_t(* ltrx_network_protocol::protocolReceiveData)(struct ltrx_network_protocol_handle *lnph, const uint8_t **dataPointerLocation, size_t length)

Receive data.

This may be called after this protocol layer has been established.

Note: Any data under the returned dataPointerLocation will remain intact until the next call to protocolReceiveData or protocolCloseConnection.

Returns
Number of bytes that have been received.
Parameters
[in,out]lnphAbstract handle from constructor.
[out]dataPointerLocationPoints to data pointer that will be filled in if any bytes have been received.
[in]lengthMaximum number of bytes that may be read by this operation.
bool(* ltrx_network_protocol::protocolSendData)(struct ltrx_network_protocol_handle *lnph, const void *data, size_t length, bool push)

Send data.

This is called after this protocol layer has been established.

Caution: This function may block until it either succeeds or fails.

Return values
trueSuccess.
falseFailed.
Parameters
[in,out]lnphAbstract handle from constructor.
[in]dataData to send.
[in]lengthLength of data to send.
[in]pushIf true, force the protocol layer to forward data now, unless no data has been buffered.
void(* ltrx_network_protocol::protocolShutdown)(struct ltrx_network_protocol_handle *lnph, enum ltrx_network_protocol_shutdown how)

Protocol shutdown.

This may be called after this protocol layer has been established.

Parameters
[in,out]lnphAbstract handle from constructor.
[in]howSpecifies directions of flow to be shut down.
unsigned int ltrx_network_protocol::requiresCredentials

1 if credentials are used.


The documentation for this struct was generated from the following file: