IOTC Platform: P2PTunnelAPIs.h File Reference

| IOTC Platform Ver: 2.1.0.25 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Typedefs | Functions
P2PTunnelAPIs.h File Reference

## Data Structures

struct | st_P2PTunnelSessionInfo

## Macros

#define | TUNNEL_MAX_PORT_MAPPING_SERVICE_NUMBER 256
#define | MAX_AUTH_DATA_LEN 1000
#define | TUNNEL_ER_NoERROR 0
#define | TUNNEL_ER_NOT_INITIALIZED -30000
#define | TUNNEL_ER_EXCEED_MAX_SERVICE -30001
#define | TUNNEL_ER_BIND_LOCAL_SERVICE -30002
#define | TUNNEL_ER_LISTEN_LOCAL_SERVICE -30003
#define | TUNNEL_ER_FAIL_CREATE_THREAD -30004
#define | TUNNEL_ER_ALREADY_CONNECTED -30005
#define | TUNNEL_ER_DISCONNECTED -30006
#define | TUNNEL_ER_ALREADY_INITIALIZED -30007
#define | TUNNEL_ER_AUTH_FAILED -30008
#define | TUNNEL_ER_EXCEED_MAX_LEN -30009
#define | TUNNEL_ER_INVALID_SID -30010
#define | TUNNEL_ER_UID_UNLICENSE -30011
#define | TUNNEL_ER_UID_NO_PERMISSION -30012
#define | TUNNEL_ER_UID_NOT_SUPPORT_RELAY -30013
#define | TUNNEL_ER_DEVICE_NOT_ONLINE -30014
#define | TUNNEL_ER_DEVICE_NOT_LISTENING -30015
#define | TUNNEL_ER_NETWORK_UNREACHABLE -30016
#define | TUNNEL_ER_FAILED_SETUP_CONNECTION -30017
#define | TUNNEL_ER_LOGIN_FAILED -30018
#define | TUNNEL_ER_EXCEED_MAX_SESSION -30019
#define | TUNNEL_ER_AGENT_NOT_SUPPORT -30020
#define | TUNNEL_ER_INVALID_ARG -30021
#define | TUNNEL_ER_OS_RESOURCE_LACK -30022
#define | TUNNEL_ER_AGENT_NOT_CONNECTING -30023
#define | TUNNEL_ER_NO_FREE_SESSION -30024
#define | TUNNEL_ER_CONNECTION_CANCELLED -30025

## Typedefs

typedef struct st_P2PTunnelSessionInfo | sP2PTunnelSessionInfo
typedef void(__stdcall * | tunnelStatusCB )(int nErrorCode, int nSessionID, void *pArg)
typedef int(__stdcall * | tunnelSessionInfoCB )(sP2PTunnelSessionInfo *sSessionInfo, void *pArg)

## Functions

