#include "NebulaCommon.h"

Data Structures
struct	NebulaClientCtx

struct	NebulaClientInfo

Typedefs
typedef struct NebulaClientCtx	NebulaClientCtx

typedef struct NebulaClientInfo	NebulaClientInfo

typedef void(__stdcall *	NebulaClientConnectStateFn )(NebulaClientCtx *client, NebulaClientLoginState state)
	The prototype of client connect state callback function.

Enumerations
enum	NebulaClientLoginState { NEBULA_CLILOGIN_ST_CONNECTED = 1 << 0, NEBULA_CLILOGIN_ST_DISCONNECTED = 1 << 1, NEBULA_CLILOGIN_ST_RETRYLOGIN = 1 << 2 }

Functions
NEBULA_API int	Nebula_Client_New (const char public_udid, NebulaClientCtx *ctx)
	Generat client context for Nebula module at first time.

NEBULA_API int	Nebula_Client_New_From_Struct (NebulaClientInfo client_info, NebulaClientCtx *ctx)
	Generate client context with device's information for Nebula module.

NEBULA_API int	Nebula_Client_New_From_String (const char public_udid, const char string_data, NebulaClientCtx **ctx)
	Generate client context with device's information for Nebula module.

NEBULA_API char *	Nebula_Client_To_String (NebulaClientCtx *ctx)
	Generating device's information for client which used to create client's context.

NEBULA_API int	Nebula_Client_Bind (NebulaClientCtx ctx, const char pin_code, TUTKJsonObject *bind_response, unsigned int timeout_msec, unsigned int abort_flag)
	Pairing Nebula Client and Device.

NEBULA_API int	Nebula_Client_Free_Bind_Response (TUTKJsonObject *bind_response)
	Release response data of Nebula_Client_Bind.

NEBULA_API int	Nebula_Client_Connect (NebulaClientCtx ctx, NebulaClientConnectStateFn connect_state_handler, unsigned int timeout_msec, unsigned int abort_flag)
	Client connect to Bridge server.

NEBULA_API int	Nebula_Client_Send_Command (NebulaClientCtx ctx, const char request, TUTKJsonObject *response, unsigned int timeout_msec, unsigned int abort_flag)
	Send Nubula command message to Device.

NEBULA_API int	Nebula_Client_Free_Send_Command_Response (TUTKJsonObject *response)
	Release response data of Nebula_Client_Send_Command.

NEBULA_API int	Nebula_Client_Wakeup_Device (NebulaClientCtx ctx, unsigned int timeout_msec, unsigned int abort_flag)
	Wake up sleep device.

NEBULA_API int	Nebula_Client_Check_Device_Online (NebulaClientCtx client, unsigned int timeout_msec, unsigned int abort_flag)
	Check device online.

NEBULA_API int	Nebula_Client_Delete (NebulaClientCtx *ctx)
	Release client context.

Detailed Description

This file describes Nebula module APIs for client.

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

Typedef Documentation

typedef void(__stdcall * NebulaClientConnectStateFn)(NebulaClientCtx *client, NebulaClientLoginState state)

The prototype of client connect state callback function.

This callback function is called when client connect state changed.

Parameters

client	[in] client's context generate by Nebula_Client_New()
state	[in] the connect state of Nebula client

See Also: Nebula_Client_Connect()

typedef struct NebulaClientCtx NebulaClientCtx

typedef struct NebulaClientInfo NebulaClientInfo

Enumeration Type Documentation

enum NebulaClientLoginState

Enumerator:

NEBULA_CLILOGIN_ST_CONNECTED
NEBULA_CLILOGIN_ST_DISCONNECTED
NEBULA_CLILOGIN_ST_RETRYLOGIN

Function Documentation

