#include "TUTKGlobalAPIs.h"

Data Structures
struct	st_RDT_Status

Macros
#define	RDTAPI_API __declspec(dllimport)

#define	RDTAPI_API_DEPRECATED

#define	MAX_DEFAULT_RDT_CHANNEL_NUMBER 128

#define	RDT_ER_NoERROR 0

#define	RDT_ER_NOT_INITIALIZED -10000

#define	RDT_ER_ALREADY_INITIALIZED -10001

#define	RDT_ER_EXCEED_MAX_CHANNEL -10002

#define	RDT_ER_MEM_INSUFF -10003

#define	RDT_ER_FAIL_CREATE_THREAD -10004

#define	RDT_ER_FAIL_CREATE_MUTEX -10005

#define	RDT_ER_RDT_DESTROYED -10006

#define	RDT_ER_TIMEOUT -10007

#define	RDT_ER_INVALID_RDT_ID -10008

#define	RDT_ER_RCV_DATA_END -10009

#define	RDT_ER_REMOTE_ABORT -10010

#define	RDT_ER_LOCAL_ABORT -10011

#define	RDT_ER_CHANNEL_OCCUPIED -10012

#define	RDT_ER_NO_PERMISSION -10013

#define	RDT_ER_INVALID_ARG -10014

#define	RDT_ER_LOCAL_EXIT -10015

#define	RDT_ER_REMOTE_EXIT -10016

#define	RDT_ER_SEND_BUFFER_FULL -10017

#define	RDT_ER_UNCLOSED_CONNECTION_DETECTED -10018

#define	RDT_ER_DEINITIALIZING -10019

#define	RDT_ER_FAIL_INITIALIZE_DTLS -10020

#define	RDT_ER_CREATE_DTLS_FAIL -10021

#define	RDT_ER_OPERATION_IS_INVALID -10022

#define	RDT_ER_REMOTE_NOT_SUPPORT_DTLS -10023

#define	RDT_ER_LOCAL_NOT_SUPPORT_DTLS -10024

Functions
RDTAPI_API_DEPRECATED int32_t	RDT_GetRDTApiVer ()
	Get the version of RDT module.

const char *	RDT_GetRDTApiVersionString (void)
	Get the version of RDT module.

void	RDT_Set_Max_Channel_Number (uint32_t nMaxChannelNum)
	Set the max number of RDT channels.

int32_t	RDT_Initialize ()
	Initialize RDT module.

int32_t	RDT_DeInitialize ()
	Deinitialize RDT module.

RDTAPI_API_DEPRECATED int32_t	RDT_Create (int32_t nIOTCSessionID, int32_t nTimeout, uint8_t nIOTCChannelID)
	Create a RDT channel.

int32_t	RDT_Create_Exit (int32_t nIOTCSessionID, uint8_t nIOTCChannelID)
	Exit the process of a specific RDT channel create.

int32_t	RDT_Destroy (int32_t nRDTChannelID)
	Destroy a RDT channel.

int32_t	RDT_Abort (int32_t nRDTChannelID)
	Abort a RDT channel.

int32_t	RDT_Set_Max_SendBuffer_Size (int32_t nRDTChannelID, int32_t nMaxSendBufferSize)
	Set max send queue buffer size.

int32_t	RDT_Flush (int32_t nRDTChannelID)
	Flush data in an RDT channel.

int32_t	RDT_Write (int32_t nRDTChannelID, const char *cabBuf, int32_t nBufSize)
	Write data through a RDT channel.

int32_t	RDT_Read (int32_t nRDTChannelID, char *abBuf, int32_t nBufSize, int32_t nTimeout)
	Read data through a RDT channel.

int32_t	RDT_Status_Check (int32_t nRDTChannelID, struct st_RDT_Status *psRDT_Status)
	Get status of a RDT channel.

void	RDT_Set_Log_Path (const char *path, int32_t nMaxSize)
	Set path of log file.

int32_t	RDT_Set_Log_Attr (LogAttr logAttr)
	Set Attribute of log file.

int32_t	RDT_Set_Max_Pending_ACK_Number (int32_t nRDTChannelID, uint32_t nMaxNumber)
	Set the max number of pending ACKs of the RDT channel.

int32_t	RDT_Set_MaxPacketDataSize (uint32_t nMaxSize)
	Set the max packet data size of a single RDT packet.

Detailed Description

