|
3.3.0.0R11
Software Development Kit |
|
 |
|
3.3.0.0R11
Software Development Kit |
|
|
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 |
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.
| 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.
| true | Connection is active. |
| false | Connection is inactive. |
| [in,out] | lnph | Abstract 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.
| LTRX_NETWORK_RETURN__WORKING | Operation in progress. |
| LTRX_NETWORK_RETURN__SUCCESS | Success. |
| LTRX_NETWORK_RETURN__FAILURE | Failed. |
| [in,out] | lnph | Abstract handle from constructor. |
| [in] | data | Data to send. |
| [in] | length | Length of data to send. |
| [in] | push | If true, force the protocol layer to forward data now, unless no data has been buffered. |
| [in] | sendTrigger | This 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.
| [in,out] | lnph | Abstract 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.
| true | Success. |
| false | Failed. |
| [in,out] | lnph | Abstract 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.
| NULL | Failed. |
| [in] | lnp | Pointer to this structure. |
| [in] | optCredential | Name 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.
| [in,out] | lnph | Abstract handle from constructor. |
| [in] | currentCredential | Current 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.
| [in,out] | lnph | Abstract 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.
| true | Success. |
| false | Failed. |
| [in,out] | lnph | Abstract handle from constructor. |
| [in,out] | lis | Socket with established connection. |
| [in] | optionalHostname | Hostname 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.
| true | One or more bytes are available. |
| false | No data is available. |
| [in,out] | lnph | Abstract 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.
| true | No more receive data will be available. |
| false | More data might become available. |
| [in,out] | lnph | Abstract 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.
| [in,out] | lnph | Abstract handle from constructor. |
| [out] | dataPointerLocation | Points to data pointer that will be filled in if any bytes have been received. |
| [in] | length | Maximum 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.
| true | Success. |
| false | Failed. |
| [in,out] | lnph | Abstract handle from constructor. |
| [in] | data | Data to send. |
| [in] | length | Length of data to send. |
| [in] | push | If 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.
| [in,out] | lnph | Abstract handle from constructor. |
| [in] | how | Specifies directions of flow to be shut down. |
| unsigned int ltrx_network_protocol::requiresCredentials |
1 if credentials are used.