Sebastián Pastor / EtheriosCloudConnector

Etherios Cloud Connector very first porting for mbed. Tested in an LPC1768

Etherios Cloud Connector for Embedded v2.1.0.3 library for mbed. Early porting.

This port is centered mainly in the platform code. So it should work properly with the provided examples of send_data, device_request, data_points, RCI and firmware_update (stub implementation, not a real one... yet ;-)). Filesystem is not implemented yet, and some examples might need changes.

To run, it needs the following libraries: - mbed - mbed-rtos - EthernetInterface

Find more information (and the source code!) about Etherios Cloud Connector for Embedded here: http://www.etherios.com/products/devicecloud/support/connector and in: http://www.etherios.com

include/connector_api.h@1:908afea5a49d, 2013-12-03 (annotated)

Committer:
spastor
Date:
Tue Dec 03 14:10:48 2013 +0000
Revision:
1:908afea5a49d
Parent:
0:1c358ea10753 
Use internal Thread.h instead of Threads.h

Who changed what in which revision?

UserRevisionLine numberNew contents of line
spastor 0:1c358ea10753 1 /*
spastor 0:1c358ea10753 2 * Copyright (c) 2013 Digi International Inc.,
spastor 0:1c358ea10753 3 * All rights not expressly granted are reserved.
spastor 0:1c358ea10753 4 *
spastor 0:1c358ea10753 5 * This Source Code Form is subject to the terms of the Mozilla Public
spastor 0:1c358ea10753 6 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
spastor 0:1c358ea10753 7 * You can obtain one at http://mozilla.org/MPL/2.0/.
spastor 0:1c358ea10753 8 *
spastor 0:1c358ea10753 9 * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
spastor 0:1c358ea10753 10 * =======================================================================
spastor 0:1c358ea10753 11 */
spastor 0:1c358ea10753 12
spastor 0:1c358ea10753 13 #ifndef _CONNECTOR_API_H
spastor 0:1c358ea10753 14 #define _CONNECTOR_API_H
spastor 0:1c358ea10753 15
spastor 0:1c358ea10753 16 #if (defined CONNECTOR_CONST_PROTECTION)
spastor 0:1c358ea10753 17 #define CONST
spastor 0:1c358ea10753 18 #undef CONNECTOR_CONST_PROTECTION
spastor 0:1c358ea10753 19 #else
spastor 0:1c358ea10753 20 #if (defined CONST)
spastor 0:1c358ea10753 21 #define CONNECTOR_CONST_STORAGE CONST
spastor 0:1c358ea10753 22 #undef CONST
spastor 0:1c358ea10753 23 #endif
spastor 0:1c358ea10753 24 #define CONST const
spastor 0:1c358ea10753 25 #endif
spastor 0:1c358ea10753 26
spastor 0:1c358ea10753 27 /**
spastor 0:1c358ea10753 28 * Current version of Cloud Connector that application is using or built for.
spastor 0:1c358ea10753 29 *
spastor 0:1c358ea10753 30 * Note current version number denotes: 1.1.0.0
spastor 0:1c358ea10753 31 * | | | |
spastor 0:1c358ea10753 32 * v v v v
spastor 0:1c358ea10753 33 * 0x01010000
spastor 0:1c358ea10753 34 */
spastor 0:1c358ea10753 35 #define CONNECTOR_VERSION UINT32_C(0x02010003)
spastor 0:1c358ea10753 36
spastor 0:1c358ea10753 37 #include "connector_config.h"
spastor 0:1c358ea10753 38
spastor 0:1c358ea10753 39 /* NOTE: The configuration macro validation below must stay in this place, which is
spastor 0:1c358ea10753 40 after connector_config.h and before defining module specific data types. */
spastor 0:1c358ea10753 41
spastor 0:1c358ea10753 42 #if (defined CONNECTOR_FILE_SYSTEM_HAS_LARGE_FILES)
spastor 0:1c358ea10753 43 #define CONNECTOR_HAS_64_BIT_INTEGERS
spastor 0:1c358ea10753 44 #endif
spastor 0:1c358ea10753 45
spastor 0:1c358ea10753 46 #if !((defined CONNECTOR_TRANSPORT_TCP) || (defined CONNECTOR_TRANSPORT_UDP) || (defined CONNECTOR_TRANSPORT_SMS))
spastor 0:1c358ea10753 47 #define CONNECTOR_TRANSPORT_TCP
spastor 0:1c358ea10753 48 #endif
spastor 0:1c358ea10753 49
spastor 0:1c358ea10753 50 #if ((defined CONNECTOR_FIRMWARE_SERVICE) || (defined CONNECTOR_FILE_SYSTEM) || (defined CONNECTOR_RCI_SERVICE))
spastor 0:1c358ea10753 51 #if !(defined CONNECTOR_TRANSPORT_TCP)
spastor 0:1c358ea10753 52 #define CONNECTOR_TRANSPORT_TCP
spastor 0:1c358ea10753 53 #endif
spastor 0:1c358ea10753 54 #endif
spastor 0:1c358ea10753 55
spastor 0:1c358ea10753 56 #define CONNECTOR_TRANSPORT_COUNT ((defined CONNECTOR_TRANSPORT_TCP) + (defined CONNECTOR_TRANSPORT_UDP) + (defined CONNECTOR_TRANSPORT_SMS))
spastor 0:1c358ea10753 57
spastor 0:1c358ea10753 58 #if (defined CONNECTOR_DATA_POINTS) && !(defined CONNECTOR_DATA_SERVICE)
spastor 0:1c358ea10753 59 #define CONNECTOR_DATA_SERVICE
spastor 0:1c358ea10753 60 #endif
spastor 0:1c358ea10753 61
spastor 0:1c358ea10753 62 #if ((defined CONNECTOR_TRANSPORT_UDP) || (defined CONNECTOR_TRANSPORT_SMS))
spastor 0:1c358ea10753 63 #define CONNECTOR_SHORT_MESSAGE
spastor 0:1c358ea10753 64 #endif
spastor 0:1c358ea10753 65
spastor 0:1c358ea10753 66 #include "connector_types.h"
spastor 0:1c358ea10753 67
spastor 0:1c358ea10753 68 #define asizeof(array) (sizeof array/sizeof array[0])
spastor 0:1c358ea10753 69
spastor 0:1c358ea10753 70 /**
spastor 0:1c358ea10753 71 * @defgroup connector_bool_t Connector Boolean Type
spastor 0:1c358ea10753 72 * @{
spastor 0:1c358ea10753 73 */
spastor 0:1c358ea10753 74 /**
spastor 0:1c358ea10753 75 * Connector Boolean Type
spastor 0:1c358ea10753 76 *
spastor 0:1c358ea10753 77 */
spastor 0:1c358ea10753 78 typedef enum {
spastor 0:1c358ea10753 79 connector_false, /**< False */
spastor 0:1c358ea10753 80 connector_true /**< True */
spastor 0:1c358ea10753 81 } connector_bool_t;
spastor 0:1c358ea10753 82 /**
spastor 0:1c358ea10753 83 * @}
spastor 0:1c358ea10753 84 */
spastor 0:1c358ea10753 85
spastor 0:1c358ea10753 86 #include "connector_api_config.h"
spastor 0:1c358ea10753 87 #include "connector_api_network.h"
spastor 0:1c358ea10753 88 #include "connector_api_remote.h"
spastor 0:1c358ea10753 89
spastor 0:1c358ea10753 90 /**
spastor 0:1c358ea10753 91 * @defgroup connector_port_numbers Device Cloud Port
spastor 0:1c358ea10753 92 * Numbers @{
spastor 0:1c358ea10753 93 */
spastor 0:1c358ea10753 94 /**
spastor 0:1c358ea10753 95 * Port number to connect to Device Cloud
spastor 0:1c358ea10753 96 *
spastor 0:1c358ea10753 97 * This port number is for connector_network_open callback to make
spastor 0:1c358ea10753 98 * a connection to Device Cloud.
spastor 0:1c358ea10753 99 *
spastor 0:1c358ea10753 100 * @see CONNECTOR_SSL_PORT
spastor 0:1c358ea10753 101 * @see CONNECTOR_UDP_PORT
spastor 0:1c358ea10753 102 * @see connector_network_open
spastor 0:1c358ea10753 103 */
spastor 0:1c358ea10753 104 #define CONNECTOR_PORT 3197 /**< Port number used to connect to Device Cloud. */
spastor 0:1c358ea10753 105
spastor 0:1c358ea10753 106 /**
spastor 0:1c358ea10753 107 * Port number to make a secure connection to Device Cloud
spastor 0:1c358ea10753 108 *
spastor 0:1c358ea10753 109 * This port number is for connector_network_open callback to make
spastor 0:1c358ea10753 110 * a secured connection to Device Cloud.
spastor 0:1c358ea10753 111 *
spastor 0:1c358ea10753 112 * @see CONNECTOR_PORT
spastor 0:1c358ea10753 113 * @see CONNECTOR_UDP_PORT
spastor 0:1c358ea10753 114 * @see connector_network_open
spastor 0:1c358ea10753 115 */
spastor 0:1c358ea10753 116 #define CONNECTOR_SSL_PORT 3199 /**< Secured port number used to connect to Device Cloud. */
spastor 0:1c358ea10753 117
spastor 0:1c358ea10753 118 /**
spastor 0:1c358ea10753 119 * Device Cloud UDP port number
spastor 0:1c358ea10753 120 *
spastor 0:1c358ea10753 121 * This port number is for connector_network_open callback to communicate with
spastor 0:1c358ea10753 122 * the Device Cloud over UDP.
spastor 0:1c358ea10753 123 *
spastor 0:1c358ea10753 124 * @see CONNECTOR_PORT
spastor 0:1c358ea10753 125 * @see CONNECTOR_SSL_PORT
spastor 0:1c358ea10753 126 * @see connector_network_open
spastor 0:1c358ea10753 127 */
spastor 0:1c358ea10753 128 #define CONNECTOR_UDP_PORT 3297 /**< UDP port number used to communicate with Device Cloud. */
spastor 0:1c358ea10753 129 /**
spastor 0:1c358ea10753 130 * @}
spastor 0:1c358ea10753 131 */
spastor 0:1c358ea10753 132
spastor 0:1c358ea10753 133 /**
spastor 0:1c358ea10753 134 * @defgroup Cloud_status_returns Cloud Connector Status values
spastor 0:1c358ea10753 135 * @{
spastor 0:1c358ea10753 136 */
spastor 0:1c358ea10753 137 /**
spastor 0:1c358ea10753 138 * Status returned by Cloud Connector API calls.
spastor 0:1c358ea10753 139 */
spastor 0:1c358ea10753 140 typedef enum {
spastor 0:1c358ea10753 141 connector_success, /**< No error. */
spastor 0:1c358ea10753 142 connector_init_error, /**< Cloud Connector was not initialized. */
spastor 0:1c358ea10753 143 connector_invalid_data_size, /**< Callback returned configuration with invalid size. */
spastor 0:1c358ea10753 144 connector_invalid_data_range, /**< Callback returned configuration that is out of range. */
spastor 0:1c358ea10753 145 connector_invalid_data, /**< Callback returned invalid data. Callback returned a NULL data. */
spastor 0:1c358ea10753 146 connector_keepalive_error, /**< Cloud Connector did not receive keepalive messages. Device Cloud may be offline. */
spastor 0:1c358ea10753 147 connector_bad_version, /**< Invalid firmware version number. Incorrect firmware version number used in Remote Configuration (RCI) */
spastor 0:1c358ea10753 148 connector_device_terminated, /**< Cloud Connector was terminated by user via connector_initiate_action call.
spastor 0:1c358ea10753 149 All memory is freed and connector_init must be called to reStart Cloud Connector. */
spastor 0:1c358ea10753 150 connector_service_busy, /**< Someone else is using the same service or the device is busy. */
spastor 0:1c358ea10753 151 connector_invalid_response, /**< Received invalid response from Device Cloud. */
spastor 0:1c358ea10753 152 connector_no_resource, /**< Lack of resource */
spastor 0:1c358ea10753 153 connector_unavailable, /**< Not available to perform the specified action. */
spastor 0:1c358ea10753 154 connector_idle, /**< Cloud Connector is idling. Cloud Connector has no message to process.
spastor 0:1c358ea10753 155 Other task should be processed. */
spastor 0:1c358ea10753 156 connector_working, /**< Cloud Connector has processed a message and should be called at the earliest possible time. */
spastor 0:1c358ea10753 157 connector_pending, /**< Cloud Connector is waiting to process a message or a callback to complete. This allows
spastor 0:1c358ea10753 158 Cloud Connector to relinquish for other task to run. */
spastor 0:1c358ea10753 159 connector_active, /**< Cloud Connector is processing a message and it should be called at the earliest possible time. */
spastor 0:1c358ea10753 160 connector_abort, /**< Cloud Connector was aborted and terminated either Cloud Connector encountered fatal error or callback aborted Cloud Connector.
spastor 0:1c358ea10753 161 All memory is freed and connector_init must be called to reStart Cloud Connector. */
spastor 0:1c358ea10753 162 connector_device_error, /**< Close Callback returns error. If connector_step or connector_run is called again, it will re-establish the connection. */
spastor 0:1c358ea10753 163
spastor 0:1c358ea10753 164 connector_exceed_timeout, /**< Callback exceeded timeout value before it returned. */
spastor 0:1c358ea10753 165 connector_invalid_payload_packet, /**< Cloud Connector received invalid payload message. */
spastor 0:1c358ea10753 166 connector_open_error /**< Open callback was not successfully opened and returned @ref connector_callback_error.
spastor 0:1c358ea10753 167 Cloud Connector must be called again to continue running. It will reconnect if
spastor 0:1c358ea10753 168 it's initially setup to connect automatically. */
spastor 0:1c358ea10753 169 } connector_status_t;
spastor 0:1c358ea10753 170 /**
spastor 0:1c358ea10753 171 * @}
spastor 0:1c358ea10753 172 */
spastor 0:1c358ea10753 173
spastor 0:1c358ea10753 174 /**
spastor 0:1c358ea10753 175 * @defgroup connector_class_id_t Class IDs
spastor 0:1c358ea10753 176 * @{
spastor 0:1c358ea10753 177 */
spastor 0:1c358ea10753 178 /**
spastor 0:1c358ea10753 179 * Class Id for which class is used in the application's callback.
spastor 0:1c358ea10753 180 * It tells class id for the request id passed to the application's callback.
spastor 0:1c358ea10753 181 */
spastor 0:1c358ea10753 182 typedef enum {
spastor 0:1c358ea10753 183 connector_class_id_config, /**< Configuration Class Id */
spastor 0:1c358ea10753 184 connector_class_id_operating_system, /**< Operating System Class Id */
spastor 0:1c358ea10753 185 connector_class_id_firmware, /**< Firmware Facility Class Id */
spastor 0:1c358ea10753 186 connector_class_id_data_service, /**< Data Service Class Id */
spastor 0:1c358ea10753 187 connector_class_id_remote_config, /**< Remote Configuration Class ID */
spastor 0:1c358ea10753 188 connector_class_id_file_system, /**< File System Class Id */
spastor 0:1c358ea10753 189 connector_class_id_network_tcp, /**< TCP Network Class ID */
spastor 0:1c358ea10753 190 connector_class_id_network_udp, /**< UDP Network Class ID */
spastor 0:1c358ea10753 191 connector_class_id_network_sms, /**< SMS Network Class ID */
spastor 0:1c358ea10753 192 connector_class_id_status, /**< Class ID for all status */
spastor 0:1c358ea10753 193 connector_class_id_short_message, /**< Short message specific class ID */
spastor 0:1c358ea10753 194 connector_class_id_data_point /**< Data point class ID */
spastor 0:1c358ea10753 195 } connector_class_id_t;
spastor 0:1c358ea10753 196 /**
spastor 0:1c358ea10753 197 * @}
spastor 0:1c358ea10753 198 */
spastor 0:1c358ea10753 199
spastor 0:1c358ea10753 200 /**
spastor 0:1c358ea10753 201 * @defgroup connector_session_error_t Connector session error codes
spastor 0:1c358ea10753 202 * @{
spastor 0:1c358ea10753 203 */
spastor 0:1c358ea10753 204 /**
spastor 0:1c358ea10753 205 * Error values returned from lower communication layer. It can be either from Device Cloud or from
spastor 0:1c358ea10753 206 * Connector. These are errors originated from a layer where compression/decompression, resource
spastor 0:1c358ea10753 207 * allocation and state handling takes place.
spastor 0:1c358ea10753 208 */
spastor 0:1c358ea10753 209 typedef enum
spastor 0:1c358ea10753 210 {
spastor 0:1c358ea10753 211 connector_session_error_none, /**< Success */
spastor 0:1c358ea10753 212 connector_session_error_fatal, /**< Generally represents internal, unexpected error */
spastor 0:1c358ea10753 213 connector_session_error_invalid_opcode, /**< Opcode used in the message is invalid/unsupported */
spastor 0:1c358ea10753 214 connector_session_error_format, /**< Packet is framed incorrectly */
spastor 0:1c358ea10753 215 connector_session_error_session_in_use, /**< Session with same ID is already in use */
spastor 0:1c358ea10753 216 connector_session_error_unknown_session, /**< Session is not opened or already closed */
spastor 0:1c358ea10753 217 connector_session_error_compression_failure, /**< Failed during compression of the data to send */
spastor 0:1c358ea10753 218 connector_session_error_decompression_failure, /**< Failed during decompression of the received data */
spastor 0:1c358ea10753 219 connector_session_error_memory, /**< Malloc failed, try to restrict the number of active sessions */
spastor 0:1c358ea10753 220 connector_session_error_send, /**< Send socket error */
spastor 0:1c358ea10753 221 connector_session_error_cancel, /**< Used to force termination of a session */
spastor 0:1c358ea10753 222 connector_session_error_busy, /**< Either the cloud or the connector is busy processing */
spastor 0:1c358ea10753 223 connector_session_error_ack, /**< Invalid ack count */
spastor 0:1c358ea10753 224 connector_session_error_timeout, /**< Session timed out */
spastor 0:1c358ea10753 225 connector_session_error_no_service, /**< Requested service is not supported */
spastor 0:1c358ea10753 226 connector_session_error_count /**< Maximum error count value, new value goes before this element */
spastor 0:1c358ea10753 227 } connector_session_error_t;
spastor 0:1c358ea10753 228 /**
spastor 0:1c358ea10753 229 * @}
spastor 0:1c358ea10753 230 */
spastor 0:1c358ea10753 231
spastor 0:1c358ea10753 232
spastor 0:1c358ea10753 233 /**
spastor 0:1c358ea10753 234 * @defgroup connector_tcp_status_t Status Reason Types
spastor 0:1c358ea10753 235 * @{
spastor 0:1c358ea10753 236 */
spastor 0:1c358ea10753 237 /**
spastor 0:1c358ea10753 238 * TCP Status values
spastor 0:1c358ea10753 239 *
spastor 0:1c358ea10753 240 * These status values are used for an event notification.
spastor 0:1c358ea10753 241 * @see connector_status_tcp_status_t
spastor 0:1c358ea10753 242 */
spastor 0:1c358ea10753 243 typedef enum {
spastor 0:1c358ea10753 244 connector_tcp_communication_started, /**< Cloud Connector has established connection with Device Cloud and starts communicating. */
spastor 0:1c358ea10753 245 connector_tcp_keepalive_missed, /**< Cloud Connector didn't receive a keep alive message within the specified keep alive interval @ref tx_keepalive. */
spastor 0:1c358ea10753 246 connector_tcp_keepalive_restored /**< Cloud Connector received a keep alive message after a keep alive message was not received.
spastor 0:1c358ea10753 247 This is called after the callback has been previously notified with connector_miss_keepalive status. */
spastor 0:1c358ea10753 248 } connector_tcp_status_t;
spastor 0:1c358ea10753 249 /**
spastor 0:1c358ea10753 250 * @}
spastor 0:1c358ea10753 251 */
spastor 0:1c358ea10753 252
spastor 0:1c358ea10753 253 /**
spastor 0:1c358ea10753 254 * @defgroup connector_status_tcp_event_t TCP Status Structure
spastor 0:1c358ea10753 255 * @{
spastor 0:1c358ea10753 256 */
spastor 0:1c358ea10753 257 /**
spastor 0:1c358ea10753 258 * TCP status structure is used for @ref connector_request_id_status_tcp callback. See @ref status_tcp.
spastor 0:1c358ea10753 259 *
spastor 0:1c358ea10753 260 * This is used for an event notification.
spastor 0:1c358ea10753 261 */
spastor 0:1c358ea10753 262 typedef struct {
spastor 0:1c358ea10753 263 connector_tcp_status_t CONST status; /**< TCP status */
spastor 0:1c358ea10753 264 } connector_status_tcp_event_t;
spastor 0:1c358ea10753 265 /**
spastor 0:1c358ea10753 266 * @}
spastor 0:1c358ea10753 267 */
spastor 0:1c358ea10753 268
spastor 0:1c358ea10753 269
spastor 0:1c358ea10753 270 /**
spastor 0:1c358ea10753 271 * @defgroup connector_request_id_status_t Cloud Connector status
spastor 0:1c358ea10753 272 * status request IDs @{
spastor 0:1c358ea10753 273 */
spastor 0:1c358ea10753 274 /**
spastor 0:1c358ea10753 275 * These request IDs are used by Cloud Connector to communicate its status change to the user.
spastor 0:1c358ea10753 276 * The class ID associated with these request ID is connector_class_id_status.
spastor 0:1c358ea10753 277 */
spastor 0:1c358ea10753 278 typedef enum {
spastor 0:1c358ea10753 279 connector_request_id_status_tcp, /**< Used in a callback for Cloud Connector TCP status. The callback is called to notify the application that
spastor 0:1c358ea10753 280 TCP connection has been established, a keep-alive message was not received, or keep-alive message was received and restored.
spastor 0:1c358ea10753 281 @see connector_tcp_status_t */
spastor 0:1c358ea10753 282 connector_request_id_status_stop_completed /**< Used in a callback when Cloud Connector has stopped a transport running via @ref connector_initiate_action call with @ref connector_initiate_transport_stop. */
spastor 0:1c358ea10753 283
spastor 0:1c358ea10753 284 } connector_request_id_status_t;
spastor 0:1c358ea10753 285 /**
spastor 0:1c358ea10753 286 * @}
spastor 0:1c358ea10753 287 */
spastor 0:1c358ea10753 288
spastor 0:1c358ea10753 289 /**
spastor 0:1c358ea10753 290 * @defgroup connector_initiate_request_t Initiate action enumeration
spastor 0:1c358ea10753 291 * @{
spastor 0:1c358ea10753 292 */
spastor 0:1c358ea10753 293 /**
spastor 0:1c358ea10753 294 * Request IDs used in connector_initiate_action()
spastor 0:1c358ea10753 295 */
spastor 0:1c358ea10753 296 typedef enum
spastor 0:1c358ea10753 297 {
spastor 0:1c358ea10753 298 connector_initiate_transport_start, /**< Starts the specified (TCP, UDP or SMS) transport method. */
spastor 0:1c358ea10753 299 connector_initiate_transport_stop, /**< Stops the specified (TCP, UDP or SMS) transport method. */
spastor 0:1c358ea10753 300
spastor 0:1c358ea10753 301 #if (defined CONNECTOR_DATA_SERVICE)
spastor 0:1c358ea10753 302 connector_initiate_send_data, /**< Initiates the action to send data to the Device Cloud, the data will be stored in a file on Device Cloud. */
spastor 0:1c358ea10753 303 #endif
spastor 0:1c358ea10753 304
spastor 0:1c358ea10753 305 #if (defined CONNECTOR_SHORT_MESSAGE)
spastor 0:1c358ea10753 306 connector_initiate_ping_request, /**< Sends a ping request to Device Cloud. Supported only under UDP and SMS transport methods. */
spastor 0:1c358ea10753 307 connector_initiate_session_cancel, /**< Initiates the action to cancel the session, can be used in case of timeout. Supported only under UDP and SMS transport methods. */
spastor 0:1c358ea10753 308 connector_initiate_session_cancel_all, /**< Initiates the action to cancel all active sessions. Supported only under UDP and SMS transport methods. */
spastor 0:1c358ea10753 309 #endif
spastor 0:1c358ea10753 310
spastor 0:1c358ea10753 311 #if (defined CONNECTOR_DATA_POINTS)
spastor 0:1c358ea10753 312 connector_initiate_data_point_binary, /**< Initiates the action to send a binary data point to Device Cloud. */
spastor 0:1c358ea10753 313 connector_initiate_data_point_single, /**< Initiates the action to send data points of a stream to Device Cloud. */
spastor 0:1c358ea10753 314 #endif
spastor 0:1c358ea10753 315
spastor 0:1c358ea10753 316 connector_initiate_terminate /**< Terminates and stops Cloud Connector from running. */
spastor 0:1c358ea10753 317 } connector_initiate_request_t;
spastor 0:1c358ea10753 318 /**
spastor 0:1c358ea10753 319 * @}
spastor 0:1c358ea10753 320 */
spastor 0:1c358ea10753 321
spastor 0:1c358ea10753 322 /**
spastor 0:1c358ea10753 323 * @defgroup.connector_callback_status_t Callback return status
spastor 0:1c358ea10753 324 * @{
spastor 0:1c358ea10753 325 */
spastor 0:1c358ea10753 326 /**
spastor 0:1c358ea10753 327 * Return status from Cloud Connector callback
spastor 0:1c358ea10753 328 */
spastor 0:1c358ea10753 329 typedef enum {
spastor 0:1c358ea10753 330 connector_callback_continue, /**< Continues with no error */
spastor 0:1c358ea10753 331 connector_callback_busy, /**< Callback is busy */
spastor 0:1c358ea10753 332 connector_callback_abort, /**< Aborts Cloud Connector. Cloud Connector frees all memory. @ref connector_init must be called to reStart Cloud Connector. */
spastor 0:1c358ea10753 333 connector_callback_unrecognized, /**< Unsupported callback request */
spastor 0:1c358ea10753 334 connector_callback_error /**< Exits Cloud Connector when error is encountered. Cloud Connector will try reconnecting to Device Cloud
spastor 0:1c358ea10753 335 if @ref connector_step or @ref connector_run is called again. */
spastor 0:1c358ea10753 336 } connector_callback_status_t;
spastor 0:1c358ea10753 337 /**
spastor 0:1c358ea10753 338 * @}
spastor 0:1c358ea10753 339 */
spastor 0:1c358ea10753 340
spastor 0:1c358ea10753 341 /**
spastor 0:1c358ea10753 342 * @}
spastor 0:1c358ea10753 343 */
spastor 0:1c358ea10753 344
spastor 0:1c358ea10753 345 /**
spastor 0:1c358ea10753 346 * @defgroup connector_transport_t Transport layer type
spastor 0:1c358ea10753 347 * @{
spastor 0:1c358ea10753 348 */
spastor 0:1c358ea10753 349 /**
spastor 0:1c358ea10753 350 * Cloud Connector will use the specified transport
spastor 0:1c358ea10753 351 * method when sending a request to Device Cloud.
spastor 0:1c358ea10753 352 */
spastor 0:1c358ea10753 353 typedef enum
spastor 0:1c358ea10753 354 {
spastor 0:1c358ea10753 355 #if (defined CONNECTOR_TRANSPORT_TCP)
spastor 0:1c358ea10753 356 connector_transport_tcp, /**< Use TCP. @ref CONNECTOR_TRANSPORT_TCP must be enabled. */
spastor 0:1c358ea10753 357 #endif
spastor 0:1c358ea10753 358 #if (defined CONNECTOR_TRANSPORT_UDP)
spastor 0:1c358ea10753 359 connector_transport_udp, /**< Use UDP. @ref CONNECTOR_TRANSPORT_UDP must be enabled. */
spastor 0:1c358ea10753 360 #endif
spastor 0:1c358ea10753 361 #if (defined CONNECTOR_TRANSPORT_SMS)
spastor 0:1c358ea10753 362 connector_transport_sms, /**< Use SMS. @ref CONNECTOR_TRANSPORT_SMS must be enabled. */
spastor 0:1c358ea10753 363 #endif
spastor 0:1c358ea10753 364 connector_transport_all /**< All transports. */
spastor 0:1c358ea10753 365 } connector_transport_t;
spastor 0:1c358ea10753 366 /**
spastor 0:1c358ea10753 367 * @}
spastor 0:1c358ea10753 368 */
spastor 0:1c358ea10753 369
spastor 0:1c358ea10753 370 #include "connector_api_firmware.h"
spastor 0:1c358ea10753 371 #include "connector_api_data_service.h"
spastor 0:1c358ea10753 372 #include "connector_api_data_point.h"
spastor 0:1c358ea10753 373 #include "connector_api_file_system.h"
spastor 0:1c358ea10753 374 #include "connector_api_short_message.h"
spastor 0:1c358ea10753 375
spastor 0:1c358ea10753 376 #include "connector_api_os.h"
spastor 0:1c358ea10753 377
spastor 0:1c358ea10753 378
spastor 0:1c358ea10753 379 /**
spastor 0:1c358ea10753 380 * @defgroup connector_request_id_t Request IDs
spastor 0:1c358ea10753 381 * @{
spastor 0:1c358ea10753 382 */
spastor 0:1c358ea10753 383 /**
spastor 0:1c358ea10753 384 * Request IDs passed to callback identifying the type of request
spastor 0:1c358ea10753 385 * @see connector_class_id_t
spastor 0:1c358ea10753 386 */
spastor 0:1c358ea10753 387 typedef union {
spastor 0:1c358ea10753 388 connector_request_id_config_t config_request; /**< Configuration request ID for configuration class */
spastor 0:1c358ea10753 389 connector_request_id_os_t os_request; /**< Operating system request ID for operating system class */
spastor 0:1c358ea10753 390 #if (defined CONNECTOR_FIRMWARE_SERVICE)
spastor 0:1c358ea10753 391 connector_request_id_firmware_t firmware_request; /**< Firmware request ID for firmware facility class */
spastor 0:1c358ea10753 392 #endif
spastor 0:1c358ea10753 393 #if (defined CONNECTOR_DATA_SERVICE)
spastor 0:1c358ea10753 394 connector_request_id_data_service_t data_service_request; /**< Data service request ID for data service class */
spastor 0:1c358ea10753 395 #endif
spastor 0:1c358ea10753 396 #if (defined CONNECTOR_DATA_POINTS)
spastor 0:1c358ea10753 397 connector_request_id_data_point_t data_point_request; /**< Data service request ID for data service class */
spastor 0:1c358ea10753 398 #endif
spastor 0:1c358ea10753 399 #if (defined CONNECTOR_RCI_SERVICE)
spastor 0:1c358ea10753 400 connector_request_id_remote_config_t remote_config_request; /**< Remote configuration request ID for remote configuration service class */
spastor 0:1c358ea10753 401 #endif
spastor 0:1c358ea10753 402 #if (defined CONNECTOR_FILE_SYSTEM)
spastor 0:1c358ea10753 403 connector_request_id_file_system_t file_system_request; /**< File system request ID for file system class */
spastor 0:1c358ea10753 404 #endif
spastor 0:1c358ea10753 405 connector_request_id_network_t network_request; /**< Network request ID for network TCP class, network UDP class and network SMS class */
spastor 0:1c358ea10753 406 connector_request_id_status_t status_request; /**< Status request ID for status class */
spastor 0:1c358ea10753 407 #if (defined CONNECTOR_SHORT_MESSAGE)
spastor 0:1c358ea10753 408 connector_request_id_sm_t sm_request; /**< Short message request ID for short message class */
spastor 0:1c358ea10753 409 #endif
spastor 0:1c358ea10753 410 int int_value; /**< For debugging purposes. */
spastor 0:1c358ea10753 411 } connector_request_id_t;
spastor 0:1c358ea10753 412 /**
spastor 0:1c358ea10753 413 * @}
spastor 0:1c358ea10753 414 */
spastor 0:1c358ea10753 415
spastor 0:1c358ea10753 416 /**
spastor 0:1c358ea10753 417 * @defgroup connector_handle_t Cloud Connector Handle
spastor 0:1c358ea10753 418 * @{
spastor 0:1c358ea10753 419 */
spastor 0:1c358ea10753 420 /**
spastor 0:1c358ea10753 421 *
spastor 0:1c358ea10753 422 * Cloud Connector Handle type that is used throughout Cloud Connector APIs, this is used by the application
spastor 0:1c358ea10753 423 * to store context information about a connections, for example this could
spastor 0:1c358ea10753 424 * be used to store a file descriptor or a pointer to a structure.
spastor 0:1c358ea10753 425 */
spastor 0:1c358ea10753 426 #define connector_handle_t void *
spastor 0:1c358ea10753 427 /**
spastor 0:1c358ea10753 428 * @}
spastor 0:1c358ea10753 429 */
spastor 0:1c358ea10753 430
spastor 0:1c358ea10753 431 /**
spastor 0:1c358ea10753 432 * @defgroup connector_config_error_status_t Error Status
spastor 0:1c358ea10753 433 * @{
spastor 0:1c358ea10753 434 */
spastor 0:1c358ea10753 435 /**
spastor 0:1c358ea10753 436 * Error status structure for @ref connector_request_id_config_error_status callback which
spastor 0:1c358ea10753 437 * is called when Cloud Connector encounters an error.
spastor 0:1c358ea10753 438 * @see connector_request_id_config_t
spastor 0:1c358ea10753 439 */
spastor 0:1c358ea10753 440 typedef struct {
spastor 0:1c358ea10753 441 connector_class_id_t CONST class_id; /**< Class ID which Cloud Connector encounters error with */
spastor 0:1c358ea10753 442 connector_request_id_t CONST request_id; /**< Request ID which Cloud Connector encounters error with */
spastor 0:1c358ea10753 443 connector_status_t CONST status; /**< Error status */
spastor 0:1c358ea10753 444 } connector_config_error_status_t;
spastor 0:1c358ea10753 445 /**
spastor 0:1c358ea10753 446 * @}
spastor 0:1c358ea10753 447 */
spastor 0:1c358ea10753 448
spastor 0:1c358ea10753 449 /**
spastor 0:1c358ea10753 450 * @defgroup connector_stop_condition_t Condition used on @ref connector_initiate_transport_stop in @ref connector_initiate_action
spastor 0:1c358ea10753 451 * @{
spastor 0:1c358ea10753 452 */
spastor 0:1c358ea10753 453 /**
spastor 0:1c358ea10753 454 * This is used to tell how Cloud Connector handles all active sessions before stopping.
spastor 0:1c358ea10753 455 *
spastor 0:1c358ea10753 456 */
spastor 0:1c358ea10753 457 typedef enum {
spastor 0:1c358ea10753 458 connector_stop_immediately, /**< Cancel all active sessions and stop the transport of Cloud Connector immediately */
spastor 0:1c358ea10753 459 connector_wait_sessions_complete /**< Stop the transport of Cloud Connector after all active sessions complete */
spastor 0:1c358ea10753 460 } connector_stop_condition_t;
spastor 0:1c358ea10753 461 /**
spastor 0:1c358ea10753 462 * @}
spastor 0:1c358ea10753 463 */
spastor 0:1c358ea10753 464
spastor 0:1c358ea10753 465 /**
spastor 0:1c358ea10753 466 * @defgroup connector_initiate_stop_request_t Data type used to stop a transport of Cloud Connector
spastor 0:1c358ea10753 467 * @{
spastor 0:1c358ea10753 468 */
spastor 0:1c358ea10753 469 /**
spastor 0:1c358ea10753 470 * This data structure is used on @ref connector_initiate_transport_stop in @ref connector_initiate_action API
spastor 0:1c358ea10753 471 * to stop a transport.
spastor 0:1c358ea10753 472 *
spastor 0:1c358ea10753 473 */
spastor 0:1c358ea10753 474 typedef struct
spastor 0:1c358ea10753 475 {
spastor 0:1c358ea10753 476 connector_transport_t transport; /**< Transport will be stopped:
spastor 0:1c358ea10753 477 - @ref connector_transport_tcp
spastor 0:1c358ea10753 478 - @ref connector_transport_udp
spastor 0:1c358ea10753 479 - @ref connector_transport_sms
spastor 0:1c358ea10753 480 - @ref connector_transport_all */
spastor 0:1c358ea10753 481
spastor 0:1c358ea10753 482 connector_stop_condition_t condition; /**< Condition to stop the transport:
spastor 0:1c358ea10753 483 - @ref connector_stop_immediately
spastor 0:1c358ea10753 484 - @ref connector_wait_sessions_complete */
spastor 0:1c358ea10753 485
spastor 0:1c358ea10753 486 void * user_context; /**< User's defined context that will be passed to @ref connector_request_id_status_stop_completed after the transport of Cloud Connector has stopped running. */
spastor 0:1c358ea10753 487
spastor 0:1c358ea10753 488 } connector_initiate_stop_request_t;
spastor 0:1c358ea10753 489 /**
spastor 0:1c358ea10753 490 * @}
spastor 0:1c358ea10753 491 */
spastor 0:1c358ea10753 492
spastor 0:1c358ea10753 493
spastor 0:1c358ea10753 494 /**
spastor 0:1c358ea10753 495 * @defgroup connector_callback_t Application-defined callback
spastor 0:1c358ea10753 496 * @{
spastor 0:1c358ea10753 497 * @b Include: connector_api.h
spastor 0:1c358ea10753 498 *
spastor 0:1c358ea10753 499 * @brief This is Cloud Connector Application
spastor 0:1c358ea10753 500 * defined callback.
spastor 0:1c358ea10753 501 *
spastor 0:1c358ea10753 502 * An application must define this function and pass this to Connector during the
spastor 0:1c358ea10753 503 * connector_init() call. This callback is used to pass configuration data and exchange system
spastor 0:1c358ea10753 504 * services with the Connector state machine. The callback
spastor 0:1c358ea10753 505 * return value is then used to guide Connector how to
spastor 0:1c358ea10753 506 * proceed after completion of the application callback.
spastor 0:1c358ea10753 507 *
spastor 0:1c358ea10753 508 */
spastor 0:1c358ea10753 509 /**
spastor 0:1c358ea10753 510 * @param class_id This is a grouping or category of callback functions. Each class_id contains a number of related request_id's.
spastor 0:1c358ea10753 511 * @param request_id The request ID defines the specific callback being requested.
spastor 0:1c358ea10753 512 * @param data Points to specific structure for a given class ID and request ID
spastor 0:1c358ea10753 513 *
spastor 0:1c358ea10753 514 * @retval connector_callback_continue The callback completed successfully and Cloud Connector should continue
spastor 0:1c358ea10753 515 * it's process.
spastor 0:1c358ea10753 516 * @retval connector_callback_busy The callback could not complete the operation within the allowable time frame.
spastor 0:1c358ea10753 517 * Do not advance the Cloud Connector state and recall this callback at some
spastor 0:1c358ea10753 518 * later time.
spastor 0:1c358ea10753 519 * @retval connector_callback_error An application level error occurred while processing the callback.
spastor 0:1c358ea10753 520 * @retval connector_callback_abort The application is requesting Cloud Connector to abort execution. This will
spastor 0:1c358ea10753 521 * cause connector_run() or connector_step() to terminate with status @ref connector_abort.
spastor 0:1c358ea10753 522 * @retval connector_callback_unrecognized An unsupported and unrecognized callback was received. The application does not
spastor 0:1c358ea10753 523 * support this request. This should be implemented in the application to allow for
spastor 0:1c358ea10753 524 * graceful recovery and upgrade-ability to future Cloud Connector releases.
spastor 0:1c358ea10753 525 *
spastor 0:1c358ea10753 526 * @see connector_callback_status_t
spastor 0:1c358ea10753 527 * @see connector_init()
spastor 0:1c358ea10753 528 */
spastor 0:1c358ea10753 529 typedef connector_callback_status_t (* connector_callback_t) (connector_class_id_t const class_id, connector_request_id_t const request_id, void * const data);
spastor 0:1c358ea10753 530 /**
spastor 0:1c358ea10753 531 * @}
spastor 0:1c358ea10753 532 */
spastor 0:1c358ea10753 533
spastor 0:1c358ea10753 534 /**
spastor 0:1c358ea10753 535 * @defgroup connector_init Initialize Cloud Connector.
spastor 0:1c358ea10753 536 *@{
spastor 0:1c358ea10753 537 * @b Include: connector_api.h
spastor 0:1c358ea10753 538 */
spastor 0:1c358ea10753 539 /**
spastor 0:1c358ea10753 540 * @brief This API is called initially at startup to allocate and initialize Cloud Connector.
spastor 0:1c358ea10753 541 *
spastor 0:1c358ea10753 542 * This function takes the @ref iik_callback "application-defined callback" function pointer as
spastor 0:1c358ea10753 543 * it's only argument. This callback is used by Cloud Connector to communicate with the
spastor 0:1c358ea10753 544 * application environment. This function must be called prior to other Cloud Connector APIs,
spastor 0:1c358ea10753 545 * like connector_step(), connector_run(), and connector_initiate_action().
spastor 0:1c358ea10753 546 *
spastor 0:1c358ea10753 547 * @param [in] callback Callback function that is used to
spastor 0:1c358ea10753 548 * interface between the application and Cloud Connector.
spastor 0:1c358ea10753 549 *
spastor 0:1c358ea10753 550 * @retval NULL An error occurred and Cloud Connector was unable to initialize.
spastor 0:1c358ea10753 551 * @retval "Not NULL" Success. A Handle was returned for subsequent Cloud Connector calls.
spastor 0:1c358ea10753 552 *
spastor 0:1c358ea10753 553 * Example Usage:
spastor 0:1c358ea10753 554 * @code
spastor 0:1c358ea10753 555 * connector_handle = connector_init(application_callback);
spastor 0:1c358ea10753 556 * @endcode
spastor 0:1c358ea10753 557 *
spastor 0:1c358ea10753 558 * @see connector_handle_t
spastor 0:1c358ea10753 559 * @see connector_callback_t
spastor 0:1c358ea10753 560 */
spastor 0:1c358ea10753 561 connector_handle_t connector_init(connector_callback_t const callback);
spastor 0:1c358ea10753 562 /**
spastor 0:1c358ea10753 563 * @}
spastor 0:1c358ea10753 564 */
spastor 0:1c358ea10753 565
spastor 0:1c358ea10753 566 /**
spastor 0:1c358ea10753 567 * @defgroup connector_step Step Routine
spastor 0:1c358ea10753 568 * @{
spastor 0:1c358ea10753 569 * @b Include: connector_api.h
spastor 0:1c358ea10753 570 */
spastor 0:1c358ea10753 571 /**
spastor 0:1c358ea10753 572 * @brief Executes a small portion of Cloud Connector in a non-blocking call.
spastor 0:1c358ea10753 573 *
spastor 0:1c358ea10753 574 * This non-blocking function is used to execute a portion Cloud Connector after it's been
spastor 0:1c358ea10753 575 * successfully initialized with an connector_init() call. This function performs a sequence of
spastor 0:1c358ea10753 576 * operations or events and then returns. This allows applications to perform other tasks,
spastor 0:1c358ea10753 577 * especially in non-threading environment. For more information on the differences between
spastor 0:1c358ea10753 578 * connector_run() and connector_step() see the @ref threading "Cloud Connector threading model".
spastor 0:1c358ea10753 579 *
spastor 0:1c358ea10753 580 * This function is similar to connector_run() except this is the non-blocking variant. This function would
spastor 0:1c358ea10753 581 * normally be made from system control loop or state machine. This function must be repeatedly made to
spastor 0:1c358ea10753 582 * maintain Cloud Connector state.
spastor 0:1c358ea10753 583 *
spastor 0:1c358ea10753 584 * See Cloud Connector @ref threading "threading model" section for more information on the differences
spastor 0:1c358ea10753 585 * between connector_run() and connector_step().
spastor 0:1c358ea10753 586 *
spastor 0:1c358ea10753 587 * @param [in] handle Handle returned from connector_init
spastor 0:1c358ea10753 588 *
spastor 0:1c358ea10753 589 * @retval connector_init_error Cloud Connector was not properly initialized. The application requires a
spastor 0:1c358ea10753 590 * call to connector_init() prior to calling this function.
spastor 0:1c358ea10753 591 * @retval connector_abort Cloud Connector was aborted by callback function.
spastor 0:1c358ea10753 592 * @retval connector_invalid_data_size An @ref iik_callback "application callback" returned an invalid response_length.
spastor 0:1c358ea10753 593 * This is an application callback defect and should be corrected. To locate the
spastor 0:1c358ea10753 594 * faulty callback, enable @ref CONNECTOR_DEBUG. For more information on
spastor 0:1c358ea10753 595 * debugging, see the section on @ref debug_routine "how to implement debug support".
spastor 0:1c358ea10753 596 * @retval connector_invalid_data_range An @ref iik_callback "application callback" returned invalid response_data.
spastor 0:1c358ea10753 597 * This is an application callback defect and should be corrected. To locate the
spastor 0:1c358ea10753 598 * faulty callback, enable @ref CONNECTOR_DEBUG. For more information on
spastor 0:1c358ea10753 599 * debugging, see the section on @ref debug_routine "how to implement debug support".
spastor 0:1c358ea10753 600 * @retval connector_invalid_payload_packet Cloud Connector received invalid payload message.
spastor 0:1c358ea10753 601 * @retval connector_keepalive_error Cloud Connector did not receive keep alive messages. Device Cloud may be offline.
spastor 0:1c358ea10753 602 * @retval connector_bad_version Device Cloud rejected version number.
spastor 0:1c358ea10753 603 * @retval connector_exceed_timeout Callback exceeded timeout value before it returned.
spastor 0:1c358ea10753 604 * @retval connector_unsupported_security Cloud Connector received a packet with unsupported security.
spastor 0:1c358ea10753 605 * @retval connector_invalid_data An @ref iik_callback "application callback" returned unexpected NULL response_data.
spastor 0:1c358ea10753 606 * This is an application callback defect and should be corrected. To locate the
spastor 0:1c358ea10753 607 * faulty callback, enable @ref CONNECTOR_DEBUG. For more information on
spastor 0:1c358ea10753 608 * debugging, see the section on @ref debug_routine "how to implement debug support".
spastor 0:1c358ea10753 609 * @retval connector_device_terminated Cloud Connector was terminated by user via connector_initiate_action() call.
spastor 0:1c358ea10753 610 * @retval connector_idle Cloud Connector is idling. Cloud Connector has no message to process and relinquishes other task execution.
spastor 0:1c358ea10753 611 * @retval connector_working Cloud Connector is processing a message and should be called at the earliest possible time.
spastor 0:1c358ea10753 612 * @retval connector_pending Cloud Connector is busy or waiting to process a message and relinquishes other task execution
spastor 0:1c358ea10753 613 * @retval connector_active Cloud Connector is busy or waiting to process a message and should be called
spastor 0:1c358ea10753 614 * at the earliest possible time
spastor 0:1c358ea10753 615 *
spastor 0:1c358ea10753 616 *
spastor 0:1c358ea10753 617 * Example Usage:
spastor 0:1c358ea10753 618 * @code
spastor 0:1c358ea10753 619 * connector_status_t status;
spastor 0:1c358ea10753 620 * connector_handle_t connector_handle = connector_init(application_callback);
spastor 0:1c358ea10753 621 *
spastor 0:1c358ea10753 622 * for (;;)
spastor 0:1c358ea10753 623 * {
spastor 0:1c358ea10753 624 * status = connector_step(connector_handle);
spastor 0:1c358ea10753 625 * other_system_tasks();
spastor 0:1c358ea10753 626 * }
spastor 0:1c358ea10753 627 * @endcode
spastor 0:1c358ea10753 628 *
spastor 0:1c358ea10753 629 * @see connector_init()
spastor 0:1c358ea10753 630 * @see connector_handle_t
spastor 0:1c358ea10753 631 * @see connector_status_t
spastor 0:1c358ea10753 632 * @see connector_run()
spastor 0:1c358ea10753 633 */
spastor 0:1c358ea10753 634 connector_status_t connector_step(connector_handle_t const handle);
spastor 0:1c358ea10753 635 /**
spastor 0:1c358ea10753 636 * @}
spastor 0:1c358ea10753 637 */
spastor 0:1c358ea10753 638
spastor 0:1c358ea10753 639
spastor 0:1c358ea10753 640 /**
spastor 0:1c358ea10753 641 * @defgroup connector_run Run routine
spastor 0:1c358ea10753 642 * @{
spastor 0:1c358ea10753 643 * @b Include: connector_api.h
spastor 0:1c358ea10753 644 */
spastor 0:1c358ea10753 645 /**
spastor 0:1c358ea10753 646 * @brief Runs Cloud Connector as a blocking call.
spastor 0:1c358ea10753 647 *
spastor 0:1c358ea10753 648 * This blocking function is typically used in a separate thread (in a multi-threaded environment) to run
spastor 0:1c358ea10753 649 * Cloud Connector after it's been successfully initialized with an connector_init() call. This function
spastor 0:1c358ea10753 650 * only returns when Cloud Connector encounters an unexpected error. This function is similar to
spastor 0:1c358ea10753 651 * connector_step() except this is the blocking variant.
spastor 0:1c358ea10753 652 *
spastor 0:1c358ea10753 653 * See Cloud Connector @ref threading "Threading Model section" for more information on the differences
spastor 0:1c358ea10753 654 * between connector_run() and connector_step().
spastor 0:1c358ea10753 655 *
spastor 0:1c358ea10753 656 * @param [in] handle Handle returned from connector_init() call.
spastor 0:1c358ea10753 657 *
spastor 0:1c358ea10753 658 * @retval connector_init_error Cloud Connector was not properly initialized. The application requires a
spastor 0:1c358ea10753 659 * call to connector_init() prior to calling this function.
spastor 0:1c358ea10753 660 * @retval connector_abort Cloud Connector was aborted by callback function.
spastor 0:1c358ea10753 661 * @retval connector_invalid_data_size An @ref iik_callback "application callback" returned an invalid response_length.
spastor 0:1c358ea10753 662 * This is an application callback defect and should be corrected. To locate the
spastor 0:1c358ea10753 663 * faulty callback, enable @ref CONNECTOR_DEBUG. For more information on
spastor 0:1c358ea10753 664 * debugging, see the section on @ref debug_routine "how to implement debug support".
spastor 0:1c358ea10753 665 * @retval connector_invalid_data_range An @ref iik_callback "application callback" returned invalid response_data.
spastor 0:1c358ea10753 666 * This is an application callback defect and should be corrected. To locate the
spastor 0:1c358ea10753 667 * faulty callback, enable @ref CONNECTOR_DEBUG. For more information on
spastor 0:1c358ea10753 668 * debugging, see the section on @ref debug_routine "how to implement debug support".
spastor 0:1c358ea10753 669 * @retval connector_keepalive_error Cloud Connector did not receive keep alive messages. Device Cloud may be offline.
spastor 0:1c358ea10753 670 * @retval connector_bad_version Device Cloud rejected version number.
spastor 0:1c358ea10753 671 * @retval connector_exceed_timeout Callback exceeded timeout value before it returned.
spastor 0:1c358ea10753 672 * @retval connector_unsupported_security Cloud Connector received a packet with unsupported security.
spastor 0:1c358ea10753 673 * @retval connector_invalid_data An @ref iik_callback "application callback" returned unexpected NULL response_data.
spastor 0:1c358ea10753 674 * This is an application callback defect and should be corrected. To locate the
spastor 0:1c358ea10753 675 * faulty callback, enable @ref CONNECTOR_DEBUG. For more information on
spastor 0:1c358ea10753 676 * debugging, see the section on @ref debug_routine "how to implement debug support".
spastor 0:1c358ea10753 677 * @retval connector_device_error Close Callback returns
spastor 0:1c358ea10753 678 * error. If connector_step or connector_run is called again, it
spastor 0:1c358ea10753 679 * will re-establish the connection.
spastor 0:1c358ea10753 680 * @retval connector_device_terminated Cloud Connector was terminated by user via connector_initiate_action call.
spastor 0:1c358ea10753 681 *
spastor 0:1c358ea10753 682 * Example Usage:
spastor 0:1c358ea10753 683 * @code
spastor 0:1c358ea10753 684 * connector_status_t status;
spastor 0:1c358ea10753 685 * connector_handle_t connector_handle = connector_init(application_callback);
spastor 0:1c358ea10753 686 *
spastor 0:1c358ea10753 687 * status = connector_run(connector_handle);
spastor 0:1c358ea10753 688 * @endcode
spastor 0:1c358ea10753 689 *
spastor 0:1c358ea10753 690 * @see connector_init()
spastor 0:1c358ea10753 691 * @see connector_handle_t
spastor 0:1c358ea10753 692 * @see connector_status_t
spastor 0:1c358ea10753 693 * @see connector_step()
spastor 0:1c358ea10753 694 */
spastor 0:1c358ea10753 695 connector_status_t connector_run(connector_handle_t const handle);
spastor 0:1c358ea10753 696 /**
spastor 0:1c358ea10753 697 * @}
spastor 0:1c358ea10753 698 */
spastor 0:1c358ea10753 699
spastor 0:1c358ea10753 700
spastor 0:1c358ea10753 701 /**
spastor 0:1c358ea10753 702 * @defgroup connector_initiate_action Initiate Action
spastor 0:1c358ea10753 703 * @{
spastor 0:1c358ea10753 704 * @b Include: connector_api.h
spastor 0:1c358ea10753 705 */
spastor 0:1c358ea10753 706 /**
spastor 0:1c358ea10753 707 * @brief Requests Cloud Connector to perform an asynchronous action.
spastor 0:1c358ea10753 708 *
spastor 0:1c358ea10753 709 * This function is called to initiate an Cloud Connector action. It can be
spastor 0:1c358ea10753 710 * used to initiate a send data sequence from the device to Device Cloud,
spastor 0:1c358ea10753 711 * or to terminate Cloud Connector library.
spastor 0:1c358ea10753 712 *
spastor 0:1c358ea10753 713 * @param [in] handle Handle returned from the connector_init() call.
spastor 0:1c358ea10753 714 *
spastor 0:1c358ea10753 715 * @param [in] request Request action (one of the following):
spastor 0:1c358ea10753 716 * @li @b connector_initiate_terminate:
spastor 0:1c358ea10753 717 * Terminates and stops Cloud Connector from running. This call closes all open network
spastor 0:1c358ea10753 718 * Handles and frees all allocated memory.
spastor 0:1c358ea10753 719 * If the application is using connector_step(), the next call to connector_step() terminates
spastor 0:1c358ea10753 720 * Cloud Connector. If a blocking call to connector_run() is still pending, this call
spastor 0:1c358ea10753 721 * will eventually terminate that call. Once Cloud Connector is terminated, the
spastor 0:1c358ea10753 722 * Cloud Connector must restart by calling connector_init().
spastor 0:1c358ea10753 723 *
spastor 0:1c358ea10753 724 * @li @b connector_initiate_send_data:
spastor 0:1c358ea10753 725 * This is used to trigger the send
spastor 0:1c358ea10753 726 * data to Device Cloud. Only the
spastor 0:1c358ea10753 727 * header information is passed by
spastor 0:1c358ea10753 728 * this method. The actual data is
spastor 0:1c358ea10753 729 * transferred through callbacks. The
spastor 0:1c358ea10753 730 * data is stored in a specified file
spastor 0:1c358ea10753 731 * on Device Cloud.
spastor 0:1c358ea10753 732 *
spastor 0:1c358ea10753 733 * @li @b connector_initiate_transport_start:
spastor 0:1c358ea10753 734 * Starts the specified (@ref connector_transport_tcp
spastor 0:1c358ea10753 735 * , @ref connector_transport_udp or @ref connector_transport_sms) transport method.
spastor 0:1c358ea10753 736 *
spastor 0:1c358ea10753 737 * @li @b connector_initiate_transport_stop:
spastor 0:1c358ea10753 738 * Stops the Cloud Connector transport mechanism. Note this call
spastor 0:1c358ea10753 739 * triggers a @ref connector_request_id_status_stop_completed callback.
spastor 0:1c358ea10753 740 * Transports include:
spastor 0:1c358ea10753 741 * - @ref connector_transport_tcp - TCP transport
spastor 0:1c358ea10753 742 * - @ref connector_transport_udp - UDP transport
spastor 0:1c358ea10753 743 * - @ref connector_transport_sms - SMS transport
spastor 0:1c358ea10753 744 * - @ref connector_transport_all - all transports.
spastor 0:1c358ea10753 745 *
spastor 0:1c358ea10753 746 * @li @b connector_initiate_data_point_binary:
spastor 0:1c358ea10753 747 * Initiates the action to send a binary data point to Device Cloud.
spastor 0:1c358ea10753 748 *
spastor 0:1c358ea10753 749 * @li @b connector_initiate_data_point_single:
spastor 0:1c358ea10753 750 * Initiates the action to send data points which are belongs to a single stream on Device Cloud.
spastor 0:1c358ea10753 751 *
spastor 0:1c358ea10753 752 * @li @b connector_initiate_ping_request:
spastor 0:1c358ea10753 753 * Sends status message to the Device Cloud. Supported for
spastor 0:1c358ea10753 754 * @ref connector_transport_udp and @ref connector_transport_sms transports method only.
spastor 0:1c358ea10753 755 *
spastor 0:1c358ea10753 756 * @li @b connector_initiate_session_cancel:
spastor 0:1c358ea10753 757 * Initiates the action to cancel a session.
spastor 0:1c358ea10753 758 *
spastor 0:1c358ea10753 759 * @param [in] request_data Pointer to Request data
spastor 0:1c358ea10753 760 * @li @b connector_initiate_terminate:
spastor 0:1c358ea10753 761 * Should be NULL.
spastor 0:1c358ea10753 762 * @li @b connector_initiate_send_data:
spastor 0:1c358ea10753 763 * Pointer to @ref connector_request_data_service_send_t "connector_request_data_service_send_t".
spastor 0:1c358ea10753 764 * @li @b connector_initiate_transport_start:
spastor 0:1c358ea10753 765 * Pointer to @ref connector_transport_t "connector_transport_t"
spastor 0:1c358ea10753 766 * @li @b connector_initiate_transport_stop:
spastor 0:1c358ea10753 767 * Pointer to @ref connector_initiate_stop_request_t "connector_initiate_stop_request_t"
spastor 0:1c358ea10753 768 * @li @b connector_initiate_data_point_binary:
spastor 0:1c358ea10753 769 * Pointer to @ref connector_request_data_point_binary_t "connector_request_data_point_binary_t"
spastor 0:1c358ea10753 770 * @li @b connector_initiate_data_point_single:
spastor 0:1c358ea10753 771 * Pointer to @ref connector_request_data_point_single_t "connector_request_data_point_single_t"
spastor 0:1c358ea10753 772 * @li @b connector_initiate_ping_request:
spastor 0:1c358ea10753 773 * Pointer to @ref connector_sm_send_ping_request_t "connector_sm_send_ping_request_t"
spastor 0:1c358ea10753 774 * @li @b connector_initiate_session_cancel:
spastor 0:1c358ea10753 775 * Pointer to @ref connector_sm_cancel_request_t "connector_sm_cancel_request_t"
spastor 0:1c358ea10753 776 *
spastor 0:1c358ea10753 777 * @retval connector_success No error
spastor 0:1c358ea10753 778 * @retval connector_init_error Cloud Connector was not initialized or not connected to Device Cloud.
spastor 0:1c358ea10753 779 * @retval connector_abort Callback aborted Cloud Connector.
spastor 0:1c358ea10753 780 * @retval connector_invalid_data Invalid parameter
spastor 0:1c358ea10753 781 * @retval connector_no_resource Insufficient memory
spastor 0:1c358ea10753 782 * @retval connector_service_busy Cloud Connector is busy
spastor 0:1c358ea10753 783 *
spastor 0:1c358ea10753 784 * Example Usage:
spastor 0:1c358ea10753 785 * @code
spastor 0:1c358ea10753 786 * static connector_request_data_service_send_t file_info;
spastor 0:1c358ea10753 787 * :
spastor 0:1c358ea10753 788 * status = connector_initiate_action(handle, connector_initiate_send_data, &file_info);
spastor 0:1c358ea10753 789 * :
spastor 0:1c358ea10753 790 * :
spastor 0:1c358ea10753 791 * status = connector_initiate_action(connector_handle, connector_initiate_terminate, NULL);
spastor 0:1c358ea10753 792 * @endcode
spastor 0:1c358ea10753 793 *
spastor 0:1c358ea10753 794 * @see connector_handle_t
spastor 0:1c358ea10753 795 * @see connector_callback_t
spastor 0:1c358ea10753 796 */
spastor 0:1c358ea10753 797 connector_status_t connector_initiate_action(connector_handle_t const handle, connector_initiate_request_t const request, void const * const request_data);
spastor 0:1c358ea10753 798 /**
spastor 0:1c358ea10753 799 * @}.
spastor 0:1c358ea10753 800 */
spastor 0:1c358ea10753 801
spastor 0:1c358ea10753 802 #undef CONST
spastor 0:1c358ea10753 803 #if (defined CONNECTOR_CONST_STORAGE)
spastor 0:1c358ea10753 804 #define CONST CONNECTOR_CONST_STORAGE
spastor 0:1c358ea10753 805 #undef CONNECTOR_CONST_STORAGE
spastor 0:1c358ea10753 806 #endif
spastor 0:1c358ea10753 807
spastor 0:1c358ea10753 808 #endif
spastor 0:1c358ea10753 809