IOTC Platform: RDTAPIs.h File Reference

| IOTC Platform Ver: 2.1.0.25 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Functions
RDTAPIs.h File Reference

## Data Structures

struct | st_RDT_Status

## Macros

#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

## Functions

int | RDT_GetRDTApiVer ()
| Get the version of RDT module.
void | RDT_Set_Max_Channel_Number (unsigned int nMaxChannelNum)
| Set the max number of RDT channels.
int | RDT_Initialize ()
| Initialize RDT module.
int | RDT_DeInitialize ()
| Deinitialize RDT module.
int | RDT_Create (int nIOTCSessionID, int nTimeout, unsigned char nIOTCChannelID)
| Create a RDT channel.
int | RDT_Create_Exit (int nIOTCSessionID, unsigned char nIOTCChannelID)
| Exit the process of a specific RDT channel create.
int | RDT_Destroy (int nRDTChannelID)
| Destroy a RDT channel.
int | RDT_Abort (int nRDTChannelID)
| Abort a RDT channel.
int | RDT_Set_Max_SendBuffer_Size (int nRDTChannelID, int nMaxSendBufferSize)
| Set Max Send Buffer Size , when buffer is full RDT_Write will return aaaaaaaaaaaaaa of log file.
int | RDT_Write (int nRDTChannelID, const char *cabBuf, int nBufSize)
| Write data through a RDT channel.
int | RDT_Read (int nRDTChannelID, char *abBuf, int nBufSize, int nTimeout)
| Read data through a RDT channel.
int | RDT_Status_Check (int nRDTChannelID, struct st_RDT_Status *psRDT_Status)
| Get status of a RDT channel.
void | RDT_Set_Log_Path (const char *path, int nMaxSize)
| Set path of log file.

## Detailed Description

This file describes all the APIs of the RDT module in IOTC platform. RDT module is a kind of data communication modules in IOTC platform to provide Reliable Data Transfer among RDT servers and RDT clients in bi-directional way.

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

Revision Table

Version | Name | Date | Description
--- | --- | --- | ---
0.1 | Joshua | 2011-03-29 | Trial Version
0.1.1.0 | Kevin | 2011-06-07 | Workable Version
0.1.2.0 | Kevin | 2011-06-30 | Adapt to IOTC multi-channel session mechanism
1.0.0.0 | Kevin | 2011-07-12 | Formal version, stability testing
1.1.0.0 | Charlie & Kevin | 2011-08-29 | New formal version, can't be compatible with below version 1.1.0.0
1.2.0.0 | Kevin | 2011-10-03 | Add : 1.RDTInfo_t struct member "ErrorCode" to report IOTC session error 2.RDT_Status_Check() to know timeout status etc. Fix Bug : ___ListItem_SendList_RemovebyType() function will cause double tutk_platform_free or use memory already be freed. Improve : destroy procedure no need to wait until timeout
1.3.0.0 | Kevin | 2011-11-15 | Add : Control network flow to fit bandwidth dynamically. Improve : when RDT_Destroy() call set timeout to 2 sec.
1.3.1.0 | Kevin | 2011-11-28 | Fix Bug : RDT_Destroy() not add ID will cause ack to remove wrong packet. Improve : Send data via internet have good performance.
1.3.2.0 | Kevin | 2011-12-19 | Fix Bug : RDT_Destroy() not release RDT_ID. Add : 1.Big-endian SOC suport. Improve : 1.Send data via Lan have good performance. 2.Reduce CPU usage.
1.3.3.0 | Kevin | 2012-02-04 | Fix Bug : 1.Floating exception when WAN mode. 2.Access NULL pointer in send thread when WAN mode. 3.BufSizeInSendQueue info error.
1.3.4.0 | Kevin | 2012-03-30 | Fix Bug : When one site call RDT_Destroy() will cause remote site put FIN packet into sendList and lost data packet to send. Modify : RDT_Read() return read size and if data come in return immediately.

1.3.5.0

Kevin

2012-08-16

