Routines to create clients talking the OIC protocol. More...

Data Structures
struct	sol_oic_resource
	Structure defining an OIC resource. More...

Typedefs
typedef struct sol_oic_client	sol_oic_client
	Opaque handler for an OIC client instance. More...

typedef struct sol_oic_pending	sol_oic_pending
	Represents a pending OIC client call. More...

typedef struct sol_oic_resource	sol_oic_resource
	Structure defining an OIC resource. More...

Functions
void	sol_oic_client_del (struct sol_oic_client *client)
	Delete client. More...

struct sol_oic_pending *	sol_oic_client_find_resources (struct sol_oic_client client, struct sol_network_link_addr addr, const char resource_type, const char resource_interface, bool(resource_found_cb)(void data, struct sol_oic_client cli, struct sol_oic_resource res), const void *data)
	Send a discovevery packet to find resources. More...

struct sol_oic_pending *	sol_oic_client_get_platform_info (struct sol_oic_client client, struct sol_oic_resource resource, void(info_received_cb)(void data, struct sol_oic_client cli, const struct sol_oic_platform_info info), const void *data)
	Retrieve platform information. More...

struct sol_oic_pending *	sol_oic_client_get_platform_info_by_addr (struct sol_oic_client client, struct sol_network_link_addr addr, void(info_received_cb)(void data, struct sol_oic_client cli, const struct sol_oic_platform_info info), const void *data)
	Retrieve platform information from addr. More...

struct sol_oic_pending *	sol_oic_client_get_server_info (struct sol_oic_client client, struct sol_oic_resource resource, void(info_received_cb)(void data, struct sol_oic_client cli, const struct sol_oic_device_info info), const void *data)
	Retrieve server information. More...

struct sol_oic_pending *	sol_oic_client_get_server_info_by_addr (struct sol_oic_client client, struct sol_network_link_addr addr, void(info_received_cb)(void data, struct sol_oic_client cli, const struct sol_oic_device_info info), const void *data)
	Retrieve server information from addr. More...

struct sol_oic_client *	sol_oic_client_new (void)
	Creates a new OIC client intance. More...

struct sol_oic_request *	sol_oic_client_non_confirmable_request_new (enum sol_coap_method method, struct sol_oic_resource *res)
	Create an OIC client request for an specific resource, using a non-confirmable CoAP packet. More...

struct sol_oic_pending *	sol_oic_client_request (struct sol_oic_client client, struct sol_oic_request request, void(callback)(void data, enum sol_coap_response_code response_code, struct sol_oic_client cli, const struct sol_network_link_addr addr, const struct sol_oic_map_reader repr_vec), const void callback_data)
	Send a request packet to server. More...

void	sol_oic_client_request_free (struct sol_oic_request *request)
	Release memory from a request. More...

struct sol_oic_map_writer *	sol_oic_client_request_get_writer (struct sol_oic_request *request)
	Get the packet writer from a client request. More...

struct sol_oic_request *	sol_oic_client_request_new (enum sol_coap_method method, struct sol_oic_resource *res)
	Create an OIC client request for an specific resource, using a confirmable CoAP packet. More...

int	sol_oic_client_resource_set_observable (struct sol_oic_client client, struct sol_oic_resource res, void(callback)(void data, enum sol_coap_response_code response_code, struct sol_oic_client cli, const struct sol_network_link_addr addr, const struct sol_oic_map_reader repr_map), const void data, bool observe)
	Set this resource as observable for this client. More...

int	sol_oic_client_resource_set_observable_non_confirmable (struct sol_oic_client client, struct sol_oic_resource res, void(callback)(void data, enum sol_coap_response_code response_code, struct sol_oic_client cli, const struct sol_network_link_addr addr, const struct sol_oic_map_reader repr_map), const void data, bool observe)
	Set this resource as observable for this client, using non-confirmable packets. More...

void	sol_oic_pending_cancel (struct sol_oic_pending *pending)
	Cancel a pending OIC call. More...

struct sol_oic_resource *	sol_oic_resource_ref (struct sol_oic_resource *r)
	Take a reference of the given server. More...

void	sol_oic_resource_unref (struct sol_oic_resource *r)
	Release a reference from the given resource. More...

Detailed Description

Routines to create clients talking the OIC protocol.

Typedef Documentation

sol_oic_client

Opaque handler for an OIC client instance.

It's created with sol_oic_client_new() and should be later deleted with sol_oic_client_del()

sol_oic_pending