This file describes all the APIs of the RDT module in IOTC platform.

Copyright: Copyright (c) 2010 by Throughtek Co., Ltd. All Rights Reserved.

Macro Definition Documentation

#define MAX_DEFAULT_RDT_CHANNEL_NUMBER 128

#define RDT_ER_ALREADY_INITIALIZED -10001

RDT module is already initialized. It is not necessary to re-initialize.

#define RDT_ER_CHANNEL_OCCUPIED -10012

The specific IOTC session and channel ID is used now so can't use the same resource. You can choose other IOTC channel for RDT use or wait RDT_Abort() to release resource automatically.

#define RDT_ER_CREATE_DTLS_FAIL -10021

RDT fails to create safe channel

#define RDT_ER_DEINITIALIZING -10019

RDT module is currently deinitializing. It is not necessary to re-deinitialize.

#define RDT_ER_EXCEED_MAX_CHANNEL -10002

The number of RDT channels has reached maximum. Please use RDT_Set_Max_Channel_Number() to set up the max number of RDT channels. By default, the maximum channel number is MAX_DEFAULT_RDT_CHANNEL_NUMBER.

#define RDT_ER_FAIL_CREATE_MUTEX -10005

RDT module fails to create Mutexs when doing initialization. Please check if OS has sufficient Mutexs for RDT module.

#define RDT_ER_FAIL_CREATE_THREAD -10004

RDT module fails to create threads. Please check if OS has ability to create threads for RDT module.

#define RDT_ER_FAIL_INITIALIZE_DTLS -10020

RDT fails to initialize DTLS module.

#define RDT_ER_INVALID_ARG -10014

The arguments passed to a function is invalid.

#define RDT_ER_INVALID_RDT_ID -10008

The specified RDT channel ID is valid

#define RDT_ER_LOCAL_ABORT -10011

The local site called RDT_Abort() so the RDT channel is already not available.

#define RDT_ER_LOCAL_EXIT -10015

The local site called RDT_Create_Exit() so the RDT channel exit creating.

#define RDT_ER_LOCAL_NOT_SUPPORT_DTLS -10024

Remote RDT need connect with DTLS

#define RDT_ER_MEM_INSUFF -10003

Insufficient memory for allocation

#define RDT_ER_NO_PERMISSION -10013

This is a lite UID and it does not support RDT module.

#define RDT_ER_NoERROR 0

The function is performed successfully.

#define RDT_ER_NOT_INITIALIZED -10000

RDT module is not initialized yet. Please use RDT_Initialize() for initialization.

#define RDT_ER_OPERATION_IS_INVALID -10022

The API operation is invalid

#define RDT_ER_RCV_DATA_END -10009

The remote site has finished sending data, then destroy the RDT channel. The local site will get this error code by RDT_Read() when there is no more data from this RDT channel.

#define RDT_ER_RDT_DESTROYED -10006

RDT channel has been destroyed. Probably caused by local or remote site calls RDT_Destroy(), or remote site has closed IOTC session.

#define RDT_ER_REMOTE_ABORT -10010

The remote site want to abort the RDT channel immediately and don't care data transmission. The local site will get this error code by RDT_Read(), RDT_Write(), RDT_Destroy() for handling this RDT channel to close.

#define RDT_ER_REMOTE_EXIT -10016

The remote site called RDT_Create_Exit() so the RDT channel exit creating.

#define RDT_ER_REMOTE_NOT_SUPPORT_DTLS -10023

Remote RDT not support DTLS

#define RDT_ER_SEND_BUFFER_FULL -10017

The RDT write buffer is full. Try again after min 1ms this Error code only return when RDT_Set_Max_SendBuff_Size is be set.

#define RDT_ER_TIMEOUT -10007

The specified timeout has expired during the execution of some RDT module service. For most cases, it is caused by slow response of remote site or network connection issues

#define RDT_ER_UNCLOSED_CONNECTION_DETECTED -10018

All RDT connection should call RDT_Abort or RDT_Destroy before doing RDT_Deinitialize

#define RDTAPI_API __declspec(dllimport)

#define RDTAPI_API_DEPRECATED

Function Documentation

int32_t RDT_Abort ( int32_t nRDTChannelID )

Abort a RDT channel.

This function will abort the RDT channel connection specified by a channel ID

Parameters

nRDTChannelID [in] The channel ID of the RDT channel to abort

Returns

