arm_uc_http_socket_private.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 __ARM_UC_HTTP_SOCKET_PRIVATE_H__
00020 #define __ARM_UC_HTTP_SOCKET_PRIVATE_H__
00021 
00022 #include "update-client-source-http-socket/arm_uc_http_socket.h"
00023 #include "update-client-common/arm_uc_common.h"
00024 
00025 /**
00026  * @brief Initialize Http module.
00027  * @details A memory struct is passed as well as a function pointer for event
00028  *          handling.
00029  *
00030  * @param context Struct holding all global variables.
00031  * @param handler Event handler for signaling when each operation is complete.
00032  * @return Error code.
00033  */
00034 arm_uc_error_t arm_uc_http_socket_initialize(arm_uc_http_socket_context_t *context,
00035                                              ARM_UCS_HttpEvent_t handler);
00036 
00037 /**
00038  * @brief Resets HTTP socket to uninitialized state and clears memory struct.
00039  * @details HTTP sockets must be initialized again before use.
00040  * @return Error code.
00041  */
00042 arm_uc_error_t arm_uc_http_socket_terminate(void);
00043 
00044 /**
00045  * @brief Get resource at URI.
00046  * @details Download resource at URI from given offset and store in buffer.
00047  *          Events are generated when download finish or on error
00048  *
00049  * @param uri Pointer to structure with resource location.
00050  * @param buffer Pointer to structure with buffer location, maxSize, and size.
00051  * @param offset Offset in resource to begin download from.
00052  * @param type Indicate what type of request that was initiated.
00053  * @return Error code.
00054  */
00055 arm_uc_error_t arm_uc_http_socket_get(arm_uc_uri_t *uri,
00056                                       arm_uc_buffer_t *buffer,
00057                                       uint32_t offset,
00058                                       arm_uc_http_rqst_t type);
00059 
00060 /**
00061  * @brief Connect to server set in the global URI struct.
00062  * @details Connecting generates a socket event, which automatically processes
00063  *          the request passed in arm_uc_http_socket_get.
00064  * @return Error code.
00065  */
00066 arm_uc_error_t arm_uc_http_socket_connect(void);
00067 
00068 /**
00069  * @brief Send request passed in arm_uc_http_socket_get.
00070  * @details This call assumes the HTTP socket is already connected to server.
00071  * @return Error code.
00072  */
00073 arm_uc_error_t arm_uc_http_socket_send_request(void);
00074 
00075 /**
00076  * @brief Receive data from HTTP socket.
00077  * @details Data is stored in global buffer. The call will automatically retry
00078  *          if the socket is busy.
00079  */
00080 arm_uc_error_t arm_uc_http_socket_receive(void);
00081 
00082 /**
00083  * @brief Function is called when some data has been received but an HTTP
00084  *        header has yet to be processed.
00085  * @details Function is called repeatedly until a header is found or the buffer
00086  *          is full. Once a header is found, the ETag, date, or content length
00087  *          is parsed. For file and fragment downloads the receive process is
00088  *          restarted and the header is erased.
00089  * @return Error code.
00090  */
00091 arm_uc_error_t arm_uc_http_socket_process_header(void);
00092 
00093 /**
00094  * @brief Function is called when file or fragment is being downloaded.
00095  * @details Function drives the download and continues until the buffer is full
00096  *          or the expected amount of data has been downloaded.
00097  * @return Error code.
00098  */
00099 arm_uc_error_t arm_uc_http_socket_process_frag(void);
00100 
00101 /**
00102  * @brief Close socket and set internal state to disconnected.
00103  * @return Error code.
00104  */
00105 arm_uc_error_t arm_uc_http_socket_close(void);
00106 
00107 /**
00108  * @brief Close socket, set internal state to disconnected and generate error
00109  *        event.
00110  * @param error The code of the error event.
00111  * @return Error code.
00112  */
00113 arm_uc_error_t arm_uc_http_socket_fatal_error(arm_ucs_http_event_t error);
00114 
00115 /**
00116  * @brief Callback function for handling events in application context.
00117  * @param unused Unused.
00118  */
00119 void arm_uc_http_socket_callback(uintptr_t unused);
00120 
00121 /**
00122  * @brief Helper function to cancel resume engine externally
00123  * @param unused Unused.
00124  */
00125 void arm_uc_http_socket_end_resume(void);
00126 
00127 #endif // __ARM_UC_HTTP_SOCKET_PRIVATE_H__