iotc.h

Go to the documentation of this file.

/* Copyright 2018-2019 Google LLC
 *
 * This is part of the Google Cloud IoT Device SDK for Embedded C,
 * it is licensed under the BSD 3-Clause license; you may not use this file
 * except in compliance with the License.
 *
 * You may obtain a copy of the License at:
 *  https://opensource.org/licenses/BSD-3-Clause
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __IOTC_H__
#define __IOTC_H__

#include <stdint.h>
#include <stdlib.h>

#include <iotc_connection_data.h>
#include <iotc_mqtt.h>
#include <iotc_time.h>
#include <iotc_types.h>

#ifdef __cplusplus
extern "C" {
#endif

/* -----------------------------------------------------------------------
 * MAIN LIBRARY FUNCTIONS
 * ----------------------------------------------------------------------- */

extern iotc_state_t iotc_initialize();

extern iotc_state_t iotc_shutdown();

extern iotc_context_handle_t iotc_create_context();

extern iotc_state_t iotc_delete_context(iotc_context_handle_t context_handle);

extern uint8_t iotc_is_context_connected(iotc_context_handle_t context_handle);

extern void iotc_events_process_blocking();

extern iotc_state_t iotc_events_process_tick();

extern void iotc_events_stop();

extern 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);

extern 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);

/*
 * @detailed  Using the provided context, this function requests that a message
 * be delivered to the IoT Core service on the given topic. This requires that a
 * connection has already been established to the IoT Core service via a call
 * to iotc_connect or iot_connect_to.
 *
 * The callback function should have the following signature:
 *  void foo( iotc_context_handle_t in_context_handle
 *                , void* user_data
 *                , iotc_state_t state )
 *
 * where the callback parameters are:
 *   - in_context_handle is context handle that you provided to iotc_publish.
 *   - user_data is the value that the application passed in the user_data
 * parameter of the publish call (below.) This can be used for you attach
 * any sort support data or relevant data that would help identify the message.
 *   - state should be IOTC_STATE_OK if the publication succeded, or a non ok
 * value if the publish failed.
 *
 * please return IOTC_STATE_OK for these callbacks.
 *
 * @param [in] iotc_h a context handle created by invoking iotc_create_context.
 * @param [in] topic a string based topic name that you have created for
 * messaging via the IoT Core webservice.
 * @param [in] msg the payload to send to the IoT Core service.
 * @param [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.
 * Note: Currently Google Cloud IoT Core does not support QoS 2.
 * @param [in] callback Optional callback function that will be called upon
 * successful or unsuccessful msg delivery. This may be NULL.
 * @param [in] user_data Optional abstract data that will be passed to callback
 * when the publication completes. This may be NULL.
 *
 * @see iotc_create_context
 * @see iotc_publish_data
 *
 * @retval IOTC_STATE_OK         If the publication request was formatted
 * correctly and has be queued for publication.
 * @retval IOTC_OUT_OF_MEMORY    If the platform did not have enough free memory
 * to fulfill the request.
 * @retval IOTC_INTERNAL_ERROR   If an unforseen and unrecoverable error has
 * occurred.
 * @retval IOTC_BACKOFF_TERMINAL If backoff has been applied.
 */
extern 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);

extern 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);

extern 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);

extern 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);

/*-----------------------------------------------------------------------
 * HELPER FUNCTIONS
 * ---------------------------------------------------------------------- */

extern void iotc_set_network_timeout(uint32_t timeout);

extern 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);

extern const uint16_t iotc_major;

extern const uint16_t iotc_minor;

extern const uint16_t iotc_revision;

extern const char iotc_cilent_version_str[];

#ifdef IOTC_EXPOSE_FS
#include "iotc_fs_api.h"

iotc_state_t iotc_set_fs_functions(const iotc_fs_functions_t fs_functions);

#endif /* IOTC_EXPOSE_FS */

#ifdef __cplusplus
}
#endif

#endif /* __IOTC_H__ */