#include <stdint.h>
#include <stdbool.h>
#include "st_things_types.h"

Typedefs
typedef bool(*	st_things_get_request_cb )(st_things_get_request_message_s req_msg, st_things_representation_s resp_rep)
	Callback for handling GET request. More...

typedef bool(*	st_things_set_request_cb )(st_things_set_request_message_s req_msg, st_things_representation_s resp_rep)
	Callback for handling SET(POST) request. More...

typedef bool(*	st_things_reset_confirm_cb )(void)
	Callback for getting user's opinion regarding device reset. More...

typedef void(*	st_things_reset_result_cb )(bool is_success)
	Callback for carrying the result of reset. More...

typedef void(*	st_things_pin_generated_cb )(const char *pin_data, const size_t pin_size)
	Callback for carrying the randomly generated PIN info. More...

typedef void(*	st_things_pin_display_close_cb )(void)
	Callback for informing the application to close the PIN display. More...

typedef bool(*	st_things_user_confirm_cb )(void)
	Callback for getting user's input regarding mutual verification. More...

typedef void(*	st_things_status_change_cb )(st_things_status_e things_status)
	Callback for getting the current state of ST Things. More...

Functions
int	st_things_initialize (const char json_path, bool easysetup_complete)
	Initializes things stack and returns whether easy-setup is completed or not. Easy-setup enable users to acquire the ownership of things and to connect the things with the cloud. After performing easy-setup, users can access things from anywhere through the cloud. In things stack, easy-setup is a primary and the first operation to be performed on the thing. Application running on the thing can know whether easy-setup is done already or not. If easy-setup is done, app can start the things stack by calling st_things_start(). If easy-setup is not done, app can either wait for the user interaction before starting the things stack or start the things stack directly without waiting for any events(This case is for those things which doesn't support input capability and for all other unknown cases). To use a new json file after initialization, stack should be deinitialized and stopped(if its started already). More...

int	st_things_deinitialize (void)
	Deinitializes things stack. Stack should have been initialized before calling this API. More...

int	st_things_register_request_cb (st_things_get_request_cb get_cb, st_things_set_request_cb set_cb)
	Callback registration function for handling request messages. More...

int	st_things_start (void)
	Starts things stack. Parses the thing definition(whose path is passed to st_things_initialize(), configures the thing, creates the resources and prepares it for easy-setup. If easy-setup is not done yet, onboarding will be started using either SoftAP or BLE connection. Onboarding creates an ad-hoc network between the thing and the client for performing easy-setup. If easy-setup is already done, thing will be connected with the cloud. Application can know whether easy-setup is done or not through st_things_initialize API. Stack should have been initialized before calling this API. More...

int	st_things_stop (void)
	Stops things stack. Removes all the data being used internally and releases all the memory allocated for the stack. Stack should have been initialized and started before calling this API. More...

int	st_things_register_reset_cb (st_things_reset_confirm_cb confirm_cb, st_things_reset_result_cb result_cb)
	Callback registration function for Reset-Confirmation and Reset-Result functions. More...

int	st_things_reset (void)
	Reset all the data related to security and cloud being used in the stack. Stack should have been initialized and started before calling this API. More...

int	st_things_register_pin_handling_cb (st_things_pin_generated_cb generated_cb, st_things_pin_display_close_cb close_cb)
	Callback registration function for getting randomly generated PIN for the PIN-Based Ownership Transfer Request. More...

int	st_things_register_user_confirm_cb (st_things_user_confirm_cb confirm_cb)
	Callback registration function for getting user confirmation for MUTUAL VERIFICATION BASED JUST WORK Ownership transfer. More...

int	st_things_register_things_status_change_cb (st_things_status_change_cb status_cb)
	Callback registration function for getting notified when ST Things state changes. More...

int	st_things_notify_observers (const char *resource_uri)
	Notify the observers of a specific resource. Stack should have been initialized and started before calling this API. More...

st_things_representation_s *	st_things_create_representation_inst (void)
	Create an instance of representation. More...

void	st_things_destroy_representation_inst (st_things_representation_s *rep)
	Destroy an instance of representation. More...

Typedef Documentation

typedef bool(* st_things_get_request_cb)(st_things_get_request_message_s *req_msg, st_things_representation_s *resp_rep)

Callback for handling GET request.

Parameters

[in]	req_msg	GET request message.
[out]	resp_rep	Representation that will be set to payload of response.

Returns: true in case of success, otherwise false

typedef void(* st_things_pin_display_close_cb)(void)

Callback for informing the application to close the PIN display.

typedef void(* st_things_pin_generated_cb)(const char *pin_data, const size_t pin_size)

Callback for carrying the randomly generated PIN info.

Device should show the PIN on display.

Parameters

[in]	pin_data	PIN data in string format.
[in]	pin_size	Length of the PIN String.

typedef bool(* st_things_reset_confirm_cb)(void)

Callback for getting user's opinion regarding device reset.

Returns: true to confirm, otherwise to deny

typedef void(* st_things_reset_result_cb)(bool is_success)

Callback for carrying the result of reset.

Parameters

[in] is_success Result of Stack-reset. (true : success, false : failure)

typedef bool(* st_things_set_request_cb)(st_things_set_request_message_s *req_msg, st_things_representation_s *resp_rep)

Callback for handling SET(POST) request.

Parameters

[in]	req_msg	SET request message.
[out]	resp_rep	Representation that will be set to payload of response.

Returns: true in case of success, otherwise false

typedef void(* st_things_status_change_cb)(st_things_status_e things_status)

Callback for getting the current state of ST Things.

Parameters

[in] things_status ST Things State

typedef bool(* st_things_user_confirm_cb)(void)

Callback for getting user's input regarding mutual verification.

Returns: true true in cse of confirmed, otherwise false

Function Documentation

st_things_representation_s* st_things_create_representation_inst ( void )

Create an instance of representation.

Remarks: To destroy an instance, st_things_destroy_representation_inst() should be used.

Returns: a pointer of the created representation, otherwise a null pointer if the memory is insufficient.

int st_things_deinitialize ( void )

Deinitializes things stack. Stack should have been initialized before calling this API.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed
ST_THINGS_ERROR_STACK_NOT_INITIALIZED	Stack is not initialized. Initialize the stack by calling st_things_initialize().
ST_THINGS_ERROR_STACK_RUNNING	Stack is currently running. Before deinitialize, stack needs to be stopped by calling st_things_stop().

void st_things_destroy_representation_inst ( st_things_representation_s * rep )

Destroy an instance of representation.

Parameters

[in] rep Representation that will be destroyed.

int st_things_initialize	(	const char *	json_path,
		bool *	easysetup_complete
	)

Initializes things stack and returns whether easy-setup is completed or not. Easy-setup enable users to acquire the ownership of things and to connect the things with the cloud. After performing easy-setup, users can access things from anywhere through the cloud. In things stack, easy-setup is a primary and the first operation to be performed on the thing. Application running on the thing can know whether easy-setup is done already or not. If easy-setup is done, app can start the things stack by calling st_things_start(). If easy-setup is not done, app can either wait for the user interaction before starting the things stack or start the things stack directly without waiting for any events(This case is for those things which doesn't support input capability and for all other unknown cases). To use a new json file after initialization, stack should be deinitialized and stopped(if its started already).

Parameters

[in]	json_path	Path to Json file which defines a thing. Definition includes the device information, resources and their properties, configuration info for connectivity and easy-setup, etc.
[out]	easysetup_complete	Indicates whether easysetup is completed already or not.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed
ST_THINGS_ERROR_STACK_ALREADY_INITIALIZED	Stack already initialized. To initialize again, stack should be deinitilized first by calling st_things_deinitialize().
ST_THINGS_ERROR_STACK_RUNNING	Stack is currently running. To initialize again, stack should be stopped first by calling st_things_stop() and then deinitialized by calling st_things_deinitialize().

int st_things_notify_observers ( const char * resource_uri )

Notify the observers of a specific resource. Stack should have been initialized and started before calling this API.

Parameters

[in] resource_uri Resource URI of the resource which will be notified to observers.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed
ST_THINGS_ERROR_STACK_NOT_INITIALIZED	Stack is not intialized. Initialize the stack by calling st_things_initialize().
ST_THINGS_ERROR_STACK_NOT_STARTED	Stack is not started. Start the stack by calling st_things_start().

int st_things_register_pin_handling_cb	(	st_things_pin_generated_cb	generated_cb,
		st_things_pin_display_close_cb	close_cb
	)

Callback registration function for getting randomly generated PIN for the PIN-Based Ownership Transfer Request.

Remarks: Only one callback function can be set with this API.
If multiple callbacks are set, the last one is registered only.
And the callbacks are called in the internal thread, which is not detached,
so application should return it to get the next callbacks.

Parameters

[in]	generated_cb	Callback function that will be called when device receives a Ownership Transfer request from client.
[in]	close_cb	Callback function that will be called when Ownership Transfer is done so device can stop showing PIN on display. This parameter can be NULL if stop triggering is not needed.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed

int st_things_register_request_cb	(	st_things_get_request_cb	get_cb,
		st_things_set_request_cb	set_cb
	)

Callback registration function for handling request messages.

The callbacks ensure that a request message will be carried with one of the resource uris from json file of st_things_start().

Remarks: Only one callback function can be set with this API.
If multiple callbacks are set, the last one is registered only.
And the callbacks are called in the internal thread, which is not detached,
so application should return it to get the next callbacks.

Parameters

[in]	get_cb	Reference of the callback function to handle GET request.
[in]	set_cb	Reference of the callback function to handle SET(POST) request.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed

int st_things_register_reset_cb	(	st_things_reset_confirm_cb	confirm_cb,
		st_things_reset_result_cb	result_cb
	)

Callback registration function for Reset-Confirmation and Reset-Result functions.

Remarks: Only one callback function can be set with this API.
If multiple callbacks are set, the last one is registered only.
And the callbacks are called in the internal thread, which is not detached,
so application should return it to get the next callbacks.

Parameters

[in]	confirm_cb	Callback function that will be called to get the user's input when reset is triggered.
[in]	result_cb	Callback function that will be called after the reset process is done. This parameter can be NULL if notification for result of reset is not needed.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed

int st_things_register_things_status_change_cb ( st_things_status_change_cb status_cb )

Callback registration function for getting notified when ST Things state changes.

Remarks: Only one callback function can be set with this API.
If multiple callbacks are set, the last one is registered only.
And the callbacks are called in the internal thread, which is not detached,
so application should return it to get the next callbacks.

Parameters

[in] status_cb Refernce of the callback function to get ST Things status

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed

int st_things_register_user_confirm_cb ( st_things_user_confirm_cb confirm_cb )

Callback registration function for getting user confirmation for MUTUAL VERIFICATION BASED JUST WORK Ownership transfer.

Remarks: Only one callback function can be set with this API.
If multiple callbacks are set, the last one is registered only.
And the callbacks are called in the internal thread, which is not detached,
so application should return it to get the next callbacks.

Parameters

[in] confirm_cb Callback function that will be called when device receives a confirm request from client.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_INVALID_PARAMETER	Invalid parameter
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed

int st_things_reset ( void )

Reset all the data related to security and cloud being used in the stack. Stack should have been initialized and started before calling this API.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed
ST_THINGS_ERROR_STACK_NOT_INITIALIZED	Stack is not intialized. Initialize the stack by calling st_things_initialize().
ST_THINGS_ERROR_STACK_NOT_STARTED	Stack is not started. Start the stack by calling st_things_start().

int st_things_start ( void )

Starts things stack. Parses the thing definition(whose path is passed to st_things_initialize(), configures the thing, creates the resources and prepares it for easy-setup. If easy-setup is not done yet, onboarding will be started using either SoftAP or BLE connection. Onboarding creates an ad-hoc network between the thing and the client for performing easy-setup. If easy-setup is already done, thing will be connected with the cloud. Application can know whether easy-setup is done or not through st_things_initialize API. Stack should have been initialized before calling this API.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful. It is also used for the case that the stack is started already.
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed
ST_THINGS_ERROR_STACK_NOT_INITIALIZED	Stack is not initialized. Initialize the stack by calling st_things_initialize().

int st_things_stop ( void )

Stops things stack. Removes all the data being used internally and releases all the memory allocated for the stack. Stack should have been initialized and started before calling this API.

Returns: 0 on success, otherwise a negative error value

Return values

ST_THINGS_ERROR_NONE	Successful
ST_THINGS_ERROR_OPERATION_FAILED	Operation failed
ST_THINGS_ERROR_STACK_NOT_INITIALIZED	Stack is not initialized. Initialize the stack by calling st_things_initialize().
ST_THINGS_ERROR_STACK_NOT_STARTED	Stack is not started. Start the stack by calling st_things_start().

Typedefs

Functions

Typedef Documentation

Function Documentation