Skip to content

Commit a946315

Browse files
mikoto2000mikoto2000
committed
Web.AsyncHTTP: Added documents.
1 parent 4e03b15 commit a946315

1 file changed

Lines changed: 205 additions & 0 deletions

File tree

‎doc/vital/Web/AsyncHTTP.txt‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
*vital/Web/AsyncHTTP.txt* simple Async HTTP client library.
2+
3+
Maintainer: mattn <mattn.jp@gmail.com>
4+
thinca <thinca+vim@gmail.com>
5+
6+
==============================================================================
7+
CONTENTS *Vital.Web.AsyncHTTP-contents*
8+
9+
INTRODUCTION |Vital.Web.AsyncHTTP-introduction|
10+
INTERFACE |Vital.Web.AsyncHTTP-interface|
11+
Functions |Vital.Web.AsyncHTTP-functions|
12+
Response |Vital.Web.AsyncHTTP-response|
13+
14+
==============================================================================
15+
INTRODUCTION *Vital.Web.AsyncHTTP-introduction*
16+
17+
*Vital.Web.AsyncHTTP* is an Async HTTP Utilities Library. It provides a simple
18+
Async HTTP client.
19+
20+
==============================================================================
21+
INTERFACE *Vital.Web.AsyncHTTP-interface*
22+
------------------------------------------------------------------------------
23+
FUNCTIONS *Vital.Web.AsyncHTTP-functions*
24+
25+
get({url} [, {param} [, {header}]]) *Vital.Web.AsyncHTTP.get()*
26+
Send a GET request to the server.
27+
This is just a wrapper of |Vital.Web.AsyncHTTP.request()|.
28+
29+
post({url} [, {param} [, {header}]]) *Vital.Web.AsyncHTTP.post()*
30+
Send a POST request to the server.
31+
This is just a wrapper of |Vital.Web.AsyncHTTP.request()|.
32+
33+
request({settings}) *Vital.Web.AsyncHTTP.request()*
34+
request({url} [, {settings}])
35+
request({method}, {url} [, {settings}])
36+
Send a request to the server.
37+
This function requires one of the clients, "curl" or "wget".
38+
{settings} is a |Dictionary| which contains the following items:
39+
40+
"url" Required
41+
URL of a server.
42+
43+
"method" Default: "GET"
44+
HTTP Method, such as GET, HEAD, POST, PUT, DELETE, or PATCH.
45+
46+
"param" Default: (None)
47+
GET parameters. This is a string or a dictionary.
48+
If dictionary, it is converted to a string by
49+
|Vital.Web.AsyncHTTP.encodeURI()|.
50+
This is appended to url.
51+
52+
"data" Default: (None)
53+
POST data. This is a string, a list, or a dictionary.
54+
If it is a dictionary, it is converted to a string by
55+
|Vital.Web.AsyncHTTP.encodeURI()|.
56+
57+
"headers" Default: (None)
58+
Request headers. This is a dictionary.
59+
60+
"contentType" Default: (None)
61+
Content-Type for "data".
62+
This is one of "headers". This is used preferentially.
63+
64+
"outputFile" Default: (None)
65+
Output the result to this file.
66+
"content" of the result become empty when this is specified.
67+
68+
"timeout" Default: (None)
69+
Network timeout by seconds.
70+
71+
"username" Default: (None)
72+
User name for an HTTP authentication.
73+
74+
"password" Default: (None)
75+
Password for an HTTP authentication.
76+
77+
"bearerToken" Default: (None)
78+
Bearer token for an HTTP authentication (OAuth2).
79+
80+
"maxRedirect" Default: 20
81+
Maximum number of redirections.
82+
The default is 20, which is usually far more than necessary.
83+
84+
"retry" Default: 1
85+
Maximum number of retries.
86+
87+
"client" Default: ["python", "curl", "wget",
88+
"python3", "python2"]
89+
Candidate list of HTTP client to use for a request.
90+
The first available one is used.
91+
A string as an HTTP client is also possible.
92+
See also |Vital.Web.AsyncHTTP-client|.
93+
94+
"command"
95+
Command name for a client. You should use with "client".
96+
This is a |Dictionary| that has client name as key and has the
97+
command as value.
98+
This maybe becomes like the following. >
99+
{
100+
"curl": "/usr/bin/curl",
101+
"wget": "/usr/local/bin/wget",
102+
}
103+
<
104+
"authMethod" Default: (None)
105+
(This is only valid for "curl" interface.)
106+
Specify the authorization method.
107+
The value must be in ['basic', 'digest', 'ntlm', 'negotiate',
108+
'oauth2']
109+
The default value is None, and then use "anyauth".
110+
111+
"gzipDecompress" Default: 0
112+
Attempt to decompress response data as if it was gzipped
113+
114+
"unixSocket" Default: (None)
115+
Use --unix-sokect (only curl >= 7.40.0)
116+
117+
"user_cb" Default: (None)
118+
A |function| of callback function called when the process
119+
outputs some data. The callback function has one argument,
120+
response(|Dictionary| of response).
121+
122+
parseHeader({headers}) *Vital.Web.AsyncHTTP.parseHeader()*
123+
Parse {headers} list to a dictionary.
124+
Duplicated fields are overwritten.
125+
126+
encodeURI({param}) *Vital.Web.AsyncHTTP.encodeURI()*
127+
Encode params as URI query.
128+
129+
decodeURI({str}) *Vital.Web.AsyncHTTP.decodeURI()*
130+
Decode string as URI params.
131+
132+
encodeURIComponent({str}) *Vital.Web.AsyncHTTP.encodeURIComponent()*
133+
Encode param as URI components.
134+
135+
------------------------------------------------------------------------------
136+
RESPONSE *Vital.Web.AsyncHTTP-response*
137+
138+
|Vital.Web.AsyncHTTP.request()|, |Vital.Web.AsyncHTTP.get()|, and
139+
|Vital.Web.AsyncHTTP.post()| pass it to the resonse argument of |user_cb|.
140+
Data structure as |Directory| like following.
141+
>
142+
{
143+
"header": [
144+
"Content-Type: text/html",
145+
"Content-Length: 310"
146+
],
147+
"allHeaders": [
148+
"Set-Cookie: k1=v1; Path=/",
149+
"Content-Type: text/html",
150+
"Content-Length: 310"
151+
],
152+
"content": "<html> .....",
153+
"status": 200,
154+
"statusText": "OK",
155+
"success": 1,
156+
"redirectInfo": [],
157+
}
158+
<
159+
"header"
160+
The header lines of a response. This can convert to
161+
|Dictionary| by |Vital.Web.AsyncHTTP.parseHeader()|.
162+
163+
"allHeaders"
164+
All of header lines that includes redirectInfo.
165+
166+
"content"
167+
The content of a response.
168+
169+
"status"
170+
The http status code of a response.
171+
If the code couldn't take, this is 0.
172+
173+
"statusText"
174+
The http status code text of a response.
175+
If the code couldn't take, this is the empty string.
176+
177+
"success"
178+
This is 1 if the "status" is 2xx.
179+
180+
"redirectInfo"
181+
When the request was redirected, the redirected responses are
182+
stored. Form of these are the same as a response.
183+
184+
185+
186+
------------------------------------------------------------------------------
187+
CLIENT *Vital.Web.AsyncHTTP-client*
188+
189+
The following can be used.
190+
(TODO: More document. Especially about limitation.)
191+
192+
curl *Vital.Web.AsyncHTTP-client-curl*
193+
Use curl command.
194+
195+
http://curl.haxx.se/
196+
197+
wget *Vital.Web.AsyncHTTP-client-wget*
198+
Use wget command.
199+
200+
http://www.gnu.org/software/wget/
201+
202+
203+
==============================================================================
204+
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl
205+

0 commit comments

Comments
 (0)