IOTC Platform  Ver: 3.1.4.33
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Typedefs | Enumerations | Functions
IOTCAPIs.h File Reference

Data Structures

struct  st_SInfo
 
struct  st_SInfoEx
 
struct  st_LanSearchInfo
 
struct  st_LanSearchInfo2
 
struct  st_SearchDeviceInfo
 
struct  st_ConnectOption
 
struct  st_DeviceStInfo
 

Macros

#define P2PAPI_API   __declspec(dllimport)
 
#define MAX_DEFAULT_IOTC_SESSION_NUMBER   128
 
#define IOTC_MAX_PACKET_SIZE   1388
 
#define RELIABLE_MAX_PACKET_SIZE   1384
 
#define MAX_CHANNEL_NUMBER   32
 
#define IOTC_SESSION_ALIVE_TIMEOUT   60
 
#define IOTC_RELIABLE_MSG_SEND_DONE   1
 
#define IOTC_RELIABLE_MSG_SENDING   0
 
#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_CONNECT_IS_CALLING   -20
 
#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_INVALID_MODE   -38
 
#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_OFFLINE   -90
 
#define IOTC_ER_MASTER_INVALID   -91
 

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 st_ConnectOption st_ConnectOption_t
 
typedef struct st_DeviceStInfo st_DeviceStInfo_t
 
typedef void(__stdcall * loginInfoCB )(unsigned int nLoginInfo)
 
typedef void(* loginStateHandler )(IOTCDeviceLoginState state, int errCode, void *pUserData)
 
typedef void(* connectStateHandler )(IOTCConnectState state, int errCode, void *pUserData)
 
typedef void(__stdcall * sessionStatusCB )(int nIOTCSessionID, int nErrorCode)
 
typedef void(__stdcall * ConnectModeChangeCB )(int nIOTCSessionID, unsigned int nConnMode)
 
typedef void(__stdcall * onLineResult )(int result, void *userData)
 

Enumerations

enum  IOTCSessionMode { IOTC_NON_SECURE_MODE = 0, IOTC_SECURE_MODE = 1, IOTC_ARBITRARY_MODE = 2 }
 
enum  IOTCDeviceLoginState {
  IOTC_DEVLOGIN_ST_START = 1 << 0, IOTC_DEVLOGIN_ST_READY_FOR_LAN = 1 << 1, IOTC_DEVLOGIN_ST_LOGINING = 1 << 2, IOTC_DEVLOGIN_ST_LOGINED = 1 << 3,
  IOTC_DEVLOGIN_ST_RELOGINING = 1 << 4, IOTC_DEVLOGIN_ST_MULTI_LOGIN = 1 << 5, IOTC_DEVLOGIN_ST_LOGIN_FAILED = -1
}
 
enum  IOTCConnectState { IOTC_CONNECT_UID_ST_FAILED = -1, IOTC_CONNECT_UID_ST_START = 0, IOTC_CONNECT_UID_ST_CONNECTING, IOTC_CONNECT_UID_ST_CONNECTED }
 
enum  IOTCDeviceState {
  IOTC_DEV_ST_LOGIN_FAILED = -2, IOTC_DEV_ST_ERROR = -1, IOTC_DEV_ST_UNINITIALIZED = 0, IOTC_DEV_ST_INITIALIZED,
  IOTC_DEV_ST_LOGINING, IOTC_DEV_ST_LOGINED, IOTC_DEV_ST_CONNECTING, IOTC_DEV_ST_CONNECTED_WAITING
}
 

Functions

void IOTC_Get_Version (unsigned int *pnVersion)
 Get the version of IOTC module.
 
void IOTC_Set_Max_Session_Number (unsigned int nMaxSessionNum)
 Set the max number of IOTC sessions of IOTC module.
 
int IOTC_Initialize (unsigned short nUDPPort, const char *cszP2PHostNamePrimary, const char *cszP2PHostNameSecondary, const char *cszP2PHostNameThird, const char *cszP2PHostNameFourth)
 Initialize IOTC module.
 
int IOTC_Initialize2 (unsigned short nUDPPort)
 Initialize IOTC module.
 
int IOTC_DeInitialize (void)
 Deinitialize IOTC module.
 
int IOTC_Device_Login (const char *cszUID, const char *cszDeviceName, const char *cszDevicePWD)
 Used by a device to login to IOTC servers.
 
int IOTC_Device_LoginNB (const char *cszUID, const char *cszDeviceName, const char *cszDevicePWD, loginStateHandler handler, void *userData)
 Used by a device to login to IOTC servers.
 
int IOTC_Get_Login_Info (unsigned int *pnLoginInfo)
 Used by a device to get the login information.
 
int IOTC_Check_Device_On_Line (const char *UID, const unsigned int timeOut, onLineResult handler, void *userData)
 Checking a device on line or not.
 
void IOTC_Get_Login_Info_ByCallBackFn (loginInfoCB pfxLoginInfoFn)
 Used by a device to get the login information.
 
int IOTC_Get_Device_Status (struct st_DeviceStInfo *pDevStInfo)
 This function is used for getting device status information.
 
int IOTC_Listen (unsigned int nTimeout)
 Used by a device to listen connections from clients.
 
void IOTC_Listen_Exit (void)
 Used by a device to exit listen process.
 
int IOTC_Accept (int *SID)
 To get a new connected session id.
 
