internal.h File Reference

The declarations in this header file correspond to the definitions in internal.c. More...

#include <assert.h>
#include "configuration.h"
#include "adapter_api.h"
#include "cdi_core_api.h"
#include "cdi_log_api.h"
#include "cdi_raw_api.h"
#include "internal_log.h"

Go to the source code of this file.

Macros
#define	PAYLOAD_ERROR(con_state_ptr, app_cb_data_ptr, status_code, ...)
#define	BACK_PRESSURE_ERROR(back_pressure_state, log_level, ...)

Functions
static bool	IsValidTxHandle (const CdiConnectionHandle handle)
static bool	IsValidRxHandle (const CdiConnectionHandle handle)
static bool	IsValidConnectionHandle (const CdiConnectionHandle handle)
static bool	IsValidEndpointHandle (const CdiEndpointHandle handle)
static bool	IsValidMemoryHandle (const CdiMemoryHandle handle)
static bool	IsValidAdapterHandle (const CdiAdapterHandle handle)
CdiReturnStatus	CdiGlobalInitialization (const CdiCoreConfigData *core_config_ptr)
int	CdiGatherInternal (const CdiSgList *sgl_ptr, int offset, void *dest_data_ptr, int byte_count)
CdiReturnStatus	AdapterInitializeInternal (CdiAdapterData *adapter_data_ptr, CdiAdapterHandle *ret_handle_ptr)
CdiReturnStatus	NetworkAdapterDestroyInternal (CdiAdapterHandle handle)
void	ConnectionDestroyInternal (CdiConnectionHandle handle)
void	EndpointDestroyInternal (CdiEndpointHandle handle)
CdiReturnStatus	SdkShutdownInternal (void)
CdiReturnStatus	ConnectionCommonResourcesCreate (CdiConnectionHandle handle, CdiCoreStatsCallback stats_cb_ptr, CdiUserCbParameter stats_user_cb_param, const CdiStatsConfigData *stats_config_ptr)
void	ConnectionCommonResourcesDestroy (CdiConnectionHandle handle)
CdiReturnStatus	ConnectionCommonPacketMessageThreadCreate (CdiConnectionHandle handle, char const *thread_name)
CdiReturnStatus	CoreStatsConfigureInternal (CdiConnectionHandle handle, const CdiStatsConfigData *new_config_ptr, bool force_changes)
void	PayloadErrorSet (CdiConnectionState *con_state_ptr, AppPayloadCallbackData *app_cb_data_ptr, CdiReturnStatus status_code, const char *format_str,...)
void	PayloadErrorFreeBuffer (CdiPoolHandle pool_handle, AppPayloadCallbackData *app_cb_data_ptr)
static void	SglAppend (CdiSgList *sgl_list_ptr, CdiSglEntry *sgl_add_ptr)
static void	SglMoveEntries (CdiSgList *destination_sgl_ptr, CdiSgList *source_sgl_ptr)
static void	SglSetEmptyForExternalUse (CdiSgList *sgl_ptr)
bool	FreeSglEntries (CdiPoolHandle pool_handle, CdiSglEntry *sgl_entry_head_ptr)
void	DumpPayloadConfiguration (const CdiCoreExtraData *core_extra_data_ptr, int extra_data_size, const uint8_t *extra_data_array, CdiConnectionProtocolType protocol_type)
void	BytesToHexString (const void *data_ptr, int data_byte_count, char *dest_buffer_str, int dest_buffer_size)
void	DeviceGidToString (const uint8_t *device_gid_ptr, int gid_length, char *dest_buffer_str, int dest_buffer_size)
void	SdkThreadJoin (CdiThreadID thread_id, CdiSignalType shutdown_signal)
CdiLogHandle	CdiLogGlobalGetInternal (void)

Detailed Description

The declarations in this header file correspond to the definitions in internal.c.

Macro Definition Documentation

BACK_PRESSURE_ERROR

#define BACK_PRESSURE_ERROR	(		back_pressure_state,
			log_level,
			... )

Value:

    if (kCdiBackPressureNone == back_pressure_state) { \
        back_pressure_state = kCdiBackPressureActive; \
        CdiLogger(CdiLoggerThreadLogGet(), kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, __VA_ARGS__); \
    }

Macro used to generate back pressure related errors for the specified connection, with suppression. If an error has already been generated for the specified connection then future messages will be suppressed until the error condition has been resolved.

