|
CDI SDK
SDK for transporting chunks of data reliably and with low latency using a polled mode network driver.
|
This file declares the public API data types, structures and functions that comprise the CDI audio, video and metadata SDK API. More...
Go to the source code of this file.
Data Structures | |
| struct | CdiAvmConfig |
| This is the generic AVM configuration structure which describes the format of each stream. More... | |
| struct | CdiAvmExtraData |
| Extra data that is sent along with the AVM payload to the receiver. It will be provided to the receiver through a registered user receive callback function. More... | |
| struct | CdiAvmTxPayloadConfig |
| A structure used to configure a AVM transmit payload. More... | |
| struct | CdiAvmRxCbData |
| A structure of this type is passed as the parameter to CdiAvmRxCallback(). It contains a single payload sent from a transmitter. More... | |
| struct | CdiAvmTxCbData |
| A structure of this type is passed as the parameter to CdiAvmTxCallback(). It contains data related to the transmission of a single payload to a receiver. More... | |
| struct | CdiTxConfigDataStream |
| Stream configuration data used by the CdiAvmTxStreamEndpointCreate() API function. More... | |
Typedefs | |
| typedef void(* | CdiAvmRxCallback) (const CdiAvmRxCbData *data_ptr) |
| Prototype of receive data callback function. The user code must implement a function with this prototype and provide it to CdiAvmRxCreate() as a parameter. | |
| typedef void(* | CdiAvmTxCallback) (const CdiAvmTxCbData *data_ptr) |
| Prototype of transmit data callback function. The user code must implement a function with this prototype and provide it to CdiAvmTxCreate() as a parameter. | |
This file declares the public API data types, structures and functions that comprise the CDI audio, video and metadata SDK API.
| typedef void(* CdiAvmRxCallback) (const CdiAvmRxCbData *data_ptr) |
Prototype of receive data callback function. The user code must implement a function with this prototype and provide it to CdiAvmRxCreate() as a parameter.
This callback function is invoked when a complete payload has been received. The application must use the CdiCoreRxFreeBuffer() API function to free the buffer. This can either be done within the user callback function or at a later time whenever the application is done with the buffer.
| data_ptr | A pointer to an CdiAvmRxData structure. |
| typedef void(* CdiAvmTxCallback) (const CdiAvmTxCbData *data_ptr) |
Prototype of transmit data callback function. The user code must implement a function with this prototype and provide it to CdiAvmTxCreate() as a parameter.
This callback function is invoked when a complete payload has been transmitted.
| data_ptr | A pointer to an CdiAvmTxCbData structure. |
| CDI_INTERFACE 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. |
| CDI_INTERFACE 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. |
| CDI_INTERFACE 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. |
| CDI_INTERFACE 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. |
| CDI_INTERFACE 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. |
| CDI_INTERFACE 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. |
| CDI_INTERFACE 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. |