.\"
.\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd @IRCCD_MAN_DATE@
.Dt IRCCD-IPC 7
.Os
.\" NAME
.Sh NAME
.Nm irccd-ipc
.Nd irccd network protocol
.\" SYNOPSIS
.Sh SYNOPSIS
.Nm HOOK-ADD
.Ar name Ar path
.Nm HOOK-LIST
.Nm HOOK-REMOVE
.Ar name
.Nm PLUGIN-CONFIG
.Ar name Op Ar variable Op Ar value
.Nm PLUGIN-INFO
.Ar name
.Nm PLUGIN-LOAD
.Ar name
.Nm PLUGIN-PATH
.Ar name Op Ar variable Op Ar value
.Nm PLUGIN-LIST
.Nm PLUGIN-RELOAD
.Ar name
.Nm PLUGIN-TEMPLATE
.Ar name Op Ar variable Op Ar value
.Nm PLUGIN-UNLOAD
.Ar name
.Nm RULE-ADD
.Ar accept|drop
.Op ceiops=value
.Nm RULE-EDIT
.Ar index
.Op ceops(+|-)value
.Op a=accept|drop
.Nm RULE-LIST
.Nm RULE-MOVE
.Ar from
.Ar to
.Nm RULE-REMOVE
.Ar index
.Nm SERVER-DISCONNECT
.Op name
.Nm SERVER-MESSAGE
.Ar name
.Ar channel
.Ar message
.Nm SERVER-ME
.Ar name
.Ar channel
.Ar message
.Nm SERVER-MODE
.Ar name
.Ar channel
.Ar mode
.Op Ar args
.Nm SERVER-NOTICE
.Ar name
.Ar channel
.Ar notice
.Nm SERVER-INFO
.Ar name
.Nm SERVER-INVITE
.Ar name
.Ar channel
.Ar target
.Nm SERVER-JOIN
.Ar name
.Ar channel
.Op Ar password
.Nm SERVER-KICK
.Ar name
.Ar channel
.Ar target
.Op Ar reason
.Nm SERVER-LIST
.Nm SERVER-PART
.Ar name
.Ar channel
.Op Ar reason
.Nm SERVER-TOPIC
.Ar name
.Ar channel
.Ar topic
.Nm WATCH
.\" DESCRIPTION
.Sh DESCRIPTION
This guide will help you controlling irccd via sockets.
.Pp
For this to work, you need to define a transport in your
.Pa irccd.conf
file, for more information see
.Xr irccd.conf 5 .
.Pp
Most of the commands are similar to
.Nm irccdctl
and mapped to the same network command. For more detailed information about each
command, take a look at
.Xr irccdctl 1
before.
.\" SYNTAX
.Sh SYNTAX
The irccd program uses plain text for networking messages that consist of a
command name, its arguments and ends with a CRLF delimiter.
.Pp
Example of command:
.Bd -literal -offset indent
SERVER-MESSAGE malikania #test Hello world!
.Ed
.\" RESPONSES
.Sh RESPONSES
All command emit a response even though if they don't produce output. If a
command succeeds, a plain
.Dq OK
is returned, otherwise
.Dq ERROR
followed by a message is sent instead.
.Pp
Example with a successful message:
.Bd -literal -offset indent
OK
.Ed
.Pp
Example of error:
.Bd -literal -offset indent
ERROR server not found
.Ed
.Pp
Some command may produce more output that are printed under several lines for an
easier interpretation client side. In that case commands usually return
.Dq OK
followed by the number of lines provided.
.Pp
Example with
.Ar PLUGIN-CONFIG :
.Bd -literal -offset indent
OK 2
collaborative=true
level=hard
.Ed
.Sh COMMANDS
.\" COMMANDS
The following commands are available.
.Bl -tag -width "SERVER-DISCONNECT"
.\" HOOK-ADD
.It Cm HOOK-ADD
Add the hook
.Ar name
at the given
.Ar path .
.\" HOOK-LIST
.It Cm HOOK-LIST
Returns the list of hooks by their names separated by a space immediately after
.Dq OK
status.
.Pp
Example:
.Bd -literal -offset indent
OK irc-notify mail-notify
.Ed
.\" HOOK-REMOVE
.It Cm HOOK-REMOVE
Removes the hook specified by
.Ar name .
.\" PLUGIN-CONFIG
.It Cm PLUGIN-CONFIG
Set or get
.Ar variable
and its
.Ar value
if specified for the plugin
.Ar name .
Returns the list of configuration variables if there were only the plugin
.Ar name
or return only the value if
.Ar variable
was specified.
.Pp
Example if
.Ar variable
was specified:
.Bd -literal -offset indent
OK 1
current value
.Ed
.Pp
Example if
.Ar variable
was not specified:
.Bd -literal -offset indent
OK 2
collaborative=true
level=hard
.Ed
.\" PLUGIN-INFO
.It Cm PLUGIN-INFO
Return the information about the plugin
.Ar name
in the form:
.Pp
.Bd -literal -offset indent
OK 5
name
long description
version
license
author
.Ed
.\" PLUGIN-LOAD
.It Cm PLUGIN-LOAD
Find and load the plugin specified by
.Ar name .
.\" PLUGIN-PATH
.It Cm PLUGIN-PATH
Exactly the same usage as
.Cm PLUGIN-CONFIG
but for the plugin paths.
.\" PLUGIN-LIST
.It Cm PLUGIN-LIST
Returns the list of plugins by their names separated by a space immediately
after
.Dq OK
status.
.Pp
Example:
.Bd -literal -offset indent
OK ask auth hangman
.Ed
.\" PLUGIN-RELOAD
.It Cm PLUGIN-RELOAD
Reload the plugin specified by
.Ar name .
.\" PLUGIN-TEMPLATE
.It Cm PLUGIN-TEMPLATE
Exactly the same usage as
.Cm PLUGIN-CONFIG
but for the plugin paths.
.\" PLUGIN-UNLOAD
.It Cm PLUGIN-UNLOAD
Unload and remove the plugin
.Ar name .
.\" RULE-ADD
.It Cm RULE-ADD
Add a new rule with matching action to
.Ar accept
or
.Ar drop .
Then by a list separated by spaces, add any key=value pair where the key
defines the criterion to set from
.Dq ceops
which adds a channel, event, origin, plugin or server respectively. The
.Ar i
character is the optional index where to insert the new rule.
.Pp
Example of client request:
.Bd -literal -offset indent
RULE-ADD accept c=#test s=example i=1
.Ed
.\" RULE-EDIT
.It Cm RULE-EDIT
Edit the rule at the given
.Ar index .
Similarly to
.Cm RULE-ADD
command, you can specify a criterion modification using the
.Dq ceops
characters followed by a minus or plus string to either remove or add the
criterion respectively. It is also possible to change the rule action with the
key value pair
.Ar a=accept
Or
.Ar a=drop
.Pp
Example of client request:
.Bd -literal -offset indent
RULE-EDIT c-#staff s+example a=drop
.Ed
.\" RULE-LIST
.It Cm RULE-LIST
Return the list of rules loaded in the form:
.Pp
.Bd -literal -offset indent
OK 1
accept
list of servers
list of channels
list of origins
list of plugins
list of events
.Ed
.Pp
For each rule, the block of 6 lines is repeated for every rule returned in the
.Dq OK
response. So if you have 4 rules, you'll have to read 24 lines total.
.\" RULE-MOVE
.It Cm RULE-MOVE
Move the rule at the position
.Ar from
to the position specified by
.Ar to .
.\" RULE-REMOVE
.It Cm RULE-REMOVE
Remove the rule at the given
.Ar index .
.\" SERVER-DISCONNECT
.It Cm SERVER-DISCONNECT
Disconnect and remove the server specified by
.Ar name
if specified otherwise, remove all.
.\" SERVER-MESSAGE
.It Cm SERVER-MESSAGE
Send the private
.Ar message
to the
.Ar channel
into the server
.Ar name .
.\" SERVER-ME
.It Cm SERVER-ME
Send an action emote
.Ar message
to the
.Ar channel
into the server
.Ar name .
.\" SERVER-MODE
.It Cm SERVER-MODE
Change
.Ar channel
to the new
.Ar mode
with optional list of mode arguments specified by
.Ar args .
.\" SERVER-NOTICE
.It Cm SERVER-NOTICE
Send the
.Ar notice
to the
.Ar channel
into the server
.Ar name .
.\" SERVER-INFO
.It Cm SERVER-INFO
Get the information about the server
.Ar name
in the form:
.Bd -literal -offset indent
OK name
hostname port [ssl]
nickname username real name
#channels #channels...
.Ed
.\" SERVER-INVITE
.It Cm SERVER-INVITE
Invite the
.Ar target
to the
.Ar channel
into the server
.Ar name .
.\" SERVER-JOIN
.It Cm SERVER-JOIN
Join a
.Ar channel
into the server
.Ar name
using an optional
.Ar password .
.\" SERVER-KICK
.It Cm SERVER-KICK
Kick the
.Ar target
from the
.Ar channel
in the server
.Ar name
using an optional
.Ar reason .
.\" SERVER-LIST
.It Cm SERVER-LIST
Returns the list of servers by their names separated by a space immediately
after
.Dq OK
status.
.Pp
Example:
.Bd -literal -offset indent
OK caramail wanadoo
.Ed
.\" SERVER-PART
.It Cm SERVER-PART
Leaves the
.Ar channel
from the server
.Ar name
using an optional
.Ar reason .
.\" SERVER-TOPIC
.It Cm SERVER-TOPIC
Sets the new
.Ar topic
to the
.Ar channel
into the server
.Ar name .
.\" WATCH
.It Cm WATCH
Enable watch mode.
.Pp
When set, irccd will notify the client about new IRC event incoming using the
syntax:
.Bd -literal -offset indent
EVENT-<NAME> arguments...
.Ed
.Pp
Example:
.Bd -literal -offset indent
EVENT-CONNECT wanadoo
EVENT-MESSAGE wanadoo jean!jean@caramail.com #games hello guys!
.Ed
.El
.\" SEE ALSO
.Sh SEE ALSO
.Xr irccd 1 ,
.Xr irccdctl 1