1/* 2 * Copyright (C) 2021-2022 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 16import {AsyncCallback, Callback} from "./basic"; 17 18/** 19 * Provides http related APIs. 20 * 21 * @since 6 22 * @syscap SystemCapability.Communication.NetStack 23 */ 24declare namespace http { 25 /** 26 * Creates an HTTP request task. 27 */ 28 function createHttp(): HttpRequest; 29 30 export interface HttpRequestOptions { 31 /** 32 * Request method. 33 */ 34 method?: RequestMethod; // default is GET 35 36 /** 37 * Additional data of the request. 38 * extraData can be a string or an Object (API 6) or an ArrayBuffer(API 8). 39 */ 40 extraData?: string | Object | ArrayBuffer; 41 42 /** 43 * Data type to be returned. If this parameter is set, the system preferentially returns the specified type. 44 * 45 * @since 9 46 */ 47 expectDataType?: HttpDataType; 48 49 /** 50 * @since 9 51 */ 52 usingCache?: boolean; // default is true 53 54 /** 55 * @since 9 56 */ 57 priority?: number; // [1, 1000], default is 1. 58 59 /** 60 * HTTP request header. 61 */ 62 header?: Object; // default is 'content-type': 'application/json' 63 64 /** 65 * Read timeout period. The default value is 60,000, in ms. 66 */ 67 readTimeout?: number; // default is 60s 68 69 /** 70 * Connection timeout interval. The default value is 60,000, in ms. 71 */ 72 connectTimeout?: number; // default is 60s. 73 74 /** 75 * @since 9 76 */ 77 usingProtocol?: HttpProtocol; // default is automatically specified by the system. 78 } 79 80 export interface HttpRequest { 81 /** 82 * Initiates an HTTP request to a given URL. 83 * 84 * @param url URL for initiating an HTTP request. 85 * @param options Optional parameters {@link HttpRequestOptions}. 86 * @param callback Returns {@link HttpResponse}. 87 * @permission ohos.permission.INTERNET 88 * @throws {BusinessError} 401 - Parameter error. 89 * @throws {BusinessError} 201 - Permission denied. 90 * @throws {BusinessError} 2300001 - Unsupported protocol. 91 * @throws {BusinessError} 2300003 - URL using bad/illegal format or missing URL. 92 * @throws {BusinessError} 2300005 - Couldn't resolve proxy name. 93 * @throws {BusinessError} 2300006 - Couldn't resolve host name. 94 * @throws {BusinessError} 2300007 - Couldn't connect to server. 95 * @throws {BusinessError} 2300008 - Weird server reply. 96 * @throws {BusinessError} 2300009 - Access denied to remote resource. 97 * @throws {BusinessError} 2300016 - Error in the HTTP2 framing layer. 98 * @throws {BusinessError} 2300018 - Transferred a partial file. 99 * @throws {BusinessError} 2300023 - Failed writing received data to disk/application. 100 * @throws {BusinessError} 2300025 - Upload failed. 101 * @throws {BusinessError} 2300026 - Failed to open/read local data from file/application. 102 * @throws {BusinessError} 2300027 - Out of memory. 103 * @throws {BusinessError} 2300028 - Timeout was reached. 104 * @throws {BusinessError} 2300047 - Number of redirects hit maximum amount. 105 * @throws {BusinessError} 2300052 - Server returned nothing (no headers, no data). 106 * @throws {BusinessError} 2300055 - Failed sending data to the peer. 107 * @throws {BusinessError} 2300056 - Failure when receiving data from the peer. 108 * @throws {BusinessError} 2300058 - Problem with the local SSL certificate. 109 * @throws {BusinessError} 2300059 - Couldn't use specified SSL cipher. 110 * @throws {BusinessError} 2300060 - SSL peer certificate or SSH remote key was not OK. 111 * @throws {BusinessError} 2300061 - Unrecognized or bad HTTP Content or Transfer-Encoding. 112 * @throws {BusinessError} 2300063 - Maximum file size exceeded. 113 * @throws {BusinessError} 2300070 - Disk full or allocation exceeded. 114 * @throws {BusinessError} 2300073 - Remote file already exists. 115 * @throws {BusinessError} 2300077 - Problem with the SSL CA cert (path? access rights?). 116 * @throws {BusinessError} 2300078 - Remote file not found. 117 * @throws {BusinessError} 2300094 - An authentication function returned an error. 118 * @throws {BusinessError} 2300999 - Unknown Other Error. 119 */ 120 request(url: string, callback: AsyncCallback<HttpResponse>): void; 121 request(url: string, options: HttpRequestOptions, callback: AsyncCallback<HttpResponse>): void; 122 request(url: string, options?: HttpRequestOptions): Promise<HttpResponse>; 123 124 /** 125 * Destroys an HTTP request. 126 */ 127 destroy(): void; 128 129 /** 130 * Registers an observer for HTTP Response Header events. 131 * 132 * @deprecated since 8 133 * @useinstead on_headersReceive 134 */ 135 on(type: "headerReceive", callback: AsyncCallback<Object>): void; 136 137 /** 138 * Unregisters the observer for HTTP Response Header events. 139 * 140 * @deprecated since 8 141 * @useinstead off_headersReceive 142 */ 143 off(type: "headerReceive", callback?: AsyncCallback<Object>): void; 144 145 /** 146 * Registers an observer for HTTP Response Header events. 147 * 148 * @since 8 149 */ 150 on(type: "headersReceive", callback: Callback<Object>): void; 151 152 /** 153 * Unregisters the observer for HTTP Response Header events. 154 * 155 * @since 8 156 */ 157 off(type: "headersReceive", callback?: Callback<Object>): void; 158 159 /** 160 * Registers a one-time observer for HTTP Response Header events. 161 * 162 * @since 8 163 */ 164 once(type: "headersReceive", callback: Callback<Object>): void; 165 } 166 167 export enum RequestMethod { 168 OPTIONS = "OPTIONS", 169 GET = "GET", 170 HEAD = "HEAD", 171 POST = "POST", 172 PUT = "PUT", 173 DELETE = "DELETE", 174 TRACE = "TRACE", 175 CONNECT = "CONNECT" 176 } 177 178 export enum ResponseCode { 179 OK = 200, 180 CREATED, 181 ACCEPTED, 182 NOT_AUTHORITATIVE, 183 NO_CONTENT, 184 RESET, 185 PARTIAL, 186 MULT_CHOICE = 300, 187 MOVED_PERM, 188 MOVED_TEMP, 189 SEE_OTHER, 190 NOT_MODIFIED, 191 USE_PROXY, 192 BAD_REQUEST = 400, 193 UNAUTHORIZED, 194 PAYMENT_REQUIRED, 195 FORBIDDEN, 196 NOT_FOUND, 197 BAD_METHOD, 198 NOT_ACCEPTABLE, 199 PROXY_AUTH, 200 CLIENT_TIMEOUT, 201 CONFLICT, 202 GONE, 203 LENGTH_REQUIRED, 204 PRECON_FAILED, 205 ENTITY_TOO_LARGE, 206 REQ_TOO_LONG, 207 UNSUPPORTED_TYPE, 208 INTERNAL_ERROR = 500, 209 NOT_IMPLEMENTED, 210 BAD_GATEWAY, 211 UNAVAILABLE, 212 GATEWAY_TIMEOUT, 213 VERSION 214 } 215 216 /** 217 * Supported protocols. 218 * 219 * @since 9 220 */ 221 export enum HttpProtocol { 222 HTTP1_1, 223 HTTP2, 224 } 225 226 /** 227 * Indicates the type of the returned data. 228 * 229 * @since 9 230 */ 231 export enum HttpDataType { 232 STRING, 233 OBJECT = 1, 234 ARRAY_BUFFER = 2, 235 } 236 237 export interface HttpResponse { 238 /** 239 * result can be a string (API 6) or an ArrayBuffer(API 8). Object is deprecated from API 8. 240 * If {@link HttpRequestOptions#expectDataType} is set, the system preferentially returns this parameter. 241 */ 242 result: string | Object | ArrayBuffer; 243 244 /** 245 * If the resultType is string, you can get result directly. 246 * If the resultType is Object, you can get result such as this: result['key']. 247 * If the resultType is ArrayBuffer, you can use ArrayBuffer to create the binary objects. 248 * 249 * @since 9 250 */ 251 resultType: HttpDataType; 252 253 /** 254 * Server status code. 255 */ 256 responseCode: ResponseCode | number; 257 258 /** 259 * All headers in the response from the server. 260 */ 261 header: Object; 262 263 /** 264 * @since 8 265 */ 266 cookies: string; 267 } 268 269 /** 270 * Creates a default {@code HttpResponseCache} object to store the responses of HTTP access requests. 271 * 272 * @param cacheSize the size of cache(max value is 10MB), default is 10*1024*1024(10MB). 273 * @since 9 274 */ 275 function createHttpResponseCache(cacheSize?: number): HttpResponseCache; 276 277 /** 278 * @since 9 279 */ 280 export interface HttpResponseCache { 281 /** 282 * Writes data in the cache to the file system so that all the cached data can be accessed in the next HTTP request. 283 */ 284 flush(callback: AsyncCallback<void>): void; 285 flush(): Promise<void>; 286 287 /** 288 * Disables a cache and deletes the data in it. 289 */ 290 delete(callback: AsyncCallback<void>): void; 291 delete(): Promise<void>; 292 } 293} 294 295export default http; 296