int IOTC_Listen2 (unsigned int nTimeout, const char *cszAESKey, IOTCSessionMode nSessionMode)
 Used by a device to listen connections from clients.
 
int IOTC_Connect_ByUID (const char *cszUID)
 Used by a client to connect a device.
 
int IOTC_Connect_ByUIDNB (const char *cszUID, connectStateHandler handler, void *userData)
 Used by a client to connect a device. Non-Blocking.
 
int IOTC_Get_SessionID (void)
 Used by a client to get a tutk_platform_free session ID.
 
int IOTC_Connect_ByUID_Parallel (const char *cszUID, int SID)
 Used by a client to connect a device and bind to a specified session ID.
 
int IOTC_Connect_ByUID_ParallelNB (const char *cszUID, int SID, connectStateHandler handler, void *userData)
 Used by a client to connect a device and bind to a specified session ID. Non-Blocking.
 
int IOTC_Connect_ByUID2 (const char *cszUID, const char *cszAESKey, IOTCSessionMode nSessionMode)
 Used by a client to connect a device.
 
void IOTC_Connect_Stop (void)
 Used by a client to stop connecting a device.
 
int IOTC_Connect_Stop_BySID (int SID)
 Used by a client to stop a specific session connecting a device.
 
int IOTC_Session_Read_Check_Lost (int nIOTCSessionID, char *abBuf, int nMaxBufSize, unsigned int nTimeout, unsigned short *pnPacketSN, char *pbFlagLost, unsigned char nIOTCChannelID)
 Used by a device or a client to read data from the other.
 
int IOTC_Session_Check (int nIOTCSessionID, struct st_SInfo *psSessionInfo)
 Used by a device or a client to check the IOTC session info.
 
int IOTC_Session_Check_Ex (int nIOTCSessionID, struct st_SInfoEx *psSessionInfo)
 Used by a device or a client to check the IOTC session info.
 
int IOTC_Session_Check_ByCallBackFn (int nIOTCSessionID, sessionStatusCB pfxSessionStatusFn)
 Used by a device or a client to get the session status.
 
int IOTC_Session_Read (int nIOTCSessionID, char *abBuf, int nMaxBufSize, unsigned int nTimeout, unsigned char nIOTCChannelID)
 Used by a device or a client to read data from the other.
 
int IOTC_Session_Write (int nIOTCSessionID, const char *cabBuf, int nBufSize, unsigned char nIOTCChannelID)
 Used by a device or a client to write data to the other.
 
void IOTC_Session_Close (int nIOTCSessionID)
 Used by a device or a client to close a IOTC session.
 
int IOTC_Session_Get_Free_Channel (int nIOTCSessionID)
 Used by a device or a client to get a tutk_platform_free IOTC channel.
 
int IOTC_Session_Channel_ON (int nIOTCSessionID, unsigned char nIOTCChannelID)
 Used by a device or a client to turn on a IOTC channel.
 
int IOTC_Session_Channel_OFF (int nIOTCSessionID, unsigned char nIOTCChannelID)
 Used by a device or a client to turn off a IOTC channel.
 
int IOTC_Session_Channel_Check_ON_OFF (int nIOTCSessionID, unsigned char nIOTCChannelID)
 Used by a device or a client to check whether the IOTC channel is ON or OFF.
 
int IOTC_Lan_Search (struct st_LanSearchInfo *psLanSearchInfo, int nArrayLen, int nWaitTimeMs)
 Used by search devices in LAN.
 
void IOTC_Set_Log_Path (char *path, int nMaxSize)
 Set path of log file.
 
int IOTC_Set_Partial_Encryption (int nIOTCSessionID, unsigned char bPartialEncryption)
 Set partial encode On/Off.
 
void IOTC_Set_Device_Name (const char *cszDeviceName)
 Set device name.
 
int IOTC_Lan_Search2 (struct st_LanSearchInfo2 *psLanSearchInfo2, int nArrayLen, int nWaitTimeMs)
 Used for searching devices in LAN.
 
int IOTC_Lan_Search2_Ex (struct st_LanSearchInfo2 *psLanSearchInfo2, int nArrayLen, int nWaitTimeMs, int nSendIntervalMs)
 Used for searching devices in LAN.
 
int IOTC_Search_Device_Start (int nWaitTimeMs, int nSendIntervalMs)
 Start to search devices in LAN.
 
int IOTC_Search_Device_Result (struct st_SearchDeviceInfo *psSearchDeviceInfo, int nArrayLen, int nGetAll)
 Poll the results of searched device in LAN.
 
int IOTC_Search_Device_Stop ()
 Stop to search devices in LAN.
 
void IOTC_TCPRelayOnly_TurnOn (void)
 Turn on only TCP relay mode function.
 
void IOTC_Setup_LANConnection_Timeout (unsigned int nTimeout)
 Setup LAN search and LAN connection timeout.
 
void IOTC_Setup_P2PConnection_Timeout (unsigned int nTimeout)
 Setup P2P connection timeout.
 
int IOTC_ReInitSocket (unsigned short nUDPPort)
 ReInitialize IOTC module socket.
 
void IOTC_Setup_DetectNetwork_Timeout (unsigned int nTimeout)
 Setup detect network reachable timeout.
 
int IOTC_Session_Write_Reliable_NB (int nIOTCSessionID, const char *cabBuf, int nBufSize, unsigned char nIOTCChannelID)
 Used by a device or a client to write data to the other in reliable way.
 
int IOTC_Session_Write_Reliable_NB_Abort (int nIOTCSessionID, unsigned char nIOTCChannelID)
 Used by a device or a client to abort specific IOTC_Session_Write_Reliable_NB() immediately.
 
int IOTC_Reliable_All_MSG_Is_Sent (int nIOTCSessionID, unsigned char nIOTCChannelID)
 Used by a device or a client to check if all the message are sent out from the reliable send queue.
 
void IOTC_Setup_Session_Alive_Timeout (unsigned int nTimeout)
 Setup session alive timeout value.
 
int IOTC_Set_Connection_Option (struct st_ConnectOption *S_ConnectOption)
 Setup connect option when client connects to device.
 
void IOTC_Setup_ErrorUpload (int nEnable)
 Switch of Uploading Error code to Server.
 
void IOTC_ConnModeChange_CallBack (ConnectModeChangeCB fpCallback)
 Register IOTC connection mode change callback.
 
int IOTC_Set_LanSearchPort (unsigned int nPort)
 Change default LAN search port.
 
int IOTC_Add_MasterServer (const char *cszMasterHostName1, const char *cszMasterHostName2, const char *cszMasterHostName3, const char *cszMasterHostName4)
 Add Customize Master server.
 

Detailed Description

This file describes all the APIs of the IOTC module in IOTC platform. IOTC module is a kind of data communication modules to provide basic data transfer among devices and clients.

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

Revision Table

Version | Name |Date |Description ---------—|---------------—|------------—|----------------—

Macro Definition Documentation

#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_CONNECT_IS_CALLING   -20

The client is already connecting to a device currently so it is prohibited to invoke connection again at this moment.

#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

#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_OFFLINE   -90

All Server response can not find device

#define IOTC_ER_DEVICE_SECURE_MODE   -37

A device does not support connection in non-secure mode

#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. Please check if OS 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_MODE   -38

The IOTC session mode specified in IOTC_Listen2(), IOTC_Connect_ByUID2() is not valid. Please see IOTCSessionMode for possible modes.

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

For IOTC Reliable checking send queue

#define IOTC_RELIABLE_MSG_SENDING   0
#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

The default max number of IOTC sessions in IOTC module. It is platform dependent and refer to source code for more detail.

#define P2PAPI_API   __declspec(dllimport)
#define RELIABLE_MAX_PACKET_SIZE   1384

The maximum size, in byte, of the buffer used in IOTC_Session_Write_Reliable_NB().

Typedef Documentation

typedef void(__stdcall * ConnectModeChangeCB)(int nIOTCSessionID, unsigned int 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 void(* connectStateHandler)(IOTCConnectState state, int errCode, void *pUserData)

This handler is used for IOTC_Connect_ByUIDNB and IOTC_Connect_ByUID_ParallelNB. It will be called when the connect state is changed. So that the user is able to check if a client connects to a device successfully or not.

Attention
This handler SHOULD NOT be blocked for any reason.
Parameters
state[out] The connect state. refer to IOTCConnectState for more information. errCode [out] The error code represents what the problems it during the connect. To be noted, This value is meaningful when state is IOTC_CONNECT_UID_ST_FAILED.

pUserData [out] The user date which is passed from IOTC_Connect_ByUIDNB or IOTC_Connect_ByUID_ParallelNB call.

typedef void(__stdcall * loginInfoCB)(unsigned int nLoginInfo)

The prototype of getting login info function, used by a device to be notified if it is still kept login with IOTC servers or is disconnected with IOTC servers.

Parameters
pnLoginInfo[out] The login info with meanings of following bits
  • bit 0: the device is ready for connection by client from LAN if this bit is 1
  • bit 1: the device is ready for connection by client from Internet if this bit is 1
  • bit 2: if this bit is 1, it means the device has received login response from IOTC servers since IOTC_Get_Login_Info() is called last time.
typedef void(* loginStateHandler)(IOTCDeviceLoginState state, int errCode, void *pUserData)

This handler is used for IOTC_Device_Login_NB. It will be called when the login state is changed. So that the user is able to check if a device registers itself to the P2P server successfully.

Attention
This handler SHOULD NOT be blocked for any reason.
Parameters
state[out] The device login state. refer to IOTCDeviceLoginState for more information. errCode [out] The error code represents what the problems it during the device login. To be noted, This value is meaningful when state is IOTC_DEVLOGIN_ST_LOGIN_FAILED.
  • IOTC_ER_NoERROR if device had obtained server list and sent login packets successfully.

pUserData [out] The user date which is passed from IOTC_Device_Login_NB call.

typedef void(__stdcall * onLineResult)(int result, void *userData)

This is the handler for reporting the device on line status. It is used for IOTC_Check_Device_On_Line().

Parameters
result[out] The result of getting the device status.
userData[in] The data which was passed during IOTC_Check_Device_On_Line() is called.
typedef void(__stdcall * sessionStatusCB)(int nIOTCSessionID, int 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_ConnectOption st_ConnectOption_t
typedef struct st_DeviceStInfo st_DeviceStInfo_t
typedef struct st_LanSearchInfo2 st_LanSearchInfo2_t
typedef struct st_LanSearchInfo st_LanSearchInfo_t
typedef struct st_SearchDeviceInfo st_SearchDeviceInfo_t
typedef struct st_SInfo st_SInfo_t
typedef struct st_SInfoEx st_SInfoEx_t

Enumeration Type Documentation

enum IOTCConnectState

IOTC Client Connection State which shows the state of a Client connects to a device. IOTC_Connect_ByUIDNB and IOTC_Connect_ByUID_ParallelNB are non-blocking calls. This state should be checked after the two functions are called. The state will be shown in connectStateHandler which needs to be assigned when calling IOTC_Connect_ByUIDNB or IOTC_Connect_ByUID_ParallelNB.

Enumerator:
IOTC_CONNECT_UID_ST_FAILED 
IOTC_CONNECT_UID_ST_START 
IOTC_CONNECT_UID_ST_CONNECTING 
IOTC_CONNECT_UID_ST_CONNECTED 
enum IOTCDeviceLoginState

IOTC Device Login states which indicates the state of a device login process. IOTC_Device_Login_NB is a non-blocking function which means it returns immediately. The state will be shown in loginStateHandler which needs to be assigned when calling IOTC_Device_Login_NB.

Enumerator:
IOTC_DEVLOGIN_ST_START 
IOTC_DEVLOGIN_ST_READY_FOR_LAN 
IOTC_DEVLOGIN_ST_LOGINING 
IOTC_DEVLOGIN_ST_LOGINED 
IOTC_DEVLOGIN_ST_RELOGINING 
IOTC_DEVLOGIN_ST_MULTI_LOGIN 
IOTC_DEVLOGIN_ST_LOGIN_FAILED 
enum IOTCDeviceState
Enumerator:
IOTC_DEV_ST_LOGIN_FAILED 
IOTC_DEV_ST_ERROR 
IOTC_DEV_ST_UNINITIALIZED 
IOTC_DEV_ST_INITIALIZED 
IOTC_DEV_ST_LOGINING 
IOTC_DEV_ST_LOGINED 
IOTC_DEV_ST_CONNECTING 
IOTC_DEV_ST_CONNECTED_WAITING 
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

int IOTC_Accept ( int *  SID)

To get a new connected session id.

As a device, it allows a client to connect. The way to know if a client connects or not is to get the device status information by calling IOTC_Get_Device_Status. Once the information indicates a new client is connected, IOTC_Accept() is used for getting the new session id for further usage.

Parameters
SID[out] The session id for the new connection.
Returns
IOTC_ER_NoERROR on success.
The value < 0
  • IOTC_ER_INVALID_ARG Invalid input argument.
  • IOTC_ER_NOT_INITIALIZED The module has not bee initialized.
  • IOTC_ER_EXCEED_MAX_SESSION It reaches the max session number.
  • IOTC_ER_DEVICE_IS_BANNED The device is banned.
int IOTC_Add_MasterServer ( const char *  cszMasterHostName1,
const char *  cszMasterHostName2,
const char *  cszMasterHostName3,
const char *  cszMasterHostName4 
)

Add Customize Master server.

IOTC module has default master servers. If users need to add their own master server, this function can add the customize master servers.

Parameters
cszMasterHostName1[in] Specify the domain name or IP address of the primary master. Cannot be NULL. See attention below for more detail.
cszMasterHostName2[in] Specify the domain name or IP address of the secondary master. Can be NULL if only one master is required.
cszMasterHostName3[in] Specify the domain name or IP address of the third master. Can be NULL if only one master is required.
cszMasterHostName4[in] Specify the domain name or IP address of the fourth master. Can be NULL if only one master is required.
Returns
IOTC_ER_NoERROR if initializing successfully
Error code if return value < 0
Attention
This function must be used before IOTC_Device_Login(), IOTC_Connect_ByUID(), IOTC_Connect_ByUID_Parallel()

int IOTC_Check_Device_On_Line ( const char *  UID,
const unsigned int  timeOut,
onLineResult  handler,
void *  userData 
)

Checking a device on line or not.

This function is used for checking a device on line status. A device is on line means the device login to a server or the device is able to be searched on LAN. To check to state, it takes a little bit time to query the device status from IOTC servers. In order to not blocking anything, the function returns immediately, the result will be shown in the handler.

Attention
THE "hander" MUST NOT BE BLOCKED. IT SHOULD BE RETURNED ASAP. IF YOU WANT TO DO SOMETHING BLOCK (i.e. sleep, or any kind of loop.), PLEASE CREATE A THREAD TO DO IT.
Parameters
UID[in] A device UID which is used to check the state.
timeOut[in] The time out value of checking device information in millisecond.
handler[in] A handle function for getting the device on line result.
userData[in] The data would like to bring to the handler for feather processing.
Returns
IOTC_ER_NoERROR on successful. The others are error.
int IOTC_Connect_ByUID ( const char *  cszUID)

Used by a client to connect a device.

This function is for a client to connect a device by specifying the UID of that device. If connection is established with the help of IOTC servers, the IOTC session ID will be returned in this function and then device and client can communicate for the other later by using this IOTC session ID.

Parameters
cszUID[in] The UID of a device that client wants to connect
Returns
IOTC session ID if return value >= 0
Error code if return value < 0
Attention
This process is a block process.
int IOTC_Connect_ByUID2 ( const char *  cszUID,
const char *  cszAESKey,
IOTCSessionMode  nSessionMode 
)

Used by a client to connect a device.

This function is for a client to connect a device by specifying the UID of that device. If connection is established with the help of IOTC servers, the IOTC session ID will be returned in this function and then device and client can communicate for the other later by using this IOTC session ID.

The different between this function and IOTC_Connect_ByUID() is that this function supports IOTC session established in secure mode. Also, by specifying IOTC_ARBITRARY_MODE as IOTC session mode, this function can let clients establish IOTC session in either non-secure mode and secure mode according to devices' secure settings.

Parameters
cszUID[in] The UID of a device that client wants to connect
cszAESKey[in] The AES key for certification. Specify it as NULL will make IOTC module use predefined AES key.
nSessionMode[in] The IOTC session mode that a client want to connect. Please refer to IOTCSessionMode for more detail
Returns
IOTC session ID if return value >= 0
Error code if return value < 0
Attention
(1) This process is a block process.

(2) The AES key shall be matched between a device and a client in order to establish connection successfully.

(3) This function is available on Win32, Linux, Android, iOS and ARC platforms.
int IOTC_Connect_ByUID_Parallel ( const char *  cszUID,
int  SID 
)

Used by a client to connect a device and bind to a specified session ID.

This function is for a client to connect a device by specifying the UID of that device, and bind to a tutk_platform_free session ID from IOTC_Get_SessionID(). If connection is established with the help of IOTC servers, the IOTC_ER_NoERROR will be returned in this function and then device and client can communicate for the other later by using this IOTC session ID. If this function is called by multiple threads, the connections will be processed concurrently.

Parameters
cszUID[in] The UID of a device that client wants to connect
SID[in] The Session ID got from IOTC_Get_SessionID() the connection should bind to.
Returns
IOTC session ID if return value >= 0 and equal to the input parameter SID.
Error code if return value < 0
Attention
If you call IOTC_Connect_Stop_BySID() and this function not return yet, and then use the same session ID to call again will cause session ID in wrong status.
int IOTC_Connect_ByUID_ParallelNB ( const char *  cszUID,
int  SID,
connectStateHandler  handler,
void *  userData 
)

Used by a client to connect a device and bind to a specified session ID. Non-Blocking.

This function is for a client to connect a device by specifying the UID of that device, and bind to a tutk_platform_free session ID from IOTC_Get_SessionID(). If connection is established with the help of IOTC servers, the IOTC_ER_NoERROR will be returned in this function and then device and client can communicate for the other later by using this IOTC session ID. If this function is called by multiple threads, the connections will be processed concurrently. Since this function is a non-blocking call, it only triggers the connecting mechanisms to connect a device. A handler should be specified for handling each state of connecting. The handler will be called once the state has been changed.

Parameters
cszUID[in] The UID of a device that client wants to connect
SID[in] The Session ID got from IOTC_Get_SessionID() the connection should bind to.
handler[in] The state handler. This handler will be called once the connecting state (IOTCConnectState) is changed.
userData[in] The user data which will be brought to the handler.
Returns
IOTC session ID if return value >= 0 and equal to the input parameter SID.
Error code if return value < 0
Attention
If you call IOTC_Connect_Stop_BySID() and this function not return yet, and then use the same session ID to call again will cause session ID in wrong status.
int IOTC_Connect_ByUIDNB ( const char *  cszUID,
connectStateHandler  handler,
void *  userData 
)

Used by a client to connect a device. Non-Blocking.

This function is used for connecting a device by a specific UID. After this function is called, a IOTC session ID will be retruned if no error occurs. This function triggers the connecting mechanisms to connect a device. A handler should be specified for handling each state of connecting. The handler will be called once the state has been changed. The IOTC Session ID should be used to read/write the data afterwards.

Parameters
cszUID[in] The UID of a device that client wants to connect
handler[in] The state handler. This handler will be called once the connecting state (IOTCConnectState) is changed.
userData[in] The user data which will be brought to the handler.
Returns
IOTC session ID if return value >= 0
Error code if return value < 0
void IOTC_Connect_Stop ( void  )

Used by a client to stop connecting a device.

This function is for a client to stop connecting a device. Since IOTC_Connect_ByUID(), IOTC_Connect_ByUID2() are all block processes, that means the client will have to wait for the return of these functions before executing sequential instructions. In some cases, users may want the client to stop connecting immediately by this function in another thread before the return of connection process.

Attention
Only use to stop IOTC_Connect_ByUID() and 2, NOT use to stop IOTC_Connect_ByUID_Parallel().
int IOTC_Connect_Stop_BySID ( int  SID)

Used by a client to stop a specific session connecting a device.

This function is for a client to stop connecting a device. Since IOTC_Connect_ByUID_Parallel() is a block processes, that means the client will have to wait for the return of these functions before executing sequential instructions. In some cases, users may want the client to stop connecting immediately by this function in another thread before the return of connection process.

Parameters
SID[in] The Session ID of a connection which will be stop.
Returns
IOTC_ER_NoERROR
Error code if return value < 0
void IOTC_ConnModeChange_CallBack ( ConnectModeChangeCB  fpCallback)

Register IOTC connection mode change callback.

Callback will be triggered when connection mode is changed.

Parameters
fpCallback[in] function pointer of callback.
int 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 automatically close all IOTC sessions in local site while the remote site will find sessions have been closed after certain period of time. Therefore, it is suggested to close all sessions before invoking this function to ensure the remote site and real-time session status.
int IOTC_Device_Login ( const char *  cszUID,
const char *  cszDeviceName,
const char *  cszDevicePWD 
)

Used by a device to login to IOTC servers.

This function will let a device login to IOTC servers. UID is required when login to IOTC servers. The device name and password are applicable only in LAN mode when the device cannot login to IOTC servers due to network issue.

Parameters
cszUID[in] The UID of that device login to IOTC servers
cszDeviceName[in] The name of that device, used in LAN mode for clients to connect
cszDevicePWD[in] This parameter is no longer used
Returns
IOTC_ER_NoERROR if device had obtained server list and sent login packets successfully
Error code if return value < 0
Attention
(1) This function is a block process. That means this function will return until the device can login into IOTC servers successfully or some error happens during the process. It is suggested to use another thread to perform login process so that sequential instructions will not blocked.

(2) Please use IOTC_Get_Login_Info() to check if device really logins into server successfully.
int IOTC_Device_LoginNB ( const char *  cszUID,
const char *  cszDeviceName,
const char *  cszDevicePWD,
loginStateHandler  handler,
void *  userData 
)

Used by a device to login to IOTC servers.

This function is used for registering a device to IOTC servers which is called login process. During login a UID is a mandatory argument for inditifing the device. The device name and password are applicable only in LAN mode when the device cannot login to IOTC servers due to network issue. This is a non-blocking call. It triggers the login process. Therefore a state handler is needed to take care all the states. This handler will be called once the state is changed.

Parameters
cszUID[in] The UID of that device login to IOTC servers
cszDeviceName[in] The name of that device, used in LAN mode for clients to connect
cszDevicePWD[in] The password of that device, used in LAN mode for clients to connect
hadler[in] The login state handler which will be called once the login state is changed.
userData[in] The user data which will be brought to the handler.
Returns
IOTC_ER_NoERROR if device had obtained server list and sent login packets successfully
int IOTC_Get_Device_Status ( struct st_DeviceStInfo *  pDevStInfo)

This function is used for getting device status information.

Getting device status information to know what device is doing. Also to know how many sesstion has been used and if there is a new client is connected. Usually, this function can be used with IOTC_Accept(). First all, calling IOTC_Get_Device_Status to check if a new client is connected. If so, calling IOTC_Accept to get the new session id. To be noted, the memory that the argument pDevStInfo points to will be clear to 0 in the function before getting the information.

Parameters
pDevStInfo[out] A pointer that points to a memory which the device information is saved to.
Returns
IOTC_ER_NoERROR on success. Otherwise it fails.
int IOTC_Get_Login_Info ( unsigned int *  pnLoginInfo)

Used by a device to get the login information.

This function gets the login information of a device to IOTC servers.

Parameters
pnLoginInfo[out] The login info with meanings of following bits
  • bit 0: the device is ready for connection by client from LAN if this bit is 1
  • bit 1: the device is ready for connection by client from Internet if this bit is 1
  • bit 2: if this bit is 1, it means the device has received login response from IOTC servers since IOTC_Get_Login_Info() is called last time.
Returns
The number of fails to login to IOTC servers.
Error code if return value < 0
void IOTC_Get_Login_Info_ByCallBackFn ( loginInfoCB  pfxLoginInfoFn)

Used by a device to get the login information.

This function gets the login information of a device to IOTC servers.
The difference of this function and IOTC_Get_Login_Info() is this function will set callback function inside IOTC module and that callback function will be invoked whenever the login status of that device is updated from IOTC servers, for example, IOTC servers response login message to that device or the connection between IOTC servers and that device has been lost.

Parameters
pfxLoginInfoFn[in] The function pointer to getting login info function
int 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().
void IOTC_Get_Version ( unsigned int *  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()
int IOTC_Initialize ( unsigned short  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. The host name and IP address of each master is listed as below:
  • Master #1: m1.iotcplatform.com => 50.19.254.134
  • Master #2: m2.iotcplatform.com => 122.248.234.207
  • Master #3: m3.iotcplatform.com => 46.137.188.54
  • Master #4: m4.iotcplatform.com => 122.226.84.253
  • Master #5: m5.iotcplatform.com => 61.188.37.216
  • Master #6: m6.iotcplatform.com => 120.24.59.150
  • Master #7: m7.iotcplatform.com => 114.215.137.159
  • Master #8: m8.iotcplatform.com => 104.199.156.58
int IOTC_Initialize2 ( unsigned short  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().
int IOTC_Lan_Search ( struct st_LanSearchInfo *  psLanSearchInfo,
int  nArrayLen,
int  nWaitTimeMs 
)

Used by search devices in LAN.

When clients and devices are stay in a LAN environment, client can call this function to discovery devices and connect it directly.

Parameters
psLanSearchInfo[in] The array of struct st_LanSearchInfo to store search result
nArrayLen[in] The size of the psLanSearchInfo array
nWaitTimeMs[in] The timeout in milliseconds before discovery process end.
Returns
The number of devices found.
Error code if return value < 0
Attention
(1) Not support IPv6. The IP length is only for IPv4.

* (2) This API is deprecated. Please use IOTC_Search_Device_Start / IOTC_Search_Device_Result.

*
int IOTC_Lan_Search2 ( struct st_LanSearchInfo2 *  psLanSearchInfo2,
int  nArrayLen,
int  nWaitTimeMs 
)

Used for searching devices in LAN.

When client and devices are in LAN, client can search devices and their name by calling this function.

Parameters
psLanSearchInfo2[in] The array of struct st_LanSearchInfo2 store the search result and Device name.
nArrayLen[in] The size of psLanSearchInfo2 array
nWaitTimeMs[in] Period (or timeout) of searching LAN. (milliseconds)
Returns
The number of devices found.
Error code if return value < 0
Attention
(1) Not support IPv6. The IP length is only for IPv4.

* (2) This API is deprecated. Please use IOTC_Search_Device_Start / IOTC_Search_Device_Result.

*
int IOTC_Lan_Search2_Ex ( struct st_LanSearchInfo2 *  psLanSearchInfo2,
int  nArrayLen,
int  nWaitTimeMs,
int  nSendIntervalMs 
)

Used for searching devices in LAN.

When client and devices are in LAN, client can search devices and their name by calling this function.

Parameters
psLanSearchInfo2[in] The array of struct st_LanSearchInfo2 store the search result and Device name.
nArrayLen[in] The size of psLanSearchInfo2 array
nWaitTimeMs[in] Period (or timeout) of searching LAN. (milliseconds)
nSendIntervalMs[in] Interval of sending broadcast for searching device in LAN. (milliseconds)
Returns
The number of devices found.
Error code if return value < 0
Attention
(1) Not support IPv6. The IP length is only for IPv4.

* (2) This API is deprecated. Please use IOTC_Search_Device_Start / IOTC_Search_Device_Result.

*
int IOTC_Listen ( unsigned int  nTimeout)

Used by a device to listen connections from clients.

This function is for a device to listen any connection from clients. If connection is established with the help of IOTC servers, the IOTC session ID will be returned in this function and then device and client can communicate for the other later by using this IOTC session ID.

Parameters
nTimeout[in] The timeout for this function in unit of millisecond, give 0 means block forever
Returns
IOTC session ID if return value >= 0
Error code if return value < 0
Attention
(1) This function is a block process, waiting for following two conditions happens before executing sequential instructions (a) any connection from clients is established (b) timeout expires.

(2) nTimeout has no effect in 8051 platform.
int IOTC_Listen2 ( unsigned int  nTimeout,
const char *  cszAESKey,
IOTCSessionMode  nSessionMode 
)

Used by a device to listen connections from clients.

This function is for a device to listen any connection from clients. If connection is established with the help of IOTC servers, the IOTC session ID will be returned in this function and then device and client can communicate for the other later by using this IOTC session ID.

The difference between this function and IOTC_Listen() is that this function supports IOTC session established in secure mode. Also, by specifying IOTC_ARBITRARY_MODE as IOTC session mode, this function can let devices establish IOTC session in either non-secure mode and secure mode according to clients' request.

Parameters
nTimeout[in] The timeout for this function in unit of millisecond, give 0 means block forever
cszAESKey[in] The AES key for certification. Specify it as NULL will make IOTC module use predefined AES key.
nSessionMode[in] The IOTC session mode that a device want to connect. Please refer to IOTCSessionMode for more detail
Returns
IOTC session ID if return value >= 0
Error code if return value < 0
Attention
(1) This function is available on Win32, Linux, Android, iOS and ARC platforms.

(2) The AES key shall be matched between a device and a client in order to establish connection successfully.
void IOTC_Listen_Exit ( void  )

Used by a device to exit listen process.

Since listen process is a block process and that means a device will wait for following two conditions happens before executing sequential instructions (1) any connection from clients is established (2) timeout expires. In some cases, users may want the device to exit listen immediately by this function in another thread before the two conditions above happens.

int IOTC_ReInitSocket ( unsigned short  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
Must call it before any connection process.
int IOTC_Reliable_All_MSG_Is_Sent ( int  nIOTCSessionID,
unsigned char  nIOTCChannelID 
)

Used by a device or a client to check if all the message are sent out from the reliable send queue.

A device or a client uses this function to verify wether or not all the message are sent out succefully.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to check the data
nIOTCChannelID[in] The IOTC channel ID in this IOTC session to check the data
Returns
Return IOTC_RELIABLE_MSG_SENDING means that the queue has messages still. IOTC_RELIABLE_MSG_SEND_DONE means that all the message are sent out successfully.
Error code if return value < 0
int IOTC_Search_Device_Result ( struct st_SearchDeviceInfo *  psSearchDeviceInfo,
int  nArrayLen,
int  nGetAll 
)

Poll the results of searched device in LAN.

Use the function to poll the result of device search in LAN, the IOTC_Search_Device_Start should be called before use the function

Parameters
st_SearchDeviceInfo[in] The array of struct st_SearchDeviceInfo store the search result and Device name.
nArrayLen[in] The length of array
nGetAll[in] 0: get new queried device 1: get all queried devices
Returns
IOTC_ER_NoERROR if search devices in LAN successfully
Error code if return value < 0
Attention
(1) Support IPv6. The IP length supports both for IPv4/IPv6.

*
int IOTC_Search_Device_Start ( int  nWaitTimeMs,
int  nSendIntervalMs 
)

Start to search devices in LAN.

When client and devices are in LAN, client can search devices and their name and the result can be polled by function IOTC_Search_Device_Result

Parameters
nWaitTimeMs[in] Period (or timeout) of searching LAN. (milliseconds)
nSendIntervalMs[in] Interval of sending broadcast for searching device in LAN. (milliseconds)
Returns
The number of devices found in the LAN (it is limited by the length of array)
Error code if return value < 0
int IOTC_Search_Device_Stop ( )

Stop to search devices in LAN.

Stop to do device search in LAN, the IOTC_Search_Device_Start should be called before use the function

Parameters
st_SearchDeviceInfo[in] The array of struct st_SearchDeviceInfo store the search result and Device name.
nArrayLen[in] The length of array
nGetAll[in] 0: get new queried device 1: get all queried devices
Returns
IOTC_ER_NoERROR if search devices in LAN successfully
Error code if return value < 0
int IOTC_Session_Channel_Check_ON_OFF ( int  nIOTCSessionID,
unsigned char  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
int IOTC_Session_Channel_OFF ( int  nIOTCSessionID,
unsigned char  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.
int IOTC_Session_Channel_ON ( int  nIOTCSessionID,
unsigned char  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.
int IOTC_Session_Check ( int  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
int IOTC_Session_Check_ByCallBackFn ( int  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
int IOTC_Session_Check_Ex ( int  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 ( int  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
int IOTC_Session_Get_Free_Channel ( int  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.
int IOTC_Session_Read ( int  nIOTCSessionID,
char *  abBuf,
int  nMaxBufSize,
unsigned int  nTimeout,
unsigned char  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.
int IOTC_Session_Read_Check_Lost ( int  nIOTCSessionID,
char *  abBuf,
int  nMaxBufSize,
unsigned int  nTimeout,
unsigned short *  pnPacketSN,
char *  pbFlagLost,
unsigned char  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
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.
int IOTC_Session_Write ( int  nIOTCSessionID,
const char *  cabBuf,
int  nBufSize,
unsigned char  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 block when session is connected via TCP and socket buffer is full. (3) This function will need 4976 bytes stack size.
int IOTC_Session_Write_Reliable_NB ( int  nIOTCSessionID,
const char *  cabBuf,
int  nBufSize,
unsigned char  nIOTCChannelID 
)

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

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

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 RELIABLE_MAX_PACKET_SIZE
nBufSize[in] The length of the byte buffer. It cannot be larger than RELIABLE_MAX_PACKET_SIZE
nIOTCChannelID[in] The IOTC channel ID in this IOTC session to write data
Returns
Return 0 if send 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) IOTC reliabe non-blocking call has a send queue. Before calling IOTC_Session_Close() you might need to make sure all the messages are sent out successfully. IOTC_Reliable_All_MSG_Is_Sent() is the function to check the send queue. In case of the enqueue messages don't matter. IOTC_Session_Close() can be calling without checking.
int IOTC_Session_Write_Reliable_NB_Abort ( int  nIOTCSessionID,
unsigned char  nIOTCChannelID 
)

Used by a device or a client to abort specific IOTC_Session_Write_Reliable_NB() immediately.

A device or a client uses this function to write data through a specific IOTC channel in a IOTC session in a reliable way. Once this function is called, the items in the send queue will not be sent out and be clear. The make queue free for writing other data.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to write data
nIOTCChannelID[in] The IOTC channel ID in this IOTC session to write data
Returns
Return 0 if IOTC_Session_Write_Reliable_Abort() call successfully.
Error code if return value < 0
Attention
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.

int IOTC_Set_Connection_Option ( struct st_ConnectOption *  S_ConnectOption)

Setup connect option when client connects to device.

Client uses this function to set the Option of Connection.

Parameters
nIOTCSessionID[in] The session ID of the IOTC session to be checked.
S_ConnectOption[in] the connect option that contained the option to be set.
void IOTC_Set_Device_Name ( const char *  cszDeviceName)

Set device name.

Device can let client know its name when client call IOTC_Lan_Search2(). The maximum size of device name is 131 Byte. We filled in 0 at the 132th Byte.

Parameters
cszDeviceName[in] This is user-defined device name. Clients will get it by calling IOTC_Lan_Search2().
int IOTC_Set_LanSearchPort ( unsigned int  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.
void IOTC_Set_Log_Path ( 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 = unlimited
void IOTC_Set_Max_Session_Number ( unsigned int  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.
int IOTC_Set_Partial_Encryption ( int  nIOTCSessionID,
unsigned char  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_DetectNetwork_Timeout ( unsigned int  nTimeout)

Setup detect network reachable timeout.

Both device and client can call this, it can determine how many time to detect internet reachable. Once it called the timeout value is effective forever until IOTC_DeInitialize() be called.

Parameters
nTimeout[in] The timeout for this function in unit of millisecond
Attention
Mast be called before start login or connection.
void IOTC_Setup_ErrorUpload ( int  nEnable)

Switch of Uploading Error code to Server.

Use this function to enable or disable error code uploading. The default setup is disable.

Parameters
nEnable[in] Set nEnable to 0 to disable error code uploading. Set nEnable to 1 to enable error code uploading.
void IOTC_Setup_LANConnection_Timeout ( unsigned int  nTimeout)

Setup LAN search and LAN connection timeout.

Only client can call this, it can determine how many time to try LAN search and LAN connection. Once it called the timeout value is effective forever until IOTC_DeInitialize() be called.

Parameters
nTimeout[in] The timeout for this function in unit of millisecond, give 0 means skip LAN flow
Attention
Mast be called before start connection. Minimum is 100 millisecond.
void IOTC_Setup_P2PConnection_Timeout ( unsigned int  nTimeout)

Setup P2P connection timeout.

Only client can call this, it can determine how many time to try P2P connection. Once it called the timeout value is effective forever until IOTC_DeInitialize() be called.

Parameters
nTimeout[in] The timeout for this function in unit of millisecond, give 0 means skip P2P flow
Attention
Mast be called before start connection. Minimum is 100 millisecond.
void IOTC_Setup_Session_Alive_Timeout ( unsigned int  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
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.
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.