Parameters

back_pressure_state	Back pressure state variable (CdiBackPressureState).
log_level	Log level for the message. The remaining parameters contain a variable length list of arguments to generate the error message (CdiLogLevel).

PAYLOAD_ERROR

#define PAYLOAD_ERROR	(		con_state_ptr,
			app_cb_data_ptr,
			status_code,
			... )

Value:

    { \
    PayloadErrorSet(con_state_ptr, app_cb_data_ptr, status_code, __VA_ARGS__); \
    CdiLogger(CdiLoggerThreadLogGet(), kLogComponentGeneric, kLogError, __FUNCTION__, __LINE__ , __VA_ARGS__); }

Macro used to set error message string in the specified payload callback. The error message is made available to the application through the user-registered Tx/Rx payload callback functions.

Parameters

con_state_ptr	Pointer to connection state data (CdiConnectionState).
app_cb_data_ptr	Pointer to payload callback data (AppPayloadCallbackData).
status_code	Status code to set (CdiReturnStatus). The remaining parameters contain a variable length list of arguments to generate the error message.

Function Documentation

AdapterInitializeInternal()

CdiReturnStatus AdapterInitializeInternal	(	CdiAdapterData *	adapter_data_ptr,
		CdiAdapterHandle *	ret_handle_ptr )

Initialize an adapter.

Parameters

adapter_data_ptr	Address of a structure containing all of the pertinent information required to perform the initialization.
ret_handle_ptr	Pointer to a location in memory to place the handle to the initialized adapter.

Returns

CdiReturnStatus kCdiStatusOk if all went well, otherwise a value indicating why it failed.

See also

CdiCoreNetworkAdapterInitialize

BytesToHexString()

void BytesToHexString	(	const void *	data_ptr,
		int	data_byte_count,
		char *	dest_buffer_str,
		int	dest_buffer_size )

Convert an array of bytes to a hexadecimal string.

Parameters

data_ptr	Pointer to array of bytes.
data_byte_count	Number of data bytes.
dest_buffer_str	Address where to write the hex string to.
dest_buffer_size	Size of destination string buffer.

CdiGatherInternal()

int CdiGatherInternal	(	const CdiSgList *	sgl_ptr,
		int	offset,
		void *	dest_data_ptr,
		int	byte_count )

This is the implementation behind the API function CdiGather(). It is located in a private implementation file since it references names we wish to hide from cdiAPI.c.

Parameters

sgl_ptr	The scatter-gather list containing the data to be gathered.
offset	Number of bytes to skip in SGL before starting the copy.
dest_data_ptr	Where to write the gathered data in linear format.
byte_count	The number of bytes to copy.

Returns

The number of bytes copied. This will be less than byte_count if fewer than that number of bytes are present in the source SGL starting from the specified offset. A value of -1 indicates that a fatal error was encountered.

CdiGlobalInitialization()

CdiReturnStatus CdiGlobalInitialization

(

const CdiCoreConfigData *

core_config_ptr

)

Performs initialization of the SDK that only needs to be done once and applies to programs that transmit, receive, or both transmit and receive.

Parameters

core_config_ptr

Pointer to core configuration data that is used to initalize the SDK. Value is required and cannot be NULL.

Returns

A value from the CdiReturnStatus enumeration.

CdiLogGlobalGetInternal()

CdiLogHandle CdiLogGlobalGetInternal

(

void

)

Get the handle to the global log set by the CdiGlobalInitialization() function.

Returns

Handle of global log. If the CdiGlobalInitialization() function has not been used, NULL is returned.

ConnectionCommonPacketMessageThreadCreate()

CdiReturnStatus ConnectionCommonPacketMessageThreadCreate	(	CdiConnectionHandle	handle,
		char const *	thread_name )

Create connection packet message thread that is common to both Tx and Rx connection types.

Parameters

handle	The handle of the connection being created.
thread_name	The internal name of the thread.

Returns

CdiReturnStatus kCdiStatusOk if the thread was successfully created, otherwise the value indicates the nature of the failure.

ConnectionCommonResourcesCreate()

CdiReturnStatus ConnectionCommonResourcesCreate	(	CdiConnectionHandle	handle,
		CdiCoreStatsCallback	stats_cb_ptr,
		CdiUserCbParameter	stats_user_cb_param,
		const CdiStatsConfigData *	stats_config_ptr )

