1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup netstack 18 * @{ 19 * 20 * @brief Defines the APIs for http. 21 * 22 * @syscap SystemCapability.Communication.NetStack 23 * @since 20 24 */ 25 26 /** 27 * @file net_http.h 28 * @brief Defines the APIs for http. 29 * 30 * @library libnet_http.so 31 * @kit NetworkKit 32 * @syscap SystemCapability.Communication.NetStack 33 * @since 20 34 */ 35 36 #ifndef NET_HTTP_H 37 #define NET_HTTP_H 38 39 #include <stdint.h> 40 #include <string.h> 41 42 #include "net_http_type.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Creates headers for a request or response. 50 * 51 * @return Http_Headers* Pointer to {@link Http_Headers}. 52 * @syscap SystemCapability.Communication.NetStack 53 * @since 20 54 */ 55 Http_Headers *OH_Http_CreateHeaders(void); 56 57 /** 58 * @brief Destroys the headers of a request or response. 59 * 60 * @param headers Pointer to the {@link Http_Headers} to be destroyed, headers ends with null. 61 * @syscap SystemCapability.Communication.NetStack 62 * @since 20 63 */ 64 void OH_Http_DestroyHeaders(Http_Headers **headers); 65 66 /** 67 * @brief Sets the key-value pair of the request or response header. 68 * 69 * @param headers Pointer to the {@link Http_Headers} to be set. 70 * @param name Key. 71 * @param value Value. 72 * @return uint32_t 0 - success. 401 - Parameter error. 2300027 - Out of memory. 73 * @syscap SystemCapability.Communication.NetStack 74 * @since 20 75 */ 76 uint32_t OH_Http_SetHeaderValue(struct Http_Headers *headers, const char *name, const char *value); 77 78 /** 79 * @brief Obtains the value of a request or response header by key. 80 * 81 * @param headers Pointer to {@link Http_Headers}. 82 * @param name Key. 83 * @return Http_HeaderValue* Pointer to the obtained {@link Http_HeaderValue}. 84 * @syscap SystemCapability.Communication.NetStack 85 * @since 20 86 */ 87 Http_HeaderValue *OH_Http_GetHeaderValue(Http_Headers *headers, const char *name); 88 89 /** 90 * @brief Obtains all the key-value pairs of a request or response header. 91 * 92 * @param headers Pointer to {@link Http_Headersaders}. 93 * @return Http_HeaderEntry* Pointers to all obtained key-value pairs {@link Http_HeaderEntry}. 94 * @syscap SystemCapability.Communication.NetStack 95 * @since 20 96 */ 97 Http_HeaderEntry *OH_Http_GetHeaderEntries(Http_Headers *headers); 98 99 /** 100 * @brief Destroys all key-value pairs obtained in {@link OH_Http_GetHeaderEntries}. 101 * 102 * @param headerEntry Pointer to the {@link Http_HeaderEntry} to be destroyed, headerEntry ends with null. 103 * @syscap SystemCapability.Communication.NetStack 104 * @since 20 105 */ 106 void OH_Http_DestroyHeaderEntries(Http_HeaderEntry **headerEntry); 107 108 /** 109 * @brief Create a http request. 110 * 111 * @param url Http request url. 112 * @return Pointer of HttpRequest if success; Null otherwise. 113 * @syscap SystemCapability.Communication.NetStack 114 * @since 20 115 */ 116 Http_Request *OH_Http_CreateRequest(const char *url); 117 118 /** 119 * @brief Initiates an HTTP request. 120 * 121 * @param request Pointer to {@link Http_Request}. 122 * @param callback Http response info, pointer to {@link Http_ResponseCallback} 123 * @param handler Callbacks to watch different events, pointer to {@link Http_EventsHandler}. 124 * @return 0 if success; non-0 otherwise. For details about error codes, see {@link Http_ErrCode}. 125 * @permission ohos.permission.INTERNET 126 * @syscap SystemCapability.Communication.NetStack 127 * @since 20 128 */ 129 int OH_Http_Request(Http_Request *request, Http_ResponseCallback callback, Http_EventsHandler handler); 130 131 /** 132 * @brief Destroy the HTTP request. 133 * 134 * @param request Pointer to the http request {@link Http_Request}. 135 * @syscap SystemCapability.Communication.NetStack 136 * @since 20 137 */ 138 void OH_Http_Destroy(struct Http_Request **request); 139 #ifdef __cplusplus 140 } 141 #endif 142 #endif // NET_HTTP_H 143 144 /** @} */