Line data Source code
1 : // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
2 : // for details. All rights reserved. Use of this source code is governed by a
3 : // BSD-style license that can be found in the LICENSE file.
4 :
5 : import 'dart:async';
6 : import 'dart:convert';
7 : import 'dart:typed_data';
8 :
9 : import 'base_client.dart';
10 : import 'base_request.dart';
11 : import 'io_client.dart';
12 : import 'response.dart';
13 : import 'streamed_response.dart';
14 :
15 : /// The interface for HTTP clients that take care of maintaining persistent
16 : /// connections across multiple requests to the same server. If you only need to
17 : /// send a single request, it's usually easier to use [head], [get], [post],
18 : /// [put], [patch], or [delete] instead.
19 : ///
20 : /// When creating an HTTP client class with additional functionality, you must
21 : /// extend [BaseClient] rather than [Client]. In most cases, you can wrap
22 : /// another instance of [Client] and add functionality on top of that. This
23 : /// allows all classes implementing [Client] to be mutually composable.
24 : abstract class Client {
25 : /// Creates a new client.
26 : ///
27 : /// Currently this will create an [IOClient] if `dart:io` is available and
28 : /// throw an [UnsupportedError] otherwise. In the future, it will create a
29 : /// [BrowserClient] if `dart:html` is available.
30 0 : factory Client() => new IOClient();
31 :
32 : /// Sends an HTTP HEAD request with the given headers to the given URL, which
33 : /// can be a [Uri] or a [String].
34 : ///
35 : /// For more fine-grained control over the request, use [send] instead.
36 : Future<Response> head(url, {Map<String, String> headers});
37 :
38 : /// Sends an HTTP GET request with the given headers to the given URL, which
39 : /// can be a [Uri] or a [String].
40 : ///
41 : /// For more fine-grained control over the request, use [send] instead.
42 : Future<Response> get(url, {Map<String, String> headers});
43 :
44 : /// Sends an HTTP POST request with the given headers and body to the given
45 : /// URL, which can be a [Uri] or a [String].
46 : ///
47 : /// [body] sets the body of the request. It can be a [String], a [List<int>]
48 : /// or a [Map<String, String>]. If it's a String, it's encoded using
49 : /// [encoding] and used as the body of the request. The content-type of the
50 : /// request will default to "text/plain".
51 : ///
52 : /// If [body] is a List, it's used as a list of bytes for the body of the
53 : /// request.
54 : ///
55 : /// If [body] is a Map, it's encoded as form fields using [encoding]. The
56 : /// content-type of the request will be set to
57 : /// `"application/x-www-form-urlencoded"`; this cannot be overridden.
58 : ///
59 : /// [encoding] defaults to [UTF8].
60 : ///
61 : /// For more fine-grained control over the request, use [send] instead.
62 : Future<Response> post(url, {Map<String, String> headers, body,
63 : Encoding encoding});
64 :
65 : /// Sends an HTTP PUT request with the given headers and body to the given
66 : /// URL, which can be a [Uri] or a [String].
67 : ///
68 : /// [body] sets the body of the request. It can be a [String], a [List<int>]
69 : /// or a [Map<String, String>]. If it's a String, it's encoded using
70 : /// [encoding] and used as the body of the request. The content-type of the
71 : /// request will default to "text/plain".
72 : ///
73 : /// If [body] is a List, it's used as a list of bytes for the body of the
74 : /// request.
75 : ///
76 : /// If [body] is a Map, it's encoded as form fields using [encoding]. The
77 : /// content-type of the request will be set to
78 : /// `"application/x-www-form-urlencoded"`; this cannot be overridden.
79 : ///
80 : /// [encoding] defaults to [UTF8].
81 : ///
82 : /// For more fine-grained control over the request, use [send] instead.
83 : Future<Response> put(url, {Map<String, String> headers, body,
84 : Encoding encoding});
85 :
86 : /// Sends an HTTP PATCH request with the given headers and body to the given
87 : /// URL, which can be a [Uri] or a [String].
88 : ///
89 : /// [body] sets the body of the request. It can be a [String], a [List<int>]
90 : /// or a [Map<String, String>]. If it's a String, it's encoded using
91 : /// [encoding] and used as the body of the request. The content-type of the
92 : /// request will default to "text/plain".
93 : ///
94 : /// If [body] is a List, it's used as a list of bytes for the body of the
95 : /// request.
96 : ///
97 : /// If [body] is a Map, it's encoded as form fields using [encoding]. The
98 : /// content-type of the request will be set to
99 : /// `"application/x-www-form-urlencoded"`; this cannot be overridden.
100 : ///
101 : /// [encoding] defaults to [UTF8].
102 : ///
103 : /// For more fine-grained control over the request, use [send] instead.
104 : Future<Response> patch(url, {Map<String, String> headers, body,
105 : Encoding encoding});
106 :
107 : /// Sends an HTTP DELETE request with the given headers to the given URL,
108 : /// which can be a [Uri] or a [String].
109 : ///
110 : /// For more fine-grained control over the request, use [send] instead.
111 : Future<Response> delete(url, {Map<String, String> headers});
112 :
113 : /// Sends an HTTP GET request with the given headers to the given URL, which
114 : /// can be a [Uri] or a [String], and returns a Future that completes to the
115 : /// body of the response as a String.
116 : ///
117 : /// The Future will emit a [ClientException] if the response doesn't have a
118 : /// success status code.
119 : ///
120 : /// For more fine-grained control over the request and response, use [send] or
121 : /// [get] instead.
122 : Future<String> read(url, {Map<String, String> headers});
123 :
124 : /// Sends an HTTP GET request with the given headers to the given URL, which
125 : /// can be a [Uri] or a [String], and returns a Future that completes to the
126 : /// body of the response as a list of bytes.
127 : ///
128 : /// The Future will emit a [ClientException] if the response doesn't have a
129 : /// success status code.
130 : ///
131 : /// For more fine-grained control over the request and response, use [send] or
132 : /// [get] instead.
133 : Future<Uint8List> readBytes(url, {Map<String, String> headers});
134 :
135 : /// Sends an HTTP request and asynchronously returns the response.
136 : Future<StreamedResponse> send(BaseRequest request);
137 :
138 : /// Closes the client and cleans up any resources associated with it. It's
139 : /// important to close each client when it's done being used; failing to do so
140 : /// can cause the Dart process to hang.
141 : void close();
142 : }
|