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_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_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_socket_get(arm_uc_uri_t* uri,
00056                                  arm_uc_buffer_t* buffer,
00057                                  uint32_t offset,
00058                                  arm_uc_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_socket_get.
00064  * @return Error code.
00065  */
00066 arm_uc_error_t arm_uc_socket_connect(void);
00067 
00068 /**
00069  * @brief Send request passed in arm_uc_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_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 void arm_uc_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  */
00090 void arm_uc_socket_process_header(void);
00091 
00092 /**
00093  * @brief Function is called when file or fragment is being downloaded.
00094  * @details Function drives the download and continues until the buffer is full
00095  *          or the expected amount of data has been downloaded.
00096  */
00097 void arm_uc_socket_process_body(void);
00098 
00099 /**
00100  * @brief Close socket and set internal state to disconnected.
00101  */
00102 void arm_uc_socket_close(void);
00103 
00104 /**
00105  * @brief Close socket, set internal state to disconnected and generate error
00106  *        event.
00107  * @param error The code of the error event.
00108  */
00109 void arm_uc_socket_error(arm_ucs_http_event_t error);
00110 
00111 /**
00112  * @brief Callback function for handling events in application context.
00113  * @param unused Unused.
00114  */
00115 void arm_uc_socket_callback(uint32_t unused);
00116 
00117 /**
00118  * @brief Callback function for handling events in interrupt context.
00119  * @details All events are de-escalated through the callback queue.
00120  */
00121 void arm_uc_socket_isr(void*);
00122 
00123 /**
00124  * @brief Callback handler for the socket timeout timer callback.
00125  *        Callbacks go through the task queue because we don't know
00126  *        what context we are running from.
00127  */
00128 void arm_uc_timeout_timer_callback(void const *);
00129 
00130 #endif // __ARM_UC_HTTP_SOCKET_PRIVATE_H__