+ Add error code RDT_ER_RCV_DATA_END for RDT_Read() to indicate remote site has destroyed the RDT channel
o Re-arrange error codes to distinguish from the ones defined by IOTC modules
o Modify API name from RDT_Set_Max_Session_Number() to RDT_Set_Max_Channel_Number() for unifying naming rule
- Remove error codes: RDT_ER_INVALID_ARG, RDT_ER_IOTC_SENDTO_FAILED, RDT_ER_IOTC_SESSION_CLOSE_BY_REMOTE, RDT_ER_IOTC_REMOTE_TIMEOUT_DISCONNECT, RDT_ER_IOTC_CH_NOT_ON

1.3.7.0 | Kevin | 2012-10-12 | o Improve RDT transfer rate o Add const modifier for input parameters in function prototype
1.3.8.0 | Han-Lin, Harry | 2013-03-28 | + Add RDT_Set_Log_Path() to set log file name, path and maximum size. + Log error codes in specified file. o Modify RDT connection timeout from 10 to 20 seconds.
1.3.9.0 | Han-Lin, Harry | 2013-04-17 | o Modify congestion control, dynamic window size and timeout.
1.3.10.0 | Han-Lin, Harry | 2013-05-07 | + Add CRC16 mechanism. o Fix file pointer leak in log function.
1.4.0.0 | Han-Lin | 2013-06-26 | o Modify queue process algorithm to improve performance.

1.4.1.0

Kevin

2013-08-28

+ Add RDT_Abort() API to close a channel with non blocking mode.
+ Add error code RDT_ER_REMOTE_ABORT for RDT_Write(), RDT_Read(), RDT_Destroy() and RDT_Abort().
+ Add error code RDT_ER_LOCAL_ABORT for RDT_Write() and RDT_Read().
+ Add error code RDT_ER_CHANNEL_OCCUPIED for RDT_Create().
o Fix CRC error in a Big Endian platform.

1.4.1.5 | Han-Lin, Victor | 2013-10-28 | o Use call back function instead of polling when reading packets. o Fix RDT algorithm in LAN mode to improve performance. o Fix compiler warnings in Win32 platform.
1.4.2.0 | Han-Lin, Alex | 2013-11-19 | o Improve transmission machanism. o Fix variables conflict error. o Fix variables conflict error. - Remove CRC machanism.
1.4.3.0 | Han-Lin | 2014-02-17 | o Improve transmission machanism.
1.5.0.0 | TUTK RD team | 2014-06-06 | o Improve multi-connection performance.
1.6.0.0 | TUTK RD team | 2014-08-28 | o Fix re-connection error when do it frequently. o Improve RDT_Abort() function call will exit immediately. o Improve RDT connection performance. + Add RDT_Create_Exit() for exit RDT_Create() process before reach timeout. - Remove include platform_config.h
1.7.0.0 | TUTK RD team | 2014-09-22 | o Fix RDT_Abort() not release channel resource. + Add 64-bit library.
1.7.2.0 | TUTK RD team | 2014-10-17 | o Fix process rarely dead lock. o Improve call RDT_Abort() can let RDT_Read() to exit before reach timeout.
1.8.1.1 | TUTK RD team | 2015-05-20 | o Add SetMaxRecvBuff and Reduce CPU loading .

## 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_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_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_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_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_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

## Function Documentation

int RDT_Abort | ( | int | 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
  - RDT_ER_REMOTE_ABORT Remote site already aborted this RDT channel connection so RDT_Abort() is useless now.

See Also
  RDT_Create()

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

int RDT_Create | ( | int | nIOTCSessionID,
|  | int | nTimeout,
|  | unsigned char | 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

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.

int RDT_Create_Exit | ( | int | nIOTCSessionID,
|  | unsigned char | 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_Create()

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

int 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

int RDT_Destroy | ( | int | 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_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.

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

int 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

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

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

int RDT_Read | ( | int | nRDTChannelID,
|  | char * | abBuf,
|  | int | nBufSize,
|  | int | 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.

void RDT_Set_Log_Path | ( | const char * | path,
|  | int | 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 | ( | unsigned int | 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.

int RDT_Set_Max_SendBuffer_Size | ( | int | nRDTChannelID,
|  | int | nMaxSendBufferSize
| ) |  |

Set Max Send Buffer Size , when buffer is full RDT_Write will return aaaaaaaaaaaaaa 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

int RDT_Status_Check | ( | int | 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

int RDT_Write | ( | int | nRDTChannelID,
|  | const char * | cabBuf,
|  | int | 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.

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

See Also
  RDT_Read()

Attention
  This function will need 5088 bytes stack size.