IOTC Platform  Ver: 4.3.6.2-0-ge1f616e
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Typedefs | Enumerations | Functions
IOTCCommon.h File Reference
#include "TUTKGlobalAPIs.h"

Data Structures

struct  st_SInfo
 
struct  st_SInfoEx
 
struct  st_LanSearchInfo
 
struct  st_LanSearchInfo2
 
struct  st_SearchDeviceInfo
 
struct  IOTCConnectInput
 

Macros

#define P2PAPI_API   __declspec(dllimport)
 
#define P2PAPI_API_DEPRECATED
 
#define MAX_DEFAULT_IOTC_SESSION_NUMBER   128
 
#define IOTC_MAX_PACKET_SIZE   1388
 
#define MAX_CHANNEL_NUMBER   32
 
#define IOTC_SESSION_ALIVE_TIMEOUT   60
 
#define IOTC_AUTH_KEY_LENGTH   8
 
#define IOTC_ER_NoERROR   0
 
#define IOTC_ER_SERVER_NOT_RESPONSE   -1
 
#define IOTC_ER_FAIL_RESOLVE_HOSTNAME   -2
 
#define IOTC_ER_ALREADY_INITIALIZED   -3
 
#define IOTC_ER_FAIL_CREATE_MUTEX   -4
 
#define IOTC_ER_FAIL_CREATE_THREAD   -5
 
#define IOTC_ER_FAIL_CREATE_SOCKET   -6
 
#define IOTC_ER_FAIL_SOCKET_OPT   -7
 
#define IOTC_ER_FAIL_SOCKET_BIND   -8
 
#define IOTC_ER_UNLICENSE   -10
 
#define IOTC_ER_LOGIN_ALREADY_CALLED   -11
 
#define IOTC_ER_NOT_INITIALIZED   -12
 
#define IOTC_ER_TIMEOUT   -13
 
#define IOTC_ER_INVALID_SID   -14
 
#define IOTC_ER_UNKNOWN_DEVICE   -15
 
#define IOTC_ER_FAIL_GET_LOCAL_IP   -16
 
#define IOTC_ER_LISTEN_ALREADY_CALLED   -17
 
#define IOTC_ER_EXCEED_MAX_SESSION   -18
 
#define IOTC_ER_CAN_NOT_FIND_DEVICE   -19
 
#define IOTC_ER_SESSION_CLOSE_BY_REMOTE   -22
 
#define IOTC_ER_REMOTE_TIMEOUT_DISCONNECT   -23
 
#define IOTC_ER_DEVICE_NOT_LISTENING   -24
 
#define IOTC_ER_CH_NOT_ON   -26
 
#define IOTC_ER_FAIL_CONNECT_SEARCH   -27
 
#define IOTC_ER_MASTER_TOO_FEW   -28
 
#define IOTC_ER_AES_CERTIFY_FAIL   -29
 
#define IOTC_ER_SESSION_NO_FREE_CHANNEL   -31
 
#define IOTC_ER_TCP_TRAVEL_FAILED   -32
 
#define IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED   -33
 
#define IOTC_ER_CLIENT_NOT_SECURE_MODE   -34
 
#define IOTC_ER_CLIENT_SECURE_MODE   -35
 
#define IOTC_ER_DEVICE_NOT_SECURE_MODE   -36
 
#define IOTC_ER_DEVICE_SECURE_MODE   -37
 
#define IOTC_ER_EXIT_LISTEN   -39
 
#define IOTC_ER_NO_PERMISSION   -40
 
#define IOTC_ER_NETWORK_UNREACHABLE   -41
 
#define IOTC_ER_FAIL_SETUP_RELAY   -42
 
#define IOTC_ER_NOT_SUPPORT_RELAY   -43
 
#define IOTC_ER_NO_SERVER_LIST   -44
 
#define IOTC_ER_DEVICE_MULTI_LOGIN   -45
 
#define IOTC_ER_INVALID_ARG   -46
 
#define IOTC_ER_NOT_SUPPORT_PE   -47
 
#define IOTC_ER_DEVICE_EXCEED_MAX_SESSION   -48
 
#define IOTC_ER_BLOCKED_CALL   -49
 
#define IOTC_ER_SESSION_CLOSED   -50
 
#define IOTC_ER_REMOTE_NOT_SUPPORTED   -51
 
#define IOTC_ER_ABORTED   -52
 
#define IOTC_ER_EXCEED_MAX_PACKET_SIZE   -53
 
#define IOTC_ER_SERVER_NOT_SUPPORT   -54
 
#define IOTC_ER_NO_PATH_TO_WRITE_DATA   -55
 
#define IOTC_ER_SERVICE_IS_NOT_STARTED   -56
 
#define IOTC_ER_STILL_IN_PROCESSING   -57
 
#define IOTC_ER_NOT_ENOUGH_MEMORY   -58
 
#define IOTC_ER_DEVICE_IS_BANNED   -59
 
#define IOTC_ER_MASTER_NOT_RESPONSE   -60
 
#define IOTC_ER_RESOURCE_ERROR   -61
 
#define IOTC_ER_QUEUE_FULL   -62
 
#define IOTC_ER_NOT_SUPPORT   -63
 
#define IOTC_ER_DEVICE_IS_SLEEP   -64
 
#define IOTC_ER_TCP_NOT_SUPPORT   -65
 
#define IOTC_ER_WAKEUP_NOT_INITIALIZED   -66
 
#define IOTC_ER_DEVICE_REJECT_BYPORT   -67
 
