Google Cloud IoT device SDK for embedded C  1.0.2
iotc.h File Reference

Go to the source code of this file.

Functions

iotc_state_t iotc_initialize ()
 
iotc_state_t iotc_shutdown ()
 
iotc_context_handle_t iotc_create_context ()
 
iotc_state_t iotc_delete_context (iotc_context_handle_t context_handle)
 
uint8_t iotc_is_context_connected (iotc_context_handle_t context_handle)
 
void iotc_events_process_blocking ()
 
iotc_state_t iotc_events_process_tick ()
 
void iotc_events_stop ()
 
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)
 
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)
 
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)
 
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)
 
iotc_state_t iotc_shutdown_connection (iotc_context_handle_t iotc_h)
 
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)
 
void iotc_cancel_timed_task (iotc_timed_task_handle_t timed_task_handle)
 
void iotc_set_network_timeout (uint32_t timeout)
 
uint32_t iotc_get_network_timeout (void)
 
iotc_state_t iotc_set_maximum_heap_usage (const size_t max_bytes)
 
iotc_state_t iotc_get_heap_usage (size_t *const heap_usage)
 
iotc_state_t iotc_set_fs_functions (const iotc_fs_functions_t fs_functions)
 

Variables

const uint16_t iotc_major
 
const uint16_t iotc_minor
 
const uint16_t iotc_revision
 
const char iotc_cilent_version_str []
 

Detailed Description

Connects to and communicates with Cloud IoT Core.

Definition in file iotc.h.

Function Documentation

◆ iotc_cancel_timed_task()

void iotc_cancel_timed_task ( iotc_timed_task_handle_t  timed_task_handle)

Removes a scheduled task from the internal event system.

Parameters
[in]timed_task_handleA unique ID for the scheduled task.

◆ iotc_connect()

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 
)

Connects to Cloud IoT Core.

Parameters
[in]iotc_hA context handle.
[in]usernameThe MQTT username. Cloud IoT Core ignores this parameter, but some platforms will not send the password field unless the username field is specified. For best results, supply an arbitrary username like "unused" or "ignored."
[in]passwordThe MQTT password. Cloud IoT Core requires a JWT.
[in]client_idThe MQTT client ID. Cloud IoT Core requires a device path.
[in]connection_timeoutThe number of seconds to wait for an MQTT CONNACK response before closing the socket. If 0, the TCP timeout is used.
[in]keepalive_timeoutThe number of seconds the broker will wait for the client application to send a PINGREQ message. The PINGREQ is automatically sent at the specified interval, so you don't need to write the PINGREQ message contents.
[in](Optional)client_callback The callback function. Invoked when the client connects to or is disconnected from the MQTT broker.

◆ iotc_connect_to()

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 
)

Connects to a custom MQTT broker endpoint.

Performs the same operations as iotc_connect() but you can configure the endpoint.

Parameters
[in]hostThe address at which the client connects.
[in]portThe port of the host on which to connect.
[in]iotc_hA context handle.
[in]usernameThe MQTT username. Some platforms will not send the password field unless the username field is specified.
[in]passwordThe MQTT password.
[in]client_idThe MQTT client ID.
[in]connection_timeoutThe number of seconds to wait for an MQTT CONNACK response before closing the socket. If 0, the TCP timeout is used.
[in]keepalive_timeoutThe number of seconds the broker will wait for the client application to send a PINGREQ message. The PINGREQ is automatically sent at the specified interval, so you don't need to write the PINGREQ message contents.
[in](Optional)client_callback The callback function. Invoked when the client connects to or is disconnected from the MQTT broker.

◆ iotc_create_context()

iotc_context_handle_t iotc_create_context ( )

Creates a connection context. If this function fails, it returns the opposite of the numeric error code.

Before running this function, call iotc_initialize().

◆ iotc_delete_context()

iotc_state_t iotc_delete_context ( iotc_context_handle_t  context_handle)

Frees the provided context.

If iotc_events_process_blocking() invokes the event engine, the client application must free the context after iotc_events_process_blocking() returns. The application must free the context on the event loop tick after the disconnection event (not in the disconnection callback itself).

Parameters
[in]context_handleThe context handle to free.

◆ iotc_events_process_blocking()

void iotc_events_process_blocking ( )

Invokes the event processing loop and executes event engine as the main application process. This function processes events on platforms with main application loops that can block indefinitely. For other platforms, call iotc_events_process_tick().

You can call this function anytime but it returns only after calling iotc_events_stop().

The event engine won't process events when the IoT device SDK is in the IOTC_EVENT_PROCESS_STOPPED state. If the function returns IOTC_EVENT_PROCESS_STOPPED, shutdown and reinitialize the IoT device SDK to process events again.

◆ iotc_events_process_tick()

iotc_state_t iotc_events_process_tick ( )

Invokes the event processing loop on RTOS or non-OS devices that must yield for standard tick operations.

The event engine won't process events when the IoT device SDK is in the IOTC_EVENT_PROCESS_STOPPED state. If the function returns IOTC_EVENT_PROCESS_STOPPED, shutdown and reinitialize the IoT device SDK to process events again.

◆ iotc_events_stop()

void iotc_events_stop ( )

Shuts down the event engine.

◆ iotc_get_heap_usage()

iotc_state_t iotc_get_heap_usage ( size_t *const  heap_usage)

Gets the amount of heap memory allocated to the SDK.

This function is part of the memory limiter. If no heap memory is allocated, this function runs but returns IOTC_INVALID_PARAMETER.

◆ iotc_get_network_timeout()

uint32_t iotc_get_network_timeout ( void  )

Gets the connection timeout.

◆ iotc_initialize()

iotc_state_t iotc_initialize ( )

Initializes the time and random number libraries in the BSP. You must call this function before you create a new connection context.

◆ iotc_is_context_connected()

uint8_t iotc_is_context_connected ( iotc_context_handle_t  context_handle)

Checks if a context is connected to Cloud IoT Core.

Parameters
[in]context_handleThe handle for which to determine the connection.
Return values
1The context is connected to Cloud IoT Core.
0The context is invalid or the connection is either uninitialized, connecting, closing, or closed.

◆ iotc_publish()

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 
)

Publishes a message to an MQTT topic.

Parameters
[in]iotc_hA context handle.
[in]topicThe MQTT topic.
[in]msgThe payload of the message.
[in]qosThe Quality of Service (QoS) level. Can be 0 or 1. QoS level 2 isn't supported.
[in]callback(Optional) The callback function. Invoked after a message is successfully or unsuccessfully delivered.
[in](Optional)callback The callback function. Invoked when the client connects to or is disconnected from the MQTT broker.
[in]user_data(Optional) Abstract data passed to the callback function.

◆ iotc_publish_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 an MQTT topic.

Performs the same operations as iotc_publish() but the payload can contain bytes with zero values.

Parameters
[in]iotc_hA context handle.
[in]topicThe MQTT topic.
[in]dataA pointer to a buffer with the message payload.
[in]data_lenThe size, in bytes, of the message.
[in]qosThe Quality of Service (QoS) level. Can be 0 or 1. QoS level 2 isn't supported.
[in]callback(Optional) The callback function. Invoked after a message is successfully or unsuccessfully delivered.
[in]user_data(Optional) Abstract data passed to the callback function.

◆ iotc_schedule_timed_task()

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 
)

Returns a unique ID for the scheduled task and invokes a callback after an interval.

This is a non-blocking function until the callback is invoked. If the callback returns an error, the ID is the opposite of the numeric error code.

Parameters
[in]iotc_hA context handle.
[in]iotc_user_task_callback_tThe function invoked after an interval.
[in]seconds_from_nowThe number of seconds to wait before invoking the callback.
[in]repeats_foreverIf the repeats_forever parameter is set to 0, the callback is executed only once. Otherwise, the callback is repeatedly executed at seconds_from_now intervals.
[in]data(Optional) A pointer that will be passed to the callback function's user_data parameter.

◆ iotc_set_fs_functions()

iotc_state_t iotc_set_fs_functions ( const iotc_fs_functions_t  fs_functions)

Sets the file operations to the custom file management functions in the BSP.

◆ iotc_set_maximum_heap_usage()

iotc_state_t iotc_set_maximum_heap_usage ( const size_t  max_bytes)

Sets the maximum heap memory that the SDK can use.

This function is part of the memory limiter.

Parameters
[in]max_bytesThe maximum amount of heap memory, in bytes, that the IoT device SDK can use during standard execution.

◆ iotc_set_network_timeout()

void iotc_set_network_timeout ( uint32_t  timeout)

Sets the connection timeout.

Only new connections observe this timeout.

Note: The IoT device SDK periodically creates network traffic per MQTT specifications.

Parameters
[in]timeoutThe number of seconds sockets remain open when data isn't passing through them. When the socket initializes, this parameter is passed to the implemented networking layer to automatically keep connections open.

◆ iotc_shutdown()

iotc_state_t iotc_shutdown ( )

Shuts down the IoT device SDK and frees all resources created during initialization. Free all contexts before calling this function.

◆ iotc_shutdown_connection()

iotc_state_t iotc_shutdown_connection ( iotc_context_handle_t  iotc_h)

Disconnects asynchronously from an MQTT broker.

After disconnecting, the disconnection status code is passed to the iotc_connect() callback. You may reuse disconnected contexts until iotc_events_stop() returns; you don't need to destroy and recreate contexts.

Parameters
[in]iotc_hA context handle.

◆ iotc_subscribe()

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 an MQTT topic.

Parameters
[in]iotc_hA context handle.
[in]topicThe MQTT topic.
[in]qosThe Quality of Service (QoS) level. Can be 0, 1, or 2.
[in]callbackThe callback invoked after a message is published to the MQTT topic.
[in]user_data(Optional) A pointer that to the callback function's user_data parameter.

Variable Documentation

◆ iotc_cilent_version_str

const char iotc_cilent_version_str[]

The SDK "{@link ::iotc_major major}.{@link ::iotc_minor minor}.{@link ::iotc_revision revision}" version string.

◆ iotc_major

const uint16_t iotc_major

The SDK major version number.

◆ iotc_minor

const uint16_t iotc_minor

The SDK minor version number.

◆ iotc_revision

const uint16_t iotc_revision

The SDK revision number.