connector_api.h

00001 /*
00002  * Copyright (c) 2013 Digi International Inc.,
00003  * All rights not expressly granted are reserved.
00004  *
00005  * This Source Code Form is subject to the terms of the Mozilla Public
00006  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
00007  * You can obtain one at http://mozilla.org/MPL/2.0/.
00008  *
00009  * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
00010  * =======================================================================
00011  */
00012 
00013 #ifndef _CONNECTOR_API_H
00014 #define _CONNECTOR_API_H
00015 
00016 #if (defined CONNECTOR_CONST_PROTECTION)
00017 #define CONST
00018 #undef CONNECTOR_CONST_PROTECTION
00019 #else
00020 #if (defined CONST)
00021 #define CONNECTOR_CONST_STORAGE CONST
00022 #undef CONST
00023 #endif
00024 #define CONST const
00025 #endif
00026 
00027 /**
00028  * Current version of Cloud Connector that application is using or built for.
00029  *
00030  * Note current version number denotes:  1.1.0.0
00031  *                                       | | | |
00032  *                                       v v v v
00033  *                                    0x01010000
00034  */
00035 #define CONNECTOR_VERSION    UINT32_C(0x02010003)
00036 
00037 #include "connector_config.h"
00038 
00039 /* NOTE: The configuration macro validation below must stay in this place, which is
00040          after connector_config.h and before defining module specific data types. */
00041 
00042 #if (defined CONNECTOR_FILE_SYSTEM_HAS_LARGE_FILES)
00043 #define CONNECTOR_HAS_64_BIT_INTEGERS
00044 #endif
00045 
00046 #if !((defined CONNECTOR_TRANSPORT_TCP) || (defined CONNECTOR_TRANSPORT_UDP) || (defined CONNECTOR_TRANSPORT_SMS))
00047 #define CONNECTOR_TRANSPORT_TCP
00048 #endif
00049 
00050 #if ((defined CONNECTOR_FIRMWARE_SERVICE) || (defined CONNECTOR_FILE_SYSTEM) || (defined CONNECTOR_RCI_SERVICE))
00051 #if !(defined CONNECTOR_TRANSPORT_TCP)
00052 #define CONNECTOR_TRANSPORT_TCP
00053 #endif
00054 #endif
00055 
00056 #define CONNECTOR_TRANSPORT_COUNT ((defined CONNECTOR_TRANSPORT_TCP) + (defined CONNECTOR_TRANSPORT_UDP) + (defined CONNECTOR_TRANSPORT_SMS))
00057 
00058 #if (defined CONNECTOR_DATA_POINTS) && !(defined CONNECTOR_DATA_SERVICE)
00059 #define CONNECTOR_DATA_SERVICE
00060 #endif
00061 
00062 #if ((defined CONNECTOR_TRANSPORT_UDP) || (defined CONNECTOR_TRANSPORT_SMS))
00063 #define CONNECTOR_SHORT_MESSAGE
00064 #endif
00065 
00066 #include "connector_types.h"
00067 
00068 #define asizeof(array)  (sizeof array/sizeof array[0])
00069 
00070 /**
00071  * @defgroup connector_bool_t Connector Boolean Type
00072  * @{
00073  */
00074 /**
00075  * Connector Boolean Type
00076  *
00077  */
00078 typedef enum {
00079     connector_false,    /**< False */
00080     connector_true      /**< True */
00081 } connector_bool_t;
00082 /**
00083 * @}
00084 */
00085 
00086 #include "connector_api_config.h"
00087 #include "connector_api_network.h"
00088 #include "connector_api_remote.h"
00089 
00090  /**
00091  * @defgroup connector_port_numbers Device Cloud Port
00092  * Numbers @{
00093  */
00094 /**
00095  * Port number to connect to Device Cloud
00096  *
00097  * This port number is for connector_network_open callback to make
00098  * a connection to Device Cloud.
00099  *
00100  * @see CONNECTOR_SSL_PORT
00101  * @see CONNECTOR_UDP_PORT
00102  * @see connector_network_open
00103  */
00104 #define CONNECTOR_PORT       3197   /**< Port number used to connect to Device Cloud. */
00105 
00106 /**
00107  * Port number to make a secure connection to Device Cloud
00108  *
00109  * This port number is for connector_network_open callback to make
00110  * a secured connection to Device Cloud.
00111  *
00112  * @see CONNECTOR_PORT
00113  * @see CONNECTOR_UDP_PORT
00114  * @see connector_network_open
00115  */
00116 #define CONNECTOR_SSL_PORT   3199   /**< Secured port number used to connect to Device Cloud. */
00117 
00118 /**
00119  * Device Cloud UDP port number
00120  *
00121  * This port number is for connector_network_open callback to communicate with
00122  * the Device Cloud over UDP.
00123  *
00124  * @see CONNECTOR_PORT
00125  * @see CONNECTOR_SSL_PORT
00126  * @see connector_network_open
00127  */
00128 #define CONNECTOR_UDP_PORT       3297   /**< UDP port number used to communicate with Device Cloud. */
00129 /**
00130 * @}
00131 */
00132 
00133  /**
00134  * @defgroup Cloud_status_returns Cloud Connector Status values
00135  * @{
00136  */
00137  /**
00138  * Status returned by Cloud Connector API calls.
00139  */
00140 typedef enum {
00141    connector_success,               /**< No error. */
00142    connector_init_error,            /**< Cloud Connector was not initialized. */
00143    connector_invalid_data_size,     /**< Callback returned configuration with invalid size. */
00144    connector_invalid_data_range,    /**< Callback returned configuration that is out of range. */
00145    connector_invalid_data,          /**< Callback returned invalid data. Callback returned a NULL data. */
00146    connector_keepalive_error,       /**< Cloud Connector did not receive keepalive messages. Device Cloud may be offline. */
00147    connector_bad_version,           /**< Invalid firmware version number. Incorrect firmware version number used in Remote Configuration (RCI) */
00148    connector_device_terminated,     /**< Cloud Connector was terminated by user via connector_initiate_action call.
00149                                      All memory is freed and connector_init must be called to reStart Cloud Connector. */
00150    connector_service_busy,          /**< Someone else is using the same service or the device is busy. */
00151    connector_invalid_response,      /**< Received invalid response from Device Cloud. */
00152    connector_no_resource,           /**< Lack of resource */
00153    connector_unavailable,           /**< Not available to perform the specified action. */
00154    connector_idle,                  /**< Cloud Connector is idling. Cloud Connector has no message to process.
00155                                      Other task should be processed. */
00156    connector_working,               /**< Cloud Connector has processed a message and should be called at the earliest possible time. */
00157    connector_pending,               /**< Cloud Connector is waiting to process a message or a callback to complete. This allows
00158                                      Cloud Connector to relinquish for other task to run. */
00159    connector_active,                /**< Cloud Connector is processing a message and it should be called at the earliest possible time. */
00160    connector_abort,                 /**< Cloud Connector was aborted and terminated either Cloud Connector encountered fatal error or callback aborted Cloud Connector.
00161                                      All memory is freed and connector_init must be called to reStart Cloud Connector. */
00162    connector_device_error,          /**< Close Callback returns error. If connector_step or connector_run is called again, it will re-establish the connection. */
00163 
00164    connector_exceed_timeout,        /**< Callback exceeded timeout value before it returned. */
00165    connector_invalid_payload_packet, /**< Cloud Connector received invalid payload message. */
00166    connector_open_error             /**< Open callback was not successfully opened and returned @ref connector_callback_error.
00167                                      Cloud Connector must be called again to continue running. It will reconnect if
00168                                      it's initially setup to connect automatically. */
00169 } connector_status_t;
00170 /**
00171 * @}
00172 */
00173 
00174 /**
00175 * @defgroup connector_class_id_t Class IDs
00176 * @{
00177 */
00178 /**
00179 * Class Id for which class is used in the application's callback.
00180 * It tells class id for the request id passed to the application's callback.
00181 */
00182 typedef enum {
00183     connector_class_id_config,           /**< Configuration Class Id */
00184     connector_class_id_operating_system, /**< Operating System Class Id */
00185     connector_class_id_firmware,         /**< Firmware Facility Class Id */
00186     connector_class_id_data_service,     /**< Data Service Class Id */
00187     connector_class_id_remote_config,    /**< Remote Configuration Class ID */
00188     connector_class_id_file_system,      /**< File System Class Id */
00189     connector_class_id_network_tcp,      /**< TCP Network Class ID */
00190     connector_class_id_network_udp,      /**< UDP Network Class ID */
00191     connector_class_id_network_sms,      /**< SMS Network Class ID */
00192     connector_class_id_status,           /**< Class ID for all status */
00193     connector_class_id_short_message,    /**< Short message specific class ID */
00194     connector_class_id_data_point        /**< Data point class ID */
00195 } connector_class_id_t;
00196 /**
00197 * @}
00198 */
00199 
00200 /**
00201 * @defgroup connector_session_error_t Connector session error codes
00202 * @{
00203 */
00204 /**
00205 * Error values returned from lower communication layer. It can be either from Device Cloud or from
00206 * Connector. These are errors originated from a layer where compression/decompression, resource
00207 * allocation and state handling takes place.
00208 */
00209 typedef enum
00210 {
00211     connector_session_error_none,                   /**< Success */
00212     connector_session_error_fatal,                  /**< Generally represents internal, unexpected error */
00213     connector_session_error_invalid_opcode,         /**< Opcode used in the message is invalid/unsupported */
00214     connector_session_error_format,                 /**< Packet is framed incorrectly */
00215     connector_session_error_session_in_use,         /**< Session with same ID is already in use */
00216     connector_session_error_unknown_session,        /**< Session is not opened or already closed */
00217     connector_session_error_compression_failure,    /**< Failed during compression of the data to send */
00218     connector_session_error_decompression_failure,  /**< Failed during decompression of the received data */
00219     connector_session_error_memory,                 /**< Malloc failed, try to restrict the number of active sessions */
00220     connector_session_error_send,                   /**< Send socket error */
00221     connector_session_error_cancel,                 /**< Used to force termination of a session */
00222     connector_session_error_busy,                   /**< Either the cloud or the connector is busy processing */
00223     connector_session_error_ack,                    /**< Invalid ack count */
00224     connector_session_error_timeout,                /**< Session timed out */
00225     connector_session_error_no_service,             /**< Requested service is not supported */
00226     connector_session_error_count                   /**< Maximum error count value, new value goes before this element */
00227 } connector_session_error_t;
00228 /**
00229 * @}
00230 */
00231 
00232 
00233 /**
00234 * @defgroup connector_tcp_status_t Status Reason Types
00235 * @{
00236 */
00237 /**
00238 * TCP Status values
00239 *
00240 * These status values are used for an event notification.
00241 * @see connector_status_tcp_status_t
00242 */
00243 typedef enum {
00244     connector_tcp_communication_started,      /**< Cloud Connector has established connection with Device Cloud and starts communicating. */
00245     connector_tcp_keepalive_missed,           /**< Cloud Connector didn't receive a keep alive message within the specified keep alive interval @ref tx_keepalive. */
00246     connector_tcp_keepalive_restored          /**< Cloud Connector received a keep alive message after a keep alive message was not received.
00247                                          This is called after the callback has been previously notified with connector_miss_keepalive status. */
00248 } connector_tcp_status_t;
00249 /**
00250 * @}
00251 */
00252 
00253 /**
00254 * @defgroup connector_status_tcp_event_t TCP Status Structure
00255 * @{
00256 */
00257 /**
00258 * TCP status structure is used for @ref connector_request_id_status_tcp callback. See @ref status_tcp.
00259 *
00260 * This is used for an event notification.
00261 */
00262 typedef struct {
00263     connector_tcp_status_t CONST status; /**< TCP status */
00264 } connector_status_tcp_event_t;
00265 /**
00266 * @}
00267 */
00268 
00269 
00270 /**
00271 * @defgroup connector_request_id_status_t  Cloud Connector status
00272 * status request IDs @{
00273 */
00274 /**
00275 * These request IDs are used by Cloud Connector to communicate its status change to the user.
00276 * The class ID associated with these request ID is connector_class_id_status.
00277 */
00278 typedef enum {
00279     connector_request_id_status_tcp,            /**< Used in a callback for Cloud Connector TCP status. The callback is called to notify the application that
00280                                                     TCP connection has been established, a keep-alive message was not received, or keep-alive message was received and restored.
00281                                                     @see connector_tcp_status_t */
00282     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. */
00283 
00284 } connector_request_id_status_t;
00285 /**
00286 * @}
00287 */
00288 
00289 /**
00290 * @defgroup connector_initiate_request_t Initiate action enumeration
00291 * @{
00292 */
00293 /**
00294 * Request IDs used in connector_initiate_action()
00295 */
00296 typedef enum
00297 {
00298     connector_initiate_transport_start, /**< Starts the specified (TCP, UDP or SMS) transport method. */
00299     connector_initiate_transport_stop,  /**< Stops the specified (TCP, UDP or SMS) transport method. */
00300 
00301     #if (defined CONNECTOR_DATA_SERVICE)
00302     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. */
00303     #endif
00304 
00305     #if (defined CONNECTOR_SHORT_MESSAGE)
00306     connector_initiate_ping_request,       /**< Sends a ping request to Device Cloud. Supported only under UDP and SMS transport methods. */
00307     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. */
00308     connector_initiate_session_cancel_all,  /**< Initiates the action to cancel all active sessions. Supported only under UDP and SMS transport methods. */
00309     #endif
00310 
00311     #if (defined CONNECTOR_DATA_POINTS)
00312     connector_initiate_data_point_binary,  /**< Initiates the action to send a binary data point to Device Cloud. */
00313     connector_initiate_data_point_single,  /**< Initiates the action to send data points of a stream to Device Cloud. */
00314     #endif
00315 
00316     connector_initiate_terminate        /**< Terminates and stops Cloud Connector from running. */
00317 } connector_initiate_request_t;
00318 /**
00319 * @}
00320 */
00321 
00322 /**
00323 * @defgroup.connector_callback_status_t Callback return status
00324 * @{
00325 */
00326 /**
00327 * Return status from Cloud Connector callback
00328 */
00329 typedef enum  {
00330     connector_callback_continue,        /**< Continues with no error */
00331     connector_callback_busy,            /**< Callback is busy */
00332     connector_callback_abort,           /**< Aborts Cloud Connector. Cloud Connector frees all memory. @ref connector_init must be called to reStart Cloud Connector. */
00333     connector_callback_unrecognized,    /**< Unsupported callback request */
00334     connector_callback_error            /**< Exits Cloud Connector when error is encountered. Cloud Connector will try reconnecting to Device Cloud
00335                                          if @ref connector_step or @ref connector_run is called again. */
00336 } connector_callback_status_t;
00337 /**
00338 * @}
00339 */
00340 
00341 /**
00342 * @}
00343 */
00344 
00345 /**
00346 * @defgroup connector_transport_t  Transport layer type
00347 * @{
00348 */
00349 /**
00350 * Cloud Connector will use the specified transport
00351 * method when sending a request to Device Cloud.
00352 */
00353 typedef enum
00354 {
00355 #if (defined CONNECTOR_TRANSPORT_TCP)
00356     connector_transport_tcp, /**< Use TCP. @ref CONNECTOR_TRANSPORT_TCP must be enabled. */
00357 #endif
00358 #if (defined CONNECTOR_TRANSPORT_UDP)
00359     connector_transport_udp, /**< Use UDP. @ref CONNECTOR_TRANSPORT_UDP must be enabled. */
00360 #endif
00361 #if (defined CONNECTOR_TRANSPORT_SMS)
00362     connector_transport_sms, /**< Use SMS. @ref CONNECTOR_TRANSPORT_SMS must be enabled. */
00363 #endif
00364     connector_transport_all  /**< All transports. */
00365 } connector_transport_t;
00366 /**
00367 * @}
00368 */
00369 
00370 #include "connector_api_firmware.h"
00371 #include "connector_api_data_service.h"
00372 #include "connector_api_data_point.h"
00373 #include "connector_api_file_system.h"
00374 #include "connector_api_short_message.h"
00375 
00376 #include "connector_api_os.h"
00377 
00378 
00379 /**
00380 * @defgroup connector_request_id_t Request IDs
00381 * @{
00382 */
00383 /**
00384 * Request IDs passed to callback identifying the type of request
00385 * @see connector_class_id_t
00386 */
00387 typedef union {
00388     connector_request_id_config_t config_request;               /**< Configuration request ID for configuration class */
00389     connector_request_id_os_t os_request;                       /**< Operating system request ID for operating system class */
00390     #if (defined CONNECTOR_FIRMWARE_SERVICE)
00391     connector_request_id_firmware_t firmware_request;           /**< Firmware request ID for firmware facility class */
00392     #endif
00393     #if (defined CONNECTOR_DATA_SERVICE)
00394     connector_request_id_data_service_t data_service_request;   /**< Data service request ID for data service class */
00395     #endif
00396     #if (defined CONNECTOR_DATA_POINTS)
00397     connector_request_id_data_point_t data_point_request;       /**< Data service request ID for data service class */
00398     #endif
00399     #if (defined CONNECTOR_RCI_SERVICE)
00400     connector_request_id_remote_config_t remote_config_request; /**< Remote configuration request ID for remote configuration service class */
00401     #endif
00402     #if (defined CONNECTOR_FILE_SYSTEM)
00403     connector_request_id_file_system_t   file_system_request;   /**< File system request ID for file system class */
00404     #endif
00405     connector_request_id_network_t  network_request;            /**< Network request ID for network TCP class, network UDP class and network SMS class */
00406     connector_request_id_status_t status_request;               /**< Status request ID for status class */
00407     #if (defined CONNECTOR_SHORT_MESSAGE)
00408     connector_request_id_sm_t sm_request;                       /**< Short message request ID for short message class */
00409     #endif
00410     int int_value;                                             /**< For debugging purposes. */
00411 } connector_request_id_t;
00412 /**
00413 * @}
00414 */
00415 
00416 /**
00417 * @defgroup connector_handle_t Cloud Connector Handle
00418 * @{
00419 */
00420 /**
00421 *
00422 * Cloud Connector Handle type that is used throughout Cloud Connector APIs, this is used by the application
00423 * to store context information about a connections, for example this could
00424 * be used to store a file descriptor or a pointer to a structure.
00425 */
00426 #define connector_handle_t void *
00427 /**
00428 * @}
00429 */
00430 
00431 /**
00432 * @defgroup connector_config_error_status_t Error Status
00433 * @{
00434 */
00435 /**
00436 * Error status structure for @ref connector_request_id_config_error_status callback which
00437 * is called when Cloud Connector encounters an error.
00438 * @see connector_request_id_config_t
00439 */
00440 typedef struct  {
00441     connector_class_id_t CONST class_id;         /**< Class ID which Cloud Connector encounters error with */
00442     connector_request_id_t CONST request_id;     /**< Request ID which Cloud Connector encounters error with */
00443     connector_status_t CONST status;             /**< Error status */
00444 } connector_config_error_status_t;
00445 /**
00446 * @}
00447 */
00448 
00449 /**
00450 * @defgroup connector_stop_condition_t Condition used on @ref connector_initiate_transport_stop in @ref connector_initiate_action
00451 * @{
00452 */
00453 /**
00454 * This is used to tell how Cloud Connector handles all active sessions before stopping.
00455 *
00456 */
00457 typedef enum {
00458     connector_stop_immediately,             /**< Cancel all active sessions and stop the transport of Cloud Connector immediately */
00459     connector_wait_sessions_complete         /**< Stop the transport of Cloud Connector after all active sessions complete */
00460 } connector_stop_condition_t;
00461 /**
00462 * @}
00463 */
00464 
00465 /**
00466 * @defgroup connector_initiate_stop_request_t Data type used to stop a transport of Cloud Connector
00467 * @{
00468 */
00469 /**
00470 * This data structure is used on @ref connector_initiate_transport_stop in @ref connector_initiate_action API
00471 * to stop a transport.
00472 *
00473 */
00474 typedef struct
00475 {
00476     connector_transport_t transport;        /**< Transport will be stopped:
00477                                             - @ref connector_transport_tcp
00478                                             - @ref connector_transport_udp
00479                                             - @ref connector_transport_sms
00480                                             - @ref connector_transport_all */
00481 
00482     connector_stop_condition_t condition;   /**< Condition to stop the transport:
00483                                              - @ref connector_stop_immediately
00484                                              - @ref connector_wait_sessions_complete */
00485 
00486     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. */
00487 
00488 } connector_initiate_stop_request_t;
00489 /**
00490 * @}
00491 */
00492 
00493 
00494  /**
00495  * @defgroup connector_callback_t Application-defined callback
00496  * @{
00497  * @b Include: connector_api.h
00498  *
00499  * @brief   This is Cloud Connector Application
00500  *          defined callback.
00501  *
00502  * An application must define this function and pass this to Connector during the
00503  * connector_init() call.  This callback is used to pass configuration data and exchange system
00504  * services with the Connector state machine.  The callback
00505  * return value is then used to guide Connector how to
00506  * proceed after completion of the application callback.
00507  *
00508  */
00509  /**
00510  * @param class_id              This is a grouping or category of callback functions.  Each class_id contains a number of related request_id's.
00511  * @param request_id            The request ID defines the specific callback being requested.
00512  * @param data                  Points to specific structure for a given class ID and request ID
00513  *
00514  * @retval  connector_callback_continue The callback completed successfully and Cloud Connector should continue
00515  *                                      it's process.
00516  * @retval  connector_callback_busy     The callback could not complete the operation within the allowable time frame.
00517  *                                      Do not advance the Cloud Connector state and recall this callback at some
00518  *                                      later time.
00519  * @retval  connector_callback_error    An application level error occurred while processing the callback.
00520  * @retval  connector_callback_abort    The application is requesting Cloud Connector to abort execution.  This will
00521  *                                      cause connector_run() or connector_step() to terminate with status @ref connector_abort.
00522  * @retval  connector_callback_unrecognized An unsupported and unrecognized callback was received.  The application does not
00523  *                                      support this request.  This should be implemented in the application to allow for
00524  *                                      graceful recovery and upgrade-ability to future Cloud Connector releases.
00525  *
00526  * @see connector_callback_status_t
00527  * @see connector_init()
00528  */
00529 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);
00530 /**
00531 * @}
00532 */
00533 
00534  /**
00535  * @defgroup connector_init Initialize Cloud Connector.
00536  *@{
00537  * @b Include: connector_api.h
00538  */
00539 /**
00540  * @brief This API is called initially at startup to allocate and initialize Cloud Connector.
00541  *
00542  * This function takes the @ref iik_callback "application-defined callback" function pointer as
00543  * it's only argument.  This callback is used by Cloud Connector to communicate with the
00544  * application environment.  This function must be called prior to other Cloud Connector APIs,
00545  * like connector_step(), connector_run(), and connector_initiate_action().
00546  *
00547  * @param [in] callback  Callback function that is used to
00548  *        interface between the application and Cloud Connector.
00549  *
00550  * @retval NULL         An error occurred and Cloud Connector was unable to initialize.
00551  * @retval "Not NULL"   Success.  A Handle was returned for subsequent Cloud Connector calls.
00552  *
00553  * Example Usage:
00554  * @code
00555  *    connector_handle = connector_init(application_callback);
00556  * @endcode
00557  *
00558  * @see connector_handle_t
00559  * @see connector_callback_t
00560  */
00561 connector_handle_t connector_init(connector_callback_t  const callback);
00562 /**
00563 * @}
00564 */
00565 
00566 /**
00567  * @defgroup connector_step Step Routine
00568  * @{
00569  * @b Include: connector_api.h
00570  */
00571 /**
00572  * @brief   Executes a small portion of Cloud Connector in a non-blocking call.
00573  *
00574  * This non-blocking function is used to execute a portion Cloud Connector after it's been
00575  * successfully initialized with an connector_init() call.  This function performs a sequence of
00576  * operations or events and then returns.  This allows applications to perform other tasks,
00577  * especially in non-threading environment.  For more information on the differences between
00578  * connector_run() and connector_step() see the @ref threading "Cloud Connector threading model".
00579  *
00580  * This function is similar to connector_run() except this is the non-blocking variant.  This function would
00581  * normally be made from system control loop or state machine.  This function must be repeatedly made to
00582  * maintain Cloud Connector state.
00583  *
00584  * See Cloud Connector @ref threading "threading model" section for more information on the differences
00585  * between connector_run() and connector_step().
00586  *
00587  * @param [in] handle  Handle returned from connector_init
00588  *
00589  * @retval connector_init_error             Cloud Connector was not properly initialized.  The application requires a
00590  *                                      call to connector_init() prior to calling this function.
00591  * @retval connector_abort                  Cloud Connector was aborted by callback function.
00592  * @retval connector_invalid_data_size      An @ref iik_callback "application callback" returned an invalid response_length.
00593  *                                      This is an application callback defect and should be corrected.  To locate the
00594  *                                      faulty callback, enable @ref CONNECTOR_DEBUG.  For more information on
00595  *                                      debugging, see the section on @ref debug_routine "how to implement debug support".
00596  * @retval connector_invalid_data_range     An @ref iik_callback "application callback" returned invalid response_data.
00597  *                                      This is an application callback defect and should be corrected.  To locate the
00598  *                                      faulty callback, enable @ref CONNECTOR_DEBUG.  For more information on
00599  *                                      debugging, see the section on @ref debug_routine "how to implement debug support".
00600  * @retval connector_invalid_payload_packet Cloud Connector received invalid payload message.
00601  * @retval connector_keepalive_error        Cloud Connector did not receive keep alive messages. Device Cloud may be offline.
00602  * @retval connector_bad_version            Device Cloud rejected version number.
00603  * @retval connector_exceed_timeout         Callback exceeded timeout value before it returned.
00604  * @retval connector_unsupported_security   Cloud Connector received a packet with unsupported security.
00605  * @retval connector_invalid_data           An @ref iik_callback "application callback" returned unexpected NULL response_data.
00606  *                                      This is an application callback defect and should be corrected.  To locate the
00607  *                                      faulty callback, enable @ref CONNECTOR_DEBUG.  For more information on
00608  *                                      debugging, see the section on @ref debug_routine "how to implement debug support".
00609  * @retval connector_device_terminated      Cloud Connector was terminated by user via connector_initiate_action() call.
00610  * @retval connector_idle                   Cloud Connector is idling. Cloud Connector has no message to process and relinquishes other task execution.
00611  * @retval connector_working                Cloud Connector is processing a message and should be called at the earliest possible time.
00612  * @retval connector_pending                Cloud Connector is busy or waiting to process a message and relinquishes other task execution
00613  * @retval connector_active                 Cloud Connector is busy or waiting to process a message and should be called
00614  *                                      at the earliest possible time
00615  *
00616  *
00617  * Example Usage:
00618  * @code
00619  *     connector_status_t status;
00620  *     connector_handle_t connector_handle = connector_init(application_callback);
00621  *
00622  *     for (;;)
00623  *     {
00624  *          status = connector_step(connector_handle);
00625  *          other_system_tasks();
00626  *     }
00627  * @endcode
00628  *
00629  * @see connector_init()
00630  * @see connector_handle_t
00631  * @see connector_status_t
00632  * @see connector_run()
00633  */
00634 connector_status_t connector_step(connector_handle_t const handle);
00635 /**
00636 * @}
00637 */
00638 
00639 
00640  /**
00641  * @defgroup connector_run Run routine
00642  * @{
00643  * @b Include: connector_api.h
00644  */
00645 /**
00646  * @brief   Runs Cloud Connector as a blocking call.
00647  *
00648  * This blocking function is typically used in a separate thread (in a multi-threaded environment) to run
00649  * Cloud Connector after it's been successfully initialized with an connector_init() call.  This function
00650  * only returns when Cloud Connector encounters an unexpected error.  This function is similar to
00651  * connector_step() except this is the blocking variant.
00652  *
00653  * See Cloud Connector @ref threading "Threading Model section" for more information on the differences
00654  * between connector_run() and connector_step().
00655  *
00656  * @param [in] handle                   Handle returned from connector_init() call.
00657  *
00658  * @retval connector_init_error             Cloud Connector was not properly initialized.  The application requires a
00659  *                                      call to connector_init() prior to calling this function.
00660  * @retval connector_abort                  Cloud Connector was aborted by callback function.
00661  * @retval connector_invalid_data_size      An @ref iik_callback "application callback" returned an invalid response_length.
00662  *                                      This is an application callback defect and should be corrected.  To locate the
00663  *                                      faulty callback, enable @ref CONNECTOR_DEBUG.  For more information on
00664  *                                      debugging, see the section on @ref debug_routine "how to implement debug support".
00665  * @retval connector_invalid_data_range     An @ref iik_callback "application callback" returned invalid response_data.
00666  *                                      This is an application callback defect and should be corrected.  To locate the
00667  *                                      faulty callback, enable @ref CONNECTOR_DEBUG.  For more information on
00668  *                                      debugging, see the section on @ref debug_routine "how to implement debug support".
00669  * @retval connector_keepalive_error        Cloud Connector did not receive keep alive messages. Device Cloud may be offline.
00670  * @retval connector_bad_version            Device Cloud rejected version number.
00671  * @retval connector_exceed_timeout         Callback exceeded timeout value before it returned.
00672  * @retval connector_unsupported_security   Cloud Connector received a packet with unsupported security.
00673  * @retval connector_invalid_data           An @ref iik_callback "application callback" returned unexpected NULL response_data.
00674  *                                      This is an application callback defect and should be corrected.  To locate the
00675  *                                      faulty callback, enable @ref CONNECTOR_DEBUG.  For more information on
00676  *                                      debugging, see the section on @ref debug_routine "how to implement debug support".
00677  * @retval connector_device_error           Close Callback returns
00678  *                                      error. If connector_step or connector_run is called again, it
00679  *                                      will re-establish the connection.
00680  * @retval connector_device_terminated      Cloud Connector was terminated by user via connector_initiate_action call.
00681  *
00682  * Example Usage:
00683  * @code
00684  *     connector_status_t status;
00685  *     connector_handle_t connector_handle = connector_init(application_callback);
00686  *
00687  *     status = connector_run(connector_handle);
00688  * @endcode
00689  *
00690  * @see connector_init()
00691  * @see connector_handle_t
00692  * @see connector_status_t
00693  * @see connector_step()
00694  */
00695 connector_status_t connector_run(connector_handle_t const handle);
00696 /**
00697 * @}
00698 */
00699 
00700 
00701  /**
00702  * @defgroup connector_initiate_action Initiate Action
00703  * @{
00704  * @b Include: connector_api.h
00705  */
00706 /**
00707  * @brief   Requests Cloud Connector to perform an asynchronous action.
00708  *
00709  * This function is called to initiate an Cloud Connector action.  It can be
00710  * used to initiate a send data sequence from the device to Device Cloud,
00711  * or to terminate Cloud Connector library.
00712  *
00713  * @param [in] handle  Handle returned from the connector_init() call.
00714  *
00715  * @param [in] request  Request action (one of the following):
00716  *                      @li @b connector_initiate_terminate:
00717  *                          Terminates and stops Cloud Connector from running.  This call closes all open network
00718  *                          Handles and frees all allocated memory.
00719  *                          If the application is using connector_step(), the next call to connector_step() terminates
00720  *                          Cloud Connector.  If a blocking call to connector_run() is still pending, this call
00721  *                          will eventually terminate that call.  Once Cloud Connector is terminated, the
00722  *                          Cloud Connector must restart by calling connector_init().
00723  *
00724  *                      @li @b connector_initiate_send_data:
00725  *                           This is used to trigger the send
00726  *                           data to Device Cloud. Only the
00727  *                           header information is passed by
00728  *                           this method. The actual data is
00729  *                           transferred through callbacks. The
00730  *                           data is stored in a specified file
00731  *                           on Device Cloud.
00732  *
00733  *                      @li @b connector_initiate_transport_start:
00734  *                          Starts the specified (@ref connector_transport_tcp
00735  *                          , @ref connector_transport_udp or @ref connector_transport_sms) transport method.
00736  *
00737  *                      @li @b connector_initiate_transport_stop:
00738  *                          Stops the Cloud Connector transport mechanism.  Note this call
00739  *                          triggers a @ref connector_request_id_status_stop_completed callback.
00740  *                          Transports include:
00741  *                              - @ref connector_transport_tcp - TCP transport
00742  *                              - @ref connector_transport_udp - UDP transport
00743  *                              - @ref connector_transport_sms - SMS transport
00744  *                              - @ref connector_transport_all - all transports.
00745  *
00746  *                      @li @b connector_initiate_data_point_binary:
00747  *                          Initiates the action to send a binary data point to Device Cloud.
00748  *
00749  *                      @li @b connector_initiate_data_point_single:
00750  *                          Initiates the action to send data points which are belongs to a single stream on Device Cloud.
00751  *
00752  *                      @li @b connector_initiate_ping_request:
00753  *                          Sends status message to the Device Cloud.  Supported for
00754  *                          @ref connector_transport_udp and @ref connector_transport_sms transports method only.
00755  *
00756  *                      @li @b connector_initiate_session_cancel:
00757  *                          Initiates the action to cancel a session.
00758  *
00759  * @param [in] request_data  Pointer to Request data
00760  *                      @li @b connector_initiate_terminate:
00761  *                          Should be NULL.
00762  *                      @li @b connector_initiate_send_data:
00763  *                          Pointer to @ref connector_request_data_service_send_t "connector_request_data_service_send_t".
00764  *                      @li @b connector_initiate_transport_start:
00765  *                          Pointer to @ref connector_transport_t "connector_transport_t"
00766  *                      @li @b connector_initiate_transport_stop:
00767  *                          Pointer to @ref connector_initiate_stop_request_t "connector_initiate_stop_request_t"
00768  *                      @li @b connector_initiate_data_point_binary:
00769  *                          Pointer to @ref connector_request_data_point_binary_t "connector_request_data_point_binary_t"
00770  *                      @li @b connector_initiate_data_point_single:
00771  *                          Pointer to @ref connector_request_data_point_single_t "connector_request_data_point_single_t"
00772  *                      @li @b connector_initiate_ping_request:
00773  *                          Pointer to @ref connector_sm_send_ping_request_t "connector_sm_send_ping_request_t"
00774  *                      @li @b connector_initiate_session_cancel:
00775  *                          Pointer to @ref connector_sm_cancel_request_t "connector_sm_cancel_request_t"
00776  *
00777  * @retval connector_success              No error
00778  * @retval connector_init_error           Cloud Connector was not initialized or not connected to Device Cloud.
00779  * @retval connector_abort                Callback aborted Cloud Connector.
00780  * @retval connector_invalid_data         Invalid parameter
00781  * @retval connector_no_resource          Insufficient memory
00782  * @retval connector_service_busy         Cloud Connector is busy
00783  *
00784  * Example Usage:
00785  * @code
00786  *     static connector_request_data_service_send_t  file_info;
00787  *     :
00788  *     status = connector_initiate_action(handle, connector_initiate_send_data, &file_info);
00789  *     :
00790  *     :
00791  *     status = connector_initiate_action(connector_handle, connector_initiate_terminate, NULL);
00792  * @endcode
00793  *
00794  * @see connector_handle_t
00795  * @see connector_callback_t
00796  */
00797 connector_status_t connector_initiate_action(connector_handle_t const handle, connector_initiate_request_t const request, void const * const request_data);
00798 /**
00799 * @}.
00800 */
00801 
00802 #undef CONST
00803 #if (defined CONNECTOR_CONST_STORAGE)
00804 #define CONST CONNECTOR_CONST_STORAGE
00805 #undef CONNECTOR_CONST_STORAGE
00806 #endif
00807 
00808 #endif
00809