TUNNEL_API int | P2PTunnel_Version (void)
| Get the version of P2PTunnel module.
TUNNEL_API int | P2PTunnelServerInitialize (unsigned int nMaxAgentConnection)
| Initialize P2PTunnel module in a tunnel server.
TUNNEL_API int | P2PTunnelServerDeInitialize (void)
| Deinitialize P2PTunnel module in a tunnel server.
TUNNEL_API int | P2PTunnelServer_Start (const char *cszUID)
| Start a tunnel server.
TUNNEL_API void | P2PTunnelServer_Stop (void)
| Stop a tunnel server.
TUNNEL_API void | P2PTunnelServer_GetStatus (tunnelStatusCB pfxTunnelStatusFn, void *pArg)
| Used by a tunnel server to get the tunnel status.
TUNNEL_API int | P2PTunnelServer_GetSessionInfo (tunnelSessionInfoCB pfxSessionInfoFn, void *pArg)
| Used by a tunnel server to get the tunnel session information.
TUNNEL_API int | P2PTunnelServer_Disconnect (int nSessionID)
| Used by a tunnel server to disconnect a tunnel session.
TUNNEL_API int | P2PTunnelAgentInitialize (unsigned int nMaxConnection)
| Initialize P2PTunnel module in a tunnel agent.
TUNNEL_API int | P2PTunnelAgentDeInitialize (void)
| Deinitialize P2PTunnel module in a tunnel agent.
TUNNEL_API int | P2PTunnelAgent_GetFreeSession (void)
| Used by an agent to get a free session ID.
TUNNEL_API int | P2PTunnelAgent_Connect (const char *cszUID, const void *cpAuthData, int nAuthDataLength, int *pnErrFromDeviceCB)
| Connect to a tunnel server.
TUNNEL_API int | P2PTunnelAgent_Connect_Parallel (const char *cszUID, const int SID, const void *cpAuthData, int nAuthDataLength, int *pnErrFromDeviceCB)
| Connect to a tunnel server and bind to a specified session ID.
TUNNEL_API int | P2PTunnelAgent_Disconnect (int nSessionID)
| Disconnect to a tunnel server.
TUNNEL_API int | P2PTunnelAgent_PortMapping (int nSessionID, unsigned short nLocalPort, unsigned short nRemotePort)
| Start port mapping service.
TUNNEL_API void | P2PTunnelAgent_StopPortMapping (unsigned int nPortMappingIdx)
| Stop port mapping service.
TUNNEL_API int | P2PTunnelAgent_StopPortMapping_byIndexArray (unsigned int *indexArray, unsigned int indexNum)
| Stop port mapping service.
TUNNEL_API void | P2PTunnelAgent_GetStatus (tunnelStatusCB pfxTunnelStatusFn, void *pArg)
| Used by a tunnel agent to get the tunnel status.
TUNNEL_API void | P2PTunnelAgent_Set_Log_Path (const char *path, int nMaxSize)
| Set path of log file.
TUNNEL_API int | P2PTunnel_LastIOTime (int nSessionID)
| Get last IO time of SID.
TUNNEL_API int | P2PTunnel_SetBufSize (int nSessionID, int nSize)
| Set P2PTunnel buffer size.
TUNNEL_API int | P2PTunnelAgent_Connect_Stop (const char *cszUID)
| It's to stop the progressing of connection.
TUNNEL_API int | P2PTunnelAgent_Connect_Stop_Parallel (const char *cszUID, const int nSessionID)
| It's to stop the progressing of connection.

## Detailed Description

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) 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 + Support authentication
1.2.1.0 | Kevin, Harry | 2013-03-28 | + Tunnel agent add SO_REUSEADDR option except win32. o Modify IOTC_Device_Login() stop retry if login failed. o Use IOTC_Initialize2() instead of IOTC_Initialize(). o Check pointer is not NULL before access.
1.2.2.0 | Hanlin, Harry | 2013-04-03 | + Add P2PTunnelAgent_Set_Log_Path() to set log file name, path and maximum size. + 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. 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. o Fix timer bug which causes incorrect waiting interval.
1.2.6.0 | Harry | 2013-07-26 | o Fix CPU busy issue. 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. o Fix P2PTunnel control command may not be sent correctly to prevent channel is kept after disconnected. 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. o Fix error detection in Win32. o Fix big endian bug. + P2PTunnel_SetBufSize() API to set tunnel buffer size to improve performance. 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. o Fix disconnection bug. o Fix variables conflict error. + Support Lan mode environment.
1.2.9.0 | Jelly, Alex | 2014-02-17 | o Fix restart bug. o Improve transmission machanism. o Fix LAN search issue under LAN in P2PTunnelServer_Start(). o Fix re-bind error. Fix Server restart error.
1.3.0.0 | TUTK RD TEAM | 2014-08-28 | o Improve TCP relay mode performance. - 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. o Improve LAN data transmission performance has greatly increased. + Add 64-bit library.
1.4.2.0 | TUTK RD team | 2014-10-17 | o Fix process crash with LAN mode on Win32. + Add P2PTunnelAgent_Connect_Stop() for exit connection process.

## Macro Definition Documentation

#define MAX_AUTH_DATA_LEN 1000

The maximum size, in byte, of the authentication data used in P2PTunnelAgent_Connect()

#define TUNNEL_ER_AGENT_NOT_CONNECTING -30023

Tunnel Agent isn't connecting.

#define TUNNEL_ER_AGENT_NOT_SUPPORT -30020

Tunnel agent can't call P2PTunnelServer_GetSessionInfo()

#define TUNNEL_ER_ALREADY_CONNECTED -30005

Tunnel agent has already connected to a tunnel server, therefore, it failed connect to another tunnel server

#define TUNNEL_ER_ALREADY_INITIALIZED -30007

The P2PTunnel module has been initialized in a tunnel server or a tunnel agent

#define TUNNEL_ER_AUTH_FAILED -30008

Failed to connect to tunnel server because authentication data is wrong.

#define TUNNEL_ER_BIND_LOCAL_SERVICE -30002

Failed to start port mapping when binding because local port had been used by the other service in agent side

#define TUNNEL_ER_CONNECTION_CANCELLED -30025

Connection cancelled

#define TUNNEL_ER_DEVICE_NOT_LISTENING -30015

Tunner server is not listening for connections.

#define TUNNEL_ER_DEVICE_NOT_ONLINE -30014

Tunnel server not login to IOTC server.

#define TUNNEL_ER_DISCONNECTED -30006

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_EXCEED_MAX_LEN -30009

Authentication data length exceed MAX_AUTH_DATA_LEN.

#define TUNNEL_ER_EXCEED_MAX_SERVICE -30001

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_SESSION -30019

Notify tunnel server session connection alreay reached maximum through tunnelStatusCB, can't be connected anymore until anyone session release.

#define TUNNEL_ER_FAIL_CREATE_THREAD -30004

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

#define TUNNEL_ER_FAILED_SETUP_CONNECTION -30017

Tunnel agent failed to connect to tunnel server maybe network unstable.

#define TUNNEL_ER_INVALID_ARG -30021

The arguments passed to a function is invalid.

#define TUNNEL_ER_INVALID_SID -30010

The specified P2PTunnel session ID is not valid

#define TUNNEL_ER_LISTEN_LOCAL_SERVICE -30003

Failed to start port mapping when listening because local port has been used by the other service in agent side

#define TUNNEL_ER_LOGIN_FAILED -30018

Tunnel server failed to login to IOTC Server but still can be connected by tunnel agent on LAN.

#define TUNNEL_ER_NETWORK_UNREACHABLE -30016

Internet not available or firewall block.

#define TUNNEL_ER_NO_FREE_SESSION -30024

Unable to get free session.

#define TUNNEL_ER_NoERROR 0

The function is performed successfully.

#define TUNNEL_ER_NOT_INITIALIZED -30000

P2PTunnel module is not initialized yet. Please use P2PTunnelServerInitialize() or P2PTunnelAgentInitialize() for initialization.

#define TUNNEL_ER_OS_RESOURCE_LACK -30022

OS resource not enough to malloc memory or open socket.

#define TUNNEL_ER_UID_NO_PERMISSION -30012

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

#define TUNNEL_ER_UID_NOT_SUPPORT_RELAY -30013

This UID can't setup connection through relay.

#define TUNNEL_ER_UID_UNLICENSE -30011

This UID is illegal.

#define TUNNEL_MAX_PORT_MAPPING_SERVICE_NUMBER 256

The maximum number of port mapping service in P2PTunnel module

## Typedef Documentation

typedef struct st_P2PTunnelSessionInfo sP2PTunnelSessionInfo

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 int(__stdcall * tunnelSessionInfoCB)(sP2PTunnelSessionInfo *sSessionInfo, void *pArg)

The prototype of getting tunnel session information function, used by a tunnel server to be notified after tunnel session is established.

Parameters

  sSessionInfo | [out] About remote session information
  pArg | [out] Tunnel server pass user data

Returns
  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 void(__stdcall * tunnelStatusCB)(int nErrorCode, int nSessionID, void *pArg)

The prototype of getting tunnel status function, used by a tunnel server or tunnel agent to be notified if tunnel status is changed.

Parameters

  nErrorCode

  [out]
  - TUNNEL_ER_DISCONNECTED The tunnel between tunnel agent and tunnel server has been disconnected.

  nSessionID | [in] Which session ID of the P2PTunnel session disconnected
  pArg | [out] Tunnel server or agent pass user data

## Function Documentation

TUNNEL_API int P2PTunnel_LastIOTime | ( | int | nSessionID | ) |

Get last IO time of SID.

Get last IO time of SID even if the connection is closed.

Parameters

  nSessionID | [in] Session ID

Returns
  POSIX time of last IO if return value > 0
  0 if no connection ever established on this SID
  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
| ) |  |

Set P2PTunnel buffer size.

Set P2PTunnel buffer size, larger buffer leads more maximum throughput

Parameters

  nSessionID | [in] Session ID
  nSize | [in] Buffer size in Bytes

Returns
  0 if success
  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_Version | ( | void |  | ) |

Get the version of P2PTunnel module.

This function returns the version of P2PTunnel module.

