• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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";
17import connection from "./@ohos.net.connection";
18
19/**
20 * Provides http related APIs.
21 *
22 * @since 6
23 * @syscap SystemCapability.Communication.NetStack
24 */
25declare namespace http {
26  type HttpProxy = connection.HttpProxy;
27  /**
28   * Creates an HTTP request task.
29   */
30  function createHttp(): HttpRequest;
31
32  export interface HttpRequestOptions {
33    /**
34     * Request method.
35     */
36    method?: RequestMethod; // default is GET
37
38    /**
39     * Additional data of the request.
40     * extraData can be a string or an Object (API 6) or an ArrayBuffer(API 8).
41     */
42    extraData?: string | Object | ArrayBuffer;
43
44    /**
45     * Data type to be returned. If this parameter is set, the system preferentially returns the specified type.
46     *
47     * @since 9
48     */
49    expectDataType?: HttpDataType;
50
51    /**
52     * @since 9
53     */
54    usingCache?: boolean; // default is true
55
56    /**
57     * @since 9
58     */
59    priority?: number; // [1, 1000], default is 1.
60
61    /**
62     * HTTP request header.
63     */
64    header?: Object; // default is 'content-type': 'application/json'
65
66    /**
67     * Read timeout period. The default value is 60,000, in ms.
68     */
69    readTimeout?: number; // default is 60s
70
71    /**
72     * Connection timeout interval. The default value is 60,000, in ms.
73     */
74    connectTimeout?: number; // default is 60s.
75
76    /**
77     * @since 9
78     */
79    usingProtocol?: HttpProtocol; // default is automatically specified by the system.
80    /**
81     * If this parameter is set as type of boolean, the system will use default proxy or not use proxy.
82     * If this parameter is set as type of HttpProxy, the system will use the specified HttpProxy.
83     *
84     * @since 10
85     */
86     usingProxy?: boolean | HttpProxy; // default is false.
87  }
88
89  export interface HttpRequest {
90    /**
91     * Initiates an HTTP request to a given URL.
92     *
93     * @param url URL for initiating an HTTP request.
94     * @param options Optional parameters {@link HttpRequestOptions}.
95     * @param callback Returns {@link HttpResponse}.
96     * @permission ohos.permission.INTERNET
97     */
98    request(url: string, callback: AsyncCallback<HttpResponse>): void;
99    request(url: string, options: HttpRequestOptions, callback: AsyncCallback<HttpResponse>): void;
100    request(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
101
102    /**
103     * Destroys an HTTP request.
104     */
105    destroy(): void;
106
107    /**
108     * Registers an observer for HTTP Response Header events.
109     *
110     * @deprecated since 8
111     * @useinstead on_headersReceive
112     */
113    on(type: "headerReceive", callback: AsyncCallback<Object>): void;
114
115    /**
116     * Unregisters the observer for HTTP Response Header events.
117     *
118     * @deprecated since 8
119     * @useinstead off_headersReceive
120     */
121    off(type: "headerReceive", callback?: AsyncCallback<Object>): void;
122
123    /**
124     * Registers an observer for HTTP Response Header events.
125     *
126     * @since 8
127     */
128    on(type: "headersReceive", callback: Callback<Object>): void;
129
130    /**
131     * Unregisters the observer for HTTP Response Header events.
132     *
133     * @since 8
134     */
135    off(type: "headersReceive", callback?: Callback<Object>): void;
136
137    /**
138     * Registers a one-time observer for HTTP Response Header events.
139     *
140     * @since 8
141     */
142    once(type: "headersReceive", callback: Callback<Object>): void;
143  }
144
145  export enum RequestMethod {
146    OPTIONS = "OPTIONS",
147    GET = "GET",
148    HEAD = "HEAD",
149    POST = "POST",
150    PUT = "PUT",
151    DELETE = "DELETE",
152    TRACE = "TRACE",
153    CONNECT = "CONNECT"
154  }
155
156  export enum ResponseCode {
157    OK = 200,
158    CREATED,
159    ACCEPTED,
160    NOT_AUTHORITATIVE,
161    NO_CONTENT,
162    RESET,
163    PARTIAL,
164    MULT_CHOICE = 300,
165    MOVED_PERM,
166    MOVED_TEMP,
167    SEE_OTHER,
168    NOT_MODIFIED,
169    USE_PROXY,
170    BAD_REQUEST = 400,
171    UNAUTHORIZED,
172    PAYMENT_REQUIRED,
173    FORBIDDEN,
174    NOT_FOUND,
175    BAD_METHOD,
176    NOT_ACCEPTABLE,
177    PROXY_AUTH,
178    CLIENT_TIMEOUT,
179    CONFLICT,
180    GONE,
181    LENGTH_REQUIRED,
182    PRECON_FAILED,
183    ENTITY_TOO_LARGE,
184    REQ_TOO_LONG,
185    UNSUPPORTED_TYPE,
186    INTERNAL_ERROR = 500,
187    NOT_IMPLEMENTED,
188    BAD_GATEWAY,
189    UNAVAILABLE,
190    GATEWAY_TIMEOUT,
191    VERSION
192  }
193
194  /**
195   * Supported protocols.
196   *
197   * @since 9
198   */
199  export enum HttpProtocol {
200    HTTP1_1,
201    HTTP2,
202  }
203
204  /**
205   * Indicates the type of the returned data.
206   *
207   * @since 9
208   */
209  export enum HttpDataType {
210    /**
211     * The returned type is string.
212     */
213    STRING,
214    /**
215     * The returned type is Object.
216     */
217    OBJECT = 1,
218    /**
219     * The returned type is ArrayBuffer.
220     */
221    ARRAY_BUFFER = 2,
222  }
223
224  export interface HttpResponse {
225    /**
226     * result can be a string (API 6) or an ArrayBuffer(API 8). Object is deprecated from API 8.
227     * If {@link HttpRequestOptions#expectDataType} is set, the system preferentially returns this parameter.
228     */
229    result: string | Object | ArrayBuffer;
230
231    /**
232     * If the resultType is string, you can get result directly.
233     * If the resultType is Object, you can get result such as this: result['key'].
234     * If the resultType is ArrayBuffer, you can use ArrayBuffer to create the binary objects.
235     *
236     * @since 9
237     */
238    resultType: HttpDataType;
239
240    /**
241     * Server status code.
242     */
243    responseCode: ResponseCode | number;
244
245    /**
246     * All headers in the response from the server.
247     */
248    header: Object;
249
250    /**
251     * @since 8
252     */
253    cookies: string;
254  }
255
256  /**
257   * Creates a default {@code HttpResponseCache} object to store the responses of HTTP access requests.
258   *
259   * @param cacheSize the size of cache, default is 10*1024*1024(10MB).
260   * @since 9
261   */
262  function createHttpResponseCache(cacheSize?: number): HttpResponseCache;
263
264  /**
265   * @since 9
266   */
267  export interface HttpResponseCache {
268    /**
269     * Writes data in the cache to the file system so that all the cached data can be accessed in the next HTTP request.
270     */
271    flush(callback: AsyncCallback<void>): void;
272    flush(): Promise<void>;
273
274    /**
275     * Disables a cache and deletes the data in it.
276     */
277    delete(callback: AsyncCallback<void>): void;
278    delete(): Promise<void>;
279  }
280}
281
282export default http;