P2PTunnelAPIs.h

/*! \file P2PTunnelAPIs.h

 [Kalay Kit, V1.1.0]
 Copyright (C) 2015, ThroughTek Co., Ltd.
 
 * This program is a free software; you can redistribute it and/or modify it under the terms of The BSD 3-Clause License as approved by Open Source Initiative. (See The BSD 3-Clause License for more details) But you may not decompile, disassemble, reverse-engineer, or use this program for commercial purposes.
 * This program is provided “as is” with all faults, defects and errors, and without warranty of any kind. In no event shall ThroughTek Co., Ltd. be liable for any direct, indirect, incidental, special, exemplary, or consequential damages however caused and on any theory of liability, whether in contract, strict liability, or tort arising in any way out the use of this program, even if advised of the possibility of such damage. 

ThroughTek Co., Ltd., 9F, No. 364, Sec. 1, Nangang Rd., Nangang District, Taipei City 115, Taiwan.

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 currently.

\copyright Copyright (c) 2015 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_ */