2013 lines
92 KiB
C
2013 lines
92 KiB
C
/*! \file IOTCAPIs.h
|
|
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
|
|
------------|------------------|---------------|-------------------
|
|
*/
|
|
|
|
#ifndef _IOTCAPIs_H_
|
|
#define _IOTCAPIs_H_
|
|
|
|
/* ============================================================================
|
|
* Platform Dependant Macro Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
#ifdef _WIN32
|
|
#ifdef IOTC_STATIC_LIB
|
|
#define P2PAPI_API
|
|
#elif defined P2PAPI_EXPORTS
|
|
#define P2PAPI_API __declspec(dllexport)
|
|
#else
|
|
#define P2PAPI_API __declspec(dllimport)
|
|
#endif
|
|
#else // #ifdef _WIN32
|
|
#define P2PAPI_API
|
|
#endif //#ifdef _WIN32
|
|
|
|
|
|
#ifndef _WIN32
|
|
#define __stdcall
|
|
#endif // #ifndef _WIN32
|
|
|
|
|
|
#ifdef _WIN32
|
|
/** @cond */
|
|
|
|
|
|
/** @endcond */
|
|
/** The default max number of IOTC sessions in IOTC module.
|
|
* It is platform dependent and refer to source code for more detail. */
|
|
#define MAX_DEFAULT_IOTC_SESSION_NUMBER 128
|
|
#endif // #ifdef _WIN32
|
|
|
|
#if defined (__linux__) || defined (__APPLE__) || defined(__pnacl__)
|
|
#define MAX_DEFAULT_IOTC_SESSION_NUMBER 128
|
|
#endif // #ifdef __linux__ __APPLE__ __pnacl__
|
|
|
|
#ifdef IOTC_UCOSII
|
|
#define MAX_DEFAULT_IOTC_SESSION_NUMBER 8
|
|
extern unsigned int TutkLoginTaskPri;
|
|
extern unsigned int TutkRoutineTaskPri;
|
|
#endif // #ifdef IOTC_UCOSII
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/* ============================================================================
|
|
* Generic Macro Definition
|
|
* ============================================================================
|
|
*/
|
|
/** The maximum size, in byte, of the buffer used in IOTC_Session_Read(),
|
|
* IOTC_Session_Write() and IOTC_Session_Read_Check_Lost(). */
|
|
#define IOTC_MAX_PACKET_SIZE 1388
|
|
|
|
/** The maximum size, in byte, of the buffer used in IOTC_Session_Write_Reliable_NB(). */
|
|
#define RELIABLE_MAX_PACKET_SIZE 1384
|
|
|
|
/** The maximum number of IOTC channels for each IOTC session */
|
|
#define MAX_CHANNEL_NUMBER 32
|
|
|
|
/** The timeout, in unit of second, for keeping an IOTC session alive since
|
|
* the last time remote site has response */
|
|
#define IOTC_SESSION_ALIVE_TIMEOUT 60
|
|
|
|
/** For IOTC Reliable checking send queue */
|
|
#define IOTC_RELIABLE_MSG_SEND_DONE 1
|
|
#define IOTC_RELIABLE_MSG_SENDING 0
|
|
/* ============================================================================
|
|
* Error Code Declaration
|
|
* ============================================================================
|
|
*/
|
|
/** The function is performed successfully. */
|
|
#define IOTC_ER_NoERROR 0
|
|
|
|
/** IOTC servers have no response, probably caused by many types of Internet connection issues. */
|
|
#define IOTC_ER_SERVER_NOT_RESPONSE -1
|
|
|
|
/** IOTC masters cannot be resolved their domain name, probably caused
|
|
* by network connection or DNS setting issues. */
|
|
#define IOTC_ER_FAIL_RESOLVE_HOSTNAME -2
|
|
|
|
/** IOTC module is already initialized. It is not necessary to re-initialize. */
|
|
#define IOTC_ER_ALREADY_INITIALIZED -3
|
|
|
|
/** IOTC module fails to create Mutexes when doing initialization. Please
|
|
* check if OS has sufficient Mutexes for IOTC platform. */
|
|
#define IOTC_ER_FAIL_CREATE_MUTEX -4
|
|
|
|
/** IOTC module fails to create threads. Please check if OS has ability
|
|
* to create threads for IOTC module. */
|
|
#define IOTC_ER_FAIL_CREATE_THREAD -5
|
|
|
|
/** IOTC module fails to create sockets. Please check if OS supports socket service */
|
|
#define IOTC_ER_FAIL_CREATE_SOCKET -6
|
|
|
|
/** IOTC module fails to set up socket options. */
|
|
#define IOTC_ER_FAIL_SOCKET_OPT -7
|
|
|
|
/** IOTC module fails to bind sockets */
|
|
#define IOTC_ER_FAIL_SOCKET_BIND -8
|
|
|
|
/** The specified UID is not licensed or expired. */
|
|
#define IOTC_ER_UNLICENSE -10
|
|
|
|
/** The device is already under login process currently
|
|
* so it is prohibited to invoke login again at this moment. */
|
|
#define IOTC_ER_LOGIN_ALREADY_CALLED -11
|
|
|
|
/** IOTC module is not initialized yet. Please use IOTC_Initialize() or
|
|
* IOTC_Initialize2() for initialization. */
|
|
#define IOTC_ER_NOT_INITIALIZED -12
|
|
|
|
/** 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_TIMEOUT -13
|
|
|
|
/** 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_INVALID_SID -14
|
|
|
|
/** The specified device's name is unknown to the IOTC servers */
|
|
#define IOTC_ER_UNKNOWN_DEVICE -15
|
|
|
|
/** IOTC module fails to get the local IP address */
|
|
#define IOTC_ER_FAIL_GET_LOCAL_IP -16
|
|
|
|
/** The device already start to listen for connections from clients. It is
|
|
* not necessary to listen again. */
|
|
#define IOTC_ER_LISTEN_ALREADY_CALLED -17
|
|
|
|
/** 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_EXCEED_MAX_SESSION -18
|
|
|
|
/** IOTC servers cannot locate the specified device, probably caused by
|
|
* disconnection from the device or that device does not login yet. */
|
|
#define IOTC_ER_CAN_NOT_FIND_DEVICE -19
|
|
|
|
/** 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_CLOSE_BY_REMOTE -22
|
|
|
|
/** 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_REMOTE_TIMEOUT_DISCONNECT -23
|
|
|
|
/** The client fails to connect to a device because the device is not listening for connections. */
|
|
#define IOTC_ER_DEVICE_NOT_LISTENING -24
|
|
|
|
/** The IOTC channel of specified channel ID is not turned on before transferring data. */
|
|
#define IOTC_ER_CH_NOT_ON -26
|
|
|
|
/** A client stops connecting to a device by calling IOTC_Connect_Stop() */
|
|
#define IOTC_ER_FAIL_CONNECT_SEARCH -27
|
|
|
|
/** Too few masters are specified when initializing IOTC module.
|
|
* Two masters are required for initialization at minimum. */
|
|
#define IOTC_ER_MASTER_TOO_FEW -28
|
|
|
|
/** A client fails to pass certification of a device due to incorrect key. */
|
|
#define IOTC_ER_AES_CERTIFY_FAIL -29
|
|
|
|
/** The number of IOTC channels for a IOTC session has reached maximum, say, #MAX_CHANNEL_NUMBER */
|
|
#define IOTC_ER_SESSION_NO_FREE_CHANNEL -31
|
|
|
|
/** Cannot connect to masters neither UDP mode nor TCP mode by IP or host name ways */
|
|
#define IOTC_ER_TCP_TRAVEL_FAILED -32
|
|
|
|
/** Cannot connect to IOTC servers in TCP */
|
|
#define IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED -33
|
|
|
|
/** A client wants to connect to a device in non-secure mode while that device
|
|
* supports secure mode only. */
|
|
#define IOTC_ER_CLIENT_NOT_SECURE_MODE -34
|
|
|
|
/** A client wants to connect to a device in secure mode while that device does
|
|
* not support secure mode. */
|
|
#define IOTC_ER_CLIENT_SECURE_MODE -35
|
|
|
|
/** A device does not support connection in secure mode */
|
|
#define IOTC_ER_DEVICE_NOT_SECURE_MODE -36
|
|
|
|
/** A device does not support connection in non-secure mode */
|
|
#define IOTC_ER_DEVICE_SECURE_MODE -37
|
|
|
|
/** A device stops listening for connections from clients. */
|
|
#define IOTC_ER_EXIT_LISTEN -39
|
|
|
|
/** The specified device does not support advance function
|
|
*(TCP relay and P2PTunnel module) */
|
|
#define IOTC_ER_NO_PERMISSION -40
|
|
|
|
/** Network is unreachable, please check the network settings */
|
|
#define IOTC_ER_NETWORK_UNREACHABLE -41
|
|
|
|
/** A client fails to connect to a device via relay mode */
|
|
#define IOTC_ER_FAIL_SETUP_RELAY -42
|
|
|
|
/** 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_NOT_SUPPORT_RELAY -43
|
|
|
|
/** 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_NO_SERVER_LIST -44
|
|
|
|
/** The connecting device has duplicated loggin and may unconnectable. */
|
|
#define IOTC_ER_DEVICE_MULTI_LOGIN -45
|
|
|
|
/** The arguments passed to a function is invalid. */
|
|
#define IOTC_ER_INVALID_ARG -46
|
|
|
|
/** The remote device not support partial encoding. */
|
|
#define IOTC_ER_NOT_SUPPORT_PE -47
|
|
|
|
/** The remote device no more free session can be connected. */
|
|
#define IOTC_ER_DEVICE_EXCEED_MAX_SESSION -48
|
|
|
|
|
|
/** The function call is a blocking call and was called by other thread. */
|
|
#define IOTC_ER_BLOCKED_CALL -49
|
|
|
|
/** The session was closed. */
|
|
#define IOTC_ER_SESSION_CLOSED -50
|
|
|
|
/** Remote doesn't support this function. */
|
|
#define IOTC_ER_REMOTE_NOT_SUPPORTED -51
|
|
|
|
/** The function is aborted by related function. */
|
|
#define IOTC_ER_ABORTED -52
|
|
|
|
/** The buffer size exceed maximum packet size. */
|
|
#define IOTC_ER_EXCEED_MAX_PACKET_SIZE -53
|
|
|
|
/** Server does not support this feature. */
|
|
#define IOTC_ER_SERVER_NOT_SUPPORT -54
|
|
|
|
/** Cannot find a path to write data*/
|
|
#define IOTC_ER_NO_PATH_TO_WRITE_DATA -55
|
|
|
|
/** Start function is not called */
|
|
#define IOTC_ER_SERVICE_IS_NOT_STARTED -56
|
|
|
|
/** Already in processing*/
|
|
#define IOTC_ER_STILL_IN_PROCESSING -57
|
|
|
|
/** Out of memory*/
|
|
#define IOTC_ER_NOT_ENOUGH_MEMORY -58
|
|
|
|
/** The device is banned and locked, this error code is no longer being used*/
|
|
#define IOTC_ER_DEVICE_IS_BANNED -59
|
|
|
|
/** IOTC master servers have no response, probably caused by many types of Internet connection issues. */
|
|
#define IOTC_ER_MASTER_NOT_RESPONSE -60
|
|
|
|
/** IOTC module has some resource allocating problem. */
|
|
#define IOTC_ER_RESOURCE_ERROR -61
|
|
|
|
/** IOTC Write reliable send queue is full. */
|
|
#define IOTC_ER_QUEUE_FULL -62
|
|
|
|
/** The feature is not supported. */
|
|
#define IOTC_ER_NOT_SUPPORT -63
|
|
|
|
/** Device is in sleep mode. */
|
|
#define IOTC_ER_DEVICE_IS_SLEEP -64
|
|
|
|
/** Device doesn't support this feature on TCP mode. */
|
|
#define IOTC_ER_TCP_NOT_SUPPORT -65
|
|
|
|
/** IOTC_WakeUp_Init isn't called */
|
|
#define IOTC_ER_WAKEUP_NOT_INITIALIZED -66
|
|
|
|
/** All Server response can not find device */
|
|
#define IOTC_ER_DEVICE_OFFLINE -90
|
|
|
|
/** IOTC master server is invalid */
|
|
#define IOTC_ER_MASTER_INVALID -91
|
|
|
|
/* ============================================================================
|
|
* Enumeration Declaration
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \details 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.
|
|
*/
|
|
typedef enum {
|
|
/// IOTC session will be established in non-secure mode. <br>
|
|
/// - For devices, the behavior is the same as IOTC_Listen(). <br>
|
|
/// - For clients, the behavior is the same as IOTC_Connect_ByUID()
|
|
IOTC_NON_SECURE_MODE = 0,
|
|
|
|
/// IOTC session will be established in secure mode. <br>
|
|
/// - For devices, it means only secure connection will be accepted. <br>
|
|
/// - For clients, it means only secure connection will be performed
|
|
IOTC_SECURE_MODE = 1,
|
|
|
|
/// 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. <br>
|
|
/// - For devices, it means both non-secure or secure modes are accepted. <br>
|
|
/// - For clients, it means either non-secure or secure modes can be performed.
|
|
IOTC_ARBITRARY_MODE = 2
|
|
} IOTCSessionMode;
|
|
|
|
|
|
/**
|
|
* \detials 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.
|
|
*/
|
|
typedef enum {
|
|
IOTC_DEVLOGIN_ST_START = 1 << 0, // start to doing login.
|
|
IOTC_DEVLOGIN_ST_READY_FOR_LAN = 1 << 1, // The device is able to be reached in LAN mode.
|
|
IOTC_DEVLOGIN_ST_LOGINING = 1 << 2, // Still try to login.
|
|
IOTC_DEVLOGIN_ST_LOGINED = 1 << 3, // get the login response from IOTC servers.
|
|
IOTC_DEVLOGIN_ST_RELOGINING = 1 << 4,
|
|
IOTC_DEVLOGIN_ST_MULTI_LOGIN = 1 << 5,
|
|
IOTC_DEVLOGIN_ST_LOGIN_FAILED = -1, //Login failed. check the error code.
|
|
|
|
} IOTCDeviceLoginState;
|
|
|
|
/**
|
|
* \detials 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.
|
|
*/
|
|
typedef enum {
|
|
IOTC_CONNECT_UID_ST_FAILED = -1, // A Client connects to a device failed.
|
|
IOTC_CONNECT_UID_ST_START = 0, // A Client start connecting to a Device.
|
|
IOTC_CONNECT_UID_ST_CONNECTING, // A Client is connecting a device.
|
|
IOTC_CONNECT_UID_ST_CONNECTED // The connection are established between a Client and a Device.
|
|
} IOTCConnectState;
|
|
|
|
typedef enum {
|
|
IOTC_DEV_ST_LOGIN_FAILED = -2, // The device fails to login.
|
|
IOTC_DEV_ST_ERROR = -1, // An error occurs in the device.
|
|
IOTC_DEV_ST_UNINITIALIZED = 0, // The device has not been initialized.
|
|
IOTC_DEV_ST_INITIALIZED, // The device has been initialized.
|
|
IOTC_DEV_ST_LOGINING, // The device is doing login process.
|
|
IOTC_DEV_ST_LOGINED, // The device has logined to a P2P server. Also waiting for a client to connect.
|
|
IOTC_DEV_ST_CONNECTING, // A Client is connecting to the device.
|
|
IOTC_DEV_ST_CONNECTED_WAITING, // One or more clients has been connected to the device.
|
|
// And the device still waits for more clients to connect.
|
|
} IOTCDeviceState;
|
|
|
|
/* ============================================================================
|
|
* Structure Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \details 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.
|
|
*/
|
|
struct st_SInfo {
|
|
unsigned char Mode; //!< 0: P2P mode, 1: Relay mode, 2: LAN mode
|
|
char CorD; //!< 0: As a Client, 1: As a Device
|
|
char UID[21]; //!< The UID of the device
|
|
char RemoteIP[47]; //!< The IP address of remote site used during this IOTC session
|
|
unsigned short RemotePort; //!< The port number of remote site used during this IOTC session
|
|
unsigned int TX_Packetcount; //!< The total packets sent from the device and the client during this IOTC session
|
|
unsigned int RX_Packetcount; //!< The total packets received in the device and the client during this IOTC session
|
|
unsigned int IOTCVersion; //!< The IOTC version
|
|
unsigned short VID; //!< The Vendor ID, part of VPG mechanism
|
|
unsigned short PID; //!< The Product ID, part of VPG mechanism
|
|
unsigned short GID; //!< The Group ID, part of VPG mechanism
|
|
unsigned char NatType; //!< The remote NAT type
|
|
unsigned char isSecure; //!< 0: The IOTC session is in non-secure mode, 1: The IOTC session is in secure mode
|
|
};
|
|
|
|
typedef struct st_SInfo st_SInfo_t;
|
|
|
|
/**
|
|
* \details 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.
|
|
*/
|
|
struct st_SInfoEx {
|
|
unsigned int size; //!< size of the structure
|
|
unsigned char Mode; //!< 0: P2P mode, 1: Relay mode, 2: LAN mode, 255: Not connected.
|
|
char CorD; //!< 0: As a Client, 1: As a Device
|
|
char UID[21]; //!< The UID of the device
|
|
char RemoteIP[47]; //!< The IP address of remote site used during this IOTC session
|
|
unsigned short RemotePort; //!< The port number of remote site used during this IOTC session
|
|
unsigned int TX_Packetcount; //!< The total packets sent from the device and the client during this IOTC session
|
|
unsigned int RX_Packetcount; //!< The total packets received in the device and the client during this IOTC session
|
|
unsigned int IOTCVersion; //!< The IOTC version
|
|
unsigned short VID; //!< The Vendor ID, part of VPG mechanism
|
|
unsigned short PID; //!< The Product ID, part of VPG mechanism
|
|
unsigned short GID; //!< The Group ID, part of VPG mechanism
|
|
unsigned char isSecure; //!< 0: The IOTC session is in non-secure mode, 1: The IOTC session is in secure mode
|
|
unsigned char LocalNatType; //!< The local NAT type, 0: Unknown type, 1: Type 1, 2: Type 2, 3: Type 3, 10: TCP only
|
|
unsigned char RemoteNatType; //!< The remote NAT type, 0: Unknown type, 1: Type 1, 2: Type 2, 3: Type 3, 10: TCP only
|
|
unsigned char RelayType; //!< 0: Not Relay, 1: UDP Relay, 2: TCP Relay
|
|
unsigned int NetState; //!<If no UDP packet is ever received, the first bit of value is 1, otherwise 0
|
|
char RemoteWANIP[47]; //!< The WAN IP address of remote site used during this IOTC session and it is only valid in P2P or Relay mode
|
|
unsigned short RemoteWANPort; //!< The WAN port number of remote site used during this IOTC session and it is only valid in P2P or Relay mode
|
|
};
|
|
|
|
typedef struct st_SInfoEx st_SInfoEx_t;
|
|
|
|
/**
|
|
* \details Device search info, containing all the information
|
|
* when client searches devices in LAN.
|
|
*/
|
|
struct st_LanSearchInfo {
|
|
char UID[21]; //!< The UID of discovered device
|
|
char IP[16]; //!< The IP address of discovered device
|
|
unsigned short port; //!< The port number of discovered device used for IOTC session connection
|
|
char Reserved; //!< Reserved, no use
|
|
};
|
|
|
|
typedef struct st_LanSearchInfo st_LanSearchInfo_t;
|
|
|
|
/**
|
|
* \details Device search info, containing all the information and device name
|
|
* when client searches devices in LAN.
|
|
*/
|
|
struct st_LanSearchInfo2 {
|
|
char UID[21]; //!< The UID of discovered device
|
|
char IP[16]; //!< The IP address of discovered device
|
|
unsigned short port; //!< The port number of discovered device used for IOTC session connection
|
|
char DeviceName[132]; //!< The Name of discovered device
|
|
char Reserved; //!< Reserved, no use
|
|
};
|
|
|
|
typedef struct st_LanSearchInfo2 st_LanSearchInfo2_t;
|
|
|
|
/**
|
|
* \details Device search info, containing all the information and device name
|
|
* when client searches devices in LAN.
|
|
*/
|
|
struct st_SearchDeviceInfo {
|
|
char UID[21]; //!< The UID of discovered device
|
|
char IP[46]; //!< The IP address of discovered device
|
|
unsigned short port; //!< The port number of discovered device used for IOTC session connection
|
|
char DeviceName[132]; //!< The Name of discovered device
|
|
char Reserved; //!< Reserved, no use
|
|
int nNew; //!< New device
|
|
};
|
|
|
|
typedef struct st_SearchDeviceInfo st_SearchDeviceInfo_t;
|
|
|
|
/**
|
|
* \details Connect Option, containing all options of connection setup when client connects to
|
|
* device by P2P or relay mode.
|
|
*/
|
|
struct st_ConnectOption {
|
|
char IsParallel; //!< 0: Turn off parallel connection. 1: Turn on parallel connection.
|
|
char IsLowConnectionBandwidth; //!< 0: Normal connection mode 1: Low bandwidth mode (This mode might reduce the P2P traversal rate)
|
|
char IsP2PRequestRoundRobin; //!< 0: Normal connection mode 1: P2P Request round robin mode (This mode might reduce the P2P traversal rate)
|
|
char IsNotToCheckLanIpforP2P; //!< 0: Check the P2P connected IP if it is change mode to LAN 1: Do not check the P2P connected IP
|
|
};
|
|
|
|
typedef struct st_ConnectOption st_ConnectOption_t;
|
|
|
|
struct st_DeviceStInfo {
|
|
IOTCDeviceState state;
|
|
int connectedSessionNum; // How many clients are connected to the device now.
|
|
// int connectedSessionList[MAX_SESSION_NUMBER]; // The connected session id list.
|
|
int newConnected; // One or more new clients are connected.
|
|
int errCode; // What kind of error happens once the device is in IOTC_DEV_ST_ERROR state.
|
|
};
|
|
|
|
typedef struct st_DeviceStInfo st_DeviceStInfo_t;
|
|
|
|
/* ============================================================================
|
|
* Type Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \details 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.
|
|
*
|
|
* \param 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: once the device can contact with masters and p2p servers, this bit will be set as 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. This bit will be set as 0 if p2p server has not
|
|
* responsed about 75 seconds.
|
|
*
|
|
*/
|
|
typedef void (__stdcall *loginInfoCB)(unsigned int nLoginInfo);
|
|
|
|
|
|
/**
|
|
* \details 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.
|
|
*
|
|
* \param 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.
|
|
* - #IOTC_ER_UNLICENSE The UID is not licensed or expired
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_LOGIN_ALREADY_CALLED The device is already under login process currently
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_NO_PERMISSION The device does not support TCP relay
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the device's local IP address
|
|
* - #IOTC_ER_NETWORK_UNREACHABLE Network is unreachable
|
|
* - #IOTC_ER_RESOURCE_ERROR Getting system resource fail. (i.e. socket, thread etc.)
|
|
* - #IOTC_ER_MASTER_NOT_RESPONSE All masters have no respond
|
|
* - #IOTC_ER_TCP_TRAVEL_FAILED Cannot connect to masters in neither UDP nor TCP
|
|
* - #IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED Cannot connect to IOTC servers in TCP
|
|
*
|
|
* pUserData [out] The user date which is passed from IOTC_Device_Login_NB call.
|
|
*
|
|
*/
|
|
typedef void (*loginStateHandler)(IOTCDeviceLoginState state, int errCode, void *pUserData);
|
|
|
|
|
|
/**
|
|
* \details 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.
|
|
*
|
|
* \param 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.
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_UNLICENSE The specified UID of that device is not licensed or expired
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in client side
|
|
* - #IOTC_ER_DEVICE_NOT_LISTENING The device is not listening for connection now
|
|
* - #IOTC_ER_FAIL_CONNECT_SEARCH The client stop connecting to the device
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_CAN_NOT_FIND_DEVICE IOTC servers cannot locate the specified device
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the client's local IP address
|
|
* - #IOTC_ER_FAIL_SETUP_RELAY Fails to connect the device via relay mode
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_NOT_SUPPORT_RELAY Not support relay connection by IOTC servers
|
|
* - #IOTC_ER_MASTER_NOT_RESPONSE All masters have no respond
|
|
* - #IOTC_ER_TCP_TRAVEL_FAILED Cannot connect to masters in neither UDP nor TCP
|
|
* - #IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED Cannot connect to IOTC servers in TCP
|
|
*
|
|
* pUserData [out] The user date which is passed from IOTC_Connect_ByUIDNB or IOTC_Connect_ByUID_ParallelNB call.
|
|
*
|
|
*/
|
|
typedef void (*connectStateHandler)(IOTCConnectState state, int errCode, void *pUserData);
|
|
|
|
/**
|
|
* \details The prototype of getting session status function, used by a device
|
|
* or client to be notified if session is disconnected.
|
|
*
|
|
* \param nIOTCSessionID [out] The session ID of the session being disconnected
|
|
* \param nErrorCode [out]
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
*
|
|
*/
|
|
typedef void (__stdcall *sessionStatusCB)(int nIOTCSessionID, int nErrorCode);
|
|
|
|
/**
|
|
* \details The prototype of connection mode change function, used by a device
|
|
* or client to be notified if connection mode is changed.
|
|
*
|
|
* \param nIOTCSessionID [out] return effected session ID
|
|
* \param 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(__stdcall *ConnectModeChangeCB)(int nIOTCSessionID, unsigned int nConnMode);
|
|
|
|
/**
|
|
* \details This is the handler for reporting the device on line status. It is used for
|
|
* IOTC_Check_Device_On_Line().
|
|
*
|
|
* \param result [out] The result of getting the device status.
|
|
* - #IOTC_ER_NoERROR No error happens during the checking flow and the Device is on line.
|
|
* - #IOTC_ER_NETWORK_UNREACHABLE Network is unreachable
|
|
* - #IOTC_ER_MASTER_NOT_RESPONSE All masters have no respond
|
|
* - #IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED Cannot connect to IOTC servers in TCP
|
|
* - #IOTC_ER_CAN_NOT_FIND_DEVICE IOTC servers cannot locate the specified device
|
|
* - #IOTC_ER_SERVER_NOT_RESPONSE All servers have no response
|
|
* - #IOTC_ER_TCP_TRAVEL_FAILED Cannot connect to masters in neither UDP nor TCP
|
|
* - #IOTC_ER_DEVICE_OFFLINE The device is not on line.
|
|
*
|
|
* \param userData [in] The data which was passed during IOTC_Check_Device_On_Line() is called.
|
|
*
|
|
*/
|
|
typedef void(__stdcall *onLineResult)(int result, void *userData);
|
|
|
|
/* ============================================================================
|
|
* Function Declaration
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \brief Get the version of IOTC module
|
|
*
|
|
* \details This function returns the version of IOTC module.
|
|
*
|
|
* \param 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 RDT_GetRDTApiVer(), avGetAVApiVer()
|
|
*/
|
|
P2PAPI_API void IOTC_Get_Version(unsigned int *pnVersion);
|
|
|
|
|
|
/**
|
|
* \brief Set the max number of IOTC sessions of IOTC module
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param 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.<br><br>
|
|
* (2) The maximum IOTC session number is platform dependent.
|
|
* See the definition of MAX_DEFAULT_IOTC_SESSION_NUMBER for each
|
|
* platform.
|
|
*/
|
|
P2PAPI_API void IOTC_Set_Max_Session_Number(unsigned int nMaxSessionNum);
|
|
|
|
|
|
/**
|
|
* \brief Initialize IOTC module
|
|
*
|
|
* \details **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().
|
|
*
|
|
* \param nUDPPort [in] Specify a UDP port. Random UDP port is used if it is specified as 0.
|
|
* \param cszP2PHostNamePrimary [in] Specify the host name or IP address of
|
|
* the primary master. Cannot be NULL. See attention below for more detail.
|
|
* \param cszP2PHostNameSecondary [in] Specify the host name or IP address of
|
|
* the secondary master. Cannot be NULL. See attention below for more detail.
|
|
* \param 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.
|
|
* \param 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.
|
|
*
|
|
* \return #IOTC_ER_NoERROR if initializing successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_ALREADY_INITIALIZED IOTC module is already initialized
|
|
* - #IOTC_ER_MASTER_TOO_FEW Two masters are required as parameters at minimum
|
|
* - #IOTC_ER_FAIL_CREATE_MUTEX Fails to create Mutexs
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_NOT_ENOUGH_MEMORY not enough memory
|
|
*
|
|
* \see 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(). <br><br>
|
|
* (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
|
|
*/
|
|
P2PAPI_API int IOTC_Initialize(unsigned short nUDPPort, const char *cszP2PHostNamePrimary,
|
|
const char *cszP2PHostNameSecondary, const char *cszP2PHostNameThird,
|
|
const char *cszP2PHostNameFourth);
|
|
|
|
|
|
/**
|
|
* \brief Initialize IOTC module
|
|
*
|
|
* \details 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().
|
|
* <br>
|
|
* 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.
|
|
*
|
|
* \param nUDPPort [in] Specify a UDP port. Random UDP port is used if it is specified as 0.
|
|
*
|
|
* \return #IOTC_ER_NoERROR if initializing successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_ALREADY_INITIALIZED IOTC module is already initialized
|
|
* - #IOTC_ER_FAIL_CREATE_MUTEX Fails to create Mutexes
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_NOT_ENOUGH_MEMORY not enough memory
|
|
*
|
|
* \see 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().
|
|
*/
|
|
P2PAPI_API int IOTC_Initialize2(unsigned short nUDPPort);
|
|
|
|
|
|
/**
|
|
* \brief Deinitialize IOTC module
|
|
*
|
|
* \details This function will deinitialize IOTC module.
|
|
*
|
|
* \return #IOTC_ER_NoERROR if deinitialize successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED the IOTC module is not initialized yet.
|
|
*
|
|
* \see 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.
|
|
*/
|
|
P2PAPI_API int IOTC_DeInitialize(void);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device to login to IOTC servers
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param cszUID [in] The UID of that device login to IOTC servers
|
|
* \param cszDeviceName [in] The name of that device, used in LAN mode for clients
|
|
* to connect
|
|
* \param cszDevicePWD [in] This parameter is no longer used
|
|
*
|
|
* \return #IOTC_ER_NoERROR if device had obtained server list and sent login packets successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_UNLICENSE The UID is not licensed or expired
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_LOGIN_ALREADY_CALLED The device is already under login process currently
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_TCP_TRAVEL_FAILED Cannot connect to masters in neither UDP nor TCP
|
|
* - #IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED Cannot connect to IOTC servers in TCP
|
|
* - #IOTC_ER_NO_PERMISSION The device does not support TCP relay
|
|
* - #IOTC_ER_SERVER_NOT_RESPONSE All servers have no response
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the device's local IP address
|
|
* - #IOTC_ER_NETWORK_UNREACHABLE Network is unreachable
|
|
* - #IOTC_ER_NO_SERVER_LIST No IOTC server information while device login
|
|
* - #IOTC_ER_MASTER_NOT_RESPONSE All masters have no respond
|
|
*
|
|
* \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. <br><br>
|
|
* (2) Please use IOTC_Get_Login_Info() to check if device really logins
|
|
* into server successfully.
|
|
*/
|
|
P2PAPI_API int IOTC_Device_Login(const char *cszUID, const char *cszDeviceName, const char *cszDevicePWD);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device to login to IOTC servers
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param cszUID [in] The UID of that device login to IOTC servers
|
|
* \param cszDeviceName [in] The name of that device, used in LAN mode for clients
|
|
* to connect
|
|
* \param cszDevicePWD [in] The password of that device, used in LAN mode for
|
|
* clients to connect
|
|
* \param hadler [in] The login state handler which will be called once the login
|
|
* state is changed.
|
|
* \param userData [in] The user data which will be brought to the handler.
|
|
*
|
|
* \return #IOTC_ER_NoERROR if device had obtained server list and sent login packets successfully
|
|
* - #IOTC_ER_UNLICENSE The UID is not licensed or expired
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_LOGIN_ALREADY_CALLED The device is already under login process currently
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_NO_PERMISSION The device does not support TCP relay
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the device's local IP address
|
|
* - #IOTC_ER_NETWORK_UNREACHABLE Network is unreachable
|
|
* - #IOTC_ER_RESOURCE_ERROR Getting system resource fail. (i.e. socket, thread etc.)
|
|
*/
|
|
P2PAPI_API int IOTC_Device_LoginNB(const char *cszUID, const char *cszDeviceName, const char *cszDevicePWD,
|
|
loginStateHandler handler, void *userData);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device to get the login information
|
|
*
|
|
* \details This function gets the login information of a device to IOTC servers.
|
|
*
|
|
* \param 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.
|
|
*
|
|
* \return The number of fails to login to IOTC servers.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Get_Login_Info(unsigned int *pnLoginInfo);
|
|
|
|
|
|
/**
|
|
* \brief Checking a device on line or not.
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param UID [in] A device UID which is used to check the state.
|
|
* \param timeOut [in] The time out value of checking device information in millisecond.
|
|
* \param handler [in] A handle function for getting the device on line result.
|
|
* \param userData [in] The data would like to bring to the handler for feather processing.
|
|
*
|
|
*
|
|
* \return IOTC_ER_NoERROR on successful. The others are error.
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - IOTC_ER_UNLICENSE The UID is not a valid UID.
|
|
* - IOTC_ER_EXCEED_MAX_SESSION The session is full.
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - IOTC_ER_NOT_ENOUGH_MEMORY No enough memory to run the function.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Check_Device_On_Line(const char *UID, const unsigned int timeOut,
|
|
onLineResult handler, void *userData);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device to get the login information
|
|
*
|
|
* \details This function gets the login information of a device to IOTC servers. <br>
|
|
* 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.
|
|
*
|
|
* \param pfxLoginInfoFn [in] The function pointer to getting login info function
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Get_Login_Info_ByCallBackFn(loginInfoCB pfxLoginInfoFn);
|
|
|
|
|
|
/**
|
|
* \brief This function is used for getting device status information.
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param pDevStInfo [out] A pointer that points to a memory which the device
|
|
* information is saved to.
|
|
*
|
|
* \return IOTC_ER_NoERROR on success. Otherwise it fails.
|
|
*/
|
|
|
|
P2PAPI_API int IOTC_Get_Device_Status(struct st_DeviceStInfo *pDevStInfo);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device to listen connections from clients
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param nTimeout [in] The timeout for this function in unit of millisecond, give 0 means block forever
|
|
*
|
|
* \return IOTC session ID if return value >= 0
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in device side
|
|
* - #IOTC_ER_LISTEN_ALREADY_CALLED The device is already in listen process
|
|
* - #IOTC_ER_TIMEOUT No connection is established from clients before timeout expires
|
|
* - #IOTC_ER_EXIT_LISTEN The device stops listening for connections from clients.
|
|
*
|
|
* \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.<br><br>
|
|
* (2) nTimeout has no effect in 8051 platform.
|
|
*/
|
|
P2PAPI_API int IOTC_Listen(unsigned int nTimeout);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device to exit listen process
|
|
*
|
|
* \details 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.
|
|
*/
|
|
P2PAPI_API void IOTC_Listen_Exit(void);
|
|
|
|
|
|
/**
|
|
* \brief To get a new connected session id.
|
|
*
|
|
* \detials 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.
|
|
*
|
|
* \param SID [out] The session id for the new connection.
|
|
*
|
|
* \return IOTC_ER_NoERROR on success.
|
|
* \return 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.
|
|
*/
|
|
|
|
P2PAPI_API int IOTC_Accept(int *SID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to connect a device
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param cszUID [in] The UID of a device that client wants to connect
|
|
*
|
|
* \return IOTC session ID if return value >= 0
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_UNLICENSE The specified UID of that device is not licensed or expired
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in client side
|
|
* - #IOTC_ER_DEVICE_NOT_LISTENING The device is not listening for connection now
|
|
* - #IOTC_ER_FAIL_CONNECT_SEARCH The client stop connecting to the device
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_TCP_TRAVEL_FAILED Cannot connect to masters in neither UDP nor TCP
|
|
* - #IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED Cannot connect to IOTC servers in TCP
|
|
* - #IOTC_ER_CAN_NOT_FIND_DEVICE IOTC servers cannot locate the specified device
|
|
* - #IOTC_ER_NO_PERMISSION The specified device does not support TCP relay
|
|
* - #IOTC_ER_SERVER_NOT_RESPONSE IOTC servers have no response
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the client's local IP address
|
|
* - #IOTC_ER_FAIL_SETUP_RELAY Fails to connect the device via relay mode
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - #IOTC_ER_NOT_SUPPORT_RELAY Not support relay connection by IOTC servers
|
|
* - #IOTC_ER_NO_SERVER_LIST No IOTC server information while client connect
|
|
* - #IOTC_ER_DEVICE_MULTI_LOGIN The connecting device duplicated loggin and may unconnectable
|
|
* - #IOTC_ER_MASTER_NOT_RESPONSE All masters have no respond
|
|
* - #IOTC_ER_DEVICE_IS_SLEEP Device is in sleep mode
|
|
*
|
|
* \attention This process is a block process.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Connect_ByUID(const char *cszUID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to connect a device. Non-Blocking.
|
|
*
|
|
* \details 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.
|
|
*
|
|
*
|
|
* \param cszUID [in] The UID of a device that client wants to connect
|
|
* \param handler [in] The state handler. This handler will be called once
|
|
* the connecting state (IOTCConnectState) is changed.
|
|
* \param userData [in] The user data which will be brought to the handler.
|
|
*
|
|
* \return IOTC session ID if return value >= 0
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_UNLICENSE The specified UID of that device is not licensed or expired
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in client side
|
|
* - #IOTC_ER_DEVICE_NOT_LISTENING The device is not listening for connection now
|
|
* - #IOTC_ER_FAIL_CONNECT_SEARCH The client stop connecting to the device
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_CAN_NOT_FIND_DEVICE IOTC servers cannot locate the specified device
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the client's local IP address
|
|
* - #IOTC_ER_FAIL_SETUP_RELAY Fails to connect the device via relay mode
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - #IOTC_ER_NOT_SUPPORT_RELAY Not support relay connection by IOTC servers
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Connect_ByUIDNB(const char *cszUID,
|
|
connectStateHandler handler,
|
|
void *userData);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to get a tutk_platform_free session ID.
|
|
*
|
|
* \details This function is for a client to get a tutk_platform_free session ID used for a parameter of
|
|
* IOTC_Connect_ByUID_Parallel().
|
|
*
|
|
* \return IOTC session ID if return value >= 0
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in client side
|
|
*
|
|
* \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.<br><br>
|
|
* (2) If you already get a session ID via this function and want to close it please use IOTC_Session_Close().
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Get_SessionID(void);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to connect a device and bind to a specified session ID.
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param cszUID [in] The UID of a device that client wants to connect
|
|
* \param SID [in] The Session ID got from IOTC_Get_SessionID() the connection should bind to.
|
|
*
|
|
* \return IOTC session ID if return value >= 0 and equal to the input parameter SID.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_UNLICENSE The specified UID of that device is not licensed or expired
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in client side
|
|
* - #IOTC_ER_DEVICE_NOT_LISTENING The device is not listening for connection now
|
|
* - #IOTC_ER_FAIL_CONNECT_SEARCH The client stop connecting to the device
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_TCP_TRAVEL_FAILED Cannot connect to masters in neither UDP nor TCP
|
|
* - #IOTC_ER_TCP_CONNECT_TO_SERVER_FAILED Cannot connect to IOTC servers in TCP
|
|
* - #IOTC_ER_CAN_NOT_FIND_DEVICE IOTC servers cannot locate the specified device
|
|
* - #IOTC_ER_NO_PERMISSION The specified device does not support TCP relay
|
|
* - #IOTC_ER_SERVER_NOT_RESPONSE IOTC servers have no response
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the client's local IP address
|
|
* - #IOTC_ER_FAIL_SETUP_RELAY Fails to connect the device via relay mode
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - #IOTC_ER_NOT_SUPPORT_RELAY Not support relay connection by IOTC servers
|
|
* - #IOTC_ER_NO_SERVER_LIST No IOTC server information while client connect
|
|
* - #IOTC_ER_DEVICE_MULTI_LOGIN The connecting device duplicated login and may unconnectable
|
|
* - #IOTC_ER_MASTER_NOT_RESPONSE All masters have no respond
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_DEVICE_IS_SLEEP Device is in sleep mode
|
|
*
|
|
* \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.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Connect_ByUID_Parallel(const char *cszUID, int SID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to connect a device and bind to a specified session ID. Non-Blocking
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param cszUID [in] The UID of a device that client wants to connect
|
|
* \param SID [in] The Session ID got from IOTC_Get_SessionID() the connection should bind to.
|
|
* \param handler [in] The state handler. This handler will be called once
|
|
* the connecting state (IOTCConnectState) is changed.
|
|
* \param userData [in] The user data which will be brought to the handler.
|
|
*
|
|
* \return IOTC session ID if return value >= 0 and equal to the input parameter SID.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_UNLICENSE The specified UID of that device is not licensed or expired
|
|
* - #IOTC_ER_EXCEED_MAX_SESSION The number of IOTC sessions has reached maximum in client side
|
|
* - #IOTC_ER_DEVICE_NOT_LISTENING The device is not listening for connection now
|
|
* - #IOTC_ER_FAIL_CONNECT_SEARCH The client stop connecting to the device
|
|
* - #IOTC_ER_FAIL_RESOLVE_HOSTNAME Cannot resolve masters' host name
|
|
* - #IOTC_ER_FAIL_CREATE_THREAD Fails to create threads
|
|
* - #IOTC_ER_CAN_NOT_FIND_DEVICE IOTC servers cannot locate the specified device
|
|
* - #IOTC_ER_NO_PERMISSION The specified device does not support TCP relay
|
|
* - #IOTC_ER_FAIL_GET_LOCAL_IP Fails to get the client's local IP address
|
|
* - #IOTC_ER_FAIL_SETUP_RELAY Fails to connect the device via relay mode
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - #IOTC_ER_NOT_SUPPORT_RELAY Not support relay connection by IOTC servers
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
*
|
|
* \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.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Connect_ByUID_ParallelNB(const char *cszUID, int SID,
|
|
connectStateHandler handler,
|
|
void *userData);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to stop connecting a device
|
|
*
|
|
* \details 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().
|
|
*/
|
|
P2PAPI_API void IOTC_Connect_Stop(void);
|
|
|
|
|
|
/**
|
|
* \brief Used by a client to stop a specific session connecting a device
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param SID [in] The Session ID of a connection which will be stop.
|
|
*
|
|
* \return #IOTC_ER_NoERROR
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
*/
|
|
P2PAPI_API int IOTC_Connect_Stop_BySID(int SID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to read data from the other
|
|
*
|
|
* \details A device or a client uses this function to read data through
|
|
* a specific IOTC channel in a IOTC session. <br>
|
|
* 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.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to read data
|
|
* \param abBuf [out] The array of byte buffer to receive read result
|
|
* \param nMaxBufSize [in] The maximum length of the byte buffer
|
|
* \param nTimeout [in] The timeout for this function in unit of millisecond, give 0 means return immediately
|
|
* \param pnPacketSN [out] The serial number of the packet that is read successfully
|
|
* this time. Could be NULL.
|
|
* \param pbFlagLost [out] A boolean value to indicate if there are some packets
|
|
* lost between this time and previous successful read.
|
|
* Could be NULL.
|
|
* \param nIOTCChannelID [in] The IOTC channel ID in this IOTC session to read data
|
|
*
|
|
* \return The actual length of read result stored in abBuf if read successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_CH_NOT_ON The IOTC channel of specified channel ID is not turned on
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_TIMEOUT The timeout specified by nTimeout expires before
|
|
* read process is performed completely
|
|
*
|
|
* \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.
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Read_Check_Lost(int nIOTCSessionID, char *abBuf, int nMaxBufSize, unsigned int nTimeout, unsigned short *pnPacketSN, char *pbFlagLost, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to check the IOTC session info
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to be checked
|
|
* \param psSessionInfo [out] The session info of specified IOTC session
|
|
*
|
|
* \return #IOTC_ER_NoERROR if getting the IOTC session info successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid.
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Check(int nIOTCSessionID, struct st_SInfo *psSessionInfo);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to check the IOTC session info
|
|
*
|
|
* \details 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);"
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to be checked
|
|
* \param psSessionInfo [out] The session info of specified IOTC session
|
|
*
|
|
* \return #IOTC_ER_NoERROR if getting the IOTC session info successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_INVALID_ARG The size of structure is not filled
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Check_Ex(int nIOTCSessionID, struct st_SInfoEx *psSessionInfo);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to get the session status
|
|
*
|
|
* \details This function gets the session status between device and client. <br>
|
|
* 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.
|
|
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to check status
|
|
* \param pfxSessionStatusFn [in] The function pointer to getting session status function
|
|
*
|
|
* \return #IOTC_ER_NoERROR if getting the IOTC session info successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Check_ByCallBackFn(int nIOTCSessionID, sessionStatusCB pfxSessionStatusFn);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to read data from the other
|
|
*
|
|
* \details A device or a client uses this function to read data through
|
|
* a specific IOTC channel in a IOTC session.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to read data
|
|
* \param abBuf [out] The array of byte buffer to receive read result
|
|
* \param nMaxBufSize [in] The maximum length of the byte buffer
|
|
* \param nTimeout [in] The timeout for this function in unit of millisecond, give 0 means return immediately
|
|
* \param nIOTCChannelID [in] The IOTC channel ID in this IOTC session to read data
|
|
*
|
|
* \return The actual length of read result stored in abBuf if read successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_CH_NOT_ON The IOTC channel of specified channel ID is not turned on
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_TIMEOUT The timeout specified by nTimeout expires before
|
|
* read process is performed completely
|
|
*
|
|
* \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.<br><br>
|
|
* (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.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Read(int nIOTCSessionID, char *abBuf, int nMaxBufSize, unsigned int nTimeout, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to write data to the other
|
|
*
|
|
* \details A device or a client uses this function to write data through
|
|
* a specific IOTC channel in a IOTC session.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to write data
|
|
* \param cabBuf [in] The array of byte buffer containing the data to write.
|
|
* Its size cannot be larger than #IOTC_MAX_PACKET_SIZE
|
|
* \param nBufSize [in] The length of the byte buffer. It cannot be larger than
|
|
* #IOTC_MAX_PACKET_SIZE
|
|
* \param nIOTCChannelID [in] The IOTC channel ID in this IOTC session to write data
|
|
*
|
|
* \return 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.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_CH_NOT_ON The IOTC channel of specified channel ID is not turned on
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_INVALID_ARG The buffer size is not accepted
|
|
* - #IOTC_ER_NO_PATH_TO_WRITE_DATA IOTC internal error, cannot find a path to send data
|
|
*
|
|
* \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. <br><br>
|
|
* (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.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Write(int nIOTCSessionID, const char *cabBuf, int nBufSize, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to close a IOTC session
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to be closed
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Session_Close(int nIOTCSessionID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to get a tutk_platform_free IOTC channel
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to get tutk_platform_free IOTC channel
|
|
*
|
|
* \return The IOTC channel ID of a tutk_platform_free IOTC channel if successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_SESSION_NO_FREE_CHANNEL Already reach the maximum
|
|
* number of IOTC channels, no more tutk_platform_free IOTC channel is available
|
|
*
|
|
* \attention (1) The IOTC channel returned by this function is already turned on.<br><br>
|
|
* (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.
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Get_Free_Channel(int nIOTCSessionID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to turn on a IOTC channel
|
|
*
|
|
* \details A device or a client uses this function to turn on a IOTC channel
|
|
* before sending or receiving data through this IOTC channel.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session containing the
|
|
* IOTC channel to be turned on
|
|
* \param nIOTCChannelID [in] The channel ID of the IOTC channel to be turned on
|
|
*
|
|
* \return IOTC_ER_NoERROR if turning on the IOTC channel successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_CH_NOT_ON The specified IOTC channel ID is not valid
|
|
*
|
|
* \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 int IOTC_Session_Channel_ON(int nIOTCSessionID, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to turn off a IOTC channel
|
|
*
|
|
* \details A device or a client uses this function to turn off a IOTC channel
|
|
* when this IOTC channel is no longer needed for communication.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session containing the
|
|
* IOTC channel to be turned off
|
|
* \param nIOTCChannelID [in] The channel ID of the IOTC channel to be turned off
|
|
*
|
|
* \return IOTC_ER_NoERROR if turning off the IOTC channel successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_CH_NOT_ON The specified IOTC channel ID is not valid
|
|
*
|
|
* \attention (1) IOTC Channel 0 cannot be turned off because it is a default channel.<br><br>
|
|
* (2) Turn off a IOTC channel will also make the data remaining
|
|
* in receiving queue of this channel be deleted.
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Channel_OFF(int nIOTCSessionID, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to check whether the IOTC channel is ON or OFF
|
|
*
|
|
* \details A device or a client uses this function to turn on a IOTC channel
|
|
* before sending or receiving data through this IOTC channel.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session containing the
|
|
* IOTC channel to be checked
|
|
* \param nIOTCChannelID [in] The channel ID of the IOTC channel to be checked
|
|
*
|
|
* \return 1 for channel ON return 0 for channel OFF
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_INVALID_ARG The specified IOTC channel ID is not valid
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Channel_Check_ON_OFF(int nIOTCSessionID, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by search devices in LAN.
|
|
*
|
|
* \details When clients and devices are stay in a LAN environment, client can call this function
|
|
* to discovery devices and connect it directly.
|
|
*
|
|
* \param psLanSearchInfo [in] The array of struct st_LanSearchInfo to store search result
|
|
*
|
|
* \param nArrayLen [in] The size of the psLanSearchInfo array
|
|
*
|
|
* \param nWaitTimeMs [in] The timeout in milliseconds before discovery process end.
|
|
*
|
|
* \return The number of devices found.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid.
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
*
|
|
* \attention (1) Not support IPv6. The IP length is only for IPv4.<br><br>*
|
|
* (2) This API is deprecated. Please use IOTC_Search_Device_Start / IOTC_Search_Device_Result.<br><br>*
|
|
*/
|
|
P2PAPI_API int IOTC_Lan_Search(struct st_LanSearchInfo *psLanSearchInfo, int nArrayLen, int nWaitTimeMs);
|
|
|
|
|
|
/**
|
|
* \brief Set path of log file
|
|
*
|
|
* \details Set the absolute path of log file
|
|
*
|
|
* \param path [in] The path of log file, NULL = disable Log
|
|
*
|
|
* \param nMaxSize [in] The maximum size of log file in Bytes, 0 = unlimited
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Set_Log_Path(char *path, int nMaxSize);
|
|
|
|
|
|
/**
|
|
* \brief Set partial encode On/Off
|
|
*
|
|
* \details Set partial encode On/Off
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to be encrypted.
|
|
*
|
|
* \param bPartialEncryption [in] 1: Enable partial encode, 0: Disable partial encode
|
|
*
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_REMOTE_TIMEOUT_DISCONNECT The timeout defined by #IOTC_SESSION_ALIVE_TIMEOUT
|
|
* expires because remote site has no response
|
|
* - #IOTC_ER_NOT_SUPPORT_PE The remote device don't support partial encryption
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Set_Partial_Encryption(int nIOTCSessionID, unsigned char bPartialEncryption);
|
|
|
|
|
|
/**
|
|
* \brief Set device name.
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param cszDeviceName [in] This is user-defined device name. Clients will get it by calling IOTC_Lan_Search2().
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Set_Device_Name(const char *cszDeviceName);
|
|
|
|
|
|
/**
|
|
* \brief Used for searching devices in LAN.
|
|
*
|
|
* \details When client and devices are in LAN, client can search devices and their name
|
|
* by calling this function.
|
|
*
|
|
* \param psLanSearchInfo2 [in] The array of struct st_LanSearchInfo2 store the search result and Device name.
|
|
*
|
|
* \param nArrayLen [in] The size of psLanSearchInfo2 array
|
|
*
|
|
* \param nWaitTimeMs [in] Period (or timeout) of searching LAN. (milliseconds)
|
|
*
|
|
* \return The number of devices found.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid.
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
*
|
|
* \attention (1) Not support IPv6. The IP length is only for IPv4.<br><br>*
|
|
* (2) This API is deprecated. Please use IOTC_Search_Device_Start / IOTC_Search_Device_Result.<br><br>*
|
|
*/
|
|
P2PAPI_API int IOTC_Lan_Search2(struct st_LanSearchInfo2 *psLanSearchInfo2, int nArrayLen, int nWaitTimeMs);
|
|
|
|
|
|
/**
|
|
* \brief Used for searching devices in LAN.
|
|
*
|
|
* \details When client and devices are in LAN, client can search devices and their name
|
|
* by calling this function.
|
|
*
|
|
* \param psLanSearchInfo2 [in] The array of struct st_LanSearchInfo2 store the search result and Device name.
|
|
* \param nArrayLen [in] The size of psLanSearchInfo2 array
|
|
* \param nWaitTimeMs [in] Period (or timeout) of searching LAN. (milliseconds)
|
|
* \param nSendIntervalMs [in] Interval of sending broadcast for searching device in LAN. (milliseconds)
|
|
*
|
|
* \return The number of devices found.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid.
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
*
|
|
* \attention (1) Not support IPv6. The IP length is only for IPv4.<br><br>*
|
|
* (2) This API is deprecated. Please use IOTC_Search_Device_Start / IOTC_Search_Device_Result.<br><br>*
|
|
*/
|
|
P2PAPI_API int IOTC_Lan_Search2_Ex(struct st_LanSearchInfo2 *psLanSearchInfo2, int nArrayLen, int nWaitTimeMs, int nSendIntervalMs);
|
|
|
|
|
|
/**
|
|
* \brief Start to search devices in LAN.
|
|
*
|
|
* \details 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
|
|
*
|
|
* \param nWaitTimeMs [in] Period (or timeout) of searching LAN. (milliseconds)
|
|
* \param nSendIntervalMs [in] Interval of sending broadcast for searching device in LAN. (milliseconds)
|
|
*
|
|
* \return The number of devices found in the LAN (it is limited by the length of array)
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid.
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
* - #IOTC_ER_STILL_IN_PROCESSING The function is called more then once before it stopped
|
|
* - #IOTC_ER_NOT_ENOUGH_MEMORY not enough memory
|
|
*/
|
|
P2PAPI_API int IOTC_Search_Device_Start(int nWaitTimeMs, int nSendIntervalMs);
|
|
|
|
|
|
/**
|
|
* \brief Poll the results of searched device in LAN.
|
|
*
|
|
* \details Use the function to poll the result of device search in LAN, the IOTC_Search_Device_Start should be called
|
|
* before use the function
|
|
*
|
|
* \param st_SearchDeviceInfo [in] The array of struct st_SearchDeviceInfo store the search result and Device name.
|
|
* \param nArrayLen [in] The length of array
|
|
* \param nGetAll [in] 0: get new queried device 1: get all queried devices
|
|
*
|
|
* \return IOTC_ER_NoERROR if search devices in LAN successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid.
|
|
* - #IOTC_ER_SERVICE_IS_NOT_STARTED The start function is not called
|
|
*
|
|
* \attention (1) Support IPv6. The IP length supports both for IPv4/IPv6.<br><br>*
|
|
*/
|
|
P2PAPI_API int IOTC_Search_Device_Result(struct st_SearchDeviceInfo *psSearchDeviceInfo, int nArrayLen, int nGetAll);
|
|
|
|
|
|
/**
|
|
* \brief Stop to search devices in LAN.
|
|
*
|
|
* \details Stop to do device search in LAN, the IOTC_Search_Device_Start should be called
|
|
* before use the function
|
|
*
|
|
* \param st_SearchDeviceInfo [in] The array of struct st_SearchDeviceInfo store the search result and Device name.
|
|
* \param nArrayLen [in] The length of array
|
|
* \param nGetAll [in] 0: get new queried device 1: get all queried devices
|
|
*
|
|
* \return IOTC_ER_NoERROR if search devices in LAN successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_SERVICE_IS_NOT_STARTED The start function is not called
|
|
*/
|
|
P2PAPI_API int IOTC_Search_Device_Stop();
|
|
|
|
|
|
/**
|
|
* \brief Turn on only TCP relay mode function.
|
|
*
|
|
* \details 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.
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_TCPRelayOnly_TurnOn(void);
|
|
|
|
|
|
/**
|
|
* \brief Setup LAN search and LAN connection timeout
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param 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.
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Setup_LANConnection_Timeout(unsigned int nTimeout);
|
|
|
|
|
|
/**
|
|
* \brief Setup P2P connection timeout
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param 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.
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Setup_P2PConnection_Timeout(unsigned int nTimeout);
|
|
|
|
/**
|
|
* \brief ReInitialize IOTC module socket
|
|
*
|
|
* \details This function will reopen P2P UDP socket of IOTC module.
|
|
* It is useful for iOS APP from backgroud to foreground will cause socket failed.
|
|
*
|
|
* \param nUDPPort [in] Specify a UDP port. Random UDP port is used if it is specified as 0.
|
|
*
|
|
* \return #IOTC_ER_NoERROR if initializing successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_FAIL_CREATE_SOCKET Fails to create sockets
|
|
* - #IOTC_ER_FAIL_SOCKET_OPT Fails to set up socket options
|
|
* - #IOTC_ER_FAIL_SOCKET_BIND Fails to bind sockets
|
|
*
|
|
*
|
|
* \attention Must call it before any connection process.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_ReInitSocket(unsigned short nUDPPort);
|
|
|
|
/**
|
|
* \brief Setup detect network reachable timeout
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param nTimeout [in] The timeout for this function in unit of millisecond
|
|
*
|
|
* \attention Mast be called before start login or connection.
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Setup_DetectNetwork_Timeout(unsigned int nTimeout);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to write data to the other in reliable way
|
|
*
|
|
* \details A device or a client uses this function to write data through
|
|
* a specific IOTC channel in a IOTC session in a reliable way.
|
|
*
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to write data
|
|
* \param cabBuf [in] The array of byte buffer containing the data to write.
|
|
* Its size cannot be larger than #RELIABLE_MAX_PACKET_SIZE
|
|
* \param nBufSize [in] The length of the byte buffer. It cannot be larger than
|
|
* #RELIABLE_MAX_PACKET_SIZE
|
|
* \param nIOTCChannelID [in] The IOTC channel ID in this IOTC session to write data
|
|
*
|
|
* \return Return 0 if send successfully.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid. OR the session has been closed.
|
|
* - #IOTC_ER_CH_NOT_ON The IOTC channel of specified channel ID is not turned on
|
|
* - #IOTC_ER_SESSION_CLOSE_BY_REMOTE The IOTC session of specified
|
|
* session ID has been closed by remote site
|
|
* - #IOTC_ER_EXCEED_MAX_PACKET_SIZE The packet size is larger than RELIABLE_MAX_PACKET_SIZE
|
|
* - #IOTC_ER_ABORTED Was aborted by IOTC_Session_Write_Reliable_Abort().
|
|
* - #IOTC_ER_SERVER_NOT_SUPPORT Server does not support this feature.
|
|
* - #IOTC_ER_QUEUE_FULL The send queue is full.
|
|
*
|
|
* \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. <br><br>
|
|
*
|
|
* \attention (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.
|
|
*
|
|
*/
|
|
P2PAPI_API int IOTC_Session_Write_Reliable_NB(int nIOTCSessionID, const char *cabBuf, int nBufSize, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to abort specific IOTC_Session_Write_Reliable_NB() immediately.
|
|
*
|
|
* \details 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.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to write data
|
|
* \param nIOTCChannelID [in] The IOTC channel ID in this IOTC session to write data
|
|
*
|
|
* \return Return 0 if IOTC_Session_Write_Reliable_Abort() call successfully.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_CH_NOT_ON The IOTC channel of specified channel ID is not turned on
|
|
* \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. <br><br>
|
|
*
|
|
**/
|
|
P2PAPI_API int IOTC_Session_Write_Reliable_NB_Abort(int nIOTCSessionID, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Used by a device or a client to check if all the message are sent out
|
|
* from the reliable send queue.
|
|
*
|
|
* \details A device or a client uses this function to verify wether or not
|
|
* all the message are sent out succefully.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to check the data
|
|
* \param nIOTCChannelID [in] The IOTC channel ID in this IOTC session to check the data
|
|
*
|
|
* \return 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.
|
|
*
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_INVALID_SID The specified IOTC session ID is not valid
|
|
* - #IOTC_ER_CH_NOT_ON The IOTC channel of specified channel ID is not turned on
|
|
**/
|
|
P2PAPI_API int IOTC_Reliable_All_MSG_Is_Sent(int nIOTCSessionID, unsigned char nIOTCChannelID);
|
|
|
|
|
|
/**
|
|
* \brief Setup session alive timeout value
|
|
*
|
|
* \details 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
|
|
*
|
|
* \param 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.
|
|
*
|
|
*/
|
|
P2PAPI_API void IOTC_Setup_Session_Alive_Timeout(unsigned int nTimeout);
|
|
|
|
|
|
/**
|
|
* \brief Setup connect option when client connects to device.
|
|
*
|
|
* \details Client uses this function to set the Option of Connection.
|
|
*
|
|
* \param nIOTCSessionID [in] The session ID of the IOTC session to be checked.
|
|
* \param S_ConnectOption [in] the connect option that contained the option to be set.
|
|
**/
|
|
P2PAPI_API int IOTC_Set_Connection_Option(struct st_ConnectOption *S_ConnectOption);
|
|
|
|
|
|
/**
|
|
* \brief Switch of Uploading Error code to Server.
|
|
*
|
|
* \details Use this function to enable or disable error code uploading.
|
|
* The default setup is disable.
|
|
*
|
|
* \param nEnable [in] Set nEnable to 0 to disable error code uploading.
|
|
* Set nEnable to 1 to enable error code uploading.
|
|
**/
|
|
P2PAPI_API void IOTC_Setup_ErrorUpload(int nEnable);
|
|
|
|
|
|
/**
|
|
* \brief Register IOTC connection mode change callback.
|
|
*
|
|
* \details Callback will be triggered when connection mode is changed.
|
|
*
|
|
* \param fpCallback [in] function pointer of callback.
|
|
*
|
|
**/
|
|
P2PAPI_API void IOTC_ConnModeChange_CallBack(ConnectModeChangeCB fpCallback);
|
|
|
|
|
|
/**
|
|
* \brief Change default LAN search port
|
|
*
|
|
* \details 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
|
|
*
|
|
* \param nPort [in] Pass the customized LAN search port
|
|
*
|
|
* \attention The IOTC_Set_LanSearchPort must be called before IOTC_Initialize or IOTC_Initialize2
|
|
*
|
|
* \return Return IOTC_ER_NoERROR if successfully.
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_INVALID_ARG The arguments passed in to this function is invalid or port number > 65535.
|
|
**/
|
|
P2PAPI_API int IOTC_Set_LanSearchPort(unsigned int nPort);
|
|
|
|
|
|
/**
|
|
* \brief Add Customize Master server
|
|
*
|
|
* \details IOTC module has default master servers. If users need to add their own
|
|
* master server, this function can add the customize master servers.
|
|
*
|
|
* \param cszMasterHostName1 [in] Specify the domain name or IP address of
|
|
* the primary master. Cannot be NULL. See attention below for more detail.
|
|
* \param cszMasterHostName2 [in] Specify the domain name or IP address of
|
|
* the secondary master. Can be NULL if only one master is required.
|
|
* \param cszMasterHostName3 [in] Specify the domain name or IP address of
|
|
* the third master. Can be NULL if only one master is required.
|
|
* \param cszMasterHostName4 [in] Specify the domain name or IP address of
|
|
* the fourth master. Can be NULL if only one master is required.
|
|
*
|
|
* \return #IOTC_ER_NoERROR if initializing successfully
|
|
* \return Error code if return value < 0
|
|
* - #IOTC_ER_NOT_INITIALIZED The IOTC module is not initialized yet
|
|
* - #IOTC_ER_MASTER_INVALID cszMasterDomain1 is set NULL
|
|
*
|
|
* \attention This function must be used before IOTC_Device_Login(), IOTC_Connect_ByUID(),
|
|
* IOTC_Connect_ByUID_Parallel() <br><br>
|
|
*/
|
|
P2PAPI_API int IOTC_Add_MasterServer(const char *cszMasterHostName1, const char *cszMasterHostName2,
|
|
const char *cszMasterHostName3, const char *cszMasterHostName4);
|
|
/*
|
|
P2PAPI_API int IOTC_Add_MasterServer_Test(const char* cszMasterHostName1, const char* cszMasterHostName2,
|
|
const char* cszMasterHostName3, const char* cszMasterHostName4);
|
|
*/
|
|
|
|
|
|
|
|
|
|
#ifdef IOTC_UCOSII
|
|
//void *malloc(unsigned int size);
|
|
void tutk_platform_free(void *addr);
|
|
#endif
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
|
|
#endif /* _IOTCAPIs_H_ */
|
|
|