Represents a pending OIC client call.

This can be used to cancel the pending call. Note that the context might die by other means, e.g. the user returning false on a request's response callback. The user is responsible for discarding invalid request contexts.

typedef struct sol_oic_resource sol_oic_resource

Structure defining an OIC resource.

It's open to the API user to bypass the need for getters for everything, but all fields are marked as const to emphasize that the user must not alter any of them.

Function Documentation

void sol_oic_client_del ( struct sol_oic_client * client )

Delete client.

All memory used by client and all resources associated with it will be freed.

Parameters

client The client to delete.

See Also: sol_oic_client_new()

Examples:: /src/samples/coap/iotivity-test-client.c, and /src/samples/coap/oic-client.c.

Referenced by main().

struct sol_oic_pending* sol_oic_client_find_resources	(	struct sol_oic_client *	client,
		struct sol_network_link_addr *	addr,
		const char *	resource_type,
		const char *	resource_interface,
		bool()(void data, struct sol_oic_client cli, struct sol_oic_resource res)	resource_found_cb,
		const void *	data
	)

Send a discovevery packet to find resources.

Sends a discovery packet to the destination address especified by addr, which may be a multicast address for discovery purposes.

When a response is received, the function resource_found_cb will be called. Note that multiple responses can be received for this request. As long as this function returns true, client will continue waiting for more responses. When the function returns false, the internal response handler will be freed and any new replies that may arrive for this request will be ignored. After an internal timeout is reached and the request is still alive, resource_found_cb will be called with a NULL oic_res. For this timeout invocation of resource_found_cb, if resource_found_cb returns true, client will continue waiting for responses until next a new timeout window closes, otherwise client will terminate response waiting.

Parameters

client	An OIC client instance.
addr	The address of the server that contains the desired resource. May be a multicast address if it is desired to look for resources in multiple servers.
resource_type	A string representation of the type of the desired resource. If empty or `NULL`, resources from all types will be discovered.
resource_interface	A string representation of the interface of the desired resource. If empty or `NULL`, resources with all interfaces will be discovered.
resource_found_cb	Callback to be called when a resource is found or when an internal timeout is reached. Parameter cli is the sol_oic_client used to perform the request, res is the resource that was discovered and data is a pointer to the user's data parameter.
data	A pointer to user's data.

Returns: A pending call handle on success, NULL otherwise (when errno will be set to one of EINVAL, ENOMEM, EIO, EOVERFLOW, ERANGE). It will be valid until resource_found_cb returns false.

Examples:: /src/samples/coap/iotivity-test-client.c, and /src/samples/coap/oic-client.c.

Referenced by main().

struct sol_oic_pending* sol_oic_client_get_platform_info	(	struct sol_oic_client *	client,
		struct sol_oic_resource *	resource,
		void()(void data, struct sol_oic_client cli, const struct sol_oic_platform_info info)	info_received_cb,
		const void *	data
	)

Retrieve platform information.

Sends a packet to resource's server asking for platform information defined at sol_oic_platform_info.

When a response is received, the function info_received_cb will be called, with info parameter filled with the information received, or NULL on errors.

After an internal timeout is reached, info_received_cb will be called with NULL info.

Parameters

client	An OIC client instance.
resource	The resource that is going to receive the request.
info_received_cb	Callback to be called when response is received or when timeout is reached. Parameter cli is the sol_oic_client used to perform the request, info is the sol_oic_platform_info structure with server info data, data is a pointer to user's data parameter.
data	A pointer to user's data.

Note: As info_received_cb is always called, it can be used to perform clean up operations.

Returns: A pending call handle on success, NULL otherwise (when errno will be set to one of EINVAL, ENOMEM, EIO, EOVERFLOW, ERANGE). It will be valid until info_received_cb is called.

struct sol_oic_pending* sol_oic_client_get_platform_info_by_addr	(	struct sol_oic_client *	client,
		struct sol_network_link_addr *	addr,
		void()(void data, struct sol_oic_client cli, const struct sol_oic_platform_info info)	info_received_cb,
		const void *	data
	)

Retrieve platform information from addr.

Sends a packet to server identified by addr asking for platform information defined at sol_oic_platform_info.

When a response is received, the function info_received_cb will be called, with info parameter filled with the information received, or NULL on errors.

After internal timeout is reached info_received_cb will be called with NULL info.

Parameters

client	An OIC client instance.
addr	The address of the server that contains the desired information.
info_received_cb	Callback to be called when response is received or when timeout is reached. Parameter cli is the sol_oic_client used to perform the request, info is the sol_oic_platform_info structure with server info data, data is a pointer to user's data parameter.
data	A pointer to user's data.

Note: As info_received_cb is always called, it can be used to perform clean up operations.

Returns: A pending call handle on success, NULL otherwise. (when errno will be set to one of EINVAL, ENOMEM, EIO, EOVERFLOW, ERANGE). It will be valid until info_received_cb is called.

Examples:: /src/samples/coap/iotivity-test-client.c.

Referenced by main().

struct sol_oic_pending* sol_oic_client_get_server_info	(	struct sol_oic_client *	client,
		struct sol_oic_resource *	resource,
		void()(void data, struct sol_oic_client cli, const struct sol_oic_device_info info)	info_received_cb,
		const void *	data
	)

Retrieve server information.

Sends a packet to resource's server asking for server information defined at sol_oic_device_info.

When a response is received, the function info_received_cb will be called, with info parameter filled with the information received, or NULL on errors.

After internal timeout is reached info_received_cb will be called with NULL info.

Parameters

client	An OIC client instance.
resource	The resource that is going to receive the request.
info_received_cb	Callback to be called when response is received or when timeout is reached. Parameter cli is the sol_oic_client used to perform the request, info is the sol_oic_device_info structure with server info data, data is a pointer to user's data parameter.
data	A pointer to user's data.

Note: As info_received_cb is always called, it can be used to perform clean up operations.

Returns: A pending call handle on success, NULL otherwise. (when errno will be set to one of EINVAL, ENOMEM, EIO, EOVERFLOW, ERANGE). It will be valid until info_received_cb is called

struct sol_oic_pending* sol_oic_client_get_server_info_by_addr	(	struct sol_oic_client *	client,
		struct sol_network_link_addr *	addr,
		void()(void data, struct sol_oic_client cli, const struct sol_oic_device_info info)	info_received_cb,
		const void *	data
	)

Retrieve server information from addr.

Sends a packet to server identified by addr asking for server information defined at sol_oic_device_info.

When a response is received, the function info_received_cb will be called, with info parameter filled with the information received, or NULL on errors.

After internal timeout is reached info_received_cb will be called with NULL info.

Parameters

client	An OIC client instance.
addr	The address of the server that contains the desired information.
info_received_cb	Callback to be called when response is received or when timeout is reached. Parameter cli is the sol_oic_client used to perform the request, info is the sol_oic_device_info structure with server info data, data is a pointer to user's data parameter.
data	A pointer to user's data.

Returns: A pending call handle on success, NULL otherwise (when errno will be set to one of EINVAL, ENOMEM, EIO, EOVERFLOW, ERANGE). It will be valid until info_received_cb is called.

Examples:: /src/samples/coap/iotivity-test-client.c.

Referenced by main().

struct sol_oic_client* sol_oic_client_new ( void )

Creates a new OIC client intance.

Returns: A new OIC client instance, or NULL in case of failure.

See Also: sol_oic_client_del()

Examples:: /src/samples/coap/iotivity-test-client.c, and /src/samples/coap/oic-client.c.

Referenced by main().

struct sol_oic_request* sol_oic_client_non_confirmable_request_new	(	enum sol_coap_method	method,
		struct sol_oic_resource *	res
	)

Create an OIC client request for an specific resource, using a non-confirmable CoAP packet.

Parameters

method	The coap request method as documented in sol_coap_method.
res	The resource that is going to receive the request.

Returns: A valid client request on success or NULL on errors.

Examples:: /src/samples/coap/iotivity-test-client.c.

Referenced by found_resource().

struct sol_oic_pending* sol_oic_client_request	(	struct sol_oic_client *	client,
		struct sol_oic_request *	request,
		void()(void data, enum sol_coap_response_code response_code, struct sol_oic_client cli, const struct sol_network_link_addr addr, const struct sol_oic_map_reader *repr_vec)	callback,
		const void *	callback_data
	)

Send a request packet to server.

Send a CoAP request packet to server and wait for a response. When the response arrives, callback will be called. The request memory will be freed by this function on success or failure.

Parameters

client	An OIC client instance.
request	A request created using sol_oic_client_request_new() or sol_oic_client_non_confirmable_request_new().
callback	Callback to be called when a response from this request arrives. Parameter response_code is the header response code of this request, cli is the client used to perform the request, addr is the address of the server and repr_vec is a handler to access data from response, using SOL_OIC_MAP_LOOP() macro. data is the user's callback_data. When timeout is reached and no packet has arrived, callback is called with `NULL` addr and `NULL` repr_vec so any clean up can be performed.
callback_data	User's data to be passed to callback.

Returns: A pending call handle on success, NULL otherwise (when errno will be set to one of EINVAL, ENOMEM, EIO, EOVERFLOW, ERANGE). It will be valid until callback is called.

Examples:: /src/samples/coap/iotivity-test-client.c, and /src/samples/coap/oic-client.c.

Referenced by found_resource(), and print_response().

void sol_oic_client_request_free ( struct sol_oic_request * request )

Release memory from a request.

Parameters

request A pointer to the request to be released.

struct sol_oic_map_writer* sol_oic_client_request_get_writer ( struct sol_oic_request * request )

Get the packet writer from a client request.

Parameters

request The request to retrieve the writer.

Returns: The packet writer from this request or NULL if the informed request is not a client request.

Examples:: /src/samples/coap/iotivity-test-client.c.

Referenced by found_resource().

struct sol_oic_request* sol_oic_client_request_new	(	enum sol_coap_method	method,
		struct sol_oic_resource *	res
	)

Create an OIC client request for an specific resource, using a confirmable CoAP packet.

Parameters

method	The coap request method as documented in sol_coap_method.
res	The resource that is going to receive the request.

Returns: A valid client request on success or NULL on errors.

Examples:: /src/samples/coap/iotivity-test-client.c, and /src/samples/coap/oic-client.c.

Referenced by found_resource(), and print_response().

int sol_oic_client_resource_set_observable	(	struct sol_oic_client *	client,
		struct sol_oic_resource *	res,
		void()(void data, enum sol_coap_response_code response_code, struct sol_oic_client cli, const struct sol_network_link_addr addr, const struct sol_oic_map_reader *repr_map)	callback,
		const void *	data,
		bool	observe
	)

Set this resource as observable for this client.

If the server providing the resource supports observing clients, this sends it a request to add client to its observing list. Clients in observation receive notifications when the server status for resources changes. When a notification is received by client, callback will be called. If the resource is not observable, client will emulate the observing behavior using a polling strategy, so callback will be notified with server changes from time to time.

To stop observing the server, call sol_oic_client_resource_set_observable() with observe as false.

Parameters

client	An OIC client instance.
res	The resource that is going to be observed
callback	A callback to be called when notification responses arrive. Parameter response_code is the header response code of this request, cli is the client used to perform the request, addr is the address of the server, repr_map is the data from the notification and data is a pointer to user's data. To extract data from repr_map use SOL_OIC_MAP_LOOP() macro. Callback is called with `NULL` addr and `NULL` repr_map when client is unobserved, so any clean up can be performed.
data	A pointer to user's data.
observe	If server will be obeserved or unobserved.

Returns: 0 on success or a negative number on errors.

Examples:: /src/samples/coap/iotivity-test-client.c.

Referenced by found_resource().

int sol_oic_client_resource_set_observable_non_confirmable	(	struct sol_oic_client *	client,
		struct sol_oic_resource *	res,
		void()(void data, enum sol_coap_response_code response_code, struct sol_oic_client cli, const struct sol_network_link_addr addr, const struct sol_oic_map_reader *repr_map)	callback,
		const void *	data,
		bool	observe
	)

Set this resource as observable for this client, using non-confirmable packets.

If the server providing the resource supports observing clients, this sends it a request to add client to its observing list. Clients in observation receive notifications when the server status for resources changes. When a notification is received by client, callback will be called. If the resource is not observable, client will emulate the observing behavior using a polling strategy, so callback will be notified with server changes from time to time.

When user wants to stop observing the server, call sol_oic_client_resource_set_observable() with observe as false.

The only difference from sol_oic_client_resource_set_observable() to this function is that it uses CoAP non-confirmable packets to make the request.

Parameters

client	An OIC client instance.
res	The resource that is going to be observed
callback	A callback to be called when notification responses arrive. Parameter response_code is the header response code of this request, cli is the client used to perform the request, addr is the address of the server, repr_map is the data from the notification and data is a pointer to user's data. To extract data from repr_map use SOL_OIC_MAP_LOOP() macro. Callback is called with `NULL` addr and `NULL` repr_map when client is unobserved, so any clean up can be performed.
data	A pointer to user's data.
observe	If server will be obeserved or unobserved.