#include "P2PTunnelCommon.h"

Data Structures
struct	st_P2PTunnelSessionInfo

struct	st_P2PTunnelSessionInfoEx

Typedefs
typedef struct st_P2PTunnelSessionInfo	sP2PTunnelSessionInfo

typedef struct st_P2PTunnelSessionInfoEx	sP2PTunnelSessionInfoEx

typedef int32_t(__stdcall *	tunnelSessionInfoCB )(sP2PTunnelSessionInfo sSessionInfo, void pArg)

typedef void(__stdcall *	tunnelSessionInfoExCB )(sP2PTunnelSessionInfoEx sSessionInfo, const void pArg)

typedef int32_t(__stdcall *	tunnelPortVerifyCB )(uint16_t nServicePort, const void *pArg)

typedef uint16_t(__stdcall *	tunnelServiceVerifyCB )(const char cszServiceID, const void pArg)

typedef void(__stdcall *	tunnelServerAuthCB )(const char cszAccount, char cszPassword, uint32_t nPasswordMaxLength, const void *pArg)

Functions
TUNNEL_API_DEPRECATED int32_t	P2PTunnelServerInitialize (uint32_t nMaxAgentConnection)
	Initialize P2PTunnel module in a tunnel server.

TUNNEL_API int32_t	P2PTunnelServerInitialize2 (uint32_t nMaxAgentConnection, uint8_t bEnableLanDirect)
	Initialize P2PTunnel module in a tunnel server.

TUNNEL_API int32_t	P2PTunnelServerDeInitialize (void)
	Deinitialize P2PTunnel module in a tunnel server.

TUNNEL_API int32_t	P2PTunnelServer_Register_Port_Verify (tunnelPortVerifyCB pfxTunnelPortVerifyFn, const void *pArg)
	Register Callback function for verify service port.

TUNNEL_API int32_t	P2PTunnelServer_Register_Service_Verify (tunnelServiceVerifyCB pfxTunnelServiceVerifyFn, const void *pArg)
	Register Callback function for verify service id.

TUNNEL_API int32_t	P2PTunnelServer_Listen (const int32_t SID, const int32_t CHID)
	Use the existed iotc session to listen incoming P2PTunnel connection.

TUNNEL_API int32_t	P2PTunnelServer_Listen_Abort (const int32_t SID, const int32_t CHID)
	Used to gracefully stop P2PTunnelServer_Listen process.

TUNNEL_API_DEPRECATED int32_t	P2PTunnelServer_Start (const char *cszUID)
	Start a tunnel server.

TUNNEL_API int32_t	P2PTunnelServer_Start_Ex (const char cszUID, tunnelServerAuthCB pfxTunnelServerAuthFn, tunnelSessionInfoExCB pfxSessionInfoExFn, const void pArg)
	Start a tunnel server with DTLS mode.

TUNNEL_API void	P2PTunnelServer_GetStatus (tunnelStatusCB pfxTunnelStatusFn, void *pArg)
	Used by a tunnel server to get the tunnel status.

TUNNEL_API_DEPRECATED int32_t	P2PTunnelServer_GetSessionInfo (tunnelSessionInfoCB pfxSessionInfoFn, void *pArg)
	Used by a tunnel server to get the tunnel session information.

TUNNEL_API void	P2PTunnelServer_Stop (void)
	Stop a tunnel server.

TUNNEL_API int32_t	P2PTunnelServer_Disconnect (int32_t nSessionID)
	Used by a tunnel server to disconnect a tunnel session.

Detailed Description

This file describes P2PTunnel module APIs for agent.

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

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 struct st_P2PTunnelSessionInfoEx sP2PTunnelSessionInfoEx

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_Start_Ex() to register a call back function tunnelSessionInfoExCB

typedef int32_t(__stdcall * tunnelPortVerifyCB)(uint16_t nServicePort, const void *pArg)

The prototype of Tunnel server verify port of service.

Parameters

nServicePort	[in] port number that Tunnel agent want to access
pArg	[in] Tunnel server pass user data

Returns: 0 if port passes.; < 0 to reject access

typedef void(__stdcall * tunnelServerAuthCB)(const char *cszAccount, char *cszPassword, uint32_t nPasswordMaxLength, const void *pArg)

The prototype of authenticating connect informations, used by a tunnel server to be notified when connection start.

Parameters

cszAccount	[in] Account from tunnel agent
cszPassword	[out] The password input by user
nPasswordMaxLength	[in] Max size of cszPassword
pArg	[in] Tunnel server pass user data

Attention: Set empty string "" to cszPassword meas reject this tunnel connection

typedef uint16_t(__stdcall * tunnelServiceVerifyCB)(const char *cszServiceID, const void *pArg)

The prototype of Tunnel server to verify Service ID.

Parameters

cszServiceID	[in] Service ID that Tunnel agent want to access. Max length is MAX_SERVICE_ID_LEN(16).
pArg	[in] Tunnel server pass user data

Returns: Service port number if service ID passes.; 0 to reject access