NEBULA_API int Nebula_Client_Bind	(	NebulaClientCtx *	ctx,
		const char *	pin_code,
		TUTKJsonObject **	bind_response,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Pairing Nebula Client and Device.

This function is used when Nebula client want to bind a Nebula device. Device and client need to use same pin code when doing binding process, after bind success, client will get infomations that is needed for establish a connection to device.

Parameters

client_ctx	[in] Nebula context of client, it's from Nebula_Client_New() or Nebula_Client_New_From_String()
pin_code	[in] Same PIN code of Nebula_Device_Bind()
bind_response	[out] The bind response json object,this object has identity, avToken and authKey
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever
abort_flag	[in] set *abort_flag to 1 if you need to abort this function

Returns

NEBULA_ER_NoERROR if bind to a device successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx, pin_code or json_response is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_BIND_SERVER_LOGIN_FAIL Failed to login to binding server
NEBULA_ER_DEVICE_NOT_READY Device not ready for binding
NEBULA_ER_EXCEED_BUFFER_SIZE If generate json string size larger than response_buf_size
NEBULA_ER_TIMEOUT Bind or query bind server timeout
NEBULA_ER_HTTP_ERROR Bind or query bind Server response error

See Also: Nebula_Device_Bind(), Nebula_Client_New(), Nebula_Client_New_From_String()

Attention: (1) Recommended value of timeout: 1000 millisecond ~ 30000 millisecond (2) Once the client bind to a sepecific device successfully, there is no need to do binding again when client want to connect to the device next time.

NEBULA_API int Nebula_Client_Check_Device_Online	(	NebulaClientCtx *	client,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Check device online.

This function will check if device login to bridge server

Parameters

ctx	[in] Nebula context of client, it's from Nebula_Client_New() or Nebula_Client_New_From_String()
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever
abort_flag	[in] set *abort_flag to 1 if you need to abort this function

Returns

NEBULA_ER_NoERROR if device login to bridge server

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_CLIENT_NOT_BIND_TO_DEVICE Client is not bind to device yet
NEBULA_ER_INVALID_UDID The UDID is incorrect
NEBULA_ER_UDID_EXPIRED The UDID is expired
NEBULA_ER_TIMEOUT Wakeup deivce timeout
NEBULA_ER_DEVICE_OFFLINE Device offline
NEBULA_ER_DEVICE_SLEEPING Device sleeping
NEBULA_ER_DEVICE_AWAKENING Device awakening

NEBULA_API int Nebula_Client_Connect	(	NebulaClientCtx *	ctx,
		NebulaClientConnectStateFn	connect_state_handler,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Client connect to Bridge server.

This function is used by client to connect to bridge server. Client will create persistent connection with bridge server for reduce delay of send command This function is unnecessary before Nebula_Client_Send_Command()

Parameters

ctx[in]	client's context generate by Nebula_Client_New()
connect_state_handler[in]	this function will be call when connect status change
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever
abort_flag	[in] set *abort_flag to 1 if you need to abort this function

Returns

NEBULA_ER_NoERROR if login to Nebula server successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_LOGIN_ALREADY_CALLED This function already called
NEBULA_ER_INVALID_UDID The UDID is incorrect
NEBULA_ER_UDID_EXPIRED The UDID is expired
NEBULA_ER_FAIL_CREATE_THREAD Fails to create threads

See Also: Nebula_Client_New() ,Nebula_Client_New_From_Struct(), Nebula_Client_New_From_String(), Nebula_Client_Send_Command()

NEBULA_API int Nebula_Client_Delete ( NebulaClientCtx * ctx )

Release client context.

This function will free client context that created by Nebula_Client_New()

Parameters

client_ctx [in] Nebula context of client, it's from Nebula_Client_New() or Nebula_Client_New_From_String()

Returns

NEBULA_ER_NoERROR if delete client context successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet

See Also: Nebula_Client_New(), Nebula_Client_New_From_String()

NEBULA_API int Nebula_Client_Free_Bind_Response ( TUTKJsonObject * bind_response )

Release response data of Nebula_Client_Bind.

This function is used to release json response data from Nebula_Client_Bind, you must call it after you got the json response data from Nebula_Client_Bind

Parameters

bind_response [in] This json response data pointer

Returns

#Nebula_ER_NoERROR if free json response data pointer successfully

Error code if return value < 0

#Nebula_ER_INVALID_ARG The bind_response in null

NEBULA_API int Nebula_Client_Free_Send_Command_Response ( TUTKJsonObject * response )

Release response data of Nebula_Client_Send_Command.

This function is used to release json response data from Nebula_Client_Send_Command, you must call it after you got the json response data from Nebula_Client_Send_Command

Parameters

response [in] This json response data pointer

Returns

#Nebula_ER_NoERROR if free json response data pointer successfully

Error code if return value < 0

#Nebula_ER_INVALID_ARG The response in null

NEBULA_API int Nebula_Client_New	(	const char *	public_udid,
		NebulaClientCtx **	ctx
	)

Generat client context for Nebula module at first time.

This function will generate client context for Nebula module. Client API for Nebula module need this context to work. Client need to call this api if never bind to device before. User can call Nebula_Client_New_From_String replace this api if user already bind to device.

Parameters

public_udid	[in] device's public_udid for Nebula module
ctx[out]	client's context generate by Nebula_Client_New or Nebula_Client_New_From_String;

Returns

NEBULA_ER_NoERROR if generate client context successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx or public_udid is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_MEM_INSUFFICIENT Insufficient memory for allocation

See Also: Nebula_Device_Delete()

NEBULA_API int Nebula_Client_New_From_String	(	const char *	public_udid,
		const char *	string_data,
		NebulaClientCtx **	ctx
	)

Generate client context with device's information for Nebula module.

This function will generate client context for Nebula module. Client API for Nebula module need this context to work. Client call this api if have bind to device and get device'information before.

Parameters

public_udid	[in] device's public_udid for Nebula module
string_data	[in] client's information that return by Nebula_Client_To_String.
ctx[out]	client's context generate by Nebula_Client_New or Nebula_Client_New_From_String;

Returns

NEBULA_ER_NoERROR if generate client context successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx or string_data is null or parsing string_data return null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_MEM_INSUFFICIENT Insufficient memory for allocation

See Also: Nebula_Client_To_String()

NEBULA_API int Nebula_Client_New_From_Struct	(	NebulaClientInfo *	client_info,
		NebulaClientCtx **	ctx
	)

Generate client context with device's information for Nebula module.

This function will generate client context for Nebula module. Client API for Nebula module need this context to work. Client call this api if have bind to device and get device'information before.

Parameters

NebulaClientInfo	[in] the necessary informations from Nebula device
ctx[out]	client's context generate by Nebula_Client_New or Nebula_Client_New_From_String;

Returns

NEBULA_ER_NoERROR if generate client context successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx or client_info is null or invalid UDID
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_MEM_INSUFFICIENT Insufficient memory for allocation

NEBULA_API int Nebula_Client_Send_Command	(	NebulaClientCtx *	ctx,
		const char *	request,
		TUTKJsonObject **	response,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Send Nubula command message to Device.

This function is used by Nebula client to send a command in json format. User can get response from Nebula device through the output response buffer. This function is not support for Nebula device currently.

Parameters

client_ctx	[in] Nebula context of client, it's from Nebula_Client_New() or Nebula_Client_New_From_String()
request	[in] JSON string of Nebula request
response	[out] The bind response json object
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever
abort_flag	[in] set *abort_flag to 1 if you need to abort this function

Returns

NEBULA_ER_NoERROR if exchange successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx, request or response is null.Or parsing request return null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_CLIENT_NOT_BIND_TO_DEVICE Client is not bind to device yet
NEBULA_ER_TIMEOUT Query or connect bridge server timeout
NEBULA_ER_RESOURCE_ERROR Getting system resource fail
NEBULA_ER_BRIDGE_SERVER_LOGIN_FAIL Login to bridge server fail
NEBULA_ER_DEVICE_OFFLINE Device offline
NEBULA_ER_DEVICE_SLEEPING Device sleeping
NEBULA_ER_DEVICE_AWAKENING Device awakening
NEBULA_ER_INVALID_UDID The UDID is incorrect
NEBULA_ER_UDID_EXPIRED The UDID is expired

Attention: (1) Recommended value of timeout: 1000 millisecond ~ 30000 millisecond

NEBULA_API char* Nebula_Client_To_String ( NebulaClientCtx * ctx )

Generating device's information for client which used to create client's context.

This function will generate device's information in json string after bind to device successfully. This api must be used after calling Nebula_Client_Bind.

Parameters

ctx[in] client's context generate by Nebula_Client_New or Nebula_Client_New_From_String;

Returns: null if ctx's psk, secret_id or identity is null

See Also: Nebula_Device_Delete()

NEBULA_API int Nebula_Client_Wakeup_Device	(	NebulaClientCtx *	ctx,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Wake up sleep device.

This function will wakeup sleeping device by sending wakeup pattern in Nebula_Device_Get_Sleep_Packet()

Parameters

ctx	[in] Nebula context of client, it's from Nebula_Client_New() or Nebula_Client_New_From_String()
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever
abort_flag	[in] set *abort_flag to 1 if you need to abort this function

Returns

NEBULA_ER_NoERROR if wakeup device successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_CLIENT_NOT_BIND_TO_DEVICE Client is not bind to device yet
NEBULA_ER_TIMEOUT Wakeup deivce timeout
NEBULA_ER_DEVICE_ONLINE Device already awakened
NEBULA_ER_DEVICE_OFFLINE Device offline
NEBULA_ER_SERVICE_UNAVAILABLE Nebula Server not in service
NEBULA_ER_INVALID_UDID The UDID is incorrect
NEBULA_ER_UDID_EXPIRED The UDID is expired

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation