661 lines
29 KiB
C
Executable File
661 lines
29 KiB
C
Executable File
/*! \file P2PTunnelAPIs.h
|
|
This file describes all the APIs of the P2PTunnel module in IOTC platform.
|
|
P2PTunnel module is a kind of medium module to map local service to remote can access
|
|
like port mapping among devices and clients. ex: Web, ssh etc.
|
|
|
|
* \attention P2PTunnel module can't be used with IOTC and RDT module at the same process.
|
|
|
|
\copyright Copyright (c) 2012 by Throughtek Co., Ltd. All Rights Reserved.
|
|
|
|
Revision Table
|
|
|
|
Version | Name |Date |Description
|
|
------------|------------------|---------------|-------------------
|
|
0.9.8.0 |Kevin |2013-02-25 |Alpha Version
|
|
1.2.0.0 |Harry |2013-03-07 |+ All new P2PTUNNEL module, NO backward compatible<br> + Support authentication
|
|
1.2.1.0 |Kevin, Harry |2013-03-28 |+ Tunnel agent add SO_REUSEADDR option except win32.<br> o Modify IOTC_Device_Login() stop retry if login failed.<br> o Use IOTC_Initialize2() instead of IOTC_Initialize().<br> o Check pointer is not NULL before access.<br>
|
|
1.2.2.0 |Hanlin, Harry |2013-04-03 |+ Add P2PTunnelAgent_Set_Log_Path() to set log file name, path and maximum size.<br> + Log error codes in specified file.
|
|
1.2.3.0 |Hanlin, Harry |2013-05-07 |o Fix bugs of buffer handling at low bandwidth condition.<br> o Fix file pointer leak in log function.
|
|
1.2.4.0 |Hanlin, Harry |2013-05-15 |o Fix local socket does not disconnect correctly when remotes side is disconnected.
|
|
1.2.5.0 |Han-Lin |2013-06-25 |+ Add P2PTunnel_LastIOTime() to get the last IO time of SID.<br> o Fix timer bug which causes incorrect waiting interval.
|
|
1.2.6.0 |Harry |2013-07-26 |o Fix CPU busy issue.<br> o Fix large transmission of the same packages.
|
|
1.2.7.0 |Harry, Victor |2013-08-28 |o Fix TCP socket error code handling to improve P2PTunnel stability.<br> o Fix P2PTunnel control command may not be sent correctly to prevent channel is kept after disconnected.<br> o Fix Big Endian platform will make P2PTunnelAgent_Connect returns -30008 error code.
|
|
1.2.7.3 |Han-Lin, Victor |2013-10-28 |o Fix flow control mechanism.<br> o Fix error detection in Win32.<br> o Fix big endian bug.<br> + P2PTunnel_SetBufSize() API to set tunnel buffer size to improve performance.<br> o Fix buffer control for RTSP/TCP application.
|
|
1.2.8.0 |TUTK RD TEAM |2013-11-19 |o Fix race condition and deadlock bug.<br> o Fix disconnection bug.<br> o Fix variables conflict error.<br> + Support Lan mode environment.
|
|
1.2.9.0 |Jelly, Alex |2014-02-17 |o Fix restart bug.<br> o Improve transmission machanism.<br> o Fix LAN search issue under LAN in P2PTunnelServer_Start().<br> o Fix re-bind error.<br> Fix Server restart error.
|
|
1.3.0.0 |TUTK RD TEAM |2014-08-28 |o Improve TCP relay mode performance.<br> - Remove include platform_config.h
|
|
1.4.0.0 |TUTK RD team |2014-09-22 |o Fix when do duplicate call P2PTunnelAgent_StopPortMapping() will crash.<br> o Improve LAN data transmission performance has greatly increased.<br> + Add 64-bit library.
|
|
1.4.2.0 |TUTK RD team |2014-10-17 |o Fix process crash with LAN mode on Win32.<br> + Add P2PTunnelAgent_Connect_Stop() for exit connection process.
|
|
*/
|
|
|
|
#ifndef _P2PTunnelAPIs_H_
|
|
#define _P2PTunnelAPIs_H_
|
|
|
|
|
|
/* ============================================================================
|
|
* Platform Dependant Macro Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
|
|
#ifdef _WIN32
|
|
/** @cond */
|
|
#ifdef IOTC_STATIC_LIB
|
|
#define TUNNEL_API
|
|
#elif defined P2PAPI_EXPORTS
|
|
#define TUNNEL_API __declspec(dllexport)
|
|
#else
|
|
#define TUNNEL_API __declspec(dllimport)
|
|
#endif // #ifdef P2PAPI_EXPORTS
|
|
/** @endcond */
|
|
#endif // #ifdef _WIN32
|
|
|
|
|
|
#if defined(__linux__) || defined (__APPLE__)
|
|
#define TUNNEL_API
|
|
#define __stdcall
|
|
#endif // #ifdef __linux__
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/* ============================================================================
|
|
* Generic Macro Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
/** The maximum number of port mapping service in P2PTunnel module */
|
|
#define TUNNEL_MAX_PORT_MAPPING_SERVICE_NUMBER 256
|
|
|
|
/** The maximum size, in byte, of the authentication data used in P2PTunnelAgent_Connect() */
|
|
#define MAX_AUTH_DATA_LEN 1000
|
|
|
|
/* ============================================================================
|
|
* Error Code Declaration
|
|
* ============================================================================
|
|
*/
|
|
|
|
/** The function is performed successfully. */
|
|
#define TUNNEL_ER_NoERROR 0
|
|
|
|
/** P2PTunnel module is not initialized yet. Please use P2PTunnelServerInitialize() or
|
|
* P2PTunnelAgentInitialize() for initialization. */
|
|
#define TUNNEL_ER_NOT_INITIALIZED -30000
|
|
|
|
/** The number of P2PTunnel port mapping service has reached maximum.
|
|
* The maximum number of P2PTunnel port mapping service is determined by
|
|
* #TUNNEL_MAX_PORT_MAPPING_SERVICE_NUMBER */
|
|
#define TUNNEL_ER_EXCEED_MAX_SERVICE -30001
|
|
|
|
/** Failed to start port mapping when binding because local port had been used by
|
|
* the other service in agent side */
|
|
#define TUNNEL_ER_BIND_LOCAL_SERVICE -30002
|
|
|
|
/** Failed to start port mapping when listening because local port has been used
|
|
* by the other service in agent side */
|
|
#define TUNNEL_ER_LISTEN_LOCAL_SERVICE -30003
|
|
|
|
/** P2PTunnel module fails to create threads. Please check if OS has ability
|
|
* to create threads for P2PTunnel module. */
|
|
#define TUNNEL_ER_FAIL_CREATE_THREAD -30004
|
|
|
|
/** Tunnel agent has already connected to a tunnel server, therefore, it failed
|
|
* connect to another tunnel server */
|
|
#define TUNNEL_ER_ALREADY_CONNECTED -30005
|
|
|
|
/** The tunnel between tunnel agent and tunnel server has been disconnected.
|
|
* Used in tunnel status callback function for notifying tunnel connection status */
|
|
#define TUNNEL_ER_DISCONNECTED -30006
|
|
|
|
/** The P2PTunnel module has been initialized in a tunnel server or a tunnel agent */
|
|
#define TUNNEL_ER_ALREADY_INITIALIZED -30007
|
|
|
|
/** Failed to connect to tunnel server because authentication data is wrong. */
|
|
#define TUNNEL_ER_AUTH_FAILED -30008
|
|
|
|
/** Authentication data length exceed #MAX_AUTH_DATA_LEN. */
|
|
#define TUNNEL_ER_EXCEED_MAX_LEN -30009
|
|
|
|
/** The specified P2PTunnel session ID is not valid */
|
|
#define TUNNEL_ER_INVALID_SID -30010
|
|
|
|
/** This UID is illegal. */
|
|
#define TUNNEL_ER_UID_UNLICENSE -30011
|
|
|
|
/** The specified device does not support advance function
|
|
*(TCP relay and P2PTunnel module) */
|
|
#define TUNNEL_ER_UID_NO_PERMISSION -30012
|
|
|
|
/** This UID can't setup connection through relay. */
|
|
#define TUNNEL_ER_UID_NOT_SUPPORT_RELAY -30013
|
|
|
|
/** Tunnel server not login to IOTC server. */
|
|
#define TUNNEL_ER_DEVICE_NOT_ONLINE -30014
|
|
|
|
/** Tunner server is not listening for connections. */
|
|
#define TUNNEL_ER_DEVICE_NOT_LISTENING -30015
|
|
|
|
/** Internet not available or firewall block. */
|
|
#define TUNNEL_ER_NETWORK_UNREACHABLE -30016
|
|
|
|
/** Tunnel agent failed to connect to tunnel server maybe network unstable. */
|
|
#define TUNNEL_ER_FAILED_SETUP_CONNECTION -30017
|
|
|
|
/** Tunnel server failed to login to IOTC Server but still can be connected by tunnel agent on LAN. */
|
|
#define TUNNEL_ER_LOGIN_FAILED -30018
|
|
|
|
/** Notify tunnel server session connection alreay reached maximum through tunnelStatusCB,
|
|
* can't be connected anymore until anyone session release. */
|
|
#define TUNNEL_ER_EXCEED_MAX_SESSION -30019
|
|
|
|
/** Tunnel agent can't call P2PTunnelServer_GetSessionInfo() */
|
|
#define TUNNEL_ER_AGENT_NOT_SUPPORT -30020
|
|
|
|
/** The arguments passed to a function is invalid. */
|
|
#define TUNNEL_ER_INVALID_ARG -30021
|
|
|
|
/** OS resource not enough to malloc memory or open socket. */
|
|
#define TUNNEL_ER_OS_RESOURCE_LACK -30022
|
|
|
|
/** Tunnel Agent isn't connecting. */
|
|
#define TUNNEL_ER_AGENT_NOT_CONNECTING -30023
|
|
|
|
/** Unable to get free session.*/
|
|
#define TUNNEL_ER_NO_FREE_SESSION -30024
|
|
|
|
/** Connection cancelled*/
|
|
#define TUNNEL_ER_CONNECTION_CANCELLED -30025
|
|
|
|
/* ============================================================================
|
|
* Structure Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \details P2PTunnel session info, containing all the information when a P2PTunnel session is
|
|
* established between a tunnel server and a tunnel agent. Users can get this information
|
|
* through use P2PTunnelServer_GetSessionInfo() to register a call back function tunnelSessionInfoCB
|
|
*/
|
|
typedef struct st_P2PTunnelSessionInfo
|
|
{
|
|
int nSID; //!< P2PTunnel session index
|
|
unsigned char nMode; //!< 0: P2P mode, 1: Relay mode, 2: LAN mode
|
|
unsigned char nNatType; //!< The remote NAT type
|
|
char szRemoteIP[16]; //!< The IP address of remote site used during this P2PTunnel session
|
|
unsigned short nRemotePort; //!< The port number of remote site used during this P2PTunnel session
|
|
unsigned int nVersion; //!< The remote P2PTunnel API version.
|
|
int nAuthDataLen; //!< How many byte of the authentication data.
|
|
void *pAuthData; //!< The authentication data buffer, it will be freed by API automatically.
|
|
} sP2PTunnelSessionInfo;
|
|
|
|
|
|
/* ============================================================================
|
|
* Type Definition
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \details The prototype of getting tunnel status function, used by a tunnel server
|
|
* or tunnel agent to be notified if tunnel status is changed.
|
|
*
|
|
* \param nErrorCode [out]
|
|
* - #TUNNEL_ER_DISCONNECTED The tunnel between tunnel agent and tunnel server
|
|
* has been disconnected.
|
|
* \param nSessionID [in] Which session ID of the P2PTunnel session disconnected
|
|
* \param pArg [out] Tunnel server or agent pass user data
|
|
*
|
|
*/
|
|
typedef void (__stdcall *tunnelStatusCB)(int nErrorCode, int nSessionID, void *pArg);
|
|
|
|
|
|
/**
|
|
* \details The prototype of getting tunnel session information function,
|
|
* used by a tunnel server to be notified after tunnel session is established.
|
|
*
|
|
* \param sSessionInfo [out] About remote session information
|
|
* \param pArg [out] Tunnel server pass user data
|
|
*
|
|
*
|
|
* \return User define value.
|
|
* - if value == 0, it means a tunnel server passes tunnel agent authentication
|
|
* - if value < 0, it means a tunnel server rejects tunnel agent authentication
|
|
* and P2PTunnel module will send the value back to tunnel agent
|
|
* for tell the reason why this tunnel server rejects connection.
|
|
*
|
|
*/
|
|
typedef int (__stdcall *tunnelSessionInfoCB)(sP2PTunnelSessionInfo *sSessionInfo, void *pArg);
|
|
|
|
|
|
/* ============================================================================
|
|
* Function Declaration
|
|
* ============================================================================
|
|
*/
|
|
|
|
/**
|
|
* \brief Get the version of P2PTunnel module
|
|
*
|
|
* \details This function returns the version of P2PTunnel module.
|
|
*
|
|
* \return The version of P2PTunnel module from high byte to low byte, for example,
|
|
* 0x01020304 means the version is 1.2.3.4
|
|
*/
|
|
TUNNEL_API int P2PTunnel_Version(void);
|
|
|
|
|
|
/**
|
|
* \brief Initialize P2PTunnel module in a tunnel server
|
|
*
|
|
* \details This function is used by a tunnel server to initialize P2PTunnel
|
|
* module and shall be called before any P2PTunnel module related
|
|
* function is invoked.
|
|
*
|
|
* \param nMaxAgentConnection [in] Specify max number of tunnel agents that
|
|
* can connect to this tunnel server
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if initializing successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_ALREADY_INITIALIZED P2PTunnel module is already initialized
|
|
* - #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
|
|
* - #RDT_ER_ALREADY_INITIALIZED RDT module is already initialized
|
|
* - #RDT_ER_FAIL_CREATE_MUTEX Fails to create Mutexs
|
|
*
|
|
* \see P2PTunnelServerDeInitialize()
|
|
*/
|
|
TUNNEL_API int P2PTunnelServerInitialize(unsigned int nMaxAgentConnection);
|
|
|
|
|
|
/**
|
|
* \brief Deinitialize P2PTunnel module in a tunnel server
|
|
*
|
|
* \details This function will deinitialize P2PTunnel module in a tunnel server
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if deinitialize successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NOT_INITIALIZED the P2PTunnel module is not initialized yet.
|
|
*
|
|
* \see P2PTunnelServerInitialize()
|
|
*
|
|
* \attention Must call P2PTunnelServer_Stop() before calling this function,
|
|
* otherwise resource in P2PTunnel module will not be freed.
|
|
*/
|
|
TUNNEL_API int P2PTunnelServerDeInitialize(void);
|
|
|
|
|
|
/**
|
|
* \brief Start a tunnel server
|
|
*
|
|
* \details This function will start a tunnel server with given UID
|
|
*
|
|
* \param cszUID [in] The UID of that tunnel server
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if start successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NOT_INITIALIZED P2PModule has not been initialized in that tunnel server
|
|
* - #TUNNEL_ER_FAIL_CREATE_THREAD Failed to create thread
|
|
* - #TUNNEL_ER_UID_NO_PERMISSION This UID not support P2PModule and TCP relay function
|
|
* - #TUNNEL_ER_UID_UNLICENSE This UID is not licensed or expired
|
|
*/
|
|
TUNNEL_API int P2PTunnelServer_Start(const char *cszUID);
|
|
|
|
|
|
/**
|
|
* \brief Stop a tunnel server
|
|
*
|
|
* \details This function will stop a tunnel server
|
|
*
|
|
*/
|
|
TUNNEL_API void P2PTunnelServer_Stop(void);
|
|
|
|
|
|
/**
|
|
* \brief Used by a tunnel server to get the tunnel status
|
|
*
|
|
* \details This function will set a callback function pointer in P2PTunnel
|
|
* module for a tunnel server to get the tunnel status from given callback
|
|
* function. Whenever tunnel status changes, P2PTunnel module will invoke
|
|
* the given callback function to notify tunnel server with corresponding
|
|
* status.
|
|
*
|
|
* \param pfxTunnelStatusFn [in] The function pointer to get tunnel status function
|
|
* \param pArg [in] User can give data pointer to pass to pfxSessionInfoFn when this
|
|
* call back function is triggered. Can be NULL.
|
|
*/
|
|
TUNNEL_API void P2PTunnelServer_GetStatus(tunnelStatusCB pfxTunnelStatusFn, void *pArg);
|
|
|
|
|
|
/**
|
|
* \brief Used by a tunnel server to get the tunnel session information
|
|
*
|
|
* \details This function will set a callback function pointer in P2PTunnel
|
|
* module for a tunnel server to get the tunnel session information from
|
|
* given callback function. Whenever tunnel agent try to establish session with tunnel server
|
|
* successfully, P2PTunnel module will invoke the given callback function to notify
|
|
* tunnel server and pass information through sP2PTunnelSessionInfo data struct.
|
|
*
|
|
* \param pfxSessionInfoFn [in] The function pointer to get tunnel session information function
|
|
* \param pArg [in] User can give data pointer to pass to pfxSessionInfoFn when this
|
|
* call back function is triggered. Can be NULL.
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if register successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_AGENT_NOT_SUPPORT Tunnel agent not support this function call
|
|
*
|
|
* \attention Must call P2PTunnelServer_Start() before calling this function,
|
|
* otherwise it will return TUNNEL_ER_AGENT_NOT_SUPPORT.
|
|
*/
|
|
TUNNEL_API int P2PTunnelServer_GetSessionInfo(tunnelSessionInfoCB pfxSessionInfoFn, void *pArg);
|
|
|
|
|
|
/**
|
|
* \brief Used by a tunnel server to disconnect a tunnel session
|
|
*
|
|
* \details This function will disconnect a tunnel session anytime after tunnel session
|
|
* established and it call be called anywhere.
|
|
*
|
|
* \param nSessionID [in] Which session ID of the P2PTunnel session established
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if disconnect P2PTunnel session successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_AGENT_NOT_SUPPORT Tunnel agent not support this function call
|
|
* - #TUNNEL_ER_INVALID_SID The session ID already disconnected or not yet established
|
|
* - #TUNNEL_ER_INVALID_ARG The session ID is not in valid range.
|
|
*/
|
|
TUNNEL_API int P2PTunnelServer_Disconnect(int nSessionID);
|
|
|
|
|
|
/**
|
|
* \brief Initialize P2PTunnel module in a tunnel agent
|
|
*
|
|
* \details This function is used by a tunnel agent to initialize P2PTunnel
|
|
* module and shall be called before any P2PTunnel module related
|
|
* function is invoked.
|
|
*
|
|
* \param nMaxConnection [in] Specify max number of tunnel agents that
|
|
* can connect to tunnel servers
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if initializing successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_ALREADY_INITIALIZED P2PTunnel module is already initialized
|
|
* - #TUNNEL_ER_FAIL_CREATE_THREAD Failed to create thread
|
|
* - #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
|
|
* - #RDT_ER_ALREADY_INITIALIZED RDT module is already initialized
|
|
* - #RDT_ER_FAIL_CREATE_MUTEX Fails to create Mutexs
|
|
*
|
|
* \see P2PTunnelAgentDeInitialize()
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgentInitialize(unsigned int nMaxConnection);
|
|
|
|
|
|
/**
|
|
* \brief Deinitialize P2PTunnel module in a tunnel agent
|
|
*
|
|
* \details This function will deinitialize P2PTunnel module in a tunnel agent
|
|
*
|
|
* \return #TUNNEL_ER_NoERROR if deinitialize successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NOT_INITIALIZED the P2PTunnel module is not initialized yet.
|
|
*
|
|
* \see P2PTunnelAgentInitialize()
|
|
*
|
|
* \attention Must call P2PTunnelAgent_Disconnect() before calling this function,
|
|
* otherwise resource in P2PTunnel module will not be freed and connection
|
|
* will not be closed (the remote site will have connection timeout event
|
|
* eventually).
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgentDeInitialize(void);
|
|
|
|
/**
|
|
* \brief Used by an agent to get a free session ID.
|
|
*
|
|
* \datails This function is for an agent to get a free session ID used for a parameter of P2PTunnelAgent_Connect_Parallel().
|
|
*
|
|
* \return Tunnel Session ID if return value >= 0
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NO_FREE_SESSION Current tunnel session are full.
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_GetFreeSession(void);
|
|
|
|
/**
|
|
* \brief Connect to a tunnel server
|
|
*
|
|
* \details This function used by a tunnel agent to connect the tunnel server
|
|
* with specified UID
|
|
*
|
|
* \param cszUID [in] The UID of that tunnel server to be connected
|
|
* \param cpAuthData [in] Send authentication data to tunnel server for connection.
|
|
* \param nAuthDataLength [in] The length of the byte buffer. It cannot be larger than
|
|
* #MAX_AUTH_DATA_LEN
|
|
* \param pnErrFromDeviceCB [out] The reason why tunnel server rejects this connection.
|
|
* It's returned from tunnelSessionInfoCB of the tunnel server.
|
|
*
|
|
* \return Tunnel Session ID if return value >= 0
|
|
* \return #TUNNEL_ER_NoERROR if connect successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NOT_INITIALIZED P2PModule has not been initialized in that tunnel agent
|
|
* - #TUNNEL_ER_AUTH_FAILED The tunnel agent failed to connect to tunnel server
|
|
* because authentication data is illegal.
|
|
* - #TUNNEL_ER_UID_UNLICENSE This UID is illegal or does not support P2PTunnel function
|
|
* - #TUNNEL_ER_UID_NO_PERMISSION This UID not support P2PModule and TCP relay function
|
|
* - #TUNNEL_ER_UID_NOT_SUPPORT_RELAY This UID can't setup connection through relay
|
|
* - #TUNNEL_ER_DEVICE_NOT_ONLINE The specified tunnel server does not login to IOTC server yet
|
|
* - #TUNNEL_ER_DEVICE_NOT_LISTENING The specified tunnel server is not listening for connection,
|
|
* it maybe busy at establishing connection with other tunnel agent
|
|
* - #TUNNEL_ER_NETWORK_UNREACHABLE Internet is not available or firewall blocks connection
|
|
* - #TUNNEL_ER_FAILED_SETUP_CONNECTION Can't connect to the tunnel server although it is online
|
|
* and listening for connection, it maybe caused by internet unstable situation
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_Connect(const char *cszUID, const void *cpAuthData, int nAuthDataLength, int *pnErrFromDeviceCB);
|
|
|
|
/**
|
|
* \brief Connect to a tunnel server and bind to a specified session ID.
|
|
*
|
|
* \details This function is for a tunnel agent to connect a device by specifying the UID
|
|
* of that device, and bind to a free session ID from P2PTunnelAgent_GetFreeSession().
|
|
* If connection is established with the help of IOTC servers, the TUNNEL_ER_NoERROR will
|
|
* be returned in this function and then device and client can communicate for the other
|
|
* later by using this tunnel session ID. If this function is called by multiple threads,
|
|
* the connections will be processed concurrently.
|
|
*
|
|
* \param cszUID [in] The UID of that tunnel server to be connected
|
|
* \param SID [in] The SID got from P2PTunnelAgent_GetFreeSession() the connection should bind to.
|
|
* \param cpAuthData [in] Send authentication data to tunnel server for connection.
|
|
* \param nAuthDataLength [in] The length of the byte buffer. It cannot be larger than
|
|
* #MAX_AUTH_DATA_LEN
|
|
* \param pnErrFromDeviceCB [out] The reason why tunnel server rejects this connection.
|
|
* It's returned from tunnelSessionInfoCB of the tunnel server.
|
|
*
|
|
* \return Tunnel session ID if return value >= 0 and equal to the input parameter SID.
|
|
* \return #TUNNEL_ER_NoERROR if connect successfully
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NOT_INITIALIZED P2PModule has not been initialized in that tunnel agent
|
|
* - #TUNNEL_ER_AUTH_FAILED The tunnel agent failed to connect to tunnel server
|
|
* because authentication data is illegal.
|
|
* - #TUNNEL_ER_UID_UNLICENSE This UID is illegal or does not support P2PTunnel function
|
|
* - #TUNNEL_ER_UID_NO_PERMISSION This UID not support P2PModule and TCP relay function
|
|
* - #TUNNEL_ER_UID_NOT_SUPPORT_RELAY This UID can't setup connection through relay
|
|
* - #TUNNEL_ER_DEVICE_NOT_ONLINE The specified tunnel server does not login to IOTC server yet
|
|
* - #TUNNEL_ER_DEVICE_NOT_LISTENING The specified tunnel server is not listening for connection,
|
|
* it maybe busy at establishing connection with other tunnel agent
|
|
* - #TUNNEL_ER_NETWORK_UNREACHABLE Internet is not available or firewall blocks connection
|
|
* - #TUNNEL_ER_FAILED_SETUP_CONNECTION Can't connect to the tunnel server although it is online
|
|
* and listening for connection, it maybe caused by internet unstable situation
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_Connect_Parallel(const char *cszUID, const int SID, const void *cpAuthData, int nAuthDataLength, int *pnErrFromDeviceCB);
|
|
|
|
/**
|
|
* \brief Disconnect to a tunnel server
|
|
*
|
|
* \details This function used by a tunnel agent to disconnect to a tunnel server
|
|
*
|
|
* \param nSessionID [in] Which session ID of the P2PTunnel session to be disconnect
|
|
*
|
|
* \return - #TUNNEL_ER_NoERROR if connect successfully
|
|
* - #TUNNEL_ER_INVALID_ARG The session ID is not in valid range.
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_Disconnect(int nSessionID);
|
|
|
|
|
|
/**
|
|
* \brief Start port mapping service
|
|
*
|
|
* \details This function used by a tunnel agent to start port mapping service
|
|
* provided by P2PTunnel module. The tunnel agent specifies the local port
|
|
* in local host through which a tunnel is created with the remote port defined
|
|
* in the tunnel server.
|
|
*
|
|
* \param nSessionID [in] Which session ID of the P2PTunnel session to process the port mapping service
|
|
* \param nLocalPort [in] The local port used to create a tunnel with the tunnel server
|
|
* \param nRemotePort [in] The remote port defined in the tunnel server to create a tunnel
|
|
*
|
|
* \return The port mapping index if return value >= 0
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_EXCEED_MAX_SERVICE Exceed the max number of port mapping service
|
|
* - #TUNNEL_ER_BIND_LOCAL_SERVICE Failed to bind local port since it is used by the other services
|
|
* - #TUNNEL_ER_LISTEN_LOCAL_SERVICE Failed to listen local port since it is used by the other services
|
|
* - #TUNNEL_ER_OS_RESOURCE_LACK Failed to malloc memory
|
|
* - #TUNNEL_ER_INVALID_ARG The session ID is not in valid range.
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_PortMapping(int nSessionID, unsigned short nLocalPort, unsigned short nRemotePort);
|
|
|
|
|
|
/**
|
|
* \brief Stop port mapping service
|
|
*
|
|
* \details This function used by a tunnel agent to stop port mapping service
|
|
* on a given port mapping index which is started by P2PTunnelAgent_PortMapping()
|
|
*
|
|
* \param nPortMappingIdx [in] The port mapping index started in P2PTunnelAgent_PortMapping()
|
|
*
|
|
* \attention If not call P2PTunnelAgent_StopPortMapping local port can't be used until OS release it.
|
|
*/
|
|
TUNNEL_API void P2PTunnelAgent_StopPortMapping(unsigned int nPortMappingIdx);
|
|
|
|
|
|
/**
|
|
* \brief Stop port mapping service
|
|
*
|
|
* \details This function used by a tunnel agent to stop multiple port mapping service
|
|
* on an integer array set of given port mapping index which is started by P2PTunnelAgent_PortMapping()
|
|
*
|
|
* \param indexArray [in] An integer array of the port mapping index in P2PTunnelAgent_PortMapping()
|
|
* indexNum is the number of the port mapping index in indexArray
|
|
*
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_NoERROR if connect successfully
|
|
* - #TUNNEL_ER_INVALID_ARG The session ID is not in valid range.
|
|
*
|
|
* \attention If not call P2PTunnelAgent_StopPortMapping local port can't be used until OS release it.
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_StopPortMapping_byIndexArray(unsigned int *indexArray, unsigned int indexNum);
|
|
|
|
|
|
/**
|
|
* \brief Used by a tunnel agent to get the tunnel status
|
|
*
|
|
* \details This function will set a callback function pointer in P2PTunnel
|
|
* module for a tunnel agent to get the tunnel status from given callback
|
|
* function. Whenever tunnel status changes, P2PTunnel module will invoke
|
|
* the given callback function to notify tunnel agent with corresponding
|
|
* status.
|
|
*
|
|
* \param pfxTunnelStatusFn [in] The function pointer to getting tunnel status function
|
|
* \param pArg [in] User can give data pointer to pass to pfxSessionInfoFn when this
|
|
* call back function is triggered. Can be NULL.
|
|
*/
|
|
TUNNEL_API void P2PTunnelAgent_GetStatus(tunnelStatusCB pfxTunnelStatusFn, void *pArg);
|
|
|
|
/**
|
|
* \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 = unlimit
|
|
*
|
|
*/
|
|
|
|
TUNNEL_API void P2PTunnelAgent_Set_Log_Path(const char *path, int nMaxSize);
|
|
|
|
/**
|
|
* \brief Get last IO time of SID
|
|
*
|
|
* \details Get last IO time of SID even if the connection is closed.
|
|
*
|
|
* \param nSessionID [in] Session ID
|
|
*
|
|
* \return POSIX time of last IO if return value > 0
|
|
* \return 0 if no connection ever established on this SID
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_INVALID_SID The session ID already disconnected or not yet established
|
|
* - #TUNNEL_ER_INVALID_ARG The session ID is not in valid range.
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnel_LastIOTime(int nSessionID);
|
|
|
|
/**
|
|
* \brief Set P2PTunnel buffer size
|
|
*
|
|
* \details Set P2PTunnel buffer size, larger buffer leads more maximum throughput
|
|
*
|
|
* \param nSessionID [in] Session ID
|
|
* \param nSize [in] Buffer size in Bytes
|
|
*
|
|
* \return 0 if success
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_INVALID_SID The session ID already disconnected or not yet established
|
|
* - #TUNNEL_ER_INVALID_ARG The session ID is not in valid range.
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnel_SetBufSize(int nSessionID, int nSize);
|
|
|
|
/**
|
|
* \brief It's to stop the progressing of connection.
|
|
*
|
|
* \details This API is for a client to stop connecting to a device.
|
|
* We can use it to stop connecting when client blocks in P2PTunnelAgent_Connect().
|
|
*
|
|
* \param cszUID [in] The UID of that tunnel server
|
|
*
|
|
* \return 0 if success
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_AGENT_NOT_CONNECTING Tunnel Agent isn't connecting.
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_Connect_Stop (const char* cszUID);
|
|
|
|
|
|
/**
|
|
* \brief It's to stop the progressing of connection.
|
|
*
|
|
* \details This API is for a client to stop connecting to a device.
|
|
* We can use it to stop connecting when client blocks in P2PTunnelAgent_Connect_Parallel().
|
|
*
|
|
* \param cszUID [in] The UID of that tunnel server
|
|
* \param nSessionID [in] Session ID
|
|
* \return 0 if success
|
|
* \return Error code if return value < 0
|
|
* - #TUNNEL_ER_AGENT_NOT_CONNECTING Tunnel Agent isn't connecting.
|
|
*
|
|
*/
|
|
TUNNEL_API int P2PTunnelAgent_Connect_Stop_Parallel(const char* cszUID, const int nSessionID);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
|
|
#endif /* _P2PTunnelAPIs_H_ */
|