typedef int32_t(__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 * tunnelSessionInfoExCB)(sP2PTunnelSessionInfoEx *sSessionInfo, const 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

Function Documentation

TUNNEL_API int32_t P2PTunnelServer_Disconnect ( int32_t 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 can 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_DEPRECATED int32_t 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

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 int32_t P2PTunnelServer_Listen	(	const int32_t	SID,
		const int32_t	CHID
	)

Use the existed iotc session to listen incoming P2PTunnel connection.

In order to use the same iotc session with other modules, please make sure you use different channel id for each module, for example, you can use channel 0 for AV connections and channel 1 for P2PTunnel connections

Parameters

SID	[in] Base on which IOTC session id you want to build P2PTunnel connection
CHID	[in] Base on which IOTC channel id you want to build P2PTunnel connection

Returns

TUNNEL_ER_NoERROR if deinitialize successfully

Error code if return value < 0

TUNNEL_ER_INVALID_ARG if the channel id is out of range
TUNNEL_ER_OPERATION_IS_INVALID if P2PTunnelSetConnectionOption is not set as TUNNEL_CONNECT_MANUAL mode and call P2PTunnelServer_Start_Ex or call this function with IOTC client
TUNNEL_ER_INVALID_SID if IOTC session id is invalid
TUNNEL_ER_HANDSHAKE_FAILED if P2PTunnel handshake failed
TUNNEL_ER_REMOTE_NOT_SUPPORT_DTLS Remote not support DTLS
- TUNNEL_ER_LOCAL_EXIT Force stop connecting process by other APIs.
- TUNNEL_ER_CREATE_DTLS_FAIL Create DTLS connection error.

See Also: P2PTunnelSetConnectionOption(), P2PTunnelAgent_Attach_Connect()

Attention: (1) Must be called after P2PTunnelSetConnectionOption is set as TUNNEL_CONNECT_MANUAL mode (2) Must be called after P2PTunnelServer_Start_Ex

TUNNEL_API int32_t P2PTunnelServer_Listen_Abort	(	const int32_t	SID,
		const int32_t	CHID
	)

Used to gracefully stop P2PTunnelServer_Listen process.

Parameters

SID	[in] Base on which IOTC session you want to stop P2PTunnel from listening on
CHID	[in] Base on which IOTC channel id you want to stop P2PTunnel from listening on

Returns

TUNNEL_ER_NoERROR if deinitialize successfully

Error code if return value < 0

TUNNEL_ER_INVALID_ARG if the channel id is out of range
TUNNEL_ER_OPERATION_IS_INVALID if P2PTunnelSetConnectionOption is not set as TUNNEL_CONNECT_MANUAL mode and call P2PTunnelServer_Start_Ex or call this function with IOTC client
TUNNEL_ER_INVALID_SID if IOTC session id is invalid
TUNNEL_ER_HANDSHAKE_FAILED if P2PTunnel handshake failed

See Also: P2PTunnelSetConnectionOption(), P2PTunnelAgent_Attach_Connect()

Attention: (1) Must be called after P2PTunnelSetConnectionOption is set as TUNNEL_CONNECT_MANUAL mode (2) Must be called after P2PTunnelServer_Start_Ex

TUNNEL_API int32_t P2PTunnelServer_Register_Port_Verify	(	tunnelPortVerifyCB	pfxTunnelPortVerifyFn,
		const void *	pArg
	)

Register Callback function for verify service port.

When Tunnel server recevice request for access service at specific port from remote, SDK will invoke callback function.

Parameters

pfxTunnelPortVerifyFn	[in] The function pointer to verify service port function. set NULL means allow all port.
pArg	[in] User can give data pointer to pass to pfxTunnelPortVerifyFn when this callback function is triggered. Can be NULL.

Returns

TUNNEL_ER_NoERROR if register successfully

Error code if return value < 0

TUNNEL_ER_NOT_INITIALIZED P2PModule has not been initialized in that tunnel server

TUNNEL_API int32_t P2PTunnelServer_Register_Service_Verify	(	tunnelServiceVerifyCB	pfxTunnelServiceVerifyFn,
		const void *	pArg
	)

Register Callback function for verify service id.

When Tunnel server recevice request for access service at specific service id from remote, SDK will invoke callback function.

Parameters

pfxTunnelServiceVerifyFn	[in] The function pointer to verify service id function.
pArg	[in] User can give data pointer to pass to pfxTunnelServiceVerifyFn when this callback function is triggered. Can be NULL.

Returns

TUNNEL_ER_NoERROR if register successfully

Error code if return value < 0

TUNNEL_ER_NOT_INITIALIZED P2PModule has not been initialized in that tunnel server

TUNNEL_API_DEPRECATED int32_t 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 int32_t P2PTunnelServer_Start_Ex	(	const char *	cszUID,
		tunnelServerAuthCB	pfxTunnelServerAuthFn,
		tunnelSessionInfoExCB	pfxSessionInfoExFn,
		const void *	pArg
	)

Start a tunnel server with DTLS mode.

This function will start a tunnel server with given UID

Parameters

cszUID	[in] The UID of that tunnel server
pfxTunnelServerAuthFn	[in] The function pointer of authenticate account function
pfxSessionInfoExFn	[in] The function pointer to get tunnel session information function. Can be NULL.
pArg	[in] User can give data pointer to pass to pfxTunnelServerAuthFn and pfxSessionInfoExFn when this call back function is triggered. Can be NULL.

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 int32_t 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.; This function can't be called simultaneously from multiple threads.

TUNNEL_API_DEPRECATED int32_t P2PTunnelServerInitialize ( uint32_t 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
TUTK_ER_NO_LICENSE_KEY Need to call TUTK_SDK_Set_License_Key() before all module start/initialize.

See Also: P2PTunnelServerDeInitialize(), TUTK_SDK_Set_License_Key()

Attention: This function can't be called simultaneously from multiple threads.

TUNNEL_API int32_t P2PTunnelServerInitialize2	(	uint32_t	nMaxAgentConnection,
		uint8_t	bEnableLanDirect
	)

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
bEnableLanDirect	[in] Transport data directly without TUTK forward mechanism when P2PTunnelAgent and P2PTunnelSever are on the same LAN.

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
TUTK_ER_NO_LICENSE_KEY Need to call TUTK_SDK_Set_License_Key() before all module start/initialize.

See Also: P2PTunnelServerDeInitialize(), TUTK_SDK_Set_License_Key()

Attention: This function can't be called simultaneously from multiple threads.; Lan direct isn't working with service mapping.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation