Line data Source code
1 : import 'dart:async';
2 : import 'adapter.dart';
3 : import 'dio_mixin.dart';
4 : import 'options.dart';
5 : import 'headers.dart';
6 : import 'cancel_token.dart';
7 : import 'transformer.dart';
8 : import 'response.dart';
9 : import 'entry_stub.dart'
10 : // ignore: uri_does_not_exist
11 : if (dart.library.html) 'entry/dio_for_browser.dart'
12 : // ignore: uri_does_not_exist
13 : if (dart.library.io) 'entry/dio_for_native.dart';
14 :
15 : /// A powerful Http client for Dart, which supports Interceptors,
16 : /// Global configuration, FormData, File downloading etc. and Dio is
17 : /// very easy to use.
18 : ///
19 : /// You can create a dio instance and config it by two ways:
20 : /// 1. create first , then config it
21 : ///
22 : /// ```dart
23 : /// var dio = Dio();
24 : /// dio.options.baseUrl = "http://www.dtworkroom.com/doris/1/2.0.0/";
25 : /// dio.options.connectTimeout = 5000; //5s
26 : /// dio.options.receiveTimeout = 5000;
27 : /// dio.options.headers = {HttpHeaders.userAgentHeader: 'dio', 'common-header': 'xx'};
28 : /// ```
29 : /// 2. create and config it:
30 : ///
31 : /// ```dart
32 : /// var dio = Dio(BaseOptions(
33 : /// baseUrl: "http://www.dtworkroom.com/doris/1/2.0.0/",
34 : /// connectTimeout: 5000,
35 : /// receiveTimeout: 5000,
36 : /// headers: {HttpHeaders.userAgentHeader: 'dio', 'common-header': 'xx'},
37 : /// ));
38 : /// ```
39 :
40 : abstract class Dio {
41 16 : factory Dio([BaseOptions? options]) => createDio(options);
42 :
43 : /// Default Request config. More see [BaseOptions] .
44 : late BaseOptions options;
45 :
46 : Interceptors get interceptors;
47 :
48 : late HttpClientAdapter httpClientAdapter;
49 :
50 : /// [transformer] allows changes to the request/response data before it is sent/received to/from the server
51 : /// This is only applicable for request methods 'PUT', 'POST', and 'PATCH'.
52 : late Transformer transformer;
53 :
54 : /// Shuts down the dio client.
55 : ///
56 : /// If [force] is `false` (the default) the [Dio] will be kept alive
57 : /// until all active connections are done. If [force] is `true` any active
58 : /// connections will be closed to immediately release all resources. These
59 : /// closed connections will receive an error event to indicate that the client
60 : /// was shut down. In both cases trying to establish a new connection after
61 : /// calling [close] will throw an exception.
62 : void close({bool force = false});
63 :
64 : /// Handy method to make http GET request, which is a alias of [dio.fetch(RequestOptions)].
65 : Future<Response<T>> get<T>(
66 : String path, {
67 : Map<String, dynamic>? queryParameters,
68 : Options? options,
69 : CancelToken? cancelToken,
70 : ProgressCallback? onReceiveProgress,
71 : });
72 :
73 : /// Handy method to make http GET request, which is a alias of [dio.fetch(RequestOptions)].
74 : Future<Response<T>> getUri<T>(
75 : Uri uri, {
76 : Options? options,
77 : CancelToken? cancelToken,
78 : ProgressCallback? onReceiveProgress,
79 : });
80 :
81 : /// Handy method to make http POST request, which is a alias of [dio.fetch(RequestOptions)].
82 : Future<Response<T>> post<T>(
83 : String path, {
84 : data,
85 : Map<String, dynamic>? queryParameters,
86 : Options? options,
87 : CancelToken? cancelToken,
88 : ProgressCallback? onSendProgress,
89 : ProgressCallback? onReceiveProgress,
90 : });
91 :
92 : /// Handy method to make http POST request, which is a alias of [dio.fetch(RequestOptions)].
93 : Future<Response<T>> postUri<T>(
94 : Uri uri, {
95 : data,
96 : Options? options,
97 : CancelToken? cancelToken,
98 : ProgressCallback? onSendProgress,
99 : ProgressCallback? onReceiveProgress,
100 : });
101 :
102 : /// Handy method to make http PUT request, which is a alias of [dio.fetch(RequestOptions)].
103 : Future<Response<T>> put<T>(
104 : String path, {
105 : data,
106 : Map<String, dynamic>? queryParameters,
107 : Options? options,
108 : CancelToken? cancelToken,
109 : ProgressCallback? onSendProgress,
110 : ProgressCallback? onReceiveProgress,
111 : });
112 :
113 : /// Handy method to make http PUT request, which is a alias of [dio.fetch(RequestOptions)].
114 : Future<Response<T>> putUri<T>(
115 : Uri uri, {
116 : data,
117 : Options? options,
118 : CancelToken? cancelToken,
119 : ProgressCallback? onSendProgress,
120 : ProgressCallback? onReceiveProgress,
121 : });
122 :
123 : /// Handy method to make http HEAD request, which is a alias of [dio.fetch(RequestOptions)].
124 : Future<Response<T>> head<T>(
125 : String path, {
126 : data,
127 : Map<String, dynamic>? queryParameters,
128 : Options? options,
129 : CancelToken? cancelToken,
130 : });
131 :
132 : /// Handy method to make http HEAD request, which is a alias of [dio.fetch(RequestOptions)].
133 : Future<Response<T>> headUri<T>(
134 : Uri uri, {
135 : data,
136 : Options? options,
137 : CancelToken? cancelToken,
138 : });
139 :
140 : /// Handy method to make http DELETE request, which is a alias of [dio.fetch(RequestOptions)].
141 : Future<Response<T>> delete<T>(
142 : String path, {
143 : data,
144 : Map<String, dynamic>? queryParameters,
145 : Options? options,
146 : CancelToken? cancelToken,
147 : });
148 :
149 : /// Handy method to make http DELETE request, which is a alias of [dio.fetch(RequestOptions)].
150 : Future<Response<T>> deleteUri<T>(
151 : Uri uri, {
152 : data,
153 : Options? options,
154 : CancelToken? cancelToken,
155 : });
156 :
157 : /// Handy method to make http PATCH request, which is a alias of [dio.fetch(RequestOptions)].
158 : Future<Response<T>> patch<T>(
159 : String path, {
160 : data,
161 : Map<String, dynamic>? queryParameters,
162 : Options? options,
163 : CancelToken? cancelToken,
164 : ProgressCallback? onSendProgress,
165 : ProgressCallback? onReceiveProgress,
166 : });
167 :
168 : /// Handy method to make http PATCH request, which is a alias of [dio.fetch(RequestOptions)].
169 : Future<Response<T>> patchUri<T>(
170 : Uri uri, {
171 : data,
172 : Options? options,
173 : CancelToken? cancelToken,
174 : ProgressCallback? onSendProgress,
175 : ProgressCallback? onReceiveProgress,
176 : });
177 :
178 : /// Lock the current Dio instance.
179 : ///
180 : /// Dio will enqueue the incoming request tasks instead
181 : /// send them directly when [interceptor.requestOptions] is locked.
182 :
183 : void lock();
184 :
185 : /// Unlock the current Dio instance.
186 : ///
187 : /// Dio instance dequeue the request task。
188 : void unlock();
189 :
190 : ///Clear the current Dio instance waiting queue.
191 :
192 : void clear();
193 :
194 : /// Download the file and save it in local. The default http method is "GET",
195 : /// you can custom it by [Options.method].
196 : ///
197 : /// [urlPath]: The file url.
198 : ///
199 : /// [savePath]: The path to save the downloading file later. it can be a String or
200 : /// a callback:
201 : /// 1. A path with String type, eg "xs.jpg"
202 : /// 2. A callback `String Function(Headers headers)`; for example:
203 : /// ```dart
204 : /// await dio.download(url,(Headers headers){
205 : /// // Extra info: redirect counts
206 : /// print(headers.value('redirects'));
207 : /// // Extra info: real uri
208 : /// print(headers.value('uri'));
209 : /// ...
210 : /// return "...";
211 : /// });
212 : /// ```
213 : ///
214 : /// [onReceiveProgress]: The callback to listen downloading progress.
215 : /// please refer to [ProgressCallback].
216 : ///
217 : /// [deleteOnError] Whether delete the file when error occurs. The default value is [true].
218 : ///
219 : /// [lengthHeader] : The real size of original file (not compressed).
220 : /// When file is compressed:
221 : /// 1. If this value is 'content-length', the `total` argument of `onProgress` will be -1
222 : /// 2. If this value is not 'content-length', maybe a custom header indicates the original
223 : /// file size , the `total` argument of `onProgress` will be this header value.
224 : ///
225 : /// you can also disable the compression by specifying the 'accept-encoding' header value as '*'
226 : /// to assure the value of `total` argument of `onProgress` is not -1. for example:
227 : ///
228 : /// await dio.download(url, "./example/flutter.svg",
229 : /// options: Options(headers: {HttpHeaders.acceptEncodingHeader: "*"}), // disable gzip
230 : /// onProgress: (received, total) {
231 : /// if (total != -1) {
232 : /// print((received / total * 100).toStringAsFixed(0) + "%");
233 : /// }
234 : /// });
235 :
236 : Future<Response> download(
237 : String urlPath,
238 : savePath, {
239 : ProgressCallback? onReceiveProgress,
240 : Map<String, dynamic>? queryParameters,
241 : CancelToken? cancelToken,
242 : bool deleteOnError = true,
243 : String lengthHeader = Headers.contentLengthHeader,
244 : data,
245 : Options? options,
246 : });
247 :
248 : /// Download the file and save it in local. The default http method is "GET",
249 : /// you can custom it by [Options.method].
250 : ///
251 : /// [uri]: The file url.
252 : ///
253 : /// [savePath]: The path to save the downloading file later. it can be a String or
254 : /// a callback:
255 : /// 1. A path with String type, eg "xs.jpg"
256 : /// 2. A callback `String Function(Headers)`; for example:
257 : /// ```dart
258 : /// await dio.downloadUri(uri,(Headers headers){
259 : /// // Extra info: redirect counts
260 : /// print(headers.value('redirects'));
261 : /// // Extra info: real uri
262 : /// print(headers.value('uri'));
263 : /// ...
264 : /// return "...";
265 : /// });
266 : /// ```
267 : ///
268 : /// [onReceiveProgress]: The callback to listen downloading progress.
269 : /// please refer to [ProgressCallback].
270 : ///
271 : /// [lengthHeader] : The real size of original file (not compressed).
272 : /// When file is compressed:
273 : /// 1. If this value is 'content-length', the `total` argument of `onProgress` will be -1
274 : /// 2. If this value is not 'content-length', maybe a custom header indicates the original
275 : /// file size , the `total` argument of `onProgress` will be this header value.
276 : ///
277 : /// you can also disable the compression by specifying the 'accept-encoding' header value as '*'
278 : /// to assure the value of `total` argument of `onProgress` is not -1. for example:
279 : ///
280 : /// await dio.downloadUri(uri, "./example/flutter.svg",
281 : /// options: Options(headers: {HttpHeaders.acceptEncodingHeader: "*"}), // disable gzip
282 : /// onProgress: (received, total) {
283 : /// if (total != -1) {
284 : /// print((received / total * 100).toStringAsFixed(0) + "%");
285 : /// }
286 : /// });
287 : Future<Response> downloadUri(
288 : Uri uri,
289 : savePath, {
290 : ProgressCallback? onReceiveProgress,
291 : CancelToken? cancelToken,
292 : bool deleteOnError = true,
293 : String lengthHeader = Headers.contentLengthHeader,
294 : data,
295 : Options? options,
296 : });
297 :
298 : /// Make http request with options.
299 : ///
300 : /// [path] The url path.
301 : /// [data] The request data
302 : /// [options] The request options.
303 : Future<Response<T>> request<T>(
304 : String path, {
305 : data,
306 : Map<String, dynamic>? queryParameters,
307 : CancelToken? cancelToken,
308 : Options? options,
309 : ProgressCallback? onSendProgress,
310 : ProgressCallback? onReceiveProgress,
311 : });
312 :
313 : /// Make http request with options.
314 : ///
315 : /// [uri] The uri.
316 : /// [data] The request data
317 : /// [options] The request options.
318 : Future<Response<T>> requestUri<T>(
319 : Uri uri, {
320 : data,
321 : CancelToken? cancelToken,
322 : Options? options,
323 : ProgressCallback? onSendProgress,
324 : ProgressCallback? onReceiveProgress,
325 : });
326 :
327 : Future<Response<T>> fetch<T>(RequestOptions requestOptions);
328 : }
|