The file contains porting layer for implementation of the blocking queue. More...

#include <stdint.h>
#include "iotcs.h"
#include "advanced/iotcs_message.h"

Defines
#define	IOTCS_PORT_MESSAGE_QUEUE_SIZE 25
#define	IOTCS_PORT_REQUEST_QUEUE_SIZE 8
Typedefs
typedef void *	iotcs_port_message_queue
	Blocking queue that contains iotcs_message elements Queue size is build time constant IOTCS_PORT_MESSAGE_QUEUE_SIZE which is number of elements not a bytes count.
typedef void *	iotcs_port_request_queue
	Blocking queue that contains pointers to iotcs_request_message.
typedef void *	iotcs_port_request_handler_queue
	Blocking queue that contains pointers to iotcs_request_handler_message.
typedef void *	iotcs_port_storage_request_queue
	Blocking queue that contains pointers to iotcs_storage_request.
Functions
iotcs_port_message_queue	iotcs_port_message_queue_create ()
	Creates queue Queue size shell be IOTCS_PORT_MESSAGE_QUEUE_SIZE elements.
void	iotcs_port_message_queue_destroy (iotcs_port_message_queue queue)
	Destroys iotcs_port_message_queue If a queue is NULL, no operation is performed.
iotcs_result	iotcs_port_message_queue_put (iotcs_port_message_queue queue, iotcs_message *message, int32_t timeout_ms)
	Copies iotcs_message structure to the queue The whole iotcs_message structure pointed to by message is copied into the queue not just a pointer.
iotcs_result	iotcs_port_message_queue_get (iotcs_port_message_queue queue, iotcs_message *message, int32_t timeout_ms)
	Copies iotcs_message structure from the queue to given address The whole iotcs_message from queue is copied into structure pointed to by message not just a pointer.
int	iotcs_port_message_queue_count (iotcs_port_message_queue queue)
	Returns quantity of items in iotcs_port_message_queue Returned value is used to calculate message queue load factor.
iotcs_port_request_queue	iotcs_port_request_queue_create ()
	Creates queue Queue size shell be IOTCS_PORT_REQUEST_QUEUE_SIZE elements.
void	iotcs_port_request_queue_destroy (iotcs_port_request_queue queue)
	Destroys iotcs_port_request_queue If a queue is NULL, no operation is performed.
iotcs_result	iotcs_port_request_queue_put (iotcs_port_request_queue queue, iotcs_request_message *request, int32_t timeout_ms)
	Writes address of iotcs_request_message structure to the queue If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe.
iotcs_result	iotcs_port_request_queue_get (iotcs_port_request_queue queue, iotcs_request_message **request, int32_t timeout_ms)
	Gets iotcs_request_message address from the queue to given address If queue is not empty then call dequeue iotcs_request_message pointer from the queue and writes this pointer to *request address.
int	iotcs_port_request_queue_count (iotcs_port_request_queue queue)
	Returns quantity of items in iotcs_port_request_queue Returned value is used to calculate request queue load factor.
iotcs_port_request_queue	iotcs_port_storage_request_queue_create ()
	Creates queue Queue size shell be IOTCS_PORT_MEDIA_STORAGE_REQUEST_QUEUE_SIZE elements.
void	iotcs_port_storage_request_queue_destroy (iotcs_port_storage_request_queue queue)
	Destroys iotcs_port_storage_request_queue If a queue is NULL, no operation is performed.
iotcs_result	iotcs_port_storage_request_queue_put (iotcs_port_storage_request_queue queue, iotcs_storage_request *request, int32_t timeout_ms)
	Writes address of iotcs_storage_request structure to the queue If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe.
iotcs_result	iotcs_port_storage_request_queue_get (iotcs_port_storage_request_queue queue, iotcs_storage_request *request, int32_t timeout_ms)
	Gets iotcs_storage_object_handle address from the queue to given address If queue is not empty then call dequeue iotcs_storage_request pointer from the queue and writes this pointer to *request address.

