Mercurial > irccd
comparison man/irccd-api-http.3 @ 1168:5534d669b7af
irccd: document Irccd.Http API
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 06 Mar 2022 10:54:20 +0100 |
parents | |
children | 1845a0509a93 |
comparison
equal
deleted
inserted
replaced
1167:0b6d53577983 | 1168:5534d669b7af |
---|---|
1 .\" | |
2 .\" Copyright (c) 2013-2022 David Demelier <markand@malikania.fr> | |
3 .\" | |
4 .\" Permission to use, copy, modify, and/or distribute this software for any | |
5 .\" purpose with or without fee is hereby granted, provided that the above | |
6 .\" copyright notice and this permission notice appear in all copies. | |
7 .\" | |
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
15 .\" | |
16 .Dd @IRCCD_MAN_DATE@ | |
17 .Dt IRCCD-API-HTTP 3 | |
18 .Os | |
19 .\" NAME | |
20 .Sh NAME | |
21 .Nm Irccd.Http | |
22 .Nd asynchronous HTTP API | |
23 .\" SYNOPSIS | |
24 .Sh SYNOPSIS | |
25 .Fn Irccd.Http.request "options, callback" | |
26 .\" DESCRIPTION | |
27 .Sh DESCRIPTION | |
28 Execute asynchronous HTTP requests. | |
29 .Pp | |
30 This module is optional and only available if irccd was build with HTTP | |
31 support. Make sure to test availability of | |
32 .Nm | |
33 before using it. | |
34 .\" METHODS | |
35 .Sh METHODS | |
36 The | |
37 .Fn Irccd.Http.request | |
38 starts a new asynchronous HTTP request using the object | |
39 .Fa options | |
40 which should have the following properties: | |
41 .Bl -tag | |
42 .It Fa url No (string) | |
43 The destination URL which should start with the scheme | |
44 .Dq http:// | |
45 or | |
46 .Dq https:// . | |
47 .It Fa method No (string) | |
48 The HTTP method to use, examples: | |
49 .Dq GET , | |
50 .Dq POST , | |
51 .Dq DELETE . | |
52 If not set, defaults to | |
53 .Dq GET . | |
54 .It Fa body No (string) | |
55 A body to send to the request, if value is not a string it will be coerced | |
56 in-place. | |
57 .It Fa timeout No (int) | |
58 Maximum number of seconds to wait. If unset, waits indefinitely. | |
59 .El | |
60 .Pp | |
61 The argument | |
62 .Fa callback | |
63 must have the signature | |
64 .Fn fn "result" | |
65 which unique argument | |
66 .Fa result | |
67 is an object with the following properties: | |
68 .Bl -tag | |
69 .It Fa status No (int) | |
70 If non-zero, contains a native platform error code which indicates that the | |
71 operation could not complete. | |
72 .It Fa code No (int) | |
73 HTTP return code, examples | |
74 .Dq 200 , | |
75 .Dq 404 . | |
76 It it set to 0 if | |
77 .Fa status | |
78 is non-zero (operation failed). | |
79 .It Fa body No (string) | |
80 Content of body request. | |
81 .El | |
82 .\" EXAMPLES | |
83 .Sh EXAMPLES | |
84 Perform a POST request with a JSON body which will be converted on the fly. | |
85 .Bd -literal | |
86 const options = { | |
87 url: "http://foo.org", | |
88 method: "POST", | |
89 body: { | |
90 user: "francis", | |
91 password: "sicnarf" | |
92 } | |
93 }; | |
94 | |
95 Irccd.Http.request(options, function (r) { | |
96 if (r.status === 0) | |
97 Irccd.Logger.info("operation complete"); | |
98 }); | |
99 .Ed | |
100 .\" SEE ALSO | |
101 .Sh SEE ALSO | |
102 .Xr irccd-api 3 | |
103 .\" AUTHORS | |
104 .Sh AUTHORS | |
105 The | |
106 .Nm irccd | |
107 daemon was written by | |
108 .An David Demelier Aq Mt markand@malikania.fr . |