|
Google Cloud IoT Device SDK for Embedded C API
|
#include <stdint.h>#include <stdlib.h>#include <iotc_connection_data.h>#include <iotc_mqtt.h>#include <iotc_time.h>#include <iotc_types.h>Go to the source code of this file.
Variables | |
| const uint16_t | iotc_major |
| const uint16_t | iotc_minor |
| const uint16_t | iotc_revision |
| const char | iotc_cilent_version_str [] |
The main API for compiling your Application against the the Google Cloud IoT Device SDK for Embedded C (IoTC).
Definition in file iotc.h.
| void iotc_cancel_timed_task | ( | iotc_timed_task_handle_t | timed_task_handle | ) |
Cancel a timed task This function cancels the timed execution of the task specified by the given handle.
| [in] | timed_task_handle | a handle returned by iotc_schedule_timed_task. |
| iotc_state_t iotc_connect | ( | iotc_context_handle_t | iotc_h, |
| const char * | username, | ||
| const char * | password, | ||
| const char * | client_id, | ||
| uint16_t | connection_timeout, | ||
| uint16_t | keepalive_timeout, | ||
| iotc_user_callback_t * | client_callback | ||
| ) |
Opens a connection to the Google Cloud IoT Core service using the provided context.
Includes a callback. Using the provided context, this function requests that a connection be made to the Google Cloud IoT Core service given the provided credentials. The callback method is a connection state monitor callback, and will be invoked when this connection attempt completes successfully, has failed, or after disconnection if a connection was established.
The callback function is type defined by iotc_user_callback_t, which has the following signature: void foo( iotc_context_handle_t in_context_handle , void* data , iotc_state_t state )
where the callback parameters are:
| [in] | iotc_h | a context handle created by invoking iotc_create_context. |
| [in] | username | the MQTT Connect Username. For IoT Core, this parameter is unused. |
| [in] | password | the MQTT Connect Password. For IoT Core, this should be the IoT Core Connecting JWT created by the function iotc_create_iotcore_jwt. |
| [in] | client_id | the MQTT connect client identifier. For IoT Core, this must be the device_path of your device. Please see https://cloud.google.com/iot/docs/how-tos/mqtt-bridge which details how to construct the device path string. |
| [in] | connection_timeout | Number of seconds that the socket will be kept before CONNACK without data coming from the server. In case of 0, the TCP timeout will be used. |
| [in] | keepalive_timeout | Number of seconds that the socket will be kept connected while being unused. |
| IOTC_STATE_OK | If the connection request was formatted correctly and the client is processing the request with IoT Core. |
| iotc_state_t iotc_connect_to | ( | iotc_context_handle_t | iotc_h, |
| const char * | host, | ||
| uint16_t | port, | ||
| const char * | username, | ||
| const char * | password, | ||
| const char * | client_id, | ||
| uint16_t | connection_timeout, | ||
| uint16_t | keepalive_timeout, | ||
| iotc_user_callback_t * | client_callback | ||
| ) |
Opens a MQTT connection to a custom service endpoint using the provided context, host and port.
| [in] | host | client will connect to this address |
| [in] | port | client will connect to the host on this port |
This function's behavior and other parameters are identical to function iotc_connect.
| iotc_context_handle_t iotc_create_context | ( | ) |
Creates a connection context for subscriptions and publications This should by invoked following a successful libiotc initialization.
This creates a specific context that can be passed to connection, subscription, and publish functions.
| nonnegative | number A valid context handle. |
| negative | number A negated error code, defined in iotc_error.h. |
| iotc_state_t iotc_delete_context | ( | iotc_context_handle_t | context_handle | ) |
Frees the provided connection context This should by invoked to free up memory when your applicaiton has disconnected from the Google Cloud IoT Core service through the given context.
You may reuse a disconnected context to attempt to reconnect to the service; you do not need to destroy a disconnected context and create a new one.
NOTE: Please do not delete the context in the disconnection callback itself. Doing so many cause data corruption or a crash after the connect callback returns. Instead, delete the context either on the next tick of the client event loop in iotc_process_events_tick, or on POSIX, after iotc_process_blocking returns due to a call to iotc_events_stop.
| [in] | context | handle that should be freed. |
| IOTC_STATE_OK | Status OK |
| IOTC_INVALID_PARAMETER | If the provided context handle is invalid. |
| void iotc_events_process_blocking | ( | ) |
Invokes the IoTC Client Event Processing loop.
This function is meant to be execute the IoTC Client as the main application process and therefore it does not return until iotc_events_stop is invoked.
If you're executing on a platform that cannot block indefinitely, then please use iotc_events_process_tick instead.
NOTE: if the client is in a state of IOTC_EVENT_PROCESS_STOPPED, then the client will need to be destroyed and reiniitalized before the event engine will properly process events again. Therefore, stopping the event system should be used sparringly, most likely in the standard process of a reboot operation, or on POSIX, the standard process of client application shutdown.
| iotc_state_t iotc_events_process_tick | ( | ) |
Invokes the IOTC Client Event Processing loop.
This function will begin to process any pending tasks but then return control to the client application.
This function should be used on Embedded devices only. It is meant for RTOS or No OS devices which require that control be yielded to the OS for standard tick operations.
NOTE: This function WILL BLOCK on standard UNIX devices like LINUX or MAC OSX.
NOTE: if the client is in a state of IOTC_EVENT_PROCESS_STOPPED, then the client will need to be destroyed and reiniitalized before the event engine will properly process events again. Therefore, stopping the event system should be used sparringly, most likely in the standard process of a reboot operation, or on POSIX, the standard process of client application shutdown.
IOTC_STATE_OK will be returned if the event system is ongoing and can continue to operate
IOTC_EVENT_PROCESS_STOPPED will be returned if iotc_events_stop has been invoked by the client application or if the event processor has been stopped due to an unrecoverable error.
| IOTC_STATE_OK | Status OK. |
| IOTC_EVENT_PROCESS_STOPPED | If the event processor has been stopped. |
| void iotc_events_stop | ( | ) |
Causes the IoTC Client event loop to exit.
Used to exit the blocking event loop, or to signal that an irrecoverable event has occurred.
| iotc_state_t iotc_get_heap_usage | ( | size_t *const | heap_usage | ) |
Fetches the IoTC Client's current amount of heap usage This function is part of an optional configuration of the IoTC Client called the Memory Limiter.
If enabled, you can use this function to determine the current heap usage of the IoTC Client. Depending on the TLS implementation, this might also include the TLS buffers used for encoding / decoding and certificate parsing.
| IOTC_NOT_SUPPORTED | If the Memory Limiter module has not been compiled into this version of the IoTC Client Library |
| IOTC_INVALID_PARAMETER | If the provided parameter is NULL |
| IOTC_STATE_OK | if the parameter has been filled-in with the IoTC Client's current heap usage. |
| uint32_t iotc_get_network_timeout | ( | void | ) |
Returns the timeout value for socket connections.
Queries the current configuration of network timeout values that will be fed to that native network implementation when sockets are initialized.
| iotc_state_t iotc_initialize | ( | ) |
Required before use of the IoTC Client library.
This should be the first function that you call on a new runtime.
| IOTC_STATE_OK | Status OK |
| uint8_t iotc_is_context_connected | ( | iotc_context_handle_t | context_handle | ) |
Used to determine the state of a IoTC Client context's connection to the remote service.
| [in] | context | handle to determine the connection status of. |
| 1 | if the context is currently connected |
| 0 | if the context is invalid, or the connection is currently any one of the other following states: Unitialized, connecting, closing or closed. |
| iotc_state_t iotc_publish | ( | iotc_context_handle_t | iotc_h, |
| const char * | topic, | ||
| const char * | msg, | ||
| const iotc_mqtt_qos_t | qos, | ||
| iotc_user_callback_t * | callback, | ||
| void * | user_data | ||
| ) |
| iotc_state_t iotc_publish_data | ( | iotc_context_handle_t | iotc_h, |
| const char * | topic, | ||
| const uint8_t * | data, | ||
| size_t | data_len, | ||
| const iotc_mqtt_qos_t | qos, | ||
| iotc_user_callback_t * | callback, | ||
| void * | user_data | ||
| ) |
Publishes binary data to the Google Cloud IoT service on the given topic.
Using the provided context, this function requests that binary data be delivered to the IoT Core service on the given topic. This requires that a connection already be made to the IoT Core service via a iotc_connect call.
Note: This function is idential to iotc_publish except that it doesn't assume a null terminated string. Instead a pointer and data length are provided.
| [in] | data | the payload to send to the IoT Core service. |
| [in] | data_len | the size in bytes of the data buf to send. |
| IOTC_STATE_OK | If the publication request was formatted correctly. |
| IOTC_OUT_OF_MEMORY | If the platform did not have enough free memory to fulfill the request. |
| IOTC_INTERNAL_ERROR | If an unforseen and unrecoverable error has occurred. |
| iotc_timed_task_handle_t iotc_schedule_timed_task | ( | iotc_context_handle_t | iotc_h, |
| iotc_user_task_callback_t * | callback, | ||
| const iotc_time_t | seconds_from_now, | ||
| const uint8_t | repeats_forever, | ||
| void * | data | ||
| ) |
Schedule a task for timed execution Using the provided context, this function adds a task to the internal event system.
The callback method will be invoked when the given time has passed.
The callback function should have the following siguature: typedef void ( iotc_user_task_callback_t ) ( const iotc_context_handle_t context_handle, const iotc_timed_task_handle_t, timed_task_handle, void* user_data );
where:
| [in] | iotc_h | a context handle created by invoking iotc_create_context. |
| [in] | iotc_user_task_callback_t* | a function pointer to be invoked when given time has passed. |
| [in] | seconds_from_now | number of seconds to wait before task invocation. |
| [in] | repeats_forever | if zero is passed the callback will be called only once, otherwise the callback will be called continuously with the seconds_from_now delay until iotc_cancel_timed_task() called. |
| iotc_time_task_handle_t | if bigger than 0 it's the unique identifier of the task, if smaller, it's an error code multiplied by -1, the possible error codes are: |
| iotc_state_t iotc_set_maximum_heap_usage | ( | const size_t | max_bytes | ) |
Sets Maximum Amount of Heap Allocated Memory the IoTC Client may use.
This function is part of an optional configuration of the IoTC Client called the Memory Limiter.
This system can be used to guarantee that the IoTC Client will use only a certain amount of the heapspace during its standard execution. On many platforms this can also include the heap usage of the TLS implementation if the TLS implementation can be written to use the IoTC malloc and free functions.
| [in] | max_bytes | the upper bounds of memory that the IoTC Client will use in its serialization, parsing and encryption of mqtt packets, and for the facilitation of Client Application callbacks and events. |
| IOTC_NOT_SUPPORTED | If the Memory Limiter module has not been compiled into this version of the IoTC Client Library |
| IOTC_OUT_OF_MEMORY | If the new memory limit is too small to support the current IoTC Client heapspace footprint. |
| IOTC_STATE_OK | the new memory limit has been set to the value specified by max_bytes. |
| void iotc_set_network_timeout | ( | uint32_t | timeout | ) |
Timeout value that's passed to the networking implementation This function configures how long a socket will live while there is no data sent on the socket.
Note that the MQTT Keep Alive value configured in the iotc_connect will cause the IoTC Client to periodically create network traffic, as part of the MQTT specification.
This value is only observed when constructing new connections, so invoking this will not have any affect on on-going connections.
| [in] | timeout | a timeout value that will be passed to the implementing networking layer during socket initialization. |
| iotc_state_t iotc_shutdown | ( | ) |
Signals the IoTC Client library to cleanup any internal memory.
This should by the last function called while shutting down your application. Any resources that were created during initialization will be cleaned up and freed.
Note that you should always clean up IoTC contexts individually with iotc_delete_context
| IOTC_STATE_OK | Status OK |
| IOTC_FAILED_INITIALIZATION | An urecoverable error occured |
| iotc_state_t iotc_shutdown_connection | ( | iotc_context_handle_t | iotc_h | ) |
Closes the connection associated with the provide context.
Closes the connection to the Google Cloud IoT Core Service. This will happen asynchronously. The callback is defined by iotc_connect.
| [in] | iotc_h | a context handle created by invoking iotc_create_context. |
| IOTC_SOCKET_NO_ACTIVE_CONNECTION_ERROR | If there is no connection for this context. |
| IOTC_STATE_OK | If the disconnection request has been queued for process. |
| iotc_state_t iotc_subscribe | ( | iotc_context_handle_t | iotc_h, |
| const char * | topic, | ||
| const iotc_mqtt_qos_t | qos, | ||
| iotc_user_subscription_callback_t * | callback, | ||
| void * | user_data | ||
| ) |
Subscribes to notifications if a message from the Google Cloud IoT Core service is posted to the given topic.
Using the provided context, this function formats a request to subscribe to a topic in the IoT Core service. If the subscription is successful then incoming messages will be provided to the callback function. Subscription falures will also invoke the callback function with parameters that denote the error.
The callback function is type defined by iotc_user_callback_t, which has the following siguature: void foo( iotc_context_handle_t in_context_handle, iotc_sub_call_type_t call_type, const iotc_sub_call_params_t* const params, iotc_state_t state, void* user_data )
where:
| [in] | iotc_h | a context handle created by invoking iotc_create_context |
| [in] | topic | a string based topic name that you have created for messaging via the IoT Core webservice. |
| [in] | qos | Quality of Service MQTT level. 0, 1, or 2. Please see MQTT specification or iotc_mqtt_qos_e in iotc_mqtt_message.h for constant values. |
| [in] | callback | a function pointer to be invoked when a message arrives, as described above |
| [in] | user | a pointer that will be returned back during the callback invocation |
| IOTC_STATE_OK | If the publication request was formatted correctly. |
| IOTC_OUT_OF_MEMORY | If the platform did not have enough free memory to fulfill the request. |
| IOTC_INTERNAL_ERROR | If an unforseen and unrecoverable error has occurred. |
| const char iotc_cilent_version_str[] |
String representation of the Major.Minor.Revision version of the IoTC Client library.
library.
| const uint16_t iotc_major |
Contains the major version number of the IoTC Client library.
| const uint16_t iotc_minor |
Contains the minor version number of the IoTC Client library.
| const uint16_t iotc_revision |
Contains the revsion number of the IoTC Client library.
1.8.13