#include "NebulaCommon.h"

Data Structures
struct	NebulaDeviceCtx

struct	NebulaSleepConfig

struct	NebulaWakeUpData

struct	NebulaPushFileObject

Macros
#define	MAX_PROFILE_LENGTH 45000

#define	NEBULA_MAX_SLEEP_ALIVE_PACKET_SIZE 256

#define	MAX_IP_STRING_LENGTH 46

#define	MAX_LONG_SLEEP_TCP_ALIVE_SEC (36060)

Typedefs
typedef struct NebulaDeviceCtx	NebulaDeviceCtx

typedef enum NebulaSocketProtocol	NebulaSocketProtocol

typedef struct NebulaSleepConfig	NebulaSleepConfig

typedef struct NebulaWakeUpData	NebulaWakeUpData

typedef struct NebulaPushFileObject	NebulaPushFileObject

typedef void(__stdcall *	NebulaIdentityHandleFn )(NebulaDeviceCtx device, const char identity, char *psk, unsigned int psk_size)
	The prototype of identity handle callback function.

typedef int(__stdcall *	NebulaCommandHandleFn )(NebulaDeviceCtx device, const char identity, const char func, const TUTKJsonObject args, TUTKJsonObject **response)
	The prototype of command handle callback function.

typedef int(__stdcall *	NebulaSettingsChangeHandleFn )(NebulaDeviceCtx device, const char settings)
	The prototype of deivce setting change handle callback function.

typedef int(__stdcall *	NebulaDeviceLoginStateFn )(NebulaDeviceCtx *device, NebulaDeviceLoginState state)
	The prototype of deivce login state callback function.

Enumerations
enum	NebulaSocketProtocol { NEBULA_PROTO_TCP, NEBULA_PROTO_UDP }

enum	NebulaDeviceLoginState { NEBULA_DEVLOGIN_ST_CONNECTED = 1 << 0, NEBULA_DEVLOGIN_ST_DISCONNECTED = 1 << 1, NEBULA_DEVLOGIN_ST_RETRYLOGIN = 1 << 2 }

enum	NebulaPushFileType { NEBULA_PUSH_FILE_BY_BUFFER, NEBULA_PUSH_FILE_BY_PATH }

Functions
NEBULA_API int	Nebula_Device_New (const char udid, const char secret_id, const char profile, NebulaCommandHandleFn command_handler, NebulaIdentityHandleFn identity_handler, NebulaSettingsChangeHandleFn settings_change_handler, NebulaDeviceCtx *ctx)
	Generat Device context for Nebula module.

NEBULA_API int	Nebula_Device_Login (NebulaDeviceCtx *ctx, NebulaDeviceLoginStateFn login_state_handler)
	Device login to Bridge server.

NEBULA_API int32_t	Nebula_Device_Max_Command_Handler_Thread_Count (NebulaDeviceCtx *ctx, int32_t thread_count)
	Device set max command handler thread count.

NEBULA_API int	Nebula_Device_Bind (NebulaDeviceCtx ctx, const char pin_code, const char psk, unsigned int timeout_msec, unsigned int abort_flag)
	Device bind to a client.

NEBULA_API int	Nebula_Device_New_Credential (const char udid, const char identity, const char psk, const char secret_id, char **credential)
	Device generate bind message for client.

NEBULA_API_DEPRECATED int	Nebula_Device_New_Local_Bind_Message (const char udid, const char psk, const char secret_id, char *bind_message_string)
	Device generate bind message for client.

NEBULA_API int	Nebula_Device_Load_Settings (NebulaDeviceCtx ctx, const char settings)
	Nebula device load settings.

NEBULA_API int	Nebula_Device_Push_Notification (NebulaDeviceCtx ctx, TUTKJsonObject notification_obj, unsigned int timeout_msec, unsigned int *abort_flag)
	Nebula device push a notification to server.

NEBULA_API int	Nebula_Device_Push_Thumbnail (NebulaDeviceCtx ctx, TUTKJsonObject notification_obj, NebulaPushFileObject thumbnail_obj, unsigned int timeout_msec, unsigned int abort_flag)
	Nebula device push a notification to server with thumbnail.

NEBULA_API int	Nebula_Device_Delete (NebulaDeviceCtx *ctx)
	Release device context.

NEBULA_API_DEPRECATED int	Nebula_Device_Get_Sleep_Packet (NebulaDeviceCtx ctx, const unsigned char pattern, unsigned int pattern_size, NebulaSocketProtocol protocol, NebulaWakeUpData *data, unsigned int data_count, unsigned int timeout_ms)
	Get packet to keep alive when device sleeping.

NEBULA_API int	Nebula_Device_Get_Sleep_PacketEx (NebulaDeviceCtx ctx, NebulaSleepConfig config, NebulaWakeUpData *data, unsigned int data_count, unsigned int timeout_ms)
	Get packet to keep alive when device sleeping.

