arm_uc_http_socket.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef UPDATE_CLIENT_SOURCE_HTTP_SOCKET_H
00020 #define UPDATE_CLIENT_SOURCE_HTTP_SOCKET_H
00021 
00022 #include "update-client-common/arm_uc_common.h"
00023 
00024 #include <pal.h>
00025 
00026 /**
00027  * @brief Events passed to event handler.
00028  * @details EVENT_HASH Get hash complete.
00029  *          EVENT_DATE Get date complete.
00030  *          EVENT_DOWNLOAD_PENDING Download complete with data pending.
00031  *          EVENT_DOWNLOAD_DONE Download complete, all done.
00032  */
00033 typedef enum {
00034     UCS_HTTP_EVENT_HASH,
00035     UCS_HTTP_EVENT_DATE,
00036     UCS_HTTP_EVENT_DOWNLOAD,
00037     UCS_HTTP_EVENT_ERROR,
00038     UCS_HTTP_EVENT_ERROR_BUFFER_SIZE
00039 } arm_ucs_http_event_t;
00040 
00041 typedef enum {
00042     RQST_TYPE_NONE, // to indicate idle
00043     RQST_TYPE_HASH_ETAG,
00044     RQST_TYPE_HASH_DATE,
00045     RQST_TYPE_GET_FILE,
00046     RQST_TYPE_GET_FRAG
00047 } arm_uc_http_rqst_t;
00048 
00049 typedef enum {
00050     STATE_DISCONNECTED,
00051     STATE_CONNECTING,
00052     STATE_PROCESS_HEADER,
00053     STATE_PROCESS_BODY,
00054     STATE_CONNECTED_IDLE
00055 } arm_uc_http_socket_state_t;
00056 
00057 typedef enum {
00058     SOCKET_EVENT_UNDEFINED,
00059     SOCKET_EVENT_INITIATE,
00060     SOCKET_EVENT_LOOKUP_START,
00061     SOCKET_EVENT_LOOKUP_WAITING,
00062     SOCKET_EVENT_LOOKUP_BLOCKED,
00063     SOCKET_EVENT_LOOKUP_FAILED,
00064     SOCKET_EVENT_LOOKUP_DONE,
00065     SOCKET_EVENT_CONNECT_START,
00066     SOCKET_EVENT_CONNECT_BLOCKED,
00067     SOCKET_EVENT_CONNECT_DONE,
00068     SOCKET_EVENT_SEND_START,
00069     SOCKET_EVENT_SEND_BLOCKED,
00070     SOCKET_EVENT_SEND_DONE,
00071     SOCKET_EVENT_HEADER_START,
00072     SOCKET_EVENT_HEADER_MORE,
00073     SOCKET_EVENT_HEADER_BLOCKED,
00074     SOCKET_EVENT_HEADER_DONE,
00075     SOCKET_EVENT_FRAG_START,
00076     SOCKET_EVENT_FRAG_MORE,
00077     SOCKET_EVENT_FRAG_BLOCKED,
00078     SOCKET_EVENT_FRAG_DONE,
00079     SOCKET_EVENT_RECEIVE_DONE,
00080     SOCKET_EVENT_RESTART,
00081     SOCKET_EVENT_TIMER_FIRED,
00082     SOCKET_EVENT_RESUME_WAITING,
00083     SOCKET_EVENT_RESUME_IDLE,
00084     SOCKET_EVENT_RESUME_INTERVAL,
00085     SOCKET_EVENT_RESUME_ATTEMPT,
00086     SOCKET_EVENT_RESUME_TERMINATED,
00087     SOCKET_EVENT_RESUME_ERROR
00088 } arm_uc_http_socket_event_t;
00089 
00090 /**
00091  * @brief Prototype for event handler.
00092  */
00093 typedef void (*ARM_UCS_HttpEvent_t)(uintptr_t event);
00094 
00095 
00096 // Number of fragments in a burst, it is not required to use one of these values.
00097 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__DISABLED         0   // do not use http fragments. Do only single request
00098 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__ONE              1
00099 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__LIGHT            4
00100 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__MILD             16
00101 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__MODERATE         64
00102 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__HEAVY            256
00103 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__EXTREME          1024
00104 
00105 #if !defined(ARM_UC_MULTI_FRAGS_PER_HTTP_BURST)
00106 #if defined(TARGET_IS_PC_LINUX)
00107 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST           ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__DISABLED
00108 #else
00109 #define ARM_UC_MULTI_FRAGS_PER_HTTP_BURST           ARM_UC_MULTI_FRAGS_PER_HTTP_BURST__MODERATE
00110 #endif
00111 #endif
00112 
00113 // Developer-facing #defines allow easier testing of parameterised resume.
00114 // If not available, it becomes extremely difficult to detect exactly when the resume
00115 //   functionality is taking place, or to set values outside of the assumed 'reasonable'
00116 //   range (which can't predict all use cases), which hampers assessment of the settings.
00117 
00118 // Print very high priority messages about resume activity for debugging.
00119 // Also, disable checks on resume initialization values.
00120 // Normally compiler errors out if checks enabled and out of permissible range.
00121 #define ARM_UC_HTTP_RESUME_DEFAULT_ATTEMPT_TEST_MESSAGES_ENABLE 0
00122 
00123 // !do not modify or delete these definitions!
00124 // default configuration values for HTTP resume functionality.
00125 // to modify from default values, declare as below but without _DEFAULT
00126 //   eg. ARM_UC_HTTP_RESUME_EXPONENTIATION_FACTOR   3
00127 
00128 #define ARM_UC_HTTP_RESUME_DEFAULT_EXPONENTIATION_FACTOR        2
00129 #define ARM_UC_HTTP_RESUME_DEFAULT_INITIAL_DELAY_SECS           5
00130 #define ARM_UC_HTTP_RESUME_DEFAULT_MAXIMUM_DELAY_SECS           (60*60)
00131 #define ARM_UC_HTTP_RESUME_DEFAULT_MAXIMUM_DOWNLOAD_TIME_SECS   (7*24*60*60)
00132 
00133 typedef struct {
00134     /* external callback handler */
00135     ARM_UCS_HttpEvent_t callback_handler;
00136 
00137     /* location */
00138     arm_uc_uri_t *request_uri;
00139     arm_uc_uri_t *open_request_uri;
00140 
00141     /* buffer to store downloaded data */
00142     arm_uc_buffer_t *request_buffer;
00143 
00144     /* fragment offset in a multi-fragment download */
00145     uint32_t request_offset;
00146     uint32_t open_request_offset;
00147 
00148     /* request type */
00149     arm_uc_http_rqst_t request_type;
00150     arm_uc_http_rqst_t open_request_type;
00151 
00152     /* internal state */
00153 
00154     /* remaining bytes in request */
00155     uint32_t open_burst_requested;
00156     uint32_t open_burst_expected;
00157     uint32_t open_burst_received;
00158 
00159     uint32_t header_end_index;
00160     uint32_t number_of_pieces;
00161 
00162     /* socket and socket timer management */
00163     arm_uc_http_socket_state_t socket_state;
00164     palTimerID_t socket_timeout_timer_id;
00165     bool socket_timeout_timer_is_running;
00166 
00167     /* socket event future and history */
00168     arm_uc_http_socket_event_t resume_socket_phase;
00169     arm_uc_http_socket_event_t expected_socket_event;
00170 
00171     /* pointer to socket */
00172     palSocket_t socket;
00173 
00174     /* cache for storing DNS lookup */
00175     palSocketAddress_t cache_address;
00176     palSocketLength_t cache_address_length;
00177 } arm_uc_http_socket_context_t;
00178 
00179 /**
00180  * @brief Initialize Http module.
00181  * @details A memory struct is passed as well as a function pointer for event
00182  *          handling.
00183  *
00184  * @param context Struct holding all global variables.
00185  * @param handler Event handler for signaling when each operation is complete.
00186  * @return Error code.
00187  */
00188 arm_uc_error_t ARM_UCS_HttpSocket_Initialize(arm_uc_http_socket_context_t *context,
00189                                              ARM_UCS_HttpEvent_t handler);
00190 
00191 /**
00192  * @brief Resets HTTP socket to uninitialized state and clears memory struct.
00193  * @details HTTP sockets must be initialized again before use.
00194  * @return Error code.
00195  */
00196 arm_uc_error_t ARM_UCS_HttpSocket_Terminate(void);
00197 
00198 /**
00199  * @brief Get hash for resource at URI.
00200  * @details Store hash in provided buffer. Enclosing "" and '\0' are removed.
00201  *
00202  *          Event generated: EVENT_HASH
00203  *
00204  * @param uri Pointer to struct with resource location.
00205  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00206  * @return Error code.
00207  */
00208 arm_uc_error_t ARM_UCS_HttpSocket_GetHash(arm_uc_uri_t *uri, arm_uc_buffer_t *buffer);
00209 
00210 /**
00211  * @brief Get date for resource at URI.
00212  * @details Store Last-Modified data in provided buffer. Enclosing "" and '\0' are removed.
00213  *
00214  *          Event generated: EVENT_DATE
00215  *
00216  * @param uri Pointer to struct with resource location.
00217  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00218  * @return Error code.
00219  */
00220 arm_uc_error_t ARM_UCS_HttpSocket_GetDate(arm_uc_uri_t *uri, arm_uc_buffer_t *buffer);
00221 
00222 /**
00223  * @brief Get full resource at URI.
00224  * @details Download resource at URI and store in provided buffer.
00225  *          If the provided buffer is not big enough to contain the whole resource
00226  *          what can fit in the buffer will be downloaded.
00227  *          The user can then use GetFragment to download the rest.
00228 
00229  *          Events generated: EVENT_DOWNLOAD_PENDING if there is still data to
00230  *          download and EVENT_DOWNLOAD_DONE if the file is completely downloaded.
00231  *
00232  * @param uri Pointer to structure with resource location.
00233  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00234  * @return Error code.
00235  */
00236 arm_uc_error_t ARM_UCS_HttpSocket_GetFile(arm_uc_uri_t *uri, arm_uc_buffer_t *buffer);
00237 
00238 /**
00239  * @brief Get partial resource at URI.
00240  * @details Download resource at URI from given offset and store in buffer.
00241  *
00242  *          The buffer maxSize determines how big a fragment to download. If the
00243  *          buffer is larger than the requested fragment (offset to end-of-file)
00244  *          the buffer size is set to indicate the number of available bytes.
00245  *
00246  *          Events generated: EVENT_DOWNLOAD_PENDING if there is still data to
00247  *          download and EVENT_DOWNLOAD_DONE if the file is completely downloaded.
00248  *
00249  * @param uri Pointer to structure with resource location.
00250  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00251  * @param offset Offset in resource to begin download from.
00252  * @return Error code.
00253  */
00254 arm_uc_error_t ARM_UCS_HttpSocket_GetFragment(arm_uc_uri_t *uri, arm_uc_buffer_t *buffer, uint32_t offset);
00255 
00256 #endif /* UPDATE_CLIENT_SOURCE_HTTP_SOCKET_H */