Returns
  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 P2PTunnelAgent_Connect | ( | const char * | cszUID,
|  | const void * | cpAuthData,
|  | int | nAuthDataLength,
|  | int * | pnErrFromDeviceCB
| ) |  |

Connect to a tunnel server.

This function used by a tunnel agent to connect the tunnel server with specified UID

Parameters

  cszUID | [in] The UID of that tunnel server to be connected
  cpAuthData | [in] Send authentication data to tunnel server for connection.
  nAuthDataLength | [in] The length of the byte buffer. It cannot be larger than MAX_AUTH_DATA_LEN
  pnErrFromDeviceCB | [out] The reason why tunnel server rejects this connection. It's returned from tunnelSessionInfoCB of the tunnel server.

Returns
  Tunnel Session ID if return value >= 0
  TUNNEL_ER_NoERROR if connect successfully
  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
| ) |  |

Connect to a tunnel server and bind to a specified session ID.

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.

Parameters

  cszUID | [in] The UID of that tunnel server to be connected
  SID | [in] The SID got from P2PTunnelAgent_GetFreeSession() the connection should bind to.
  cpAuthData | [in] Send authentication data to tunnel server for connection.
  nAuthDataLength | [in] The length of the byte buffer. It cannot be larger than MAX_AUTH_DATA_LEN
  pnErrFromDeviceCB | [out] The reason why tunnel server rejects this connection. It's returned from tunnelSessionInfoCB of the tunnel server.

Returns
  Tunnel session ID if return value >= 0 and equal to the input parameter SID.
  TUNNEL_ER_NoERROR if connect successfully
  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_Stop | ( | const char * | cszUID | ) |

It's to stop the progressing of connection.

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().

Parameters

  cszUID | [in] The UID of that tunnel server

Returns
  0 if success
  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
| ) |  |

It's to stop the progressing of connection.

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().

Parameters

  cszUID | [in] The UID of that tunnel server
  nSessionID | [in] Session ID

Returns
  0 if success
  Error code if return value < 0
  - TUNNEL_ER_AGENT_NOT_CONNECTING Tunnel Agent isn't connecting.

TUNNEL_API int P2PTunnelAgent_Disconnect | ( | int | nSessionID | ) |

Disconnect to a tunnel server.

This function used by a tunnel agent to disconnect to a tunnel server

Parameters

  nSessionID | [in] Which session ID of the P2PTunnel session to be disconnect

Returns
  - TUNNEL_ER_NoERROR if connect successfully
  - TUNNEL_ER_INVALID_ARG The session ID is not in valid range.

TUNNEL_API int P2PTunnelAgent_GetFreeSession | ( | void |  | ) |

Used by an agent to get a free session ID.

This function is for an agent to get a free session ID used for a parameter of P2PTunnelAgent_Connect_Parallel().

Returns
  Tunnel Session ID if return value >= 0
  Error code if return value < 0
  - TUNNEL_ER_NO_FREE_SESSION Current tunnel session are full.

TUNNEL_API void P2PTunnelAgent_GetStatus | ( | tunnelStatusCB | pfxTunnelStatusFn,
|  | void * | pArg
| ) |  |

Used by a tunnel agent to get the tunnel status.

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.

Parameters

  pfxTunnelStatusFn | [in] The function pointer to getting tunnel status function
  pArg | [in] User can give data pointer to pass to pfxSessionInfoFn when this call back function is triggered. Can be NULL.

TUNNEL_API int P2PTunnelAgent_PortMapping | ( | int | nSessionID,
|  | unsigned short | nLocalPort,
|  | unsigned short | nRemotePort
| ) |  |

Start port mapping service.

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.

Parameters

  nSessionID | [in] Which session ID of the P2PTunnel session to process the port mapping service
  nLocalPort | [in] The local port used to create a tunnel with the tunnel server
  nRemotePort | [in] The remote port defined in the tunnel server to create a tunnel

Returns
  The port mapping index if return value >= 0
  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 void P2PTunnelAgent_Set_Log_Path | ( | const char * | path,
|  | int | nMaxSize
| ) |  |

Set path of log file.

Set the absolute path of log file

Parameters

  path | [in] The path of log file, NULL = disable Log
  nMaxSize | [in] The maximum size of log file in Bytes, 0 = unlimit

TUNNEL_API void P2PTunnelAgent_StopPortMapping | ( | unsigned int | nPortMappingIdx | ) |

Stop port mapping service.

This function used by a tunnel agent to stop port mapping service on a given port mapping index which is started by P2PTunnelAgent_PortMapping()

Parameters

  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 int P2PTunnelAgent_StopPortMapping_byIndexArray | ( | unsigned int * | indexArray,
|  | unsigned int | indexNum
| ) |  |

Stop port mapping service.

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()

Parameters

  indexArray | [in] An integer array of the port mapping index in P2PTunnelAgent_PortMapping() indexNum is the number of the port mapping index in indexArray

Returns
  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 P2PTunnelAgentDeInitialize | ( | void |  | ) |

Deinitialize P2PTunnel module in a tunnel agent.

This function will deinitialize P2PTunnel module in a tunnel agent

Returns
  TUNNEL_ER_NoERROR if deinitialize successfully
  Error code if return value < 0
  - TUNNEL_ER_NOT_INITIALIZED the P2PTunnel module is not initialized yet.

See Also
  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 P2PTunnelAgentInitialize | ( | unsigned int | nMaxConnection | ) |

Initialize P2PTunnel module in a tunnel agent.

This function is used by a tunnel agent to initialize P2PTunnel module and shall be called before any P2PTunnel module related function is invoked.

Parameters

  nMaxConnection | [in] Specify max number of tunnel agents that can connect to tunnel servers

Returns
  TUNNEL_ER_NoERROR if initializing successfully
  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 Also
  P2PTunnelAgentDeInitialize()

TUNNEL_API int P2PTunnelServer_Disconnect | ( | int | nSessionID | ) |

Used by a tunnel server to disconnect a tunnel session.

This function will disconnect a tunnel session anytime after tunnel session established and it call be called anywhere.

Parameters

  nSessionID | [in] Which session ID of the P2PTunnel session established

Returns
  TUNNEL_ER_NoERROR if disconnect P2PTunnel session successfully
  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_GetSessionInfo | ( | tunnelSessionInfoCB | pfxSessionInfoFn,
|  | void * | pArg
| ) |  |

Used by a tunnel server to get the tunnel session information.

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.

Parameters

  pfxSessionInfoFn | [in] The function pointer to get tunnel session information function
  pArg | [in] User can give data pointer to pass to pfxSessionInfoFn when this call back function is triggered. Can be NULL.

Returns
  TUNNEL_ER_NoERROR if register successfully
  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 void P2PTunnelServer_GetStatus | ( | tunnelStatusCB | pfxTunnelStatusFn,
|  | void * | pArg
| ) |  |

Used by a tunnel server to get the tunnel status.

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.

Parameters

  pfxTunnelStatusFn | [in] The function pointer to get tunnel status function
  pArg | [in] User can give data pointer to pass to pfxSessionInfoFn when this call back function is triggered. Can be NULL.

TUNNEL_API int P2PTunnelServer_Start | ( | const char * | cszUID | ) |

Start a tunnel server.

This function will start a tunnel server with given UID

Parameters

  cszUID | [in] The UID of that tunnel server

Returns
  TUNNEL_ER_NoERROR if start successfully
  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 void P2PTunnelServer_Stop | ( | void |  | ) |

Stop a tunnel server.

This function will stop a tunnel server

TUNNEL_API int P2PTunnelServerDeInitialize | ( | void |  | ) |

Deinitialize P2PTunnel module in a tunnel server.

This function will deinitialize P2PTunnel module in a tunnel server

Returns
  TUNNEL_ER_NoERROR if deinitialize successfully
  Error code if return value < 0
  - TUNNEL_ER_NOT_INITIALIZED the P2PTunnel module is not initialized yet.

See Also
  P2PTunnelServerInitialize()

Attention
  Must call P2PTunnelServer_Stop() before calling this function, otherwise resource in P2PTunnel module will not be freed.

TUNNEL_API int P2PTunnelServerInitialize | ( | unsigned int | nMaxAgentConnection | ) |

Initialize P2PTunnel module in a tunnel server.

This function is used by a tunnel server to initialize P2PTunnel module and shall be called before any P2PTunnel module related function is invoked.

Parameters

  nMaxAgentConnection | [in] Specify max number of tunnel agents that can connect to this tunnel server

Returns
  TUNNEL_ER_NoERROR if initializing successfully
  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 Also
  P2PTunnelServerDeInitialize()