Mercurial > irccd

comparison man/irccd-ipc.7 @ 845:00a4720c4874

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: rewrite documentation in manual pages, closes #1674 Get rid of markdown documentation and the custom generator tools, instead use raw manual pages.
author David Demelier <markand@malikania.fr>
date Mon, 08 Jul 2019 16:15:57 +0200
parents
children 5e25439fe98d
comparison
equal deleted inserted replaced
844:dc6b42d7b97a 845:00a4720c4874
1 .\"
2 .\" Copyright (c) 2013-2019 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 7
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm irccd-api
22 .Nd irccd network protocol
23 .\" DESCRIPTION
24 .Sh DESCRIPTION
25 This guide will help you controlling irccd via sockets.
26 .Pp
27 For this to work, you need to define at least one transport in your
28 .Pa irccd.conf
29 file, for more information see
30 .Xr irccd.conf 5 .
31 .Pp
32 Most of the commands are similar to
33 .Nm irccdctl
34 and mapped to the same network command. For more detailed information about each
35 command, take a look at
36 .Xr irccdctl 1
37 before.
38 .\" SYNTAX
39 .Sh SYNTAX
40 Irccd use JSON as protocol for sending and receiving data. A message must ends
41 with
42 .Em \er\en\er\en
43 to be complete, thus it's possible to write JSON messages in multiple lines.
44 .Pp
45 For example, this buffer will be parsed as two different messages.
46 .Bd -literal -offset Ds
47 {
48 "param1": "value1"
49 }
50
51 {
52 "param1": "value1"
53 }
54 .Ed
55 .Pp
56 Warning: please note that the \er\en\er\en characters are the escape characters
57 of line feed and new line, not the concatenation of \e and r.
58 .\" RESPONSES
59 .Sh RESPONSES
60 All commands emit a response with the following properties:
61 .Pp
62 .Bl -tag -width 24n -offset Ds
63 .It Va command No (string)
64 the result of the issued command.
65 .It Va error No (int)
66 the error error code, not defined on success.
67 .It Va errorCategory No (string)
68 the error category (example: server, plugin).
69 .It Va errorMessage No (string)
70 the arbitrary error message.
71 .El
72 .Pp
73 Example with a successful message:
74 .Bd -literal -offset Ds
75 {
76 "command": "server-message",
77 }
78 .Ed
79 .Pp
80 Example with an error:
81 .Bd -literal -offset Ds
82 {
83 "command": "server-message",
84 "error": 1,
85 "errorCagegory": "server",
86 "errorMessage": "server not found"
87 }
88 .Ed
89 .Sh COMMANDS
90 .\" COMMANDS
91 The following commands are available.
92 .Bl -tag -width xxxxxxxx-yyyyyyyyy
93 .\" plugin-config
94 .It Cm plugin-config
95 Set or get values to a plugin.
96 .Pp
97 Available properties:
98 .Bl -tag -width 20n
99 .It Va command No (string)
100 must be
101 .Em plugin-config .
102 .It Va plugin No (string)
103 plugin identifier.
104 .It Va variable No (string)
105 the variable (Optional, default: undefined).
106 .It Va value No (string)
107 the value (Optional, default: undefined)
108 .El
109 .Pp
110 The following properties are available in a successful response when getting a
111 value:
112 .Pp
113 .Bl -tag -width 20n
114 .It Va variables No (list)
115 All values or unique variable.
116 .El
117 .\" plugin-info
118 .It Cm plugin-info
119 Retrieve plugin information.
120 .Pp
121 Available properties:
122 .Bl -tag -width 20n
123 .It Va command No (string)
124 must be
125 .Em plugin-info .
126 .It Va plugin No (string)
127 plugin identifier.
128 .El
129 .Pp
130 The following properties are available in a successful response:
131 .Bl -tag -width 20n
132 .It Va author No (string)
133 author name.
134 .It Va license No (string)
135 plugin license.
136 .It Va summary No (string)
137 plugin description.
138 .It Va version No (string)
139 arbitrary version.
140 .El
141 .\" plugin-list
142 .It Cm plugin-list
143 Get the list of all loaded plugins.
144 .Pp
145 Available properties:
146 .Bl -tag -width 20n
147 .It Va command No (string)
148 must be
149 .Em plugin-list .
150 .El
151 .Pp
152 The following properties are available in a successful response:
153 .Bl -tag -width 20n
154 .It Va list No (list)
155 a list of plugin names.
156 .El
157 .\" plugin-load
158 .It Cm plugin-load
159 Load a plugin by searching it.
160 .Pp
161 Available properties:
162 .Bl -tag -width 20n
163 .It Va command No (string)
164 must be
165 .Em plugin-load .
166 .It Va plugin No (identifier)
167 the plugin identifier.
168 .El
169 .\" plugin-reload
170 .It Cm plugin-reload
171 Reload a plugin.
172 .Pp
173 Available properties:
174 .Bl -tag -width 20n
175 .It Va command No (string)
176 must be
177 .Em plugin-reload .
178 .It Va plugin No (identifier)
179 the plugin identifier.
180 .El
181 .\" plugin-unload
182 .It Cm plugin-unload
183 Unload a plugin.
184 .Pp
185 Available properties:
186 .Bl -tag -width 20n
187 .It Va command No (string)
188 must be
189 .Em plugin-unload .
190 .It Va plugin No (identifier)
191 the plugin identifier.
192 .El
193 .\" rule-add
194 .It Cm rule-add
195 Add a new rule.
196 .Pp
197 Available properties:
198 .Bl -tag -width 20n
199 .It Va command No (string)
200 must be
201 .Em rule-add .
202 .It Va channels No (list)
203 a list of channels to match (Optional, default: undefined).
204 .It Va events No (list)
205 a list of events to match (Optional, default: undefined).
206 .It Va origins No (list)
207 a list of origins to match (Optional, default: undefined).
208 .It Va plugins No (list)
209 a list of plugins to match (Optional, default: undefined).
210 .It Va servers No (list)
211 a list of servers to match (Optional, default: undefined).
212 .It Va action No (string)
213 must be accept or drop.
214 .It Va index No (unsigned)
215 rule index (Optional, default: undefined).
216 .El
217 .\" rule-edit
218 .It Cm rule-edit
219 Edit a rule in place.
220 .Pp
221 Available properties:
222 .Bl -tag -width 20n
223 .It Va command No (string)
224 must be
225 .Em rule-edit .
226 .It Va add-channels No (list)
227 a list of channels to match (Optional, default: undefined).
228 .It Va add-events No (list)
229 a list of events to match (Optional, default: undefined).
230 .It Va add-origins No (list)
231 a list of origins to match (Optional, default: undefined).
232 .It Va add-plugins No (list)
233 a list of plugins to match (Optional, default: undefined).
234 .It Va add-servers No (list)
235 a list of servers to match (Optional, default: undefined).
236 .It Va remove-channels No (list)
237 a list of channels to unmatch (Optional, default: undefined).
238 .It Va remove-events No (list)
239 a list of events to unmatch (Optional, default: undefined).
240 .It Va remove-origins No (list)
241 a list of origins to unmatch (Optional, default: undefined).
242 .It Va remove-plugins No (list)
243 a list of plugins to unmatch (Optional, default: undefined).
244 .It Va remove-servers No (list)
245 a list of servers to unmatch (Optional, default: undefined).
246 .It Va action No (string)
247 can be accept or drop (Optional, default: undefined).
248 .It Va index No (unsigned)
249 rule index.
250 .El
251 .\" rule-info
252 .It Cm rule-info
253 Show information about a rule.
254 .Pp
255 Available properties:
256 .Bl -tag -width 20n
257 .It Va command No (string)
258 must be
259 .Em rule-info .
260 .It Va index No (unsigned)
261 rule index.
262 .El
263 .Pp
264 The following properties are available in a successful response:
265 .Bl -tag -width 20n
266 .It Va servers No (list)
267 a list of servers matched.
268 .It Va channels No (list)
269 a list of channels matched.
270 .It Va origins No (list)
271 a list of origins matched.
272 .It Va plugins No (list)
273 a list of plugins matched.
274 .It Va events No (list)
275 a list of events matched.
276 .It Va action No (string)
277 rule action, accept or drop.
278 .El
279 .\" rule-list
280 .It Cm rule-list
281 Get a list of rules.
282 .Pp
283 Available properties:
284 .Bl -tag -width 20n
285 .It Va command No (string)
286 must be
287 .Em rule-list .
288 .El
289 .Pp
290 The following properties are available in a successful response:
291 .Bl -tag -width 20n
292 .It Va list (list)
293 a list of object that contain the same information as
294 .Cm rule-info
295 command was invoked.
296 .El
297 .\" rule-move
298 .It Cm rule-move
299 Move a rule.
300 .Pp
301 Available properties:
302 .Bl -tag -width 20n
303 .It Va command No (string)
304 must be
305 .Em rule-move .
306 .It Va from No (int)
307 the source index.
308 .It Va to No (int)
309 the destination index.
310 .El
311 .\" rule-remove
312 .It Cm rule-remove
313 Remove a rule.
314 .Pp
315 Available properties:
316 .Bl -tag -width 20n
317 .It Va command No (string)
318 must be
319 .Em rule-remove .
320 .It Va index No (int)
321 rule index.
322 .El
323 .\" server-connect
324 .It Cm server-connect
325 Connect to a server.
326 .Pp
327 Available properties:
328 .Bl -tag -width 20n
329 .It Va command No (string)
330 must be
331 .Em server-connect .
332 .It Va name No (string)
333 the server unique id.
334 .It Va hostname No (string)
335 the host address.
336 .It Va port No (int)
337 the port number (Optional, default: 6667).
338 .It Va ssl No (bool)
339 use SSL (Optional, default: false).
340 .It Va nickname No (string)
341 the nickname to use (Optional, default: irccd).
342 .It Va username No (string)
343 the user name to use (Optional, default: irccd).
344 .It Va realname No (string)
345 the real name to use. (Optional, default: IRC Client Daemon).
346 .It Va ctcpVersion No (string)
347 the CTCP Version to answer. (Optional, default: the irccd's version),
348 .It Va commandChar No (string)
349 the command character to use to invoke command. (Optional, default: !).
350 .El
351 .\" server-disconnect
352 .It Cm server-disconnect
353 Disconnect from a server.
354 .Pp
355 If server is not specified, irccd disconnects all servers.
356 .Pp
357 Available properties:
358 .Bl -tag -width 20n
359 .It Va command No (string)
360 must be
361 .Ar server-disconnect .
362 .It Va server No (string)
363 the server unique id (Optional, default: none).
364 .El
365 .\" server-info
366 .It Cm server-info
367 Get server information.
368 .Pp
369 Available properties:
370 .Bl -tag -width 20n
371 .It Va command No (string)
372 must be
373 .Ar server-info .
374 .It Va server No (string)
375 the server unique id.
376 .El
377 .Pp
378 The following properties are available in a successful response:
379 .Bl -tag -width 20n
380 .It Va name No (string)
381 the server unique id.
382 .It Va hostname No (string)
383 the server hostname.
384 .It Va port No (int)
385 the port.
386 .It Va ipv4 No (bool)
387 true if using IPv6.
388 .It Va ipv6 No (bool)
389 true if using IPv6.
390 .It Va ssl No (bool)
391 true if connection is using SSL.
392 .It Va channels No (list)
393 list of channels.
394 .It Va nickname No (string)
395 the current nickname in use.
396 .It Va username No (string)
397 the username in use.
398 .It Va realname No (string)
399 the realname in use.
400 .El
401 .\" server-invite
402 .It Cm server-invite
403 Invite the specified target on the channel.
404 .Pp
405 Available properties:
406 .Bl -tag -width 20n
407 .It Va command No (string)
408 must be
409 .Ar server-invite .
410 .It Va server No (string)
411 the server unique id.
412 .It Va target No (string)
413 the nickname to invite.
414 .It Va channel No (string)
415 the channel.
416 .El
417 .\" server-join
418 .It Cm server-join
419 Join the specified channel.
420 .Pp
421 Available properties:
422 .Bl -tag -width 20n
423 .It Va command No (string)
424 must be
425 .Ar server-join .
426 .It Va server No (string)
427 the server unique id.
428 .It Va channel No (string)
429 the channel to join.
430 .It Va password No (string)
431 the password (Optional, default: none).
432 .El
433 .\" server-kick
434 .It Cm server-kick
435 Kick the specified target from the channel.
436 .Pp
437 Available properties:
438 .Bl -tag -width 20n
439 .It Va command No (string)
440 must be
441 .Ar server-kick .
442 .It Va server No (string)
443 the server unique id.
444 .It Va target No (string)
445 the target nickname.
446 .It Va channel No (string)
447 the channel.
448 .It Va reason No (string)
449 the reason (Optional, default: none).
450 .El
451 .\" server-list
452 .It Cm server-list
453 Get the list of all connected servers.
454 .Pp
455 Available properties:
456 .Bl -tag -width 20n
457 .It Va command No (string)
458 must be
459 .Ar server-list .
460 .El
461 .Pp
462 The following properties are available in a successful response:
463 .Pp
464 .Bl -tag -width 20n
465 .It Va list No (list)
466 the list of all server unique ids as integers.
467 .El
468 .\" server-me
469 .It Cm server-me
470 Send an action emote.
471 .Pp
472 Available properties:
473 .Bl -tag -width 20n
474 .It Va command No (string)
475 must be
476 .Ar server-me .
477 .It Va server No (string)
478 the server unique id.
479 .It Va target No (string)
480 the target or channel.
481 .It Va message No (string)
482 the message.
483 .El
484 .\" server-message
485 .It Cm server-message
486 Send a message to the specified target or channel.
487 .Pp
488 Available properties:
489 .Bl -tag -width 20n
490 .It Va command No (string)
491 must be
492 .Ar server-message .
493 .It Va server No (string)
494 the server unique id.
495 .It Va target No (string)
496 the target or channel.
497 .It Va message No (string)
498 the message.
499 .El
500 .\" server-mode
501 .It Cm server-mode
502 Change channel or bot mode.
503 .Pp
504 Available properties:
505 .Bl -tag -width 20n
506 .It Va command No (string)
507 must be
508 .Ar server-mode .
509 .It Va server No (string)
510 the server unique id.
511 .It Va channel No (string)
512 the channel or irccd's nickname
513 .It Va mode No (string)
514 the mode.
515 .It Va limit No (string)
516 a optional limit.
517 .It Va user No (string)
518 a optional user.
519 .It Va mask No (string)
520 a optional mask.
521 .El
522 .\" server-nick
523 .It Cm server-nick
524 Change irccd's nickname.
525 .Pp
526 Available properties:
527 .Bl -tag -width 20n
528 .It Va command No (string)
529 must be
530 .Ar server-nick .
531 .It Va server No (string)
532 the server unique id.
533 .It Va nickname No (string)
534 the new nickname.
535 .El
536 .\" server-notice
537 .It Cm server-notice
538 Send a private notice to the specified target.
539 .Pp
540 Available properties:
541 .Bl -tag -width 20n
542 .It Va command No (string)
543 must be
544 .Ar server-notice .
545 .It Va server No (string)
546 the server unique id.
547 .It Va target No (string)
548 the target.
549 .It Va message No (string)
550 the notice message.
551 .El
552 .\" server-part
553 .It Cm server-part
554 Leave the specified channel.
555 .Pp
556 Available properties:
557 .Bl -tag -width 20n
558 .It Va command No (string)
559 must be
560 .Ar server-part .
561 .It Va server No (string)
562 the unique server id.
563 .It Va channel No (string)
564 the channel to leave.
565 .It Va reason No (string)
566 the reason (Optional, default: none).
567 .El
568 .\" server-reconnect
569 .It Cm server-reconnect
570 Force reconnection of one or all servers.
571 .Pp
572 If server is not specified, all servers will try to reconnect.
573 .Pp
574 Available properties:
575 .Bl -tag -width 20n
576 .It Va command No (string)
577 must be
578 .Ar server-reconnect .
579 .It Va server No (string)
580 the server unique id (Optional, default: none).
581 .El
582 .\" server-topic
583 .It Cm server-topic
584 Change the topic of the specified channel.
585 .Pp
586 Available properties:
587 .Bl -tag -width 20n
588 .It Va command No (string)
589 must be
590 .Ar server-topic .
591 .It Va server No (string)
592 the unique server id.
593 .It Va channel No (string)
594 the channel.
595 .It Va topic No (string)
596 the new topic.
597 .El
598 .El
599 .\" SEE ALSO
600 .Sh SEE ALSO
601 .Xr irccd 1