NEBULA_API int	Nebula_Device_Free_Sleep_Packet (NebulaWakeUpData *data)
	Release wake up data from Nebula_Device_Get_Sleep_Packet.

Detailed Description

This file describes Nebula module APIs for device.

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

Macro Definition Documentation

#define MAX_IP_STRING_LENGTH 46

#define MAX_LONG_SLEEP_TCP_ALIVE_SEC (3*60*60)

#define MAX_PROFILE_LENGTH 45000

#define NEBULA_MAX_SLEEP_ALIVE_PACKET_SIZE 256

Typedef Documentation

typedef int(__stdcall * NebulaCommandHandleFn)(NebulaDeviceCtx *device, const char *identity, const char *func, const TUTKJsonObject *args, TUTKJsonObject **response)

The prototype of command handle callback function.

This callback function is called when Nebula client send request to Nebula device. Nebula device should handle the request and send an appropriate response. The profile or document might describe getNightMode as { "func":"getNightMode", "return": { "value":"Int" } } and setNightMode as { "func":"setNightMode", "args":{ "value":"Int" } } When the value of night mode is 10, please make a JSON response as { "value": 10 } There is no need to add key "content" here

Parameters

device	[in] Device's context generate by Nebula_Device_New()
identity	[in] The identity from Nebula client
fun	[out] The json object name
args	[out] The json object
response	[in] The json response object

See Also: Nebula_Device_New()

typedef struct NebulaDeviceCtx NebulaDeviceCtx

typedef int(__stdcall * NebulaDeviceLoginStateFn)(NebulaDeviceCtx *device, NebulaDeviceLoginState state)

The prototype of deivce login state callback function.

This callback function is called when device login state changed.

Parameters

device	[in] device's context generate by Nebula_Device_New()
state	[in] the login state of Nebula device

See Also: Nebula_Device_Login()

typedef void(__stdcall * NebulaIdentityHandleFn)(NebulaDeviceCtx *device, const char *identity, char *psk, unsigned int psk_size)

The prototype of identity handle callback function.

This callback function is called when Nebula module need to decrypt the data from Nebula client. Nebula device is required to provide the correspond psk when this callback is called.

Parameters

device	[in] device's context generate by Nebula_Device_New()
identity	[in] the identity from Nebula client
psk	[out] the pre share key keep in device that is correspond with the specific identity
psk_size	[in] size of psk.

See Also: Nebula_Device_New()

typedef struct NebulaPushFileObject NebulaPushFileObject

typedef int(__stdcall * NebulaSettingsChangeHandleFn)(NebulaDeviceCtx *device, const char *settings)

The prototype of deivce setting change handle callback function.

This callback function is called when settings of Nebula device changed. Nebula device should have a safekeeping of settings and should use Nebula_Device_Load_Settings() to load the settings when Nebula device restart next time.

Parameters

device	[in] device's context generate by Nebula_Device_New()
settings	[in] the encrypted settings string of Nebula device

See Also: Nebula_Device_New() Nebula_Device_Load_Settings()

typedef struct NebulaSleepConfig NebulaSleepConfig

typedef enum NebulaSocketProtocol NebulaSocketProtocol

typedef struct NebulaWakeUpData NebulaWakeUpData

Enumeration Type Documentation

enum NebulaDeviceLoginState

Enumerator:

NEBULA_DEVLOGIN_ST_CONNECTED
NEBULA_DEVLOGIN_ST_DISCONNECTED
NEBULA_DEVLOGIN_ST_RETRYLOGIN

enum NebulaPushFileType

Enumerator:

NEBULA_PUSH_FILE_BY_BUFFER
NEBULA_PUSH_FILE_BY_PATH

enum NebulaSocketProtocol

Enumerator:

NEBULA_PROTO_TCP
NEBULA_PROTO_UDP

Function Documentation