#define IOTC_ER_DEVICE_REJECT_BY_WRONG_AUTH_KEY   -68
 
#define IOTC_ER_DEVICE_NOT_USE_KEY_AUTHENTICATION   -69
 
#define IOTC_ER_DID_NOT_LOGIN   -70
 
#define IOTC_ER_DID_NOT_LOGIN_WITH_AUTHKEY   -71
 
#define IOTC_ER_SESSION_IN_USE   -72
 
#define IOTC_ER_DEVICE_OFFLINE   -90
 
#define IOTC_ER_MASTER_INVALID   -91
 
#define IOTC_ER_RENTAL_UNKNOWN_ERROR   -200
 
#define IOTC_ER_RENTAL_INVALID_PARAMETER   -201
 
#define IOTC_ER_RENTAL_INVALID_VALIDATION   -202
 
#define IOTC_ER_RENTAL_INVALID_VENDOR   -203
 
#define IOTC_ER_RENTAL_INVALID_VPG_UID   -204
 
#define IOTC_ER_RENTAL_INVALID_REMOTE_RESPONSE   -205
 
#define IOTC_ER_RENTAL_FAILED_GENERATING_UID   -206
 
#define IOTC_ER_RENTAL_FAILED_INSERT_TO_MASTER   -207
 
#define IOTC_ER_RENTAL_FAILED_RETRIEVING_SERVER_LIST   -208
 
#define IOTC_ER_RENTAL_FAILED_DOING_REMOTE_REQUEST   -209
 
#define IOTC_ER_RENTAL_REALM_NOT_FOUND   -210
 

Typedefs

typedef struct st_SInfo st_SInfo_t
 
typedef struct st_SInfoEx st_SInfoEx_t
 
typedef struct st_LanSearchInfo st_LanSearchInfo_t
 
typedef struct st_LanSearchInfo2 st_LanSearchInfo2_t
 
typedef struct st_SearchDeviceInfo st_SearchDeviceInfo_t
 
typedef struct IOTCConnectInput IOTCConnectInput
 
typedef void(__stdcall * sessionStatusCB )(int32_t nIOTCSessionID, int32_t nErrorCode)
 
typedef void(__stdcall * ConnectModeChangeCB )(int32_t nIOTCSessionID, uint32_t nConnMode)
 

Enumerations

enum  IOTCSessionMode { IOTC_NON_SECURE_MODE = 0, IOTC_SECURE_MODE = 1, IOTC_ARBITRARY_MODE = 2 }
 
enum  IOTCAuthenticationType { AUTHENTICATE_BY_KEY }
 

Functions

P2PAPI_API_DEPRECATED void IOTC_Get_Version (uint32_t *pnVersion)
 Get the version of IOTC module.
 
const char * IOTC_Get_Version_String (void)
 Get the version of IOTC module.
 
int32_t IOTC_Set_Max_Session_Number (int32_t nMaxSessionNum)
 Set the max number of IOTC sessions of IOTC module.
 
P2PAPI_API_DEPRECATED int32_t IOTC_Initialize (uint16_t nUDPPort, const char *cszP2PHostNamePrimary, const char *cszP2PHostNameSecondary, const char *cszP2PHostNameThird, const char *cszP2PHostNameFourth)
 Initialize IOTC module.
 
int32_t IOTC_Initialize2 (uint16_t nUDPPort)
 Initialize IOTC module.
 
int32_t IOTC_DeInitialize (void)
 Deinitialize IOTC module.
 
int32_t IOTC_Get_SessionID (void)
 Used by a client to get a tutk_platform_free session ID.
 
P2PAPI_API_DEPRECATED int32_t IOTC_Session_Read_Check_Lost (int32_t nIOTCSessionID, char *abBuf, int32_t nMaxBufSize, uint32_t nTimeout, uint16_t *pnPacketSN, int8_t *pbFlagLost, uint8_t nIOTCChannelID)
 Used by a device or a client to read data from the other.
 
P2PAPI_API_DEPRECATED int32_t IOTC_Session_Check (int32_t nIOTCSessionID, struct st_SInfo *psSessionInfo)
 Used by a device or a client to check the IOTC session info.
 
int32_t IOTC_Session_Check_Ex (int32_t nIOTCSessionID, struct st_SInfoEx *psSessionInfo)
 Used by a device or a client to check the IOTC session info.
 
P2PAPI_API_DEPRECATED int32_t IOTC_Session_Check_ByCallBackFn (int32_t nIOTCSessionID, sessionStatusCB pfxSessionStatusFn)
 Used by a device or a client to get the session status.
 
int32_t IOTC_Session_Read (int32_t nIOTCSessionID, char *abBuf, int32_t nMaxBufSize, uint32_t nTimeout, uint8_t nIOTCChannelID)
 Used by a device or a client to read data from the other.
 
int32_t IOTC_Session_Write (int32_t nIOTCSessionID, const char *cabBuf, int32_t nBufSize, uint8_t nIOTCChannelID)
 Used by a device or a client to write data to the other.
 
void IOTC_Session_Close (int32_t nIOTCSessionID)
 Used by a device or a client to close a IOTC session.
 
int32_t IOTC_Session_Get_Free_Channel (int32_t nIOTCSessionID)
 Used by a device or a client to get a tutk_platform_free IOTC channel.
 
int32_t IOTC_Session_Channel_ON (int32_t nIOTCSessionID, uint8_t nIOTCChannelID)
 Used by a device or a client to turn on a IOTC channel.
 
int32_t IOTC_Session_Channel_OFF (int32_t nIOTCSessionID, uint8_t nIOTCChannelID)
 Used by a device or a client to turn off a IOTC channel.
 
int32_t IOTC_Session_Channel_Check_ON_OFF (int32_t nIOTCSessionID, uint8_t nIOTCChannelID)
 Used by a device or a client to check whether the IOTC channel is ON or OFF.
 
P2PAPI_API_DEPRECATED void IOTC_Set_Log_Path (char *path, int32_t nMaxSize)
 Set path of log file.
 
int32_t IOTC_Set_Log_Attr (LogAttr logAttr)
 Set Attribute of log file.
 
int32_t IOTC_Set_Partial_Encryption (int32_t nIOTCSessionID, uint8_t bPartialEncryption)
 Set partial encode On/Off.
 
void IOTC_TCPRelayOnly_TurnOn (void)
 Turn on only TCP relay mode function.
 
int32_t IOTC_ReInitSocket (uint16_t nUDPPort)
 ReInitialize IOTC module socket.
 
void IOTC_Setup_Session_Alive_Timeout (uint32_t nTimeout)
 Setup session alive timeout value.
 
int32_t IOTC_Set_LanSearchPort (uint32_t nPort)
 Change default LAN search port.
 
int32_t IOTC_Set_Master_Pub_Key (const char *nMasterKey)
 Set RSA Public Key for Master Server.
 

Detailed Description

This file describes common IOTC module APIs of device and client.

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

Macro Definition Documentation

#define IOTC_AUTH_KEY_LENGTH   8

For IOTC Authorization

#define IOTC_ER_ABORTED   -52

The function is aborted by related function.

#define IOTC_ER_AES_CERTIFY_FAIL   -29

A client fails to pass certification of a device due to incorrect key.

#define IOTC_ER_ALREADY_INITIALIZED   -3

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

#define IOTC_ER_BLOCKED_CALL   -49

The function call is a blocking call and was called by other thread.

#define IOTC_ER_CAN_NOT_FIND_DEVICE   -19

IOTC servers cannot locate the specified device, probably caused by disconnection from the device or that device does not login yet.

#define IOTC_ER_CH_NOT_ON   -26

The IOTC channel of specified channel ID is not turned on before transferring data.

#define IOTC_ER_CLIENT_NOT_SECURE_MODE   -34

A client wants to connect to a device in non-secure mode while that device supports secure mode only.

#define IOTC_ER_CLIENT_SECURE_MODE   -35

A client wants to connect to a device in secure mode while that device does not support secure mode.

#define IOTC_ER_DEVICE_EXCEED_MAX_SESSION   -48

The remote device no more free session can be connected.

#define IOTC_ER_DEVICE_IS_BANNED   -59

The device is banned and locked, this error code is no longer being used

#define IOTC_ER_DEVICE_IS_SLEEP   -64

Device is in sleep mode.

#define IOTC_ER_DEVICE_MULTI_LOGIN   -45

The connecting device has duplicated loggin and may unconnectable.

#define IOTC_ER_DEVICE_NOT_LISTENING   -24

The client fails to connect to a device because the device is not listening for connections.

#define IOTC_ER_DEVICE_NOT_SECURE_MODE   -36

A device does not support connection in secure mode

#define IOTC_ER_DEVICE_NOT_USE_KEY_AUTHENTICATION   -69

Being rejected by device due to disable authentication

#define IOTC_ER_DEVICE_OFFLINE   -90

All Server response can not find device

#define IOTC_ER_DEVICE_REJECT_BY_WRONG_AUTH_KEY   -68

Being rejected by device due to the wrong auth key

#define IOTC_ER_DEVICE_REJECT_BYPORT   -67

Being rejected by device due to the wrong IOTCPort

#define IOTC_ER_DEVICE_SECURE_MODE   -37

A device does not support connection in non-secure mode

#define IOTC_ER_DID_NOT_LOGIN   -70

Some functions can only be called after device login success

#define IOTC_ER_DID_NOT_LOGIN_WITH_AUTHKEY   -71

Need to login with IOTC_Device_loginEx not IOTC_Device_login

#define IOTC_ER_EXCEED_MAX_PACKET_SIZE   -53

The buffer size exceed maximum packet size.

#define IOTC_ER_EXCEED_MAX_SESSION   -18

The number of IOTC sessions has reached maximum. To increase the max number of IOTC sessions, please use IOTC_Set_Max_Session_Number() before initializing IOTC module.

#define IOTC_ER_EXIT_LISTEN   -39

A device stops listening for connections from clients.

#define IOTC_ER_FAIL_CONNECT_SEARCH   -27

A client stops connecting to a device by calling IOTC_Connect_Stop()

#define IOTC_ER_FAIL_CREATE_MUTEX   -4

IOTC module fails to create Mutexes when doing initialization. Please check if OS has sufficient Mutexes for IOTC platform.

#define IOTC_ER_FAIL_CREATE_SOCKET   -6

IOTC module fails to create sockets. if you are using Android, please check if android.permission.INTERNET setting is enabled. Otherwise, please check if your platform supports socket service

#define IOTC_ER_FAIL_CREATE_THREAD   -5

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

#define IOTC_ER_FAIL_GET_LOCAL_IP   -16

IOTC module fails to get the local IP address

#define IOTC_ER_FAIL_RESOLVE_HOSTNAME   -2

IOTC masters cannot be resolved their domain name, probably caused by network connection or DNS setting issues.

#define IOTC_ER_FAIL_SETUP_RELAY   -42

A client fails to connect to a device via relay mode

#define IOTC_ER_FAIL_SOCKET_BIND   -8

IOTC module fails to bind sockets

#define IOTC_ER_FAIL_SOCKET_OPT   -7

IOTC module fails to set up socket options.

#define IOTC_ER_INVALID_ARG   -46

The arguments passed to a function is invalid.

#define IOTC_ER_INVALID_SID   -14

The specified IOTC session ID is not valid. OR the SID of the session is closed. A valid SID must be -1 < SID < max_session_number which is set by IOTC_Set_Max_Session_Number and be got by IOTC_Connect_*.

#define IOTC_ER_LISTEN_ALREADY_CALLED   -17

The device already start to listen for connections from clients. It is not necessary to listen again.

#define IOTC_ER_LOGIN_ALREADY_CALLED   -11

The device is already under login process currently so it is prohibited to invoke login again at this moment.

#define IOTC_ER_MASTER_INVALID   -91

IOTC master server is invalid

#define IOTC_ER_MASTER_NOT_RESPONSE   -60

IOTC master servers have no response, probably caused by many types of Internet connection issues.

#define IOTC_ER_MASTER_TOO_FEW   -28

Too few masters are specified when initializing IOTC module. Two masters are required for initialization at minimum.

#define IOTC_ER_NETWORK_UNREACHABLE   -41

Network is unreachable, please check the network settings

#define IOTC_ER_NO_PATH_TO_WRITE_DATA   -55

Cannot find a path to write data

#define IOTC_ER_NO_PERMISSION   -40

The specified device does not support advance function (TCP relay and P2PTunnel module)

#define IOTC_ER_NO_SERVER_LIST   -44

No IOTC server information while device login or client connect because no IOTC server is running or not add IOTC server list

#define IOTC_ER_NoERROR   0

The function is performed successfully.

#define IOTC_ER_NOT_ENOUGH_MEMORY   -58

Out of memory

#define IOTC_ER_NOT_INITIALIZED   -12

IOTC module is not initialized yet. Please use IOTC_Initialize() or IOTC_Initialize2() for initialization.

#define IOTC_ER_NOT_SUPPORT   -63

The feature is not supported.

#define IOTC_ER_NOT_SUPPORT_PE   -47

The remote device not support partial encoding.

#define IOTC_ER_NOT_SUPPORT_RELAY   -43

A client fails to use UDP relay mode to connect to a device because UDP relay mode is not supported for that device by IOTC servers

#define IOTC_ER_QUEUE_FULL   -62

IOTC Write reliable send queue is full.

#define IOTC_ER_REMOTE_NOT_SUPPORTED   -51

Remote doesn't support this function.

#define IOTC_ER_REMOTE_TIMEOUT_DISCONNECT   -23

This IOTC session is disconnected because remote site has no any response after a specified timeout expires, i.e. IOTC_SESSION_ALIVE_TIMEOUT

#define IOTC_ER_RENTAL_FAILED_DOING_REMOTE_REQUEST   -209

Rental server return failed doing remote request

#define IOTC_ER_RENTAL_FAILED_GENERATING_UID   -206

Rental server return failed generating uid

#define IOTC_ER_RENTAL_FAILED_INSERT_TO_MASTER   -207

Rental server return failed insert to master

#define IOTC_ER_RENTAL_FAILED_RETRIEVING_SERVER_LIST   -208

Rental server return failed retrieving server list

#define IOTC_ER_RENTAL_INVALID_PARAMETER   -201

Rental server return invalid parameter

#define IOTC_ER_RENTAL_INVALID_REMOTE_RESPONSE   -205

Rental server return invalid remote response

#define IOTC_ER_RENTAL_INVALID_VALIDATION   -202

Rental server return invalid validation

#define IOTC_ER_RENTAL_INVALID_VENDOR   -203

Rental server return invalid vendor

#define IOTC_ER_RENTAL_INVALID_VPG_UID   -204

Rental server return invalid vpg uid

#define IOTC_ER_RENTAL_REALM_NOT_FOUND   -210

Rental server return realm not found

#define IOTC_ER_RENTAL_UNKNOWN_ERROR   -200

Unknown rental server error

#define IOTC_ER_RESOURCE_ERROR   -61

IOTC module has some resource allocating problem.

#define IOTC_ER_SERVER_NOT_RESPONSE   -1

IOTC servers have no response, probably caused by many types of Internet connection issues.

#define IOTC_ER_SERVER_NOT_SUPPORT   -54

Server does not support this feature.

#define IOTC_ER_SERVICE_IS_NOT_STARTED   -56

Start function is not called

#define IOTC_ER_SESSION_CLOSE_BY_REMOTE   -22

The remote site already closes this IOTC session. Please call IOTC_Session_Close() to release IOTC session resource in locate site.

#define IOTC_ER_SESSION_CLOSED   -50

The session was closed.

#define IOTC_ER_SESSION_IN_USE   -72

The function call is being rejected because there is at least one IOTC session in use

#define IOTC_ER_SESSION_NO_FREE_CHANNEL   -31

The number of IOTC channels for a IOTC session has reached maximum, say, MAX_CHANNEL_NUMBER

#define IOTC_ER_STILL_IN_PROCESSING   -57

Already in processing

#define IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED   -33

Cannot connect to IOTC servers in TCP

