Typedefs |
typedef void(* | iotcs_message_dispatcher_delivery_callback )(iotcs_message *message) |
| typedef for message dispatcher send callback.
|
typedef void(* | iotcs_message_dispatcher_error_callback )(iotcs_message *message, iotcs_result result, const char *fail_reason) |
| typedef for message dispatcher receive callback.
|
typedef void(* | iotcs_resource_handler )(iotcs_request_message *request, void *arg, iotcs_message *response) |
| resource handler callback function After handler invocation request id and url is copied from 'request' and 'request' is freed.
|
Functions |
void | iotcs_message_dispatcher_set_delivery_callback (iotcs_message_dispatcher_delivery_callback delivery_cb) |
| set delivery callback for IoT CS message dispatcher
|
void | iotcs_message_dispatcher_set_error_callback (iotcs_message_dispatcher_error_callback error_cb) |
| set error callback for IoT CS message dispatcher
|
iotcs_result | iotcs_message_dispatcher_queue (iotcs_message *message) |
| IoT CS message dispatcher send method.
|
iotcs_result | iotcs_offer (iotcs_message *message) |
iotcs_result | iotcs_send (iotcs_message messages[], size_t len) |
| Send a number of messages to IOT server.
|
iotcs_request_message * | iotcs_receive (int32_t timeout) |
| Receive a iotcs_request_message from the server, if any.
|
void | iotcs_request_message_free (iotcs_request_message *message) |
| Destroy request message when it is no longer needed.
|
iotcs_result | iotcs_request_dispatcher_init (void) |
| Initializes a request dispatcher.
|
void | iotcs_request_dispatcher_finalize (void) |
| Finalizes a request dispatcher.
|
void | iotcs_request_dispatcher_dispatch (iotcs_request_message *request_message, iotcs_message *response_message) |
| Match the request to a handler and invoke the handler.
|
iotcs_result | iotcs_register_request_handler (const char *endpoint_id, const char *path, iotcs_resource_handler handler, void *arg) |
| Register a handler for the given endpoint and path.
|
iotcs_result | iotcs_unregister_request_handler_all (iotcs_resource_handler handler) |
| Un-register the given handler for all endpoints and paths for which the handler may be registered.
|
iotcs_result | iotcs_unregister_request_handler (const char *endpoint_id, const char *path) |
| Un-register the handler for the given endpoint and path.
|
iotcs_resource_handler | iotcs_get_request_handler (const char *endpoint_id, const char *path) |
| Lookup a iotcs_resource_handler for the given endpoint_id and path.
|
The file contains API for IOT CS Message and Request Dispatchers.
Lookup a iotcs_resource_handler for the given endpoint_id and path.
The lookup will return the most specific handler for the endpoint_id and path. If there is not a specific match for endpoint_id, the lookup will try to match ("*", path). Failing that, the lookup will return a handler for ("*", "*"), or the default handler if no handler for ("*","*") has been registered. Null or empty parameters are interpreted as a wildcard.
- Parameters:
-
endpoint_id | the endpoint id that has the given the resource path, or a wildcard ("*"). |
path | the resource path, or a wildcard ("*"). |
- Return values:
-
iotcs_resource_handler | if success. |
NULL | otherwise. |
Register a handler for the given endpoint and path.
If endpoint is null, empty, or a wildcard ("*"), then the handler is registered as being used for all endpoints. If path is null, empty, or a wildcard ("*") then the handler is registered as the handler for any requests that do not have a more specific handler.
- Parameters:
-
endpoint_id | the endpoint id that has the given the resource path, or a wildcard ("*") for any endpoint. |
path | the resource path, or a wildcard ("*") for any resource. |
handler | the handler to invoke for requests to this endpoint and path |
arg | argument to be passed to handler |
- Return values:
-
IOTCS_RESULT_INVALID_ARGUMENT | if handler is NULL |
IOTCS_RESULT_OUT_OF_MEMORY | if no additional memory can be allocated for use |
IOTCS_RESULT_OK | if success |
Match the request to a handler and invoke the handler.
The function looks up for a request handler based on endpoint_id and url. If no user callback is found then default handler (does nothing if not overridden) will be invoked.
Before the handler invocation the given response_message is filled with zeros, status code is set to 404 and response_message->base is initialized with a pointer to default constant values (type = IOTCS_MESSAGE_RESPONSE, priority = IOTCS_MESSAGE_PRIORITY_HIGH, reliability = IOTCS_MESSAGE_RELIABILITY_BEST_EFFORT).
Next the handler is invoked. A handler is responsible for filling in response_message with required data. If the handler performs no actions, server will get 404 code.
After handler invocation request_message is linked to response_message by setting field response_message->u.response.request. This is required so when response_message is sent, iotcs_request_message_free will be automatically called in order to deallocate request_message resources. For operation without asynchronous message dispatcher it means that if no iotcs_send was called then user must explicitely release request by calling iotcs_request_message_free with request_message as an argument. In asynchronous mode with message dispatcher everything is sent and released automatically.
- Parameters:
-
request_message | The request message to be dispatched |
response_message | The response message to be filled by handler |