Detailed Description

The file contains porting layer for implementation of the blocking queue.

Typedef Documentation

typedef void* iotcs_port_request_handler_queue

Blocking queue that contains pointers to iotcs_request_handler_message.

Queue size is build time constant IOTCS_REQUEST_HANDLER_THREAD_POOL_SIZE which is number of elements not a bytes count.

typedef void* iotcs_port_request_queue

Blocking queue that contains pointers to iotcs_request_message.

Queue size is build time constant IOTCS_PORT_REQUEST_QUEUE_SIZE which is number of elements not a bytes count.

typedef void* iotcs_port_storage_request_queue

Blocking queue that contains pointers to iotcs_storage_request.

Queue size is build time constant IOTCS_PORT_MEDIA_STORAGE_REQUEST_QUEUE_SIZE which is number of elements not a bytes count.

Function Documentation

int iotcs_port_message_queue_count ( iotcs_port_message_queue queue )

Returns quantity of items in iotcs_port_message_queue Returned value is used to calculate message queue load factor.

Calculated load factor is sent to IoT server in a response to counters request of urn:oracle:iot:dcd:capability:message_dispatcher device model as a value of load property.

Note:: Optional API. Called by the Library if IOTCS_MESSAGE_DISPATCHER option is defined.

Parameters:

queue a iotcs_port_message_queue handle

Returns:: a quantity of items in iotcs_port_message_queue

iotcs_port_message_queue iotcs_port_message_queue_create ( )

Creates queue Queue size shell be IOTCS_PORT_MESSAGE_QUEUE_SIZE elements.

Element's size is sizeof(iotcs_message) bytes. If IOTCS_MESSAGING_THREAD_SAFETY is defined then queue shell be blocking. That means iotcs_port_message_queue_put and iotcs_port_message_queue_get calls shall be thread-safe. Also these calls shall block if operation can't be done (no free space or no messages) and use timeout_ms argument as a maximum blocking time.

Note:: Optional API. Called by the Library if IOTCS_MESSAGE_DISPATCHER option is defined.

Returns:: NULL in case of fail

void iotcs_port_message_queue_destroy ( iotcs_port_message_queue queue )

Destroys iotcs_port_message_queue If a queue is NULL, no operation is performed.

Note:: Optional API. Called by the Library if IOTCS_MESSAGE_DISPATCHER option is defined.

Parameters:

queue a iotcs_port_message_queue handle

iotcs_result iotcs_port_message_queue_get	(	iotcs_port_message_queue	queue,
		iotcs_message *	message,
		int32_t	timeout_ms
	)

Copies iotcs_message structure from the queue to given address The whole iotcs_message from queue is copied into structure pointed to by message not just a pointer.

If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe. Also if queue is empty then the call shall block waiting for a message using timeout_ms argument as a maximum blocking time. If timeout is expired then error code IOTCS_RESULT_FAIL must be returned.

If IOTCS_MESSAGING_THREAD_SAFETY is NOT defined then timeout_ms argument shell be ignored treating it like a zero timeout.

Note:: Optional API. Called by the Library if IOTCS_MESSAGE_DISPATCHER option is defined.

Parameters:

queue	a non NULL queue handle
message	an address of iotcs_message structure to copy from the queue
timeout_ms	a timeout in milliseconds.If it is equal to 0 call shell not block. Negative number means infinite timeout.

Returns:: IOTCS_RESULT_OK success; IOTCS_RESULT_FAIL timeout expired; IOTCS_RESULT_OUT_OF_MEMORY failed to allocate dynamic memory

iotcs_result iotcs_port_message_queue_put	(	iotcs_port_message_queue	queue,
		iotcs_message *	message,
		int32_t	timeout_ms
	)

Copies iotcs_message structure to the queue The whole iotcs_message structure pointed to by message is copied into the queue not just a pointer.

If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe. Also if queue is full then the call shall block waiting for free space using timeout_ms argument as a maximum blocking time. If timeout is expired then error code IOTCS_RESULT_FAIL must be returned.

If IOTCS_MESSAGING_THREAD_SAFETY is NOT defined then timeout_ms argument shell be ignored treating it like a zero timeout.

Note:: Optional API. Called by the Library if IOTCS_MESSAGE_DISPATCHER option is defined.

Parameters:

queue	a non NULL queue handle
message	an address of iotcs_message structure to copy into the queue
timeout_ms	a timeout in milliseconds. If it is equal to 0 call shell not block. Negative number means infinite timeout.

Returns:: IOTCS_RESULT_OK success; IOTCS_RESULT_FAIL timeout expired; IOTCS_RESULT_OUT_OF_MEMORY failed to allocate dynamic memory

int iotcs_port_request_queue_count ( iotcs_port_request_queue queue )

Returns quantity of items in iotcs_port_request_queue Returned value is used to calculate request queue load factor.

Note:: Optional API. Called by the Library if IOTCS_MESSAGE_DISPATCHER option is defined.

Parameters:

queue a iotcs_port_request_queue handle

Returns:: a quantity of items in iotcs_port_request_queue

iotcs_port_request_queue iotcs_port_request_queue_create ( )

Creates queue Queue size shell be IOTCS_PORT_REQUEST_QUEUE_SIZE elements.

Element's size is sizeof(iotcs_request_message*) bytes. If IOTCS_MESSAGING_THREAD_SAFETY is defined then queue shell be blocking. That means iotcs_port_request_queue_put and iotcs_port_request_queue_get calls shall be thread-safe. Also these calls shall block if operation can't be done (no free space or no messages) and use timeout_ms argument as a maximum blocking time.

Note:: Mandatory API. Called by the Library in any configuration.

Returns:: NULL in case of fail

void iotcs_port_request_queue_destroy ( iotcs_port_request_queue queue )

Destroys iotcs_port_request_queue If a queue is NULL, no operation is performed.

Note:: Mandatory API. Called by the Library in any configuration.

Parameters:

queue a iotcs_port_request_queue handle

iotcs_result iotcs_port_request_queue_get	(	iotcs_port_request_queue	queue,
		iotcs_request_message **	request,
		int32_t	timeout_ms
	)

Gets iotcs_request_message address from the queue to given address If queue is not empty then call dequeue iotcs_request_message pointer from the queue and writes this pointer to *request address.

If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe. Also if queue is empty then the call shall block waiting for a message using timeout_ms argument as a maximum blocking time. If timeout is expired then error code IOTCS_RESULT_FAIL must be returned.

If IOTCS_MESSAGING_THREAD_SAFETY is NOT defined then timeout_ms argument shell be ignored treating it like a zero timeout.

Note:: Mandatory API. Called by the Library in any configuration.

Parameters:

queue	a non NULL queue handle
request	an address of pointer to iotcs_request_message structure to return
timeout_ms	a timeout in milliseconds.If it is equal to 0 call shell not block. Negative number means infinite timeout.

Returns:: IOTCS_RESULT_OK success; IOTCS_RESULT_FAIL timeout expired; IOTCS_RESULT_OUT_OF_MEMORY failed to allocate dynamic memory

iotcs_result iotcs_port_request_queue_put	(	iotcs_port_request_queue	queue,
		iotcs_request_message *	request,
		int32_t	timeout_ms
	)

Writes address of iotcs_request_message structure to the queue If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe.

Also if queue is full then the call shall block waiting for free space using timeout_ms argument as a maximum blocking time. If timeout is expired then error code IOTCS_RESULT_FAIL must be returned.

If IOTCS_MESSAGING_THREAD_SAFETY is NOT defined then timeout_ms argument shell be ignored treating it like a zero timeout.

Note:: Mandatory API. Called by the Library in any configuration.

Parameters:

queue	a non NULL queue handle
request	an address of iotcs_request_message structure to put to the queue
timeout_ms	a timeout in milliseconds. If it is equal to 0 call shell not block. Negative number means infinite timeout.

Returns:: IOTCS_RESULT_OK success; IOTCS_RESULT_FAIL timeout expired; IOTCS_RESULT_OUT_OF_MEMORY failed to allocate dynamic memory

iotcs_port_request_queue iotcs_port_storage_request_queue_create ( )

Creates queue Queue size shell be IOTCS_PORT_MEDIA_STORAGE_REQUEST_QUEUE_SIZE elements.

Element's size is sizeof(iotcs_storage_request*) bytes. If IOTCS_MESSAGING_THREAD_SAFETY is defined then queue shell be blocking. That means iotcs_port_storage_request_queue_put and iotcs_port_storage_request_queue_get calls shall be thread-safe. Also these calls shall block if operation can't be done (no free space or no messages) and use timeout_ms argument as a maximum blocking time.

Note:: Optional API. Called by the Library when STORAGE_SUPPORT enabled.

Returns:: NULL in case of fail

void iotcs_port_storage_request_queue_destroy ( iotcs_port_storage_request_queue queue )

Destroys iotcs_port_storage_request_queue If a queue is NULL, no operation is performed.

Note:: Optional API. Called by the Library when STORAGE_SUPPORT enabled.

Parameters:

queue a iotcs_port_storage_request_queue handle

iotcs_result iotcs_port_storage_request_queue_get	(	iotcs_port_storage_request_queue	queue,
		iotcs_storage_request *	request,
		int32_t	timeout_ms
	)

Gets iotcs_storage_object_handle address from the queue to given address If queue is not empty then call dequeue iotcs_storage_request pointer from the queue and writes this pointer to *request address.

If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe. Also if queue is empty then the call shall block waiting for a message using timeout_ms argument as a maximum blocking time. If timeout is expired then error code IOTCS_RESULT_FAIL must be returned.

If IOTCS_MESSAGING_THREAD_SAFETY is NOT defined then timeout_ms argument shell be ignored treating it like a zero timeout.

Note:: Optional API. Called by the Library when STORAGE_SUPPORT enabled.

Parameters:

queue	a non NULL queue handle
request	an address of pointer to iotcs_storage_request structure to return
timeout_ms	a timeout in milliseconds.If it is equal to 0 call shell not block. Negative number means infinite timeout.

Returns:: IOTCS_RESULT_OK success; IOTCS_RESULT_FAIL timeout expired; IOTCS_RESULT_OUT_OF_MEMORY failed to allocate dynamic memory

iotcs_result iotcs_port_storage_request_queue_put	(	iotcs_port_storage_request_queue	queue,
		iotcs_storage_request *	request,
		int32_t	timeout_ms
	)

Writes address of iotcs_storage_request structure to the queue If IOTCS_MESSAGING_THREAD_SAFETY is defined then the call shall be thread-safe.

Also if queue is full then the call shall block waiting for free space using timeout_ms argument as a maximum blocking time. If timeout is expired then error code IOTCS_RESULT_FAIL must be returned.

If IOTCS_MESSAGING_THREAD_SAFETY is NOT defined then timeout_ms argument shell be ignored treating it like a zero timeout.

Note:: Optional API. Called by the Library when STORAGE_SUPPORT enabled.

Parameters:

queue	a non NULL queue handle
request	an address of iotcs_storage_request structure to put to the queue
timeout_ms	a timeout in milliseconds. If it is equal to 0 call shell not block. Negative number means infinite timeout.

Returns:: IOTCS_RESULT_OK success; IOTCS_RESULT_FAIL timeout expired; IOTCS_RESULT_OUT_OF_MEMORY failed to allocate dynamic memory

Defines

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation