|
CDI SDK
SDK for transporting chunks of data reliably and with low latency using a polled mode network driver.
|
This file contains the definitions of the functions that comprise the CDI-AVM SDK's API. More...
#include "cdi_avm_api.h"#include <stdbool.h>#include <stddef.h>#include <stdlib.h>#include "cdi_baseline_profile_api.h"#include "internal.h"#include "internal_tx.h"#include "internal_rx.h"#include "cdi_utility_api.h"This file contains the definitions of the functions that comprise the CDI-AVM SDK's API.
| CdiReturnStatus CdiAvmEndpointTxPayload | ( | CdiEndpointHandle | endpoint_handle, |
| const CdiAvmTxPayloadConfig * | payload_config_ptr, | ||
| const CdiAvmConfig * | avm_config_ptr, | ||
| const CdiSgList * | sgl_ptr, | ||
| int | max_latency_microsecs ) |
Transmit a payload of data to a remote endpoint. Endpoint handles are obtained through CdiAvmTxStreamConnectionCreate(). This function is asynchronous and will immediately return. The user callback function CdiAvmTxCallback() registered through CdiAvmTxStreamConnectionCreate() will be invoked when the payload has been acknowledged by the remote receiver or a transmission timeout occurred.
MEMORY NOTE: The payload_config_ptr, avm_config_ptr, CdiSgList and SGL entries memory can be modified or released immediately after the function returns. However, the buffers pointed to in the SGL must not be modified or released until after the CdiAvmTxCallback() has occurred.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| endpoint_handle | Connection handle returned by a previous call to CdiAvmTxStreamEndpointCreate(). |
| payload_config_ptr | Pointer to payload configuration data. Part of the data is sent along with the payload and part is provided to the registered user TX callback function. |
| avm_config_ptr | Pointer to configuration data that describes the contents of this payload and subsequent payloads. The first time this function is called for a given stream_id (in payload_config_ptr->avm_extra_data) in the connection, a value must be specified so the receiver can identify the format of the payload data. Afterwards, NULL shall be specified unless some aspect of the configuration for this stream has changed since the previous payload was transmitted. |
| sgl_ptr | Scatter-gather list containing the data to be transmitted. The addresses in the SGL must point to locations that reside within the memory region specified in CdiAdapterData at ret_tx_buffer_ptr. |
| max_latency_microsecs | Maximum latency in microseconds. If the transmission time of a payload exceeds this value, the CdiAvmTxCallback() API function will be invoked with an error. |
| CdiReturnStatus CdiAvmRxCreate | ( | CdiRxConfigData * | config_data_ptr, |
| CdiAvmRxCallback | rx_cb_ptr, | ||
| CdiConnectionHandle * | ret_handle_ptr ) |
Create an instance of an AVM receiver. When done, must call CdiCoreConnectionDestroy().
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| config_data_ptr | Pointer to receiver configuration data. Copies of the data in the configuration data structure are made as needed. A local variable can be used for composing the structure since its contents are not needed after this function returns. |
| rx_cb_ptr | Address of the user function to call whenever a payload has been received. |
| ret_handle_ptr | Pointer to returned connection handle. The handle is used as a parameter to other API functions to identify this specific receiver. |
| CdiReturnStatus CdiAvmStreamEndpointDestroy | ( | CdiEndpointHandle | handle | ) |
Destroy a specific AVM stream endpoint and free resources that were created for it.
| handle | Connection handle returned by the CdiAvmTxStreamEndpointCreate() API function. |
| CdiReturnStatus CdiAvmTxCreate | ( | CdiTxConfigData * | config_data_ptr, |
| CdiAvmTxCallback | tx_cb_ptr, | ||
| CdiConnectionHandle * | ret_handle_ptr ) |
Create an instance of an AVM transmitter. When the instance is no longer needed, use the CdiCoreConnectionDestroy() API function to free-up resources that are being used by it.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| config_data_ptr | Pointer to transmitter configuration data. Copies of the data in the configuration data structure are made as needed. A local variable can be used for composing the structure since its contents are not needed after this function returns. |
| tx_cb_ptr | Address of the user function to call whenever a payload has been transmitted or a transmit timeout error has occurred. |
| ret_handle_ptr | Pointer to returned connection handle. The handle is used as a parameter to other API functions to identify this specific transmitter. |
| CdiReturnStatus CdiAvmTxPayload | ( | CdiConnectionHandle | con_handle, |
| const CdiAvmTxPayloadConfig * | payload_config_ptr, | ||
| const CdiAvmConfig * | avm_config_ptr, | ||
| const CdiSgList * | sgl_ptr, | ||
| int | max_latency_microsecs ) |
Transmit a payload of data to the receiver. The connection must have been created with CdiAvmTxCreate(). Connections that were created by calling CdiAvmTxStreamConnectionCreate() must use CdiAvmEndpointTxPayload() instead. This function is asynchronous and will immediately return. The user callback function CdiAvmTxCallback() registered through CdiAvmTxCreate() will be invoked when the payload has been acknowledged by the remote receiver or a transmission timeout occurred.
MEMORY NOTE: The payload_config_ptr, avm_config_ptr, CdiSgList and SGL entries memory can be modified or released immediately after the function returns. However, the buffers pointed to in the SGL must not be modified or released until after the CdiAvmTxCallback() has occurred.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| con_handle | Connection handle returned by a previous call to CdiAvmTxCreate(). |
| payload_config_ptr | Pointer to payload configuration data. Part of the data is sent along with the payload and part is provided to the registered user Tx callback function. |
| avm_config_ptr | Pointer to configuration data that describes the contents of this payload and subsequent payloads. The first time this function is called for a given stream identifier (in payload_config_ptr->avm_extra_data) after the connection's status has changed to kCdiConnectionStatusConnected (reported to the transmit callback function), a value must be specified so the receiver can identify the format of the payload data. Afterwards, NULL shall be specified unless some aspect of the configuration for this stream has changed since the previous payload was transmitted. |
| sgl_ptr | Scatter-gather list containing the data to be transmitted. The addresses in the SGL must point to locations that reside within the memory region specified in CdiAdapterData at ret_tx_buffer_ptr. |
| max_latency_microsecs | Maximum latency in microseconds. If this value is specified as 0, there will be no warning messages generated for late payloads. If a value is specified, and the transmission time of a payload exceeds this value, the CdiAvmTxCallback() API function will be invoked with an error. |
| CdiReturnStatus CdiAvmTxStreamConnectionCreate | ( | CdiTxConfigData * | config_data_ptr, |
| CdiAvmTxCallback | tx_cb_ptr, | ||
| CdiConnectionHandle * | ret_handle_ptr ) |
Create an instance of an AVM transmitter that uses multiple stream endpoints. A stream identifier value is used to uniquely identify each stream. Payloads are transmitted using the CdiAvmEndpointTxPayload() API function, which contains the stream identifier. The value determines which matching endpoint to use to transmit the payload. This API function only creates instance data for the connection. Use the CdiAvmTxStreamEndpointCreate() and CdiAvmStreamEndpointDestroy() API functions to dynamically create and destroy stream endpoints associated with this connection. When the instance is no longer needed, use the CdiCoreConnectionDestroy() API function to free-up resources that are being used by it.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| config_data_ptr | Pointer to transmitter configuration data. Copies of the data in the configuration data structure are made as needed. A local variable can be used for composing the structure since its contents are not needed after this function returns. NOTE: Within the structure, dest_ip_addr_str and dest_port are only used for generating the name of the connection if one was not provided. The IP and port are defined as part of the configuration data passed to CdiAvmTxStreamConnectionCreate(), when creating streams. |
| tx_cb_ptr | Address of the user function to call whenever a payload has been transmitted or a transmit timeout error has occurred. |
| ret_handle_ptr | Pointer to returned connection handle. The handle is used as a parameter to other API functions to identify this specific transmitter. |
| CdiReturnStatus CdiAvmTxStreamEndpointCreate | ( | CdiConnectionHandle | handle, |
| CdiTxConfigDataStream * | stream_config_ptr, | ||
| CdiEndpointHandle * | ret_handle_ptr ) |
Create an instance of an AVM stream endpoint that is associated with the specified stream connection.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| handle | Stream connection handle returned by a previous call to CdiAvmTxStreamConnectionCreate(). |
| stream_config_ptr | Pointer to stream configuration data. Copies of the data in this structure are made as needed. |
| ret_handle_ptr | Pointer to returned endpoint handle. The handle is used as a parameter to other API functions to identify this specific stream endpoint. |