#define IOTC_ER_TCP_NOT_SUPPORT   -65

Device doesn't support this feature on TCP mode.

#define IOTC_ER_TCP_TRAVEL_FAILED   -32

Cannot connect to masters neither UDP mode nor TCP mode by IP or host name ways

#define IOTC_ER_TIMEOUT   -13

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

#define IOTC_ER_UNKNOWN_DEVICE   -15

The specified device's name is unknown to the IOTC servers

#define IOTC_ER_UNLICENSE   -10

The specified UID is not licensed or expired.

#define IOTC_ER_WAKEUP_NOT_INITIALIZED   -66

IOTC_WakeUp_Init isn't called

#define IOTC_MAX_PACKET_SIZE   1388

The maximum size, in byte, of the buffer used in IOTC_Session_Read(), IOTC_Session_Write() and IOTC_Session_Read_Check_Lost().

#define IOTC_SESSION_ALIVE_TIMEOUT   60

The timeout, in unit of second, for keeping an IOTC session alive since the last time remote site has response

#define MAX_CHANNEL_NUMBER   32

The maximum number of IOTC channels for each IOTC session

#define MAX_DEFAULT_IOTC_SESSION_NUMBER   128
#define P2PAPI_API   __declspec(dllimport)
#define P2PAPI_API_DEPRECATED

Typedef Documentation

typedef void(__stdcall * ConnectModeChangeCB)(int32_t nIOTCSessionID, uint32_t nConnMode)

The prototype of connection mode change function, used by a device or client to be notified if connection mode is changed.

Parameters
nIOTCSessionID[out] return effected session ID
nConnMode[out] return the current connection mode
  • # nConnMode = 0 : LAN Mode
  • # nConnMode = 1 : P2P Mode
  • # nConnMode = 2 : UDP RLY Mode
  • # nConnMode = 3 : TCP RLY Mode
typedef struct IOTCConnectInput IOTCConnectInput
typedef void(__stdcall * sessionStatusCB)(int32_t nIOTCSessionID, int32_t nErrorCode)

The prototype of getting session status function, used by a device or client to be notified if session is disconnected.

Parameters
nIOTCSessionID[out] The session ID of the session being disconnected
nErrorCode[out]
typedef struct st_LanSearchInfo2 st_LanSearchInfo2_t

Device search info, containing all the information and device name when client searches devices in LAN.

typedef struct st_LanSearchInfo st_LanSearchInfo_t

Device search info, containing all the information when client searches devices in LAN.

typedef struct st_SearchDeviceInfo st_SearchDeviceInfo_t

Device search info, containing all the information and device name when client searches devices in LAN.

typedef struct st_SInfo st_SInfo_t

IOTC session info, containing all the information when a IOTC session is established between a device and a client. Users can use IOTC_Session_Check() to get IOTC session information.

typedef struct st_SInfoEx st_SInfoEx_t

IOTC session info, containing all the information when a IOTC session is established between a device and a client. Users can use IOTC_Session_Check_Ex() to get IOTC session information.

Enumeration Type Documentation

enum IOTCAuthenticationType
Enumerator:
AUTHENTICATE_BY_KEY 

Create IOTC Session with authentication by Key.

enum IOTCSessionMode

IOTC session mode, used in IOTC_Listen2(), IOTC_Connect_ByUID2() to specify what kinds of IOTC session that devices will listen or clients will connect.

Enumerator:
IOTC_NON_SECURE_MODE 

IOTC session will be established in non-secure mode.

IOTC_SECURE_MODE 

IOTC session will be established in secure mode.

  • For devices, it means only secure connection will be accepted.
  • For clients, it means only secure connection will be performed
IOTC_ARBITRARY_MODE 

IOTC session will be established in either non-secure or secure mode, depending on remote site's request. Can use IOTC_Session_Check() to check what mode is actually used.

  • For devices, it means both non-secure or secure modes are accepted.
  • For clients, it means either non-secure or secure modes can be performed.

Function Documentation

int32_t IOTC_DeInitialize ( void  )

Deinitialize IOTC module.

This function will deinitialize IOTC module.

Returns
IOTC_ER_NoERROR if deinitialize successfully
Error code if return value < 0
See Also
IOTC_Initialize(), IOTC_Initialize2()
Attention
IOTC_DeInitialize() will release all resources being used in IOTC module, please make sure all threads calling IOTC APIs have already exited, otherwise SDK might crash in any IOTC APIs when you call IOTC_Deinitialize parallelly.
int32_t IOTC_Get_SessionID ( void  )

Used by a client to get a tutk_platform_free session ID.

This function is for a client to get a tutk_platform_free session ID used for a parameter of IOTC_Connect_ByUID_Parallel().

Returns
IOTC session ID if return value >= 0
Error code if return value < 0
Attention
(1) If you already get a session ID via this function must call IOTC_Connect_ByUID_Parallel() and then it will release session ID resource automatically when connection failed.

(2) If you already get a session ID via this function and want to close it please use IOTC_Session_Close().
P2PAPI_API_DEPRECATED void IOTC_Get_Version ( uint32_t *  pnVersion)

Get the version of IOTC module.

This function returns the version of IOTC module.

Parameters
pnVersion[out] The version of IOTC module. It contains the version from high byte to low byte, for example, 0x01020304 means the version is 1.2.3.4
See Also
RDT_GetRDTApiVer(), avGetAVApiVer()
const char* IOTC_Get_Version_String ( void  )

Get the version of IOTC module.