RDT_ER_NoERROR if abort successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid

See Also: RDT_Server_Create() RDT_Client_Create()

Attention: It will ignore all data received or not send yet, force to abort the RDT channel connection.

RDTAPI_API_DEPRECATED int32_t RDT_Create	(	int32_t	nIOTCSessionID,
		int32_t	nTimeout,
		uint8_t	nIOTCChannelID
	)

Create a RDT channel.

This function will create a RDT channel based on specified IOTC channel

Parameters

nIOTCSessionID	[in] The session ID of the IOTC session to create RDT channel
nTimeout	[in] The timeout for this function in unit of million-second. Specify it as 0 will make this function block forever until a RDT channel is successfully created or error happens
nIOTCChannelID	[in] The channel ID of the IOTC channel to create RDT channel

Returns

RDT channel ID if return value >= 0

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT module is not initialized yet
RDT_ER_EXCEED_MAX_CHANNEL The number of RDT channels has reached maximum
RDT_ER_MEM_INSUFF Insufficient memory for allocation
RDT_ER_FAIL_CREATE_MUTEX Fails to create Mutex
RDT_ER_FAIL_CREATE_THREAD Fails to create threads
RDT_ER_RDT_DESTROYED RDT has been destroyed, probably caused by disconnection from remote site
IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified session ID has been closed by remote site
IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by IOTC_SESSION_ALIVE_TIMEOUT expires because remote site has no response
RDT_ER_TIMEOUT The timeout specified by nTimeout expires before RDT creation is performed completely
RDT_ER_CHANNEL_OCCUPIED The specific IOTC session and channel ID not available, it means the resource not release yet. If caused by RDT_Abort() called must wait a minute for the resource release automatically.
RDT_ER_REMOTE_EXIT Remote site exit this RDT channel connection
RDT_ER_INVALID_ARG Invalid Argument
RDT_ER_LOCAL_NOT_SUPPORT_DTLS Remote site just allow DTLS connection

See Also: RDT_Destroy() and RDT_Abort()

Attention: (1) The IOTC channel of specified channel ID will be turned on automatically by RDT_Create() (2) This function will need 288 bytes stack size.

int32_t RDT_Create_Exit	(	int32_t	nIOTCSessionID,
		uint8_t	nIOTCChannelID
	)

Exit the process of a specific RDT channel create.

This function will create a RDT channel based on specified IOTC channel

Parameters

nIOTCSessionID	[in] The session ID argument passed to call RDT_Create()
nIOTCChannelID	[in] The channel ID argument passed to call RDT_Create()

Returns

RDT_ER_NoERROR if function called successfully

Error code if return value < 0

RDT_ER_INVALID_ARG RDT nIOTCSessionID or nIOTCChannelID is valid
RDT_ER_INVALID_RDT_ID can't find related RDT channel ID via nIOTCSessionID and nIOTCChannelID

See Also: RDT_Server_Create() RDT_Client_Create()

Attention: It will send exit message to remote but old version can't recognize it, so must wait until timeout for RDT_Server_Create() or RDT_Client_Create() return.

int32_t RDT_DeInitialize ( )

Deinitialize RDT module.

This function will deinitialize RDT module.

Returns

RDT_ER_NoERROR if deinitialize successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED if RDT module is not initialized yet.
RDT_ER_UNCLOSED_CONNECTION_DETECTED if RDT connections are not closed

See Also: RDT_Initialize()

Attention: (1) RDT module shall be deinitialized before IOTC module is deinitialized. (2) All RDT connection should call RDT_Abort or RDT_Destroy before doing RDT_Deinitialize

int32_t RDT_Destroy ( int32_t nRDTChannelID )

Destroy a RDT channel.

This function will destroy the RDT channel specified by a channel ID

Parameters

nRDTChannelID [in] The channel ID of the RDT channel to destroy

Returns

RDT_ER_NoERROR if destroying successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid
RDT_ER_REMOTE_ABORT Remote site abort this RDT channel connection so the data may not send/receive to/from remote site completely.

See Also: RDT_Server_Create() RDT_Client_Create()

Attention: The IOTC channel containing RDT channel will be turned off after the RDT channel is destroyed. It will block until remote site call RDT_Destroy() or IOTC session disconnected.

int32_t RDT_Flush ( int32_t nRDTChannelID )

Flush data in an RDT channel.

Called by a RDT server or a RDT client to flush data in the buffer, otherwise RDT may wait until data can fill out the whole packet

Parameters

nRDTChannelID [in] The channel ID of the RDT channel to write data

Returns

RDT_ER_NoERROR if flush successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT module is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid
RDT_ER_RDT_DESTROYED RDT module has been destroyed, probably caused by disconnection from remote site
IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified session ID has been closed by remote site
IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by IOTC_SESSION_ALIVE_TIMEOUT expires because remote site has no response
RDT_ER_REMOTE_ABORT Remote site abort this RDT channel connection
RDT_ER_LOCAL_ABORT Local site abort this RDT channel connection

RDTAPI_API_DEPRECATED int32_t RDT_GetRDTApiVer ( )

Get the version of RDT module.

This function returns the version of RDT module

Returns: The version of RDT module from high byte to low byte, for example, 0x01020304 means the version is 1.2.3.4

See Also: IOTC_Get_Version(), avGetAVApiVer()

const char* RDT_GetRDTApiVersionString ( void )

Get the version of RDT module.

This function returns the version of RDT module

int32_t RDT_Initialize ( )

Initialize RDT module.

This function is used by RDT servers or RDT clients to initialize RDT module and shall be called before any RDT module related function is invoked, except RDT_Set_Max_Channel_Number().

Returns

The actual maximum number of allowable RDT channels if initializing successfully

Error code if return value < 0

RDT_ER_ALREADY_INITIALIZED RDT module is already initialized
RDT_ER_FAIL_CREATE_MUTEX Fails to create Mutexs
TUTK_ER_NO_LICENSE_KEY Need to call TUTK_SDK_Set_License_Key() before all module start/initialize.
RDT_ER_FAIL_INITIALIZE_DTLS Fails to initialize DTLS mode

See Also: IOTC_Initialize(), IOTC_Initialize2(), RDT_DeInitialize(), TUTK_SDK_Set_License_Key()

Attention: IOTC module is needed to be initialized before initializing RDT module. That is, please invoke IOTC_Initialize() or IOTC_Initialize2() before this function.

int32_t RDT_Read	(	int32_t	nRDTChannelID,
		char *	abBuf,
		int32_t	nBufSize,
		int32_t	nTimeout
	)

Read data through a RDT channel.

Called by a RDT server or a RDT client to read data through a specified RDT channel from the other.

Parameters

nRDTChannelID	[in] The channel ID of the RDT channel to read data
abBuf	[out] The array of byte buffer to receive read result
nBufSize	[in] The maximum length of the byte buffer
nTimeout	[in] The timeout for this function in unit of million-second

Returns

The actual length of read result stored in abBuf if read successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT module is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid
RDT_ER_RDT_DESTROYED RDT module has been destroyed, probably caused by disconnection from remote site
RDT_ER_TIMEOUT The timeout specified by nTimeout expires before read process is performed completely
RDT_ER_RCV_DATA_END No more data can be read from the RDT channel and this RDT channel has been destroyed by the remote site
RDT_ER_REMOTE_ABORT Remote site abort this RDT channel connection
RDT_ER_LOCAL_ABORT Local site abort this RDT channel connection
RDT_ER_REMOTE_EXIT Remote site exit this RDT channel connection
RDT_ER_INVALID_ARG nBufSize or nTimeout argument is wrong

See Also: RDT_Write()

Attention: This function will need 292 bytes stack size.

int32_t RDT_Set_Log_Attr ( LogAttr logAttr )

Set Attribute of log file.

Parameters

logAttr [in] See LogAttr

Returns

RDT_ER_NoERROR on success.

The value < 0

RDT_ER_INVALID_ARG Invalid input argument.

void RDT_Set_Log_Path	(	const char *	path,
		int32_t	nMaxSize
	)

Set path of log file.

Set the absolute path of log file

Parameters

path	[in] The path of log file, NULL = disable Log
nMaxSize	[in] The maximum size of log file in Bytes, 0 = unlimit

void RDT_Set_Max_Channel_Number ( uint32_t nMaxChannelNum )

Set the max number of RDT channels.

This function set the max number of allowable RDT channels. The max number of RDT channels limits the max number of RDT channels that a RDT server can establish with multiple RDT clients from RDT server's point of view, while it limits the max number of RDT channels that a RDT client can establish with multiple RDT servers from RDT client's point of view. A RDT server or a RDT client could use this function to reduce the number of RDT channels in order to save some memory usage.

Parameters

nMaxChannelNum [in] The max number of RDT channels

Attention: (1) This function is optional if users do not want to change the default max number of RDT channels. However, if users really wants to change it, this function shall be called before RDT_Initialize().

(2) The default maximum RDT channel number is MAX_DEFAULT_RDT_CHANNEL_NUMBER in all platforms.

int32_t RDT_Set_Max_Pending_ACK_Number	(	int32_t	nRDTChannelID,
		uint32_t	nMaxNumber
	)

Set the max number of pending ACKs of the RDT channel.

This function is related to the frequency of sending RDT ACK, set 0 to nMaxNumber if you want to force RDT to send ACK immediately, it might consume more CPU resource and network bandwidth, but it might improve the performance of RDT data transmission; 0 is the default value of nMaxNumber, we suggest not to use the number bigger than 80

Parameters

nRDTChannelID	[in] The channel ID of the RDT channel to get status
nMaxNumber	[in] The max pending number of RDT ACK of the RDT channel

Returns

RDT_ER_NoERROR if getting the RDT status successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT module is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid

Attention: Please invoke this function after RDT channel is created. This function will work only when the remote RDT version is equal or bigger than 2.1.0

int32_t RDT_Set_Max_SendBuffer_Size	(	int32_t	nRDTChannelID,
		int32_t	nMaxSendBufferSize
	)

Set max send queue buffer size.

Limit the send queue buffer size, when the buffer is full RDT_Write will return RDT_ER_SEND_BUFFER_FULL

Parameters

nRDTChannelID	[in] The channel ID of the RDT channel
nMaxSendBufferSize	[in] The maximum size of send queue buffer

int32_t RDT_Set_MaxPacketDataSize ( uint32_t nMaxSize )

Set the max packet data size of a single RDT packet.

This function can set the max packet data size of a RDT packet. By default, the max data size of RDT is 1280. For some situation, the MTU size might be smaller than default value. User can adjust the max RDT packet data size by this function.

Parameters

nMaxSize [in] The max packet size of a single RDT packet.

Returns

RDT_ER_NoERROR if setting successfully

Error code if return value < 0

RDT_ER_INVALID_ARG The arg is invalid or bigger than 1280 or smaller than 100.

Attention: (1) The max packet size must be smaller than 1280. (2) The min packet size must be bigger than 100. (3) Use this function before RDT_Initialize().

int32_t RDT_Status_Check	(	int32_t	nRDTChannelID,
		struct st_RDT_Status *	psRDT_Status
	)

Get status of a RDT channel.

A RDT server or a RDT client may use this function to get the status of a specified RDT channel

Parameters

nRDTChannelID	[in] The channel ID of the RDT channel to get status
psRDT_Status	[out] The status of specified RDT channel

Returns

RDT_ER_NoERROR if getting the RDT status successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT module is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid

int32_t RDT_Write	(	int32_t	nRDTChannelID,
		const char *	cabBuf,
		int32_t	nBufSize
	)

Write data through a RDT channel.

Called by a RDT server or a RDT client to write data through a specified RDT channel to the other. RDT_Write might not send small size data directly, if you need to write small size data directly you can call RDT_Flush after RDT_Write

Parameters

nRDTChannelID	[in] The channel ID of the RDT channel to write data
cabBuf	[in] The array of byte buffer containing the data to write
nBufSize	[in] The length of the byte buffer

Returns

The actual length of buffer to be written if write successfully

Error code if return value < 0

RDT_ER_NOT_INITIALIZED RDT module is not initialized yet
RDT_ER_INVALID_RDT_ID The specified RDT channel ID is not valid
RDT_ER_RDT_DESTROYED RDT module has been destroyed, probably caused by disconnection from remote site
IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified session ID has been closed by remote site
IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by IOTC_SESSION_ALIVE_TIMEOUT expires because remote site has no response
RDT_ER_REMOTE_ABORT Remote site abort this RDT channel connection
RDT_ER_LOCAL_ABORT Local site abort this RDT channel connection
RDT_ER_SEND_BUFFER_FULL the buffer size is full, the max buffer size is set by RDT_Set_Max_SendBuffer_Size()

See Also: RDT_Read() RDT_Set_Max_SendBuffer_Size()

Attention: This function will need 5088 bytes stack size.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation