connector_api_config.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 #ifndef CONNECTOR_API_CONFIG_H
00013 #define CONNECTOR_API_CONFIG_H
00014 
00015 /**
00016 * @defgroup connector_request_id_config_t Configuration Request IDs
00017 * @{
00018 */
00019 /**
00020 * Configuration Request Id passed to the application's callback for requesting configuration data.
00021 * The class id for this connector_request_id_config_t is connector_class_id_config.
00022 */
00023 typedef enum {
00024     connector_request_id_config_device_id,         /**< Requesting callback to return a unique device id which is used to identify the device.*/
00025     connector_request_id_config_set_device_id,     /**< Requesting callback to set a new device ID given by Device Cloud (when provisioning is enabled) */
00026     connector_request_id_config_vendor_id,         /**< Requesting callback to return a unique vendor id identifying the manufacturer of a device. */
00027     connector_request_id_config_device_type,       /**< Requesting callback to return device type that identifies the type of the device  */
00028     connector_request_id_config_device_cloud_url,  /**< Requesting callback to return the Device Cloud URL which will be connected to */
00029     connector_request_id_config_get_device_cloud_phone,/**< Requesting callback to get the Device Cloud Phone Number where to send SMSs (Only used for SMS transport) */
00030     connector_request_id_config_set_device_cloud_phone,/**< Requesting callback to set the Device Cloud Phone Number where to send SMSs (Only used for SMS transport) */
00031     connector_request_id_config_device_cloud_service_id,/**< Requesting callback to return the Device Cloud Phone Number service-id (if used)
00032                                                              where to send SMSs (Only used for SMS transport) */
00033     connector_request_id_config_connection_type,   /**< Requesting callback to return LAN or WAN connection type */
00034     connector_request_id_config_mac_addr,          /**< Requesting callback to return device's MAC addresss */
00035     connector_request_id_config_link_speed,        /**< Requesting callback to return link speed for WAN connection type */
00036     connector_request_id_config_phone_number,      /**< Requesting callback to return phone number dialed for WAN connection type */
00037     connector_request_id_config_tx_keepalive,      /**< Requesting callback to return Device Cloud's Tx keep alive interval in seconds */
00038     connector_request_id_config_rx_keepalive,      /**< Requesting callback to return Device Cloud's Rx keep alive interval in seconds */
00039     connector_request_id_config_wait_count,        /**< Requesting callback to return the number of intervals of not receiving a keep alive message after which a connection should be considered lost. */
00040     connector_request_id_config_ip_addr,           /**< Requesting callback to return device's IP address */
00041     connector_request_id_config_error_status,      /**< Error status notification which tells callback that error is encountered. */
00042     connector_request_id_config_firmware_facility, /**< Requesting callback to return whether firmware facility is supported or not. */
00043     connector_request_id_config_data_service,      /**< Requesting callback to return whether data service is supported or not. */
00044     connector_request_id_config_file_system,       /**< Requesting callback to return whether file system is supported or not. */
00045     connector_request_id_config_remote_configuration, /**< Requesting callback to return whether remote configuration is supported or not. */
00046     connector_request_id_config_max_transaction,   /**< Requesting callback to obtain maximum messaging sessions supported by client. */
00047     connector_request_id_config_device_id_method,  /**< Requesting callback to obtain method on how device id is generated */
00048     connector_request_id_config_imei_number,       /**< Requesting callback to return GSM IMEI number */
00049     connector_request_id_config_network_tcp,       /**< Requesting callback to return whether connection over TCP need to start now. */
00050     connector_request_id_config_network_udp,       /**< Requesting callback to return whether connection over UDP need to start now. */
00051     connector_request_id_config_network_sms,       /**< Requesting callback to return whether connection over SMS need to start now. */
00052     connector_request_id_config_wan_type,          /**< Requesting callback to return WAN type used. It tells Cloud Connector whether it's GSM IMEI, CDMA ESN or CDMA MEID. */
00053     connector_request_id_config_esn,               /**< Requesting callback to return CDMA ESN (Electronic Serial Number) */
00054     connector_request_id_config_meid,              /**< Requesting callback to return CDMA MEID (Mobile Equipment Identifier) */
00055     connector_request_id_config_identity_verification,     /**< Requesting callback to return identity verification form. */
00056     connector_request_id_config_password           /**< Requesting callback to return password for the password identity verification form */
00057 } connector_request_id_config_t;
00058 /**
00059 * @}
00060 */
00061 
00062 /**
00063 * @defgroup connector_config_pointer_data_t Data Pointer Configuration
00064 * @{
00065 */
00066 /**
00067 * Application Binary Data Pointer Configuration for the following callbacks:
00068 *   -# @ref connector_request_id_config_device_id
00069 *   -# @ref connector_request_id_config_mac_addr
00070 *   -# @ref connector_request_id_config_imei_number
00071 *   -# @ref connector_request_id_config_esn
00072 *   -# @ref connector_request_id_config_meid
00073 *
00074 * @see @ref device_id
00075 * @see @ref mac_address
00076 * @see @ref imei_number
00077 * @see @ref esn_number
00078 * @see @ref meid_number
00079 *
00080 */
00081 typedef struct {
00082     uint8_t * data;               /**< Application data pointer */
00083     size_t CONST bytes_required;  /**< Number of bytes required and needed on the application data pointer */
00084 } connector_config_pointer_data_t;
00085 /**
00086 * @}
00087 */
00088 
00089 
00090 /**
00091 * @defgroup connector_config_vendor_t  Vendor ID Configuration
00092 * @{
00093 */
00094 /**
00095 * Vendor ID configuration for @ref connector_request_id_config_vendor_id callback
00096 *
00097 * @see @ref vendor_id
00098 *
00099 */
00100 typedef struct {
00101     uint32_t id;    /**< Vendor ID */
00102 } connector_config_vendor_id_t;
00103 /**
00104 * @}
00105 */
00106 
00107 
00108 /**
00109 * @defgroup connector_config_name_data_t String Pointer Configuration
00110 * @{
00111 */
00112 /**
00113 * Application String Pointer Configuration for the following callbacks:
00114 *
00115 *   -# @ref connector_request_id_config_device_type
00116 *   -# @ref connector_request_id_config_device_cloud_url
00117 *   -# @ref connector_request_id_config_phone_number
00118 *   -# @ref connector_request_id_config_password
00119 *
00120 * @see @ref device_type
00121 * @see @ref device_cloud_url
00122 * @see @ref phone_number
00123 * @see @ref password
00124 *
00125 */
00126 typedef struct {
00127     char * string;  /**< Application string pointer */
00128     size_t length;  /**< Number of bytes in the application string pointer */
00129 } connector_config_pointer_string_t;
00130 /**
00131 * @}
00132 */
00133 
00134 /**
00135 * @defgroup connector_connection_type_t Connection Types
00136 * @{
00137 */
00138 /**
00139 * Connection type configuration of the device
00140 *
00141 * @see connector_config_connection_type_t
00142 */
00143 typedef enum {
00144    connector_connection_type_lan,   /**< LAN connection type for Ethernet or WiFi */
00145    connector_connection_type_wan    /**< WAN connection type for PPP over Modem */
00146 } connector_connection_type_t;
00147 /**
00148 * @}
00149 */
00150 
00151 /**
00152 * @defgroup connector_config_connection_type_t Connection Type Configuration
00153 * @{
00154 */
00155 /**
00156 * Device connection type configuration for @ref connector_request_id_config_connection_type callback
00157 *
00158 * @see @ref connection_type
00159 *
00160 */
00161 typedef struct {
00162     connector_connection_type_t type; /**< Device connection type */
00163 } connector_config_connection_type_t;
00164 /**
00165 * @}
00166 */
00167 
00168 
00169 /**
00170 * @defgroup connector_config_link_speed_t  Link Speed Configuration
00171 * @{
00172 */
00173 /**
00174 * Device link speed configuration for WAN connection type for @ref connector_request_id_config_link_speed callback
00175 *
00176 * @see @ref link_speed
00177 * @see @ref connection_type
00178 */
00179 typedef struct {
00180     uint32_t speed;        /**< Device link speed  */
00181 } connector_config_link_speed_t;
00182 /**
00183 * @}
00184 */
00185 
00186 
00187 /**
00188 * @defgroup connector_config_keepalive_t Keep-Alive Interval Configuration
00189 * @{
00190 */
00191 /**
00192 * Keep-alive interval configuration used for the following callbacks:
00193 *   -# @ref connector_request_id_config_tx_keepalive
00194 *   -# @ref connector_request_id_config_rx_keepalive
00195 *
00196 * @see @ref tx_keepalive
00197 * @see @ref rx_keepalive
00198 *
00199 */
00200 typedef struct {
00201     uint16_t interval_in_seconds;       /**< Device keep-alive interval */
00202 } connector_config_keepalive_t;
00203 /**
00204 * @}
00205 */
00206 
00207 
00208 /**
00209 * @defgroup connector_config_wait_count_t Wait Count Configuration
00210 * @{
00211 */
00212 /**
00213 * Device wait count configuration for @ref connector_request_id_config_wait_count callback
00214 *
00215 * @see @ref wait_count
00216 * @see @ref tx_keepalive
00217 */
00218 typedef struct {
00219     uint16_t count;       /**< wait count */
00220 } connector_config_wait_count_t;
00221 /**
00222 * @}
00223 */
00224 
00225 /**
00226 * @defgroup connector_config_ip_address_type_t IP Address Configuration Types
00227 * @{
00228 */
00229 /**
00230 * Device IP address types
00231 *
00232 * @see connector_config_ip_address_t
00233 */
00234 typedef enum {
00235     connector_ip_address_ipv4,  /**< IPv4 address type */
00236     connector_ip_address_ipv6   /**< IPv6 address type */
00237 } connector_config_ip_address_type_t;
00238 /**
00239 * @}
00240 */
00241 
00242 /**
00243 * @defgroup connector_config_ip_addr_t Device IP Address Configuration
00244 * @{
00245 */
00246 /**
00247 * Device IP Address Configuration for @ref connector_request_id_config_ip_addr callback
00248 *
00249 * @see @ref ip_address
00250 */
00251 typedef struct {
00252     uint8_t * address;        /**< Device's IP address */
00253     connector_config_ip_address_type_t ip_address_type; /**< IPv4 or IPv6 device IP address type */
00254 } connector_config_ip_address_t;
00255 /**
00256 * @}
00257 */
00258 
00259 
00260 /**
00261 * @defgroup connector_config_support_status_t Service Supported Configuration
00262 * @{
00263 */
00264 /**
00265 * Service supported status configuration for the following callbacks:
00266 *   -# @ref connector_request_id_config_firmware_facility
00267 *   -# @ref connector_request_id_config_data_service
00268 *   -# @ref connector_request_id_config_file_system
00269 *
00270 * @see @ref firmware_support
00271 * @see @ref data_service_support
00272 * @see @ref file_system_support
00273 * @see @ref rci_support
00274 *
00275 */
00276 typedef struct {
00277     connector_bool_t supported; /**< Application service supported status */
00278 } connector_config_supported_t;
00279 /**
00280 * @}
00281 */
00282 
00283 
00284 /**
00285 * @defgroup connector_device_id_method_t Device ID Method Types
00286 * @{
00287 *
00288 */
00289 /**
00290  * Device ID method type which is used in the application's callback telling
00291  * the connector how to obtain a device ID.
00292  *
00293  * @see connector_config_device_id_method_t
00294  */
00295 typedef enum {
00296     connector_device_id_method_auto,         /**< Callback returns this type telling Cloud Connector to
00297                                                  generate the device ID from MAC address (See @ref mac_address callback)
00298                                                  for LAN connection type or generate the device ID according to the @ref wan_type.
00299                                                  @note Cloud Connector will not call @ref device_id callback. */
00300     connector_device_id_method_manual        /**< Callback returns this type telling Cloud Connector to retrieve device ID from
00301                                                   @ref device_id callback */
00302 } connector_device_id_method_t;
00303 /**
00304 * @}
00305 */
00306 
00307 
00308 /**
00309 * @defgroup connector_config_device_id_method_t Device ID Method Configuration
00310 * @{
00311 */
00312 /**
00313  * Device ID method configuration returned by the application's callback for @ref connector_request_id_config_device_id_method callback.
00314  *
00315  * @see @ref device_id_method
00316 */
00317 typedef struct {
00318     connector_device_id_method_t method;    /**< Device ID method */
00319 } connector_config_device_id_method_t;
00320 /**
00321 * @}
00322 */
00323 
00324 
00325 /**
00326 * @defgroup connector_connect_auto_type_t Network Connection Action Types
00327 * @{
00328 */
00329 /**
00330 * Network connection action used to tell Cloud Connector to automatic or manual connect.
00331 *
00332 * @see connector_config_connect_type_t
00333 */
00334 typedef enum {
00335 
00336     connector_connect_auto,     /**< Automatic connect to Device Cloud */
00337     connector_connect_manual   /**< Manual connect to Device Cloud */
00338 } connector_connect_auto_type_t;
00339 /**
00340 * @}
00341 */
00342 
00343 
00344 /**
00345 * @defgroup connector_config_connect_status_t Network Connection Action Type Configuration
00346 * @{
00347 */
00348 /**
00349 * Connection action which is used to to tell the connector to make connection to
00350 * Device Cloud automatically or manually. It's used for the following callbacks:
00351 *   -# @ref connector_request_id_config_network_tcp
00352 *   -# @ref connector_request_id_config_network_udp
00353 *   -# @ref connector_request_id_config_network_sms
00354 *
00355 * @see @ref network_tcp_start
00356 * @see @ref network_udp_start
00357 * @see @ref network_sms_start
00358 */
00359 typedef struct {
00360     connector_connect_auto_type_t type;   /**< Connection action */
00361 } connector_config_connect_type_t;
00362 /**
00363 * @}
00364 */
00365 
00366 
00367 /**
00368 * @defgroup connector_wan_type_t Device WAN Types
00369 * @{
00370 */
00371 /**
00372  * Device WAN connection type which tells the connector the device WAN type for the device WAN ID.
00373  *
00374  * @see connector_config_wan_type_t
00375  */
00376 typedef enum {
00377     connector_wan_type_imei,    /**< IMEI number for GSM network */
00378     connector_wan_type_esn,     /**< ESN for CDMA network */
00379     connector_wan_type_meid     /**< MEID for CDMA network */
00380 } connector_wan_type_t;
00381 /**
00382 * @}
00383 */
00384 
00385 
00386 /**
00387 * @defgroup connector_config_wan_type_t Device WAN Type Configuration
00388 * @{
00389 */
00390 /**
00391 * Device WAN type configuration for @ref connector_request_id_config_wan_type callback.
00392 * This is used to tell the connector the device WAN type. The connector uses this WAN type to
00393 * get a corresponding WAN ID.
00394 *
00395 * @ref wan_type
00396 * @ref imei_number
00397 * @ref esn_number
00398 * @ref meid_number
00399 **/
00400 typedef struct {
00401     connector_wan_type_t type;   /**< WAN type */
00402 } connector_config_wan_type_t;
00403 /**
00404 * @}
00405 */
00406 
00407 
00408 /**
00409 * @defgroup connector_identity_verification_t  Identity Verification Form Types
00410 * @{
00411 */
00412 /**
00413  * Identify verification tells the connector to use simple or password identity verification for TCP connection.
00414  *
00415  * @see connector_config_identity_verification_t
00416  */
00417 typedef enum {
00418     connector_identity_verification_simple,         /**< Callback returns this form for simple identity verification. Cloud Connector just transmits the
00419                                                      device ID and the Device Cloud URL. */
00420     connector_identity_verification_password        /**< Callback returns this form for password identity verification. Cloud Connector exchanges a pre-shared
00421                                                      secret password with Device Cloud. The password must match the password set in Device Cloud.
00422                                                      @note Cloud Connector will call @ref connector_request_id_config_password callback for the password. */
00423 } connector_identity_verification_t;
00424 /**
00425 * @}
00426 */
00427 
00428 
00429 /**
00430 * @defgroup connector_config_identity_verification_t Device Identity Verification Configuration
00431 * @{
00432 */
00433 /**
00434 * Identify verification configuration for @ref connector_request_id_config_identity_verification callback.
00435 * It tells the connector to use simple or password identity verification for TCP connection.
00436 *
00437 * @see @ref identity_verification
00438 * @see @ref password
00439 * @see @ref connector_request_id_config_password
00440 **/
00441 typedef struct {
00442     connector_identity_verification_t type;   /**< Identity verification type */
00443 
00444 } connector_config_identity_verification_t;
00445 /**
00446 * @}
00447 */
00448 
00449 
00450 /**
00451 * @defgroup connector_config_max_transaction_t Device Maximum Transaction Configuration
00452 * @{
00453 */
00454 /**
00455 * Device maximum transaction configuration for @ref connector_request_id_config_max_transaction callback.
00456 *
00457 * @see @ref max_msg_transactions
00458 **/
00459 typedef struct {
00460     uint8_t count;   /**< Maximum transaction count */
00461 } connector_config_max_transaction_t;
00462 /**
00463 * @}
00464 */
00465 
00466 #if !defined _CONNECTOR_API_H
00467 #error  "Illegal inclusion of connector_api_config.h. You should only include connector_api.h in user code."
00468 #endif
00469 
00470 #else
00471 #error  "Illegal inclusion of connector_api_config.h. You should only include connector_api.h in user code."
00472 #endif
00473 
00474