cdi_raw_api.h File Reference

This file declares the public API data types, structures and functions that comprise the CDI Raw payload transport SDK API. More...

#include "cdi_core_api.h"

Go to the source code of this file.

Data Structures
struct	CdiRawRxCbData
	A structure of this type is passed as the parameter to CdiRawRxCallback(). It contains a single payload sent from a transmitter. More...
struct	CdiRawTxCbData
	A structure of this type is passed as the parameter to CdiRawTxCallback(). It contains data related to the transmission of a single payload to a receiver. More...

Typedefs
typedef void(*	CdiRawRxCallback) (const CdiRawRxCbData *data_ptr)
	Prototype of receive data callback function. The user code must implement a function with this prototype, provide it to CdiRawRxCreate() as a parameter.
typedef void(*	CdiRawTxCallback) (const CdiRawTxCbData *data_ptr)
	Prototype of transmit data callback function. The user code must implement a function with this prototype and provide it to CdiRawtxCreate() as a parameter.

Functions
CDI_INTERFACE CdiReturnStatus	CdiRawTxCreate (CdiTxConfigData *config_data_ptr, CdiRawTxCallback tx_cb_ptr, CdiConnectionHandle *ret_handle_ptr)
CDI_INTERFACE CdiReturnStatus	CdiRawRxCreate (CdiRxConfigData *config_data_ptr, CdiRawRxCallback rx_cb_ptr, CdiConnectionHandle *ret_handle_ptr)
CDI_INTERFACE CdiReturnStatus	CdiRawTxPayload (CdiConnectionHandle con_handle, const CdiCoreTxPayloadConfig *payload_config_ptr, const CdiSgList *sgl_ptr, int max_latency_microsecs)

Detailed Description

This file declares the public API data types, structures and functions that comprise the CDI Raw payload transport SDK API.

Typedef Documentation

CdiRawRxCallback

typedef void(* CdiRawRxCallback) (const CdiRawRxCbData *data_ptr)

Prototype of receive data callback function. The user code must implement a function with this prototype, provide it to CdiRawRxCreate() 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.

Parameters

data_ptr

A pointer to an CdiRawRxCbData structure.

CdiRawTxCallback

typedef void(* CdiRawTxCallback) (const CdiRawTxCbData *data_ptr)

Prototype of transmit data callback function. The user code must implement a function with this prototype and provide it to CdiRawtxCreate() as a parameter.

This callback function is invoked when a complete payload has been transmitted.

Parameters

data_ptr

A pointer to an CdiRawTxCbData structure.

Function Documentation

CdiRawRxCreate()

CDI_INTERFACE CdiReturnStatus CdiRawRxCreate	(	CdiRxConfigData *	config_data_ptr,
		CdiRawRxCallback	rx_cb_ptr,
		CdiConnectionHandle *	ret_handle_ptr )

Create an instance of a raw 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.

Parameters

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.

Returns

A value from the CdiReturnStatus enumeration.

CdiRawTxCreate()

CDI_INTERFACE CdiReturnStatus CdiRawTxCreate	(	CdiTxConfigData *	config_data_ptr,
		CdiRawTxCallback	tx_cb_ptr,
		CdiConnectionHandle *	ret_handle_ptr )

Create an instance of a raw 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.

Parameters

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 being transmitted has been received by the receiver 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.

Returns

A value from the CdiReturnStatus enumeration.

CdiRawTxPayload()

CDI_INTERFACE CdiReturnStatus CdiRawTxPayload	(	CdiConnectionHandle	con_handle,
		const CdiCoreTxPayloadConfig *	payload_config_ptr,
		const CdiSgList *	sgl_ptr,
		int	max_latency_microsecs )

Transmit a payload of data to the receiver. This function is asynchronous and will immediately return. The user callback function CdiRawTxCallback() registered using the CdiRawTxCreate() API function will be invoked when the payload has been acknowledged by the remote receiver or a transmission timeout occurred.

MEMORY NOTE: The payload_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 CdiRawTxCallback() 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.

Parameters

con_handle	Connection handle returned by a previous call to CdiRawTxCreate().
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.
sgl_ptr	Scatter-gather list containing the payload 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 CdiRawTxCallback() API function will be invoked with an error.

Returns

A value from the CdiReturnStatus enumeration.