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 Provides C APIs for the Http client module. 21 * 22 * @since 20 23 */ 24 25 /** 26 * @file net_http_type.h 27 * @brief Defines the data structure for the C APIs of the http module. 28 * 29 * @library libnet_http.so 30 * @kit NetworkKit 31 * @syscap SystemCapability.Communication.NetStack 32 * @since 20 33 */ 34 35 #ifndef NET_HTTP_TYPE_H 36 #define NET_HTTP_TYPE_H 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 #define OHOS_HTTP_MAX_PATH_LEN 128 43 #define OHOS_HTTP_MAX_STR_LEN 256 44 #define OHOS_HTTP_DNS_SERVER_NUM_MAX 3 45 46 /** 47 * @brief Defines http error code. 48 * 49 * @since 20 50 */ 51 typedef enum Http_ErrCode { 52 /** Operation success. */ 53 OH_HTTP_RESULT_OK = 0, 54 /** @brief Parameter error. */ 55 OH_HTTP_PARAMETER_ERROR = 401, 56 /** @brief Permission denied. */ 57 OH_HTTP_PERMISSION_DENIED = 201, 58 /** @brief Error code base. */ 59 OH_HTTP_NETSTACK_E_BASE = 2300000, 60 /** @brief Unsupported protocol. */ 61 OH_HTTP_UNSUPPORTED_PROTOCOL = (OH_HTTP_NETSTACK_E_BASE + 1), 62 /** @brief Invalid URL format or missing URL. */ 63 OH_HTTP_INVALID_URL = (OH_HTTP_NETSTACK_E_BASE + 3), 64 /** @brief Failed to resolve the proxy name. */ 65 OH_HTTP_RESOLVE_PROXY_FAILED = (OH_HTTP_NETSTACK_E_BASE + 5), 66 /** @brief Failed to resolve the host name. */ 67 OH_HTTP_RESOLVE_HOST_FAILED = (OH_HTTP_NETSTACK_E_BASE + 6), 68 /** @brief Failed to connect to the server. */ 69 OH_HTTP_CONNECT_SERVER_FAILED = (OH_HTTP_NETSTACK_E_BASE + 7), 70 /** @brief Invalid server response. */ 71 OH_HTTP_INVALID_SERVER_RESPONSE = (OH_HTTP_NETSTACK_E_BASE + 8), 72 /** @brief Access to the remote resource denied. */ 73 OH_HTTP_ACCESS_REMOTE_DENIED = (OH_HTTP_NETSTACK_E_BASE + 9), 74 /** @brief Error in the HTTP2 framing layer. */ 75 OH_HTTP_HTTP2_FRAMING_ERROR = (OH_HTTP_NETSTACK_E_BASE + 16), 76 /** @brief Transferred a partial file. */ 77 OH_HTTP_TRANSFER_PARTIAL_FILE = (OH_HTTP_NETSTACK_E_BASE + 18), 78 /** @brief Failed to write the received data to the disk or application. */ 79 OH_HTTP_WRITE_DATA_FAILED = (OH_HTTP_NETSTACK_E_BASE + 23), 80 /** @brief Upload failed. */ 81 OH_HTTP_UPLOAD_FAILED = (OH_HTTP_NETSTACK_E_BASE + 25), 82 /** @brief Failed to open or read local data from the file or application. */ 83 OH_HTTP_OPEN_LOCAL_DATA_FAILED = (OH_HTTP_NETSTACK_E_BASE + 26), 84 /** @brief Out of memory. */ 85 OH_HTTP_OUT_OF_MEMORY = (OH_HTTP_NETSTACK_E_BASE + 27), 86 /** @brief Operation timeout. */ 87 OH_HTTP_OPERATION_TIMEOUT = (OH_HTTP_NETSTACK_E_BASE + 28), 88 /** @brief The number of redirections reaches the maximum allowed. */ 89 OH_HTTP_TOO_MANY_REDIRECTIONS = (OH_HTTP_NETSTACK_E_BASE + 47), 90 /** @brief The server returned nothing (no header or data). */ 91 OH_HTTP_SERVER_RETURNED_NOTHING = (OH_HTTP_NETSTACK_E_BASE + 52), 92 /** @brief Failed to send data to the peer. */ 93 OH_HTTP_SEND_DATA_FAILED = (OH_HTTP_NETSTACK_E_BASE + 55), 94 /** @brief Failed to receive data from the peer. */ 95 OH_HTTP_RECEIVE_DATA_FAILED = (OH_HTTP_NETSTACK_E_BASE + 56), 96 /** @brief Local SSL certificate error. */ 97 OH_HTTP_SSL_CERTIFICATE_ERROR = (OH_HTTP_NETSTACK_E_BASE + 58), 98 /** @brief The specified SSL cipher cannot be used. */ 99 OH_HTTP_SSL_CIPHER_USED_ERROR = (OH_HTTP_NETSTACK_E_BASE + 59), 100 /** @brief Invalid SSL peer certificate or SSH remote key. */ 101 OH_HTTP_INVALID_SSL_PEER_CERT = (OH_HTTP_NETSTACK_E_BASE + 60), 102 /** @brief Invalid HTTP encoding format. */ 103 OH_HTTP_INVALID_ENCODING_FORMAT = (OH_HTTP_NETSTACK_E_BASE + 61), 104 /** @brief Maximum file size exceeded. */ 105 OH_HTTP_FILE_TOO_LARGE = (OH_HTTP_NETSTACK_E_BASE + 63), 106 /** @brief Remote disk full. */ 107 OH_HTTP_REMOTE_DISK_FULL = (OH_HTTP_NETSTACK_E_BASE + 70), 108 /** @brief Remote file already exists. */ 109 OH_HTTP_REMOTE_FILE_EXISTS = (OH_HTTP_NETSTACK_E_BASE + 73), 110 /** @brief The SSL CA certificate does not exist or is inaccessible. */ 111 OH_HTTP_SSL_CA_NOT_EXIST = (OH_HTTP_NETSTACK_E_BASE + 77), 112 /** @brief Remote file not found. */ 113 OH_HTTP_REMOTE_FILE_NOT_FOUND = (OH_HTTP_NETSTACK_E_BASE + 78), 114 /** @brief Authentication error. */ 115 OH_HTTP_AUTHENTICATION_ERROR = (OH_HTTP_NETSTACK_E_BASE + 94), 116 /** @brief It is not allowed to access this domain. */ 117 OH_HTTP_ACCESS_DOMAIN_NOT_ALLOWED = (OH_HTTP_NETSTACK_E_BASE + 998), 118 /** @brief Unknown error. */ 119 OH_HTTP_UNKNOWN_ERROR = (OH_HTTP_NETSTACK_E_BASE + 999) 120 } Http_ErrCode; 121 122 /** 123 * @brief Defines http response code. 124 * 125 * @since 20 126 */ 127 typedef enum Http_ResponseCode { 128 /** @brief The request was successful. */ 129 OH_HTTP_OK = 200, 130 /** @brief Successfully requested and created a new resource. */ 131 OH_HTTP_CREATED = 201, 132 /** @brief The request has been accepted but has not been processed completely. */ 133 OH_HTTP_ACCEPTED = 202, 134 /** @brief Unauthorized information. The request was successful. */ 135 OH_HTTP_NON_AUTHORITATIVE_INFO = 203, 136 /** @brief No content. The server successfully processed, but did not return content. */ 137 OH_HTTP_NO_CONTENT = 204, 138 /** @brief Reset the content. */ 139 OH_HTTP_RESET = 205, 140 /** @brief Partial content. The server successfully processed some GET requests. */ 141 OH_HTTP_PARTIAL = 206, 142 /** @brief Multiple options. */ 143 OH_HTTP_MULTI_CHOICE = 300, 144 /** 145 * @brief Permanently move. The requested resource has been permanently moved to a new URI, 146 * and the returned information will include the new URI. The browser will automatically redirect to the new URI. 147 */ 148 OH_HTTP_MOVED_PERM = 301, 149 /** @brief Temporary movement. */ 150 OH_HTTP_MOVED_TEMP = 302, 151 /** @brief View other addresses. */ 152 OH_HTTP_SEE_OTHER = 303, 153 /** @brief Not modified. */ 154 OH_HTTP_NOT_MODIFIED = 304, 155 /** @brief Using proxies. */ 156 OH_HTTP_USE_PROXY = 305, 157 /** @brief The server cannot understand the syntax error error requested by the client. */ 158 OH_HTTP_BAD_REQUEST = 400, 159 /** @brief Request for user authentication. */ 160 OH_HTTP_UNAUTHORIZED = 401, 161 /** @brief Reserved for future use. */ 162 OH_HTTP_PAYMENT_REQUIRED = 402, 163 /** @brief The server understands the request from the requesting client, but refuses to execute it. */ 164 OH_HTTP_FORBIDDEN = 403, 165 /** @brief The server was unable to find resources (web pages) based on the client's request. */ 166 OH_HTTP_NOT_FOUND = 404, 167 /** @brief The method in the client request is prohibited. */ 168 OH_HTTP_BAD_METHOD = 405, 169 /** @brief The server unabled to complete request based on the content characteristics requested by the client. */ 170 OH_HTTP_NOT_ACCEPTABLE = 406, 171 /** @brief Request authentication of the proxy's identity. */ 172 OH_HTTP_PROXY_AUTH = 407, 173 /** @brief The request took too long and timed out. */ 174 OH_HTTP_CLIENT_TIMEOUT = 408, 175 /** 176 * @brief The server may have returned this code when completing the client's PUT request, 177 * as there was a conflict when the server was processing the request. 178 */ 179 OH_HTTP_CONFLICT = 409, 180 /** @brief The resource requested by the client no longer exists. */ 181 OH_HTTP_GONE = 410, 182 /** @brief The server is unable to process request information sent by the client without Content Length. */ 183 OH_HTTP_LENGTH_REQUIRED = 411, 184 /** @brief The prerequisite for requesting information from the client is incorrect. */ 185 OH_HTTP_PRECON_FAILED = 412, 186 /** @brief The request was rejected because the requested entity was too large for the server to process. */ 187 OH_HTTP_ENTITY_TOO_LARGE = 413, 188 /** @brief The requested URI is too long (usually a URL) and the server cannot process it. */ 189 OH_HTTP_REQUEST_TOO_LONG = 414, 190 /** @brief The server is unable to process the requested format. */ 191 OH_HTTP_UNSUPPORTED_TYPE = 415, 192 /** @brief Requested Range not satisfiable. */ 193 OH_HTTP_RANGE_NOT_MET = 416, 194 /** @brief Internal server error, unable to complete the request. */ 195 OH_HTTP_INTERNAL_ERROR = 500, 196 /** @brief The server does not support the requested functionality and cannot complete the request. */ 197 OH_HTTP_NOT_IMPLEMENTED = 501, 198 /** @brief The server acting as a gateway or proxy received an invalid request from the remote server. */ 199 OH_HTTP_BAD_GATEWAY = 502, 200 /** @brief Due to overload or system maintenance, the server is temporarily unable to process client requests. */ 201 OH_HTTP_UNAVAILABLE = 503, 202 /** @brief The server acting as gateway did not obtain requests from the remote server in a timely manner. */ 203 OH_HTTP_GATEWAY_TIMEOUT = 504, 204 /** @brief The version of the HTTP protocol requested by the server. */ 205 OH_HTTP_VERSION = 505 206 } Http_ResponseCode; 207 208 /** 209 * @brief Buffer. 210 * 211 * @since 20 212 */ 213 typedef struct Http_Buffer { 214 /** Content. Buffer will not be copied. */ 215 const char *buffer; 216 /** Buffer length. */ 217 uint32_t length; 218 } Http_Buffer; 219 220 /** 221 * @brief Defines the address Family. 222 * 223 * @since 20 224 */ 225 typedef enum Http_AddressFamilyType { 226 /** Default, The system automatically selects the IPv4 or IPv6 address of the domain name. */ 227 HTTP_ADDRESS_FAMILY_DEFAULT = 0, 228 /** IPv4, Selects the IPv4 address of the domain name. */ 229 HTTP_ADDRESS_FAMILY_ONLY_V4 = 1, 230 /** IPv6, Selects the IPv4 address of the domain name. */ 231 HTTP_ADDRESS_FAMILY_ONLY_V6 = 2 232 } Http_AddressFamilyType; 233 234 /** 235 * @brief HTTP get method. 236 * 237 * @since 20 238 */ 239 #define NET_HTTP_METHOD_GET "GET" 240 241 /** 242 * @brief HTTP head method. 243 * 244 * @since 20 245 */ 246 #define NET_HTTPMETHOD_HEAD "HEAD" 247 248 /** 249 * @brief HTTP options method. 250 * 251 * @since 20 252 */ 253 #define NET_HTTPMETHOD_OPTIONS "OPTIONS" 254 255 /** 256 * @brief HTTP trace method. 257 * 258 * @since 20 259 */ 260 #define NET_HTTPMETHOD_TRACE "TRACE" 261 /** 262 * @brief HTTP delete method. 263 * @since 20 264 */ 265 #define NET_HTTPMETHOD_DELETE "DELETE" 266 267 /** 268 * @brief HTTP post method. 269 * 270 * @since 20 271 */ 272 #define NET_HTTP_METHOD_POST "POST" 273 274 /** 275 * @brief HTTP put method. 276 * 277 * @since 20 278 */ 279 #define NET_HTTP_METHOD_PUT "PUT" 280 281 /** 282 * @brief HTTP connect method. 283 * 284 * @since 20 285 */ 286 #define NET_HTTP_METHOD_PATCH "CONNECT" 287 288 /** 289 * @brief Defines the HTTP version. 290 * 291 * @since 20 292 */ 293 typedef enum Http_HttpProtocol { 294 /** Default choose by curl. */ 295 OH_HTTP_NONE = 0, 296 /** HTTP 1.1 version. */ 297 OH_HTTP1_1, 298 /** HTTP 2 version. */ 299 OH_HTTP2, 300 /** HTTP 3 version. */ 301 OH_HTTP3 302 } Http_HttpProtocol; 303 304 /** 305 * @brief Defines the Cert Type. 306 * 307 * @since 20 308 */ 309 typedef enum Http_CertType { 310 /** PEM Cert Type. */ 311 OH_HTTP_PEM = 0, 312 /** DER Cert Type. */ 313 OH_HTTP_DER = 1, 314 /** P12 Cert Type. */ 315 OH_HTTP_P12 = 2 316 } Http_CertType; 317 318 /** 319 * @brief Headers of the request or response. 320 * 321 * @since 20 322 */ 323 typedef struct Http_Headers Http_Headers; 324 325 /** 326 * @brief The value type of the header map of the request or response. 327 * 328 * @since 20 329 */ 330 typedef struct Http_HeaderValue { 331 /** Value. */ 332 char *value; 333 /** Point to the next {@link Http_HeaderValue}. */ 334 struct Http_HeaderValue *next; 335 } Http_HeaderValue; 336 337 /** 338 * @brief All key-value pairs of the headers of the request or response. 339 * 340 * @since 20 341 */ 342 typedef struct Http_HeaderEntry { 343 /** Key. */ 344 char *key; 345 /** Value, see {@link Http_HeaderValue}. */ 346 Http_HeaderValue *value; 347 /** Points to the next key-value pair {@link Http_HeaderEntry} */ 348 struct Http_HeaderEntry *next; 349 } Http_HeaderEntry; 350 351 /** 352 * @brief Client certificate which is sent to the remote server, the the remote server will use it to verify the 353 * client's identification. 354 * 355 * @since 20 356 */ 357 typedef struct Http_ClientCert { 358 /** A path to a client certificate. */ 359 char *certPath; 360 /** Client certificate type, see {@link Http_CertType}. */ 361 Http_CertType type; 362 /** File path of your client certificate private key. */ 363 char *keyPath; 364 /** Password for your client certificate private key. */ 365 char *keyPassword; 366 } Http_ClientCert; 367 368 /** 369 * @brief Proxy type. Used to distinguish different proxy configurations. 370 * 371 * @since 20 372 */ 373 typedef enum Http_ProxyType { 374 /** No proxy */ 375 HTTP_PROXY_NOT_USE, 376 /** System proxy */ 377 HTTP_PROXY_SYSTEM, 378 /** Use custom proxy */ 379 HTTP_PROXY_CUSTOM 380 } Http_ProxyType; 381 382 /** 383 * @brief Custom proxy configuration. 384 * 385 * @since 20 386 */ 387 typedef struct Http_CustomProxy { 388 /** Indicates the URL of the proxy server. If you do not set port explicitly, port will be 1080. */ 389 const char *host; 390 int32_t port; 391 const char *exclusionLists; 392 } Http_CustomProxy; 393 394 /** 395 * @brief Proxy configuration. 396 * 397 * @since 20 398 */ 399 typedef struct Http_Proxy { 400 /** Distinguish the proxy type used by the request, see {@link Http_ProxyType}. */ 401 Http_ProxyType proxyType; 402 /** Custom proxy configuration, see {@link Http_CustomProxy}. */ 403 Http_CustomProxy customProxy; 404 } Http_Proxy; 405 406 /** 407 * @brief Response timing information. It will be collected in {@link Http_Response.performanceTiming}. 408 * 409 * @since 20 410 */ 411 typedef struct Http_PerformanceTiming { 412 /** The total time in milliseconds for the HTTP transfer, including name resolving, TCP connect etc. */ 413 double dnsTiming; 414 /** The time in milliseconds from the start until the remote host name was resolved. */ 415 double tcpTiming; 416 /** The time in milliseconds from the start until the connection to the remote host (or proxy) was completed. */ 417 double tlsTiming; 418 /** The time in milliseconds, it took from the start until the transfer is just about to begin. */ 419 double firstSendTiming; 420 /** The time in milliseconds from last modification time of the remote file. */ 421 double firstReceiveTiming; 422 /** The time in milliseconds, it took from the start until the first byte is received. */ 423 double totalFinishTiming; 424 /** The time in milliseconds it took for all redirection steps including name lookup, connect, etc.*/ 425 double redirectTiming; 426 } Http_PerformanceTiming; 427 428 /** 429 * @brief Defines the parameters for http request options. 430 * 431 * @since 20 432 */ 433 typedef struct Http_RequestOptions { 434 /** Request method. */ 435 const char *method; 436 /** Priority of http requests. A larger value indicates a higher priority. */ 437 uint32_t priority; 438 /** Header of http requests, see {@link Http_Headers}. */ 439 Http_Headers *headers; 440 /** Read timeout interval. */ 441 uint32_t readTimeout; 442 /** Connection timeout interval. */ 443 uint32_t connectTimeout; 444 /** Use the protocol. The default value is automatically specified by the system, see {@link Http_HttpProtocol}. */ 445 Http_HttpProtocol httpProtocol; 446 /** 447 * Indicates whether to use the HTTP proxy. The default value is false, 448 * and http proxy config, see {@link Http_Proxy}. 449 */ 450 Http_Proxy *httpProxy; 451 /** CA certificate of the user-specified path. */ 452 const char *caPath; 453 /** Set the download start position. This parameter can be used only in the GET method. */ 454 int64_t resumeFrom; 455 /** Set the download end position. This parameter can be used only in the GET method. */ 456 int64_t resumeTo; 457 /** Client certificates can be transferred, see {@link Http_ClientCert}. */ 458 Http_ClientCert *clientCert; 459 /** Set the DNS resolution for the https server. */ 460 const char *dnsOverHttps; 461 /** The address family can be specified when target domain name is resolved, see {@link Http_AddressFamilyType}. */ 462 Http_AddressFamilyType addressFamily; 463 } Http_RequestOptions; 464 465 /** 466 * @brief Defines the parameters for http response. 467 * 468 * @since 20 469 */ 470 typedef struct Http_Response { 471 /** Response body, see {@link Http_Buffer}. */ 472 Http_Buffer body; 473 /** Server status code, see {@link Http_ResponseCode}. */ 474 Http_ResponseCode responseCode; 475 /** Header of http response, see {@link Http_Headers}. */ 476 Http_Headers *headers; 477 /** Cookies returned by the server. */ 478 char *cookies; 479 /** The time taken of various stages of HTTP request, see {@link Http_PerformanceTiming}. */ 480 Http_PerformanceTiming *performanceTiming; 481 /** 482 * @brief Response deletion function. 483 * 484 * @param response Indicates the response to be deleted. It is a pointer that points to {@link Http_Response}. 485 * @since 20 486 */ 487 void (*destroyResponse)(struct Http_Response **response); 488 } Http_Response; 489 490 /** 491 * @brief Http request. 492 * 493 * @since 20 494 */ 495 typedef struct Http_Request { 496 /** The request id for every single request. Generated by system. */ 497 uint32_t requestId; 498 /** Request url. */ 499 char *url; 500 /** Request options, see {@link Http_RequestOptions}. */ 501 Http_RequestOptions *options; 502 } Http_Request; 503 504 /** 505 * @brief Callback function that is invoked when response is received. 506 * 507 * @param response Http response struct, see {@link Http_Response}. 508 * @param errCode Response error code. 509 * @since 20 510 */ 511 typedef void (*Http_ResponseCallback)(struct Http_Response *response, uint32_t errCode); 512 513 /** 514 * @brief Callback function that is invoked when a response body is received. 515 * 516 * @param data Response body. 517 * @param length Length of response body. 518 * @since 20 519 */ 520 typedef void (*Http_OnDataReceiveCallback)(const char *data, size_t length); 521 522 /** 523 * @brief Callback function invoked during request/response data transmission. 524 * 525 * @param totalSize total size. 526 * @param transferredSize transferred size. 527 * @since 20 528 */ 529 typedef void (*Http_OnProgressCallback)(uint64_t totalSize, uint64_t transferredSize); 530 531 /** 532 * @brief Callback called when header are received. 533 * 534 * @param headers Headers of the received requests, which points to the pointer of {@link Http_Headers}. 535 * @since 20 536 */ 537 typedef void (*Http_OnHeaderReceiveCallback)(Http_Headers *headers); 538 539 /** 540 * @brief Empty callback function for requested DataEnd or Canceled event callback. 541 * 542 * @since 20 543 */ 544 typedef void (*Http_OnVoidCallback)(void); 545 546 /** 547 * @brief Callbacks to watch different events. 548 * 549 * @since 20 550 */ 551 typedef struct Http_EventsHandler { 552 /** Callback function when the response body is received */ 553 Http_OnDataReceiveCallback onDataReceive; 554 /** Callback function during uploading */ 555 Http_OnProgressCallback onUploadProgress; 556 /** Callback function during downloading */ 557 Http_OnProgressCallback onDownloadProgress; 558 /** Callback function when a header is received */ 559 Http_OnHeaderReceiveCallback onHeadersReceive; 560 /** Callback function at the end of the transfer */ 561 Http_OnVoidCallback onDataEnd; 562 /** Callback function when a request is canceled */ 563 Http_OnVoidCallback onCanceled; 564 } Http_EventsHandler; 565 #ifdef __cplusplus 566 } 567 #endif 568 #endif // NET_HTTP_TYPE_H 569 570 /** @} */