Mercurial > irccd

comparison doc/src/network-api.md @ 607:bb9771fb5f44

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Docs: rework documentation - Change directories, - Remove handwritten manual pages.
author David Demelier <markand@malikania.fr>
date Fri, 08 Dec 2017 20:11:22 +0100
parents
children
comparison
equal deleted inserted replaced
606:4f5f306d13ac 607:bb9771fb5f44
1 % networking API
2 % David Demelier
3 % 2017-12-08
4
5 This guide will help you controlling irccd via sockets.
6
7 Currently, irccd supports internet and unix sockets, you need at least one
8 transport defined in your **irccd.conf**.
9
10 # Syntax
11
12 Irccd use JSON as protocol for sending and receiving data. A message must ends
13 with `\r\n\r\n` to be complete, thus it's possible to write JSON messages in
14 multiple lines.
15
16 For example, this buffer will be parsed as two different messages.
17
18 <div class="alert alert-success" role="alert">
19 **Example**: two commands issued
20
21 ```json
22 {
23 "param1": "value1"
24 }
25
26 {
27 "param1": "value1"
28 }
29
30 ```
31 </div>
32
33 Warning: please note that the `\r\n\r\n` characters are the escape characters of
34 line feed and new line, not the concatenation of `\` and `r`.
35
36 ## Responses
37
38 All commands emit a response with the following properties:
39
40 - **command**: (string) the result of the issued command,
41 - **error**: (int) the error error code, not defined on success.
42
43 ## Examples
44
45 Success message.
46
47 ```json
48 {
49 "command": "server-message",
50 }
51 ```
52
53 Command returned an error.
54
55 ```json
56 {
57 "command": "server-message",
58 "status": "error",
59 "error": "4001"
60 }
61 ```
62
63 # List of all commands
64
65 The following commands are available. Please note that a lot of commands require
66 a server as the first argument, it’s one of defined in the **irccd.conf** file
67 in the server section.
68
69 ## server-connect
70
71 Connect to a server.
72
73 ## Properties
74
75 - **command**: (string) "server-connect",
76 - **name**: (string) the server unique id,
77 - **host**: (string) the host address,
78 - **port**: (int) the port number (Optional, default: 6667),
79 - **ssl**: (bool) use SSL (Optional, default: false),
80 - **sslVerify**: (bool) verify SSL (Optional, default: false),
81 - **nickname**: (string) the nickname to use (Optional, default: irccd),
82 - **username**: (string) the user name to use (Optional, default: irccd),
83 - **realname**: (string) the real name to use
84 (Optional, default: IRC Client Daemon),
85 - **ctcpVersion**: (string) the CTCP Version to answer
86 (Optional, default: the irccd's version),
87 - **commandChar**: (string) the command character to use to invoke commands
88 (Optional, default: !),
89 - **reconnectTries**: (int) the number of reconnection to try
90 (Optional, default: -1),
91 - **reconnectTimeout**: (int) the number of seconds to wait before retrying to
92 connect (Optional, default: 30).
93
94 ## Example
95
96 ```json
97 {
98 "command": "server-connect",
99 "name": "myserver",
100 "host": "localhost",
101 "nickname": "edouard"
102 }
103 ```
104
105 ## server-disconnect
106
107 Disconnect from a server.
108
109 If server is not specified, irccd disconnects all servers.
110
111 ## Properties
112
113 - **command**: (string) "server-disconnect",
114 - **server**: (string) the server unique id (Optional, default: none).
115
116 ## Example
117
118 ```json
119 {
120 "command": "server-disconnect",
121 "server": "myserver"
122 }
123 ```
124
125 ## server-info
126
127 Get server information.
128
129 ## Properties
130
131 - **command**: (string) "server-info",
132 - **server**: (string) the server unique id.
133
134 ## Example
135
136 ```json
137 {
138 "command": "server-info",
139 "server": "myserver"
140 }
141 ```
142
143 ## Responses
144
145 - **name**: (string) the server unique id,
146 - **host**: (string) the server hostname,
147 - **port**: (int) the port,
148 - **ipv6**: (bool) true if using IPv6,
149 - **ssl**: (bool) true if connection is using SSL,
150 - **sslVerify**: (bool) true if SSL was verified,
151 - **channels**: (string list) list of channels.
152 - **nickname**: (string) the current nickname in use,
153 - **username**: (string) the username in use,
154 - **realname**: (string) the realname in use.
155
156 ## server-invite
157
158 Invite the specified target on the channel.
159
160 ## Properties
161
162 - **command**: (string) "server-invite",
163 - **server**: (string) the server unique id,
164 - **target**: (string) the nickname to invite,
165 - **channel**: (string) the channel.
166
167 ## Example
168
169 ```json
170 {
171 "command": "server-invite",
172 "server": "myserver",
173 "target": "edouard",
174 "channel": "#staff"
175 }
176 ```
177
178 ## server-join
179
180 Join the specified channel, the password is optional.
181
182 ## Properties
183
184 - **command**: (string) "server-join",
185 - **server**: (string) the server unique id,
186 - **channel**: (string) the channel to join,
187 - **password**: (string) the password (Optional, default: none).
188
189 ## Example
190
191 ```json
192 {
193 "command": "server-join",
194 "server": "myserver",
195 "channel": "#games"
196 }
197 ```
198
199 ## server-kick
200
201 Kick the specified target from the channel, the reason is optional.
202
203 ## Properties
204
205 - **command**: (string) "server-kick",
206 - **server**: (string) the server unique id,
207 - **target**: (string) the target nickname,
208 - **channel**: (string) the channel,
209 - **reason**: (string) the reason (Optional, default: none).
210
211 ## Example
212
213 ```json
214 {
215 "command": "server-kick",
216 "server": "myserver",
217 "target": "edouard",
218 "channel": "#staff",
219 "reason": "please be nice"
220 }
221 ```
222
223 ## server-list
224
225 Get the list of all connected servers.
226
227 ## Properties
228
229 - **command**: (string) "server-list".
230
231 ## Example
232
233 ```json
234 {
235 "command": "server-list"
236 }
237 ```
238
239 ## Responses
240
241 - The following properties:
242 - **list**: (string list) the list of all server unique ids.
243
244 ## server-me
245
246 Send an action emote.
247
248 ## Properties
249
250 - **command**: (string) "server-me",
251 - **server**: (string) the server unique id,
252 - **target**: (string) the target or channel,
253 - **message**: (string) the message.
254
255 ## Example
256
257 ```json
258 {
259 "command": "server-me",
260 "server": "myserver",
261 "channel": "#staff",
262 "message": "like that"
263 }
264 ```
265
266 ## server-message
267
268 Send a message to the specified target or channel.
269
270 ## Properties
271
272 - **command**: (string) "server-message",
273 - **server**: (string) the server unique id,
274 - **target**: (string) the target or channel,
275 - **message**: (string) the message.
276
277 ## Example
278
279 ```json
280 {
281 "command": "server-message",
282 "server": "myserver",
283 "target": "#staff",
284 "message": "this channel is nice"
285 }
286 ```
287
288 ## server-mode
289
290 Set the irccd's user mode.
291
292 ## Properties
293
294 - **command**: (string) "server-mode",
295 - **server**: (string) the server unique id,
296 - **mode**: (string) the mode.
297
298 ## Example
299
300 ```json
301 {
302 "command": "server-mode",
303 "server": "myserver",
304 "mode": "mode"
305 }
306 ```
307
308 ## server-nick
309
310 Change irccd's nickname.
311
312 ## Properties
313
314 - **command**: (string) "server-nick",
315 - **server**: (string) the server unique id,
316 - **nickname**: (string) the new nickname.
317
318 ## Example
319
320 ```json
321 {
322 "command": "server-nick",
323 "server": "myserver",
324 "nickname": "edouard"
325 }
326 ```
327
328 ## server-notice
329
330 Send a private notice to the specified target.
331
332 ## Properties
333
334 - **command**: (string) "server-notice",
335 - **server**: (string) the server unique id,
336 - **target**: (string) the target,
337 - **message**: (string) the notice message.
338
339 ## Example
340
341 ```json
342 {
343 "command": "server-notice",
344 "server": "myserver",
345 "target": "edouard",
346 "message": "hello dude"
347 }
348 ```
349
350 ## server-part
351
352 Leave the specified channel, the reason is optional.
353
354 Not all IRC servers support giving a reason to leave a channel, do not specify
355 it if this is a concern.
356
357 ## Properties
358
359 - **command**: (string) "server-part",
360 - **server**: (string) the unique server id,
361 - **channel**: (string) the channel to leave,
362 - **reason**: (string) the reason (Optional, default: none).
363
364 ## Example
365
366 ```json
367 {
368 "command": "server-part",
369 "server": "myserver",
370 "channel": "#staff",
371 "reason": "the reason"
372 }
373 ```
374
375 ## server-reconnect
376
377 Force reconnection of one or all servers.
378
379 If server is not specified, all servers will try to reconnect.
380
381 ## Properties
382
383 - **command**: (string) "server-reconnect",
384 - **server**: (string) the server unique id (Optional, default: none).
385
386 ## Example
387
388 ```json
389 {
390 "command": "server-reconnect",
391 "server": "myserver"
392 }
393 ```
394
395 ## server-topic
396
397 Change the topic of the specified channel.
398
399 ## Properties
400
401 - **command**: (string) "server-topic",
402 - **server**: (string) the unique server id,
403 - **channel**: (string) the channel,
404 - **topic**: (string) the new topic.
405
406 ## Example
407
408 ```json
409 {
410 "command": "server-topic",
411 "server": "myserver",
412 "channel": "#staff",
413 "topic": "the new topic"
414 }
415 ```