This function returns the version of IOTC module.

P2PAPI_API_DEPRECATED int32_t IOTC_Initialize ( uint16_t  nUDPPort,
const char *  cszP2PHostNamePrimary,
const char *  cszP2PHostNameSecondary,
const char *  cszP2PHostNameThird,
const char *  cszP2PHostNameFourth 
)

Initialize IOTC module.

This function is deprecated, you should use IOTC_Initialize instead. This function is used by devices or clients to initialize IOTC module and shall be called before any IOTC module related function is invoked except for IOTC_Set_Max_Session_Number().

Parameters
nUDPPort[in] Specify a UDP port. Random UDP port is used if it is specified as 0.
cszP2PHostNamePrimary[in] Specify the host name or IP address of the primary master. Cannot be NULL. See attention below for more detail.
cszP2PHostNameSecondary[in] Specify the host name or IP address of the secondary master. Cannot be NULL. See attention below for more detail.
cszP2PHostNameThird[in] Specify the host name or IP address of the third master. Can be NULL if only two masters are required. See attention below for more detail.
cszP2PHostNameFourth[in] Specify the host name or IP address of the fourth master. Can be NULL if only two masters are required. See attention below for more detail.
Returns
IOTC_ER_NoERROR if initializing successfully
Error code if return value < 0
See Also
IOTC_Initialize2(), IOTC_DeInitialize()
Attention
(1) This function is the key entry to whole IOTC platform, including RDT module and AV module. That means, if you want to use RDT module, users shall still use this function to initialize IOTC module before calling RDT_Initialize().

(2) Usually, host name is suggested to be used to specify a master. because that will ensure devices and clients can still connect to masters even the network address configuration of masters changes in the future. However, in rare case, the host name of masters can not be resolved due to network issue and it is necessary to specify IP address of masters in this function in order for successful connection. (3) This API has been deprecated and might be removed in the next version, please replace it with IOTC_Initialize2
int32_t IOTC_Initialize2 ( uint16_t  nUDPPort)

Initialize IOTC module.

This function is used by devices or clients to initialize IOTC module and shall be called before any IOTC module related function is invoked except for IOTC_Set_Max_Session_Number().
The different between this function and IOTC_Initialize() is this function uses following steps to connect masters (1) IP addresses of master (2) if fails to connect in step 1, resolve predefined domain name of masters (3) try to connect again with the resolved IP address of step 2 if IP is resolved successfully.

Parameters
nUDPPort[in] Specify a UDP port. Random UDP port is used if it is specified as 0.
Returns
IOTC_ER_NoERROR if initializing successfully
Error code if return value < 0
See Also
IOTC_Initialize(), IOTC_DeInitialize()
Attention
This function is the key entry to whole IOTC platform, including RDT module and AV module. That means, if you want to use RDT module, users shall still use this function to initialize IOTC module before calling RDT_Initialize().
int32_t IOTC_ReInitSocket ( uint16_t  nUDPPort)

ReInitialize IOTC module socket.

This function will reopen P2P UDP socket of IOTC module. It is useful for iOS APP from backgroud to foreground will cause socket failed.

Parameters
nUDPPort[in] Specify a UDP port. Random UDP port is used if it is specified as 0.
Returns
IOTC_ER_NoERROR if initializing successfully
Error code if return value < 0
Attention
(1) Must call it before any connection process. (2) This API can only be used in client side
int32_t IOTC_Session_Channel_Check_ON_OFF ( int32_t  nIOTCSessionID,
uint8_t  nIOTCChannelID 
)

Used by a device or a client to check whether the IOTC channel is ON or OFF.

A device or a client uses this function to turn on a IOTC channel before sending or receiving data through this IOTC channel.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session containing the IOTC channel to be checked
nIOTCChannelID[in] The channel ID of the IOTC channel to be checked
Returns
1 for channel ON return 0 for channel OFF
Error code if return value < 0
int32_t IOTC_Session_Channel_OFF ( int32_t  nIOTCSessionID,
uint8_t  nIOTCChannelID 
)

Used by a device or a client to turn off a IOTC channel.

A device or a client uses this function to turn off a IOTC channel when this IOTC channel is no longer needed for communication.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session containing the IOTC channel to be turned off
nIOTCChannelID[in] The channel ID of the IOTC channel to be turned off
Returns
IOTC_ER_NoERROR if turning off the IOTC channel successfully
Error code if return value < 0
Attention
(1) IOTC Channel 0 cannot be turned off because it is a default channel.

(2) Turn off a IOTC channel will also make the data remaining in receiving queue of this channel be deleted.
int32_t IOTC_Session_Channel_ON ( int32_t  nIOTCSessionID,
uint8_t  nIOTCChannelID 
)

Used by a device or a client to turn on a IOTC channel.

A device or a client uses this function to turn on a IOTC channel before sending or receiving data through this IOTC channel.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session containing the IOTC channel to be turned on
nIOTCChannelID[in] The channel ID of the IOTC channel to be turned on
Returns
IOTC_ER_NoERROR if turning on the IOTC channel successfully
Error code if return value < 0
Attention
The IOTC channel is only turned on in the local site calling this function. That means, the remote site shall also use IOTC_Session_Channel_ON() to turn on the same IOTC channel at its side before communication.
P2PAPI_API_DEPRECATED int32_t IOTC_Session_Check ( int32_t  nIOTCSessionID,
struct st_SInfo *  psSessionInfo 
)

Used by a device or a client to check the IOTC session info.