Create connection resources that are common to both Tx and Rx connection types. These are OS level resources that must be created prior to the creation of any child threads related to this connection.

Parameters

handle	The handle of the connection being created.
stats_cb_ptr	Address of stats callback function.
stats_user_cb_param	User-defined parameter in structure passed to stats_cb_ptr.
stats_config_ptr	Pointer to statistics configuration data.

Returns

CdiReturnStatus kCdiStatusOk if resources were successfully created, otherwise the value indicates the nature of the failure.

ConnectionCommonResourcesDestroy()

void ConnectionCommonResourcesDestroy

(

CdiConnectionHandle

handle

)

Destroy connection resources that are common to both Tx and Rx connection types. These are OS level resources that should be destroyed after all child threads related to this connection have finished using resources.

Parameters

handle

The handle of the connection being destroyed.

ConnectionDestroyInternal()

void ConnectionDestroyInternal

(

CdiConnectionHandle

handle

)

Shuts down a connection and frees all of the resources associated with it.

Parameters

handle

The handle of the connection to shut down.

CoreStatsConfigureInternal()

CdiReturnStatus CoreStatsConfigureInternal	(	CdiConnectionHandle	handle,
		const CdiStatsConfigData *	new_config_ptr,
		bool	force_changes )

Configure transfer statistics.

Parameters

handle	The handle of the connection to set statistics configuration.
new_config_ptr	Pointer to new statistics configuration data.
force_changes	If true, settings are applied (used to set initial values), otherwise settings are only applied if any of their values change.

Returns

A value from the CdiReturnStatus enumeration.

DeviceGidToString()

void DeviceGidToString	(	const uint8_t *	device_gid_ptr,
		int	gid_length,
		char *	dest_buffer_str,
		int	dest_buffer_size )

Convert a binary device GID to a string.

Parameters

device_gid_ptr	Pointer to binary device GID.
gid_length	Number of bytes in GID.
dest_buffer_str	Address where to write the string to.
dest_buffer_size	Size of destination string buffer.

DumpPayloadConfiguration()

void DumpPayloadConfiguration	(	const CdiCoreExtraData *	core_extra_data_ptr,
		int	extra_data_size,
		const uint8_t *	extra_data_array,
		CdiConnectionProtocolType	protocol_type )

Dump to log payload configuration data. NOTE: kLogPAYLOAD_CONFIG must be enabled in the logger using CdiFileLogEnable(), otherwise no messages will be generated.

Parameters

core_extra_data_ptr	Pointer to core extra data.
extra_data_size	Number of extra data bytes.
extra_data_array	Pointer to extra data bytes.
protocol_type	The type of connection protocol, kProtocolTypeRaw or kProtocolTypeAvm

EndpointDestroyInternal()

void EndpointDestroyInternal

(

CdiEndpointHandle

handle

)

Shuts down a endpoint and frees all of the resources associated with it.

Parameters

handle

The handle of the endpoint to shut down.

FreeSglEntries()

bool FreeSglEntries	(	CdiPoolHandle	pool_handle,
		CdiSglEntry *	sgl_entry_head_ptr )

Free a list of scatter-gather list entries from a memory pool.

Parameters

pool_handle	Handle of pool which contains the SGL entries to free.
sgl_entry_head_ptr	Pointer to the head entry of the SGL entry list to free.

Returns

bool True if entry was successfully freed, otherwise an error occurred.

IsValidAdapterHandle()

static bool IsValidAdapterHandle ( const CdiAdapterHandle handle )

inlinestatic

Function to check if a adapter handle is valid.

Parameters

handle

Pointer to adapter handle being checked.

Returns

true if handle is valid, otherwise false is returned.

IsValidConnectionHandle()

static bool IsValidConnectionHandle ( const CdiConnectionHandle handle )

inlinestatic

Function to check if a connection is valid.

Parameters

handle

Pointer to connection being checked.

Returns

true if handle is valid, otherwise false is returned.

IsValidEndpointHandle()

static bool IsValidEndpointHandle ( const CdiEndpointHandle handle )

inlinestatic

Function to check if an endpoint is valid.

Parameters

handle

Pointer to endpoint being checked.

IsValidMemoryHandle()

static bool IsValidMemoryHandle ( const CdiMemoryHandle handle )

inlinestatic

Function to check if a memory handle is valid.

Parameters

handle

Pointer to memory handle being checked.

Returns

true if handle is valid, otherwise false is returned.

IsValidRxHandle()

static bool IsValidRxHandle ( const CdiConnectionHandle handle )

inlinestatic

Function to check if an Rx is valid.

Parameters

handle

Pointer to Rx being checked.

Returns

true if handle is valid, otherwise false is returned.

IsValidTxHandle()

static bool IsValidTxHandle ( const CdiConnectionHandle handle )

inlinestatic

Function to check if a Tx is valid.

Parameters

handle

Pointer to Tx being checked.

Returns

true if handle is valid, otherwise false is returned.

NetworkAdapterDestroyInternal()

CdiReturnStatus NetworkAdapterDestroyInternal

(

CdiAdapterHandle

handle

)

Destroy an adapter.

Parameters

handle

Handle of adapter to destroy.

Returns

CdiReturnStatus kCdiStatusOk if all went well, otherwise a value indicating why it failed.

See also

CdiCoreNetworkAdapterDestroy

PayloadErrorFreeBuffer()

void PayloadErrorFreeBuffer	(	CdiPoolHandle	pool_handle,
		AppPayloadCallbackData *	app_cb_data_ptr )

Free error message buffer, if it was used.

Parameters

pool_handle	Handle for the pool to which to return the error buffer.
app_cb_data_ptr	Pointer to payload callback data (AppPayloadCallbackData).

PayloadErrorSet()

void PayloadErrorSet	(	CdiConnectionState *	con_state_ptr,
		AppPayloadCallbackData *	app_cb_data_ptr,
		CdiReturnStatus	status_code,
		const char *	format_str,
			... )

Set error message string in the specified payload callback. The error message is made available to the application through the user-registered Tx/Rx payload callback functions.

NOTE: Should not be used directly. Use the PAYLOAD_ERROR() macro instead.

Parameters

con_state_ptr	Pointer to connection state data (CdiConnectionState).
app_cb_data_ptr	Pointer to payload callback data (AppPayloadCallbackData).
status_code	Status code to set (CdiReturnStatus).
format_str	Pointer to string used for formatting the message. The remaining parameters contain a variable length list of arguments used by the format string to generate the error message.

SdkShutdownInternal()

CdiReturnStatus SdkShutdownInternal

(

void

)

Shut down the SDK, freeing all of the resources that were allocated by it.

Returns

CdiReturnStatus kCdiStatusOk if SDK was shut down cleanly, otherwise the value indicates the nature of the failure.

SdkThreadJoin()

void SdkThreadJoin	(	CdiThreadID	thread_id,
		CdiSignalType	shutdown_signal )

Set shutdown signal and wait for thread to exit.

Parameters

thread_id	Identifier of thread to wait for it to exit.
shutdown_signal	The shutdown signal used to shutdown the thread.

SglAppend()

static void SglAppend ( CdiSgList * sgl_list_ptr, CdiSglEntry * sgl_add_ptr )

inlinestatic

Append a scatter-gather list entry to the tail of an SGL entry. N.B.: sgl_add_ptr should be a single entry (that is, its next_ptr should be NULL) otherwise any chained entries may be lost. The SGL list's total_data_size is updated accordingly.

Parameters

sgl_list_ptr	Pointer to SGL list. If the head of the list is NULL, then the value is set to the new entry. Otherwise the new entry is added to the current tail's next pointer and the tail is updated to point to the new entry.
sgl_add_ptr	Pointer to new entry to add.

SglMoveEntries()

static void SglMoveEntries ( CdiSgList * destination_sgl_ptr, CdiSgList * source_sgl_ptr )

inlinestatic

Append scatter-gather list's entries to the end of another list. This handles either or both lists containing zero or more entries. The destination list's total_data_size is updated accordingly. src_sgl_ptr is empty on return.

Parameters

destination_sgl_ptr	Pointer to an SGL which will assume the entries from src_sgl_ptr.
source_sgl_ptr	Pointer to an SGL whose entries will be appended to the list at destination_sgl_ptr.

SglSetEmptyForExternalUse()

static void SglSetEmptyForExternalUse ( CdiSgList * sgl_ptr )

inlinestatic

Set a scatter-gather list as empty using a predefined static SGL entry. Used to clear an SGL that is passed to the user application and later used internally. In this case, use of an empty SGL will not generate an error.

Parameters

sgl_ptr

Pointer to an SGL to set as ampty.