cdi_raw_api.c File Reference

This file contains the definitions of the functions that comprise the CDI Raw Payload SDK's API. More...

#include "cdi_raw_api.h"
#include <stdbool.h>
#include <stddef.h>
#include "internal.h"
#include "internal_tx.h"
#include "internal_rx.h"

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

Detailed Description

This file contains the definitions of the functions that comprise the CDI Raw Payload SDK's API.

Function Documentation

CdiRawRxCreate()

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()

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()

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.