A device or a client may use this function to check if the IOTC session is still alive as well as getting the IOTC session info.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to be checked
psSessionInfo[out] The session info of specified IOTC session
Returns
IOTC_ER_NoERROR if getting the IOTC session info successfully
Error code if return value < 0
Attention
(1) This API has been deprecated and might be removed in the next version. Please replace it with IOTC_Session_Check_Ex.
P2PAPI_API_DEPRECATED int32_t IOTC_Session_Check_ByCallBackFn ( int32_t  nIOTCSessionID,
sessionStatusCB  pfxSessionStatusFn 
)

Used by a device or a client to get the session status.

This function gets the session status between device and client.
The difference of this function and IOTC_Session_Check() is this function will set callback function inside IOTC module and that callback function will be invoked whenever the session status between device and client disconnected, for example, IOTC alive timeout or one side call IOTC_Session_Close() to close this session.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to check status
pfxSessionStatusFn[in] The function pointer to getting session status function
Returns
IOTC_ER_NoERROR if getting the IOTC session info successfully
Error code if return value < 0
Attention
(1) This API has been deprecated and might be removed in the next version. Please replace it with IOTC_Session_Check_Ex.
int32_t IOTC_Session_Check_Ex ( int32_t  nIOTCSessionID,
struct st_SInfoEx *  psSessionInfo 
)

Used by a device or a client to check the IOTC session info.

A device or a client may use this function to check if the IOTC session is still alive as well as getting the IOTC session info. The structure size must be filled. For example "info.size=sizeof(struct st_SInfoEx);"

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to be checked
psSessionInfo[out] The session info of specified IOTC session
Returns
IOTC_ER_NoERROR if getting the IOTC session info successfully
Error code if return value < 0
void IOTC_Session_Close ( int32_t  nIOTCSessionID)

Used by a device or a client to close a IOTC session.

A device or a client uses this function to close a IOTC session specified by its session ID if this IOTC session is no longer required. If the closed SID is used for other APIs, the API should return IOTC_ER_INVALID_SID.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to be closed
int32_t IOTC_Session_Get_Free_Channel ( int32_t  nIOTCSessionID)

Used by a device or a client to get a tutk_platform_free IOTC channel.

A device or a client uses this function to get a tutk_platform_free IOTC channel in a specified IOTC session. By default, IOTC channel of ID 0 is turned on once a IOTC session is established. If more IOTC channels are required by users, this function can always return a tutk_platform_free IOTC channel until maximum IOTC channels are reached.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to get tutk_platform_free IOTC channel
Returns
The IOTC channel ID of a tutk_platform_free IOTC channel if successfully
Error code if return value < 0
Attention
(1) The IOTC channel returned by this function is already turned on.

(2) The IOTC channel is only turned on in the local site calling this function. That means, the remote site shall use IOTC_Session_Channel_ON() to turn on the same IOTC channel at its side before communication.
int32_t IOTC_Session_Read ( int32_t  nIOTCSessionID,
char *  abBuf,
int32_t  nMaxBufSize,
uint32_t  nTimeout,
uint8_t  nIOTCChannelID 
)

Used by a device or a client to read data from the other.

A device or a client uses this function to read data through a specific IOTC channel in a IOTC session.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to read data
abBuf[out] The array of byte buffer to receive read result
nMaxBufSize[in] The maximum length of the byte buffer
nTimeout[in] The timeout for this function in unit of millisecond, give 0 means return immediately
nIOTCChannelID[in] The IOTC channel ID in this IOTC session to read data
Returns
The actual length of read result stored in abBuf if read successfully
Error code if return value < 0
Attention
(1) The IOTC channel of ID 0 is enabled by default when a IOTC session is established. That means nIOTCChannelID can be specified as 0 if only one IOTC channel is needed by the user. If more IOTC channels are required, users should use IOTC_Session_Get_Free_Channel() and IOTC_Session_Channel_ON() to get more IOTC channel IDs and then specifying those IOTC channel IDs in this function according to the purpose defined by the user.

(2) If the size of abBuf, i.e. defined by nMaxBufSize, is less than the size of data to be read, then this function will only read the data up to nMaxBufSize and the remaining part will be truncated without error code returned. Therefore, it is suggested to allocate the size of abBuf as IOTC_MAX_PACKET_SIZE for ensure complete reading. (3) This function will need 192 bytes stack size. (4) This API is a blocking function. This function will wait until the specific IOTC channel in a IOTC session has data or some error happens during the read data process (5) Recommended value of timeout: > 1000 millisecond
P2PAPI_API_DEPRECATED int32_t IOTC_Session_Read_Check_Lost ( int32_t  nIOTCSessionID,
char *  abBuf,
int32_t  nMaxBufSize,
uint32_t  nTimeout,
uint16_t *  pnPacketSN,
int8_t *  pbFlagLost,
uint8_t  nIOTCChannelID 
)

Used by a device or a client to read data from the other.

A device or a client uses this function to read data through a specific IOTC channel in a IOTC session.
The difference between this function and IOTC_Session_Read() is this function provides packet lost information. Users may use this to check how many packets, if any, have been lost since the last time reading from this session.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to read data
abBuf[out] The array of byte buffer to receive read result
nMaxBufSize[in] The maximum length of the byte buffer
nTimeout[in] The timeout for this function in unit of millisecond, give 0 means return immediately
pnPacketSN[out] The serial number of the packet that is read successfully this time. Could be NULL.
pbFlagLost[out] A boolean value to indicate if there are some packets lost between this time and previous successful read. Could be NULL.
nIOTCChannelID[in] The IOTC channel ID in this IOTC session to read data
Returns
The actual length of read result stored in abBuf if read successfully
Error code if return value < 0
Attention
(1) The IOTC channel of ID 0 is enabled by default when a IOTC session is established. That means nIOTCChannelID can be specified as 0 if only one IOTC channel is needed by the user. If more IOTC channels are required, users should use IOTC_Session_Get_Free_Channel() and IOTC_Session_Channel_ON() to get more IOTC channel IDs and then specifying those IOTC channel IDs in this function according to the purpose defined by the user. (2) This API is a blocking function. This function will wait until the specific IOTC channel in a IOTC session has data or some error happens during the read data process (3) Recommended value of timeout: > 1000 millisecond (4) This API has been deprecated and might be removed in the next version. Please replace it IOTC_Session_Read.
int32_t IOTC_Session_Write ( int32_t  nIOTCSessionID,
const char *  cabBuf,
int32_t  nBufSize,
uint8_t  nIOTCChannelID 
)

Used by a device or a client to write data to the other.

A device or a client uses this function to write data through a specific IOTC channel in a IOTC session.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to write data
cabBuf[in] The array of byte buffer containing the data to write. Its size cannot be larger than IOTC_MAX_PACKET_SIZE
nBufSize[in] The length of the byte buffer. It cannot be larger than IOTC_MAX_PACKET_SIZE
nIOTCChannelID[in] The IOTC channel ID in this IOTC session to write data
Returns
The actual length of buffer to be written if write successfully. In non-blocking mode, the length with zero usually means the socket buffer is full and unable to write into.
Error code if return value < 0
Attention
(1) The IOTC channel of ID 0 is enabled by default when a IOTC session is established. That means nIOTCChannelID can be specified as 0 if only one IOTC channel is needed by the user. If more IOTC channels are required, users should use IOTC_Session_Get_Free_Channel() and IOTC_Session_Channel_ON() to get more IOTC channel IDs and then specifying those IOTC channel IDs in this function according to the purpose defined by the user.

(2) This function will need 4976 bytes stack size.
int32_t IOTC_Set_LanSearchPort ( uint32_t  nPort)

Change default LAN search port.

Both device and client must have the same LAN search port, otherwise client cannot find device by IOTC_Device_Search_Start or IOTC_LAN_Search

Parameters
nPort[in] Pass the customized LAN search port
Attention
The IOTC_Set_LanSearchPort must be called before IOTC_Initialize or IOTC_Initialize2
Returns
Return IOTC_ER_NoERROR if successfully.
Error code if return value < 0
  • IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid or port number > 65535.
int32_t IOTC_Set_Log_Attr ( LogAttr  logAttr)

Set Attribute of log file.

Parameters
logAttr[in] See LogAttr
Returns
IOTC_ER_NoERROR on success.
The value < 0
  • IOTC_ER_INVALID_ARG Invalid input argument.
P2PAPI_API_DEPRECATED void IOTC_Set_Log_Path ( 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 = unlimited
int32_t IOTC_Set_Master_Pub_Key ( const char *  nMasterKey)

Set RSA Public Key for Master Server.

This API is useful for when there is a need to set a specific key for master server. If not set, the "default" key will be used.

Parameters
nMasterKey[in] The RSA Public key that should be used
Returns
Returns IOTC_ER_NoError if the set was successful
or an error code if value < 0
int32_t IOTC_Set_Max_Session_Number ( int32_t  nMaxSessionNum)

Set the max number of IOTC sessions of IOTC module.

This function set the max number of allowable IOTC sessions in IOTC module. The max number of IOTC session limits the max number of connected clients in device side, while it limits the max number connected devices in client side. A device or a client could use this function to reduce the number of IOTC sessions in order to save some memory usage.

Parameters
nMaxSessionNum[in] The max number of IOTC sessions
Attention
(1) This function is optional if users do not want to change the default max number of IOTC sessions, i.e. MAX_DEFAULT_IOTC_SESSION_NUMBER. However, if users really wants to change it, this function shall be called before IOTC platform is initialized.

(2) The maximum IOTC session number is platform dependent. See the definition of MAX_DEFAULT_IOTC_SESSION_NUMBER for each platform.
Returns
On success, 0 is returned. On error, -46 is returned, it's an invalid argument.
int32_t IOTC_Set_Partial_Encryption ( int32_t  nIOTCSessionID,
uint8_t  bPartialEncryption 
)

Set partial encode On/Off.

Set partial encode On/Off

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to be encrypted.
bPartialEncryption[in] 1: Enable partial encode, 0: Disable partial encode
Returns
Error code if return value < 0
void IOTC_Setup_Session_Alive_Timeout ( uint32_t  nTimeout)

Setup session alive timeout value.

the default alive timeout value is 60 seconds since version 1.14.20.0, this function could help you to change the alive timeout value

Parameters
nTimeout[in] The timeout for this function in unit of second
Attention
(1) Must be set on client and device with the same value. Please use the function before IOTC_initialize or IOTC_initialize2. The minimum value is 1.

(2) Recommended value of timeout: > 30 secs

void IOTC_TCPRelayOnly_TurnOn ( void  )

Turn on only TCP relay mode function.

When device call this will login via TCP and only can be connected via LAN or TCP relay mode. When client call this will connect to device only via LAN or TCP relay mode.

Attention
Can be called anywhere.