NEBULA_API int Nebula_Device_Bind	(	NebulaDeviceCtx *	ctx,
		const char *	pin_code,
		const char *	psk,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Device bind to a client.

This function is used by devices to binding client. Device bind to client with identity, pin code, avtoken and psk. This api can only being called once. Device need call Nebula_Device_Login before binding to client.

Parameters

ctx[in]	device's context generate by Nebula_Device_New()
pin_code[in]	device's pin code which for authenticating with client.
psk[in]	device's psk to encode/decode data in Nebula module
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 client successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx, pin_code, av_token or psk is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_BRIDGE_SERVER_NOT_LOGIN Device not login to bridge server yet
NEBULA_ER_TIMEOUT Query bind server timeout
NEBULA_ER_HTTP_ERROR Query or login bind Server response error

See Also: Nebula_Client_Bind()

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

NEBULA_API int Nebula_Device_Delete ( NebulaDeviceCtx * ctx )

Release device context.

This function will free device context that created by Nebula_Device_New()

Parameters

ctx[in] device's context generate by Nebula_Device_New;

Returns

NEBULA_ER_NoERROR if delete device context successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The input ctx is invalid.
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet

See Also: Nebula_Device_New()

NEBULA_API int Nebula_Device_Free_Sleep_Packet ( NebulaWakeUpData * data )

Release wake up data from Nebula_Device_Get_Sleep_Packet.

This function is used to release wake up data from Nebula_Device_Get_Sleep_Packet, you must call it after you got the wake up data from Nebula_Device_Get_Sleep_Packet

Parameters

data	[in] The wake up data pointer

Returns

#Nebula_ER_NoERROR if free wake up data successfully

Error code if return value < 0

#Nebula_ER_INVALID_ARG The data is null pointer

NEBULA_API_DEPRECATED int Nebula_Device_Get_Sleep_Packet	(	NebulaDeviceCtx *	ctx,
		const unsigned char *	pattern,
		unsigned int	pattern_size,
		NebulaSocketProtocol	protocol,
		NebulaWakeUpData **	data,
		unsigned int *	data_count,
		unsigned int	timeout_ms
	)

Get packet to keep alive when device sleeping.

This function is used to get keep alive packet information when device sleeping

Parameters

ctx	[in] device's context generate by Nebula_Device_New
pattern	[in] The wakeup pattern of device, see Nebula_Client_Wakeup_Device()
pattern_size	[in] The size fo wakeup pattern
protocol	[in] The protocol to send sleep packet
data	[out] The keep alive packet information, see NebulaWakeUpData
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever

Returns

NEBULA_ER_NoERROR if get the sleep packet successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx is null or protocol invalid
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_TIMEOUT Get sleep packet timeout

NEBULA_API int Nebula_Device_Get_Sleep_PacketEx	(	NebulaDeviceCtx *	ctx,
		NebulaSleepConfig *	config,
		NebulaWakeUpData **	data,
		unsigned int *	data_count,
		unsigned int	timeout_ms
	)

Get packet to keep alive when device sleeping.

This function is used to get keep alive packet information when device sleeping

Parameters

ctx	[in] device's context generate by Nebula_Device_New
config	[in] device's sleep information, see NebulaSleepConfig
data	[out] The keep alive packet information, see NebulaWakeUpData
data_count	[out] Information count of data
timeout_msec	[in] The timeout for this function in unit of millisecond, give 0 means block forever

Returns

NEBULA_ER_NoERROR if get the sleep packet successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx is null or protocol invalid
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_TIMEOUT Get sleep packet timeout

NEBULA_API int Nebula_Device_Load_Settings	(	NebulaDeviceCtx *	ctx,
		const char *	settings
	)

Nebula device load settings.

This function is used by device to load settings.

Parameters

ctx[in]	device's context generate by Nebula_Device_New()
settings[in]	the encrypted settings string of Nebula device

Returns

NEBULA_ER_NoERROR if load settings successfully

Error code if return value < 0

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

See Also: NebulaSettingsChangeHandleFn

NEBULA_API int Nebula_Device_Login	(	NebulaDeviceCtx *	ctx,
		NebulaDeviceLoginStateFn	login_state_handler
	)

Device login to Bridge server.

This function is used by devices to login to bridge server. Device can receive data from client that is binded by nebula module after logining to Bridge server. Device need to call this api before binding to client.

Parameters

ctx[in] device's context generate by Nebula_Device_New;

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_RESOURCE_ERROR Getting system resource fail
NEBULA_ER_BRIDGE_SERVER_LOGIN_FAIL Login to bridge server fail
NEBULA_ER_TIMEOUT Query bridge server timeout
NEBULA_ER_HTTP_ERROR Query bridge server response error
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

See Also: Nebula_Device_Bind()

NEBULA_API int32_t Nebula_Device_Max_Command_Handler_Thread_Count	(	NebulaDeviceCtx *	ctx,
		int32_t	thread_count
	)

Device set max command handler thread count.

This function is used by devices to set max command handler thread count. Device invoke command handler callback with thread, the maximum thread count is thread_count.

Parameters

ctx[in]	device's context generate by Nebula_Device_New.
thread_count[in]	max command handler thread count of device, default value is 5.

Returns

NEBULA_ER_NoERROR if set 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_DEVICE_NOT_READY Nebula device is not ready

NEBULA_API int Nebula_Device_New	(	const char *	udid,
		const char *	secret_id,
		const char *	profile,
		NebulaCommandHandleFn	command_handler,
		NebulaIdentityHandleFn	identity_handler,
		NebulaSettingsChangeHandleFn	settings_change_handler,
		NebulaDeviceCtx **	ctx
	)

Generat Device context for Nebula module.

This function will generate Device context for Nebula module. Device API for Nebula module need this context to work.

Parameters

udid	[in] device's udid for Nebula module
secret_id	[in] device's secret_id for Nebula module
profile	[in] device's profile for client to use.
command_handler	[in] Nebula command handler callback function
identity_handler	[in] identity handler callback function
settings_change_handler	[in] setting change handler callback function
ctx[out]	device's context generate by Nebula_Device_New;

Returns

NEBULA_ER_NoERROR if generate device context successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The udid, secret_id, profile, command_handler, identity_handler, settings_change_handler or ctx is null or profile length larger than MAX_PROFILE_LENGTH
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_MEM_INSUFFICIENT Insufficient memory for allocation
NEBULA_ER_FAIL_CREATE_THREAD Fails to create threads

See Also: Nebula_Device_Delete()

NEBULA_API int Nebula_Device_New_Credential	(	const char *	udid,
		const char *	identity,
		const char *	psk,
		const char *	secret_id,
		char **	credential
	)

Device generate bind message for client.

This function is used by devices to generate bind message. When Device get Nebula bind request from local client (BLE or AP mode LAN), this function can provide bind message to reaopnse.

Parameters

udid[in]	device's udid for Nebula module
identity[in]	an owner of the device for the Nebula module
psk[in]	device's psk to encode/decode data in Nebula module
secret_id[in]	device's secret_id for Nebula module
credential[out]	Nebula bind string for client

Returns

NEBULA_ER_NoERROR if generate message success

Error code if return value < 0

NEBULA_ER_INVALID_ARG The udid, psk , secret_id, identity is null or length invalid
NEBULA_ER_MEM_INSUFFICIENT Insufficient memory for allocation

See Also: Nebula_Client_New_From_String()

Attention: bind_message_string shall be free after use it

NEBULA_API_DEPRECATED int Nebula_Device_New_Local_Bind_Message	(	const char *	udid,
		const char *	psk,
		const char *	secret_id,
		char **	bind_message_string
	)

Device generate bind message for client.

This function is used by devices to generate bind message. When Device get Nebula bind request from local client (BLE or AP mode LAN), this function can provide bind message to reaopnse.

Parameters

udid[in]	device's udid for Nebula module
psk[in]	device's psk to encode/decode data in Nebula module
secret_id[in]	device's secret_id for Nebula module
bind_message_string[out]	Nebula bind string for client

Returns

NEBULA_ER_NoERROR if generate message success

Error code if return value < 0

NEBULA_ER_INVALID_ARG The udid, psk , secret_id is null or length invalid
NEBULA_ER_MEM_INSUFFICIENT Insufficient memory for allocation

See Also: Nebula_Client_New_From_String()

Attention: bind_message_string shall be free after use it, the Nebula_Device_New_Local_Bind_Message API had been deprecated, please use Nebula_Device_New_Credential API.

NEBULA_API int Nebula_Device_Push_Notification	(	NebulaDeviceCtx *	ctx,
		TUTKJsonObject *	notification_obj,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Nebula device push a notification to server.

This function is used by device to push a notification to server when some event happened and device want to notify Nebula clients with event messages.

Parameters

ctx[in]	device's context generate by Nebula_Device_New()
notification_obj[in]	The json object contains a list of key value pair for push server to generate the push message. The key and value should be a 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 bind to a client successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx or notification_obj is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_BRIDGE_SERVER_NOT_LOGIN Device not login to bridge server yet
NEBULA_ER_TIMEOUT Push notification to server timeout
NEBULA_ER_HTTP_ERROR Http error occurred when push notification to server

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

NEBULA_API int Nebula_Device_Push_Thumbnail	(	NebulaDeviceCtx *	ctx,
		TUTKJsonObject *	notification_obj,
		NebulaPushFileObject *	thumbnail_obj,
		unsigned int	timeout_msec,
		unsigned int *	abort_flag
	)

Nebula device push a notification to server with thumbnail.

This function is used by device to push a notification with thumbnail to server when some event happened and device want to notify Nebula clients with event messages.

Parameters

ctx[in]	device's context generate by Nebula_Device_New()
notification_obj[in]	The json object contains a list of key value pair for push server to generate the push message. The key and value should be a string.
thumbnail_obj[in]	Information of the thumbnail which will be pushed to server, see NebulaPushFileObject
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 client successfully

Error code if return value < 0

NEBULA_ER_INVALID_ARG The ctx or notification_obj is null
NEBULA_ER_NOT_INITIALIZE The Nebula module is not initialized yet
NEBULA_ER_BRIDGE_SERVER_NOT_LOGIN Device not login to bridge server yet
NEBULA_ER_TIMEOUT Push notification to server timeout
NEBULA_ER_HTTP_ERROR Http error occurred when push notification to server

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation