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_rqst_t;
00048 
00049 typedef enum {
00050     STATE_DISCONNECTED,
00051     STATE_PROCESS_HEADER,
00052     STATE_PROCESS_BODY,
00053     STATE_CONNECTED_IDLE
00054 } arm_uc_socket_state_t;
00055 
00056 typedef enum {
00057     SOCKET_EVENT_CONNECT_DONE,
00058     SOCKET_EVENT_SEND_DONE,
00059     SOCKET_EVENT_RECEIVE_CONTINUE,
00060     SOCKET_EVENT_UNDEFINED,
00061     SOCKET_EVENT_TIMER_FIRED
00062 } arm_uc_socket_event_t;
00063 
00064 /**
00065  * @brief Prototype for event handler.
00066  */
00067 typedef void (*ARM_UCS_HttpEvent_t)(uint32_t event);
00068 
00069 typedef struct {
00070     /* external callback handler */
00071     ARM_UCS_HttpEvent_t callback_handler;
00072 
00073     /* location */
00074     arm_uc_uri_t* request_uri;
00075 
00076     /* buffer to store downloaded data */
00077     arm_uc_buffer_t* request_buffer;
00078 
00079     /* fragment offset in a multi-fragment download */
00080     uint32_t request_offset;
00081 
00082     /* request type */
00083     arm_uc_rqst_t request_type;
00084 
00085     /* internal state */
00086     arm_uc_socket_state_t socket_state;
00087 
00088     /* expected socket event */
00089     arm_uc_socket_event_t expected_event;
00090 
00091     /* remaining bytes in request */
00092     uint32_t expected_remaining;
00093 
00094     /* structs for callback queue */
00095     int32_t isr_callback_counter;
00096     arm_uc_callback_t isr_callback_struct; // initialized in source-http
00097     arm_uc_callback_t event_callback_struct; // initialized in source-http
00098     arm_uc_callback_t timer_callback_struct; // initialized in source-http
00099 
00100     /* pointer to socket */
00101     palSocket_t socket;
00102 
00103     /* timer id for the socket timeout timer */
00104     palTimerID_t timeout_timer_id;
00105 
00106     /* cache for storing DNS lookup */
00107     palSocketAddress_t cache_address;
00108     palSocketLength_t cache_address_length;
00109 } arm_uc_http_socket_context_t;
00110 
00111 /**
00112  * @brief Initialize Http module.
00113  * @details A memory struct is passed as well as a function pointer for event
00114  *          handling.
00115  *
00116  * @param context Struct holding all global variables.
00117  * @param handler Event handler for signaling when each operation is complete.
00118  * @return Error code.
00119  */
00120 arm_uc_error_t ARM_UCS_HttpSocket_Initialize(arm_uc_http_socket_context_t* context,
00121                                              ARM_UCS_HttpEvent_t handler);
00122 
00123 /**
00124  * @brief Resets HTTP socket to uninitialized state and clears memory struct.
00125  * @details HTTP sockets must be initialized again before use.
00126  * @return Error code.
00127  */
00128 arm_uc_error_t ARM_UCS_HttpSocket_Terminate(void);
00129 
00130 /**
00131  * @brief Get hash for resource at URI.
00132  * @details Store hash in provided buffer. Enclosing "" and '\0' are removed.
00133  *
00134  *          Event generated: EVENT_HASH
00135  *
00136  * @param uri Pointer to struct with resource location.
00137  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00138  * @return Error code.
00139  */
00140 arm_uc_error_t ARM_UCS_HttpSocket_GetHash(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer);
00141 
00142 /**
00143  * @brief Get date for resource at URI.
00144  * @details Store Last-Modified data in provided buffer. Enclosing "" and '\0' are removed.
00145  *
00146  *          Event generated: EVENT_DATE
00147  *
00148  * @param uri Pointer to struct with resource location.
00149  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00150  * @return Error code.
00151  */
00152 arm_uc_error_t ARM_UCS_HttpSocket_GetDate(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer);
00153 
00154 /**
00155  * @brief Get full resource at URI.
00156  * @details Download resource at URI and store in provided buffer.
00157  *          If the provided buffer is not big enough to contain the whole resource
00158  *          what can fit in the buffer will be downloaded.
00159  *          The user can then use GetFragment to download the rest.
00160 
00161  *          Events generated: EVENT_DOWNLOAD_PENDING if there is still data to
00162  *          download and EVENT_DOWNLOAD_DONE if the file is completely downloaded.
00163  *
00164  * @param uri Pointer to structure with resource location.
00165  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00166  * @return Error code.
00167  */
00168 arm_uc_error_t ARM_UCS_HttpSocket_GetFile(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer);
00169 
00170 /**
00171  * @brief Get partial resource at URI.
00172  * @details Download resource at URI from given offset and store in buffer.
00173  *
00174  *          The buffer maxSize determines how big a fragment to download. If the
00175  *          buffer is larger than the requested fragment (offset to end-of-file)
00176  *          the buffer size is set to indicate the number of available bytes.
00177  *
00178  *          Events generated: EVENT_DOWNLOAD_PENDING if there is still data to
00179  *          download and EVENT_DOWNLOAD_DONE if the file is completely downloaded.
00180  *
00181  * @param uri Pointer to structure with resource location.
00182  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00183  * @param offset Offset in resource to begin download from.
00184  * @return Error code.
00185  */
00186 arm_uc_error_t ARM_UCS_HttpSocket_GetFragment(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer, uint32_t offset);
00187 
00188 #endif /* UPDATE_CLIENT_SOURCE_HTTP_SOCKET_H */