Detailed Icecap Protocol Reference

The Protocol Introduction page explains the basics of the Icecap protocol, here you will find a detailled description of all the events, commands and replies that Icecap understands and uses.

This page is currently being written, and therefore is incomplete and probably inaccurate, as Icecap protocol is still subject to change and development.


Network Add

Define a network

1;network add;network=ircnet;protocol=irc

This really only defines the existance of a irc network called ircnet, to add the location/port/password you need to use Gateway Add.

Optional Parameters

Network List

Gets the list of the defined networks.

1;network list

Gateway Add

Define a gateway for a network.

1;gateway add;network=ircnet;

Optional Parameters

Gateway List

Lists all defined gateways.

1;gateway list

Channel List

Lists all defined channels

1;channel list

Optional Parameters

Presence Add

Define mypresence for a network. The network/mypresence combo makes a unique identifier for events and commands relating to that connection.

1;presence add;network=ircnet;mypresence=mynick

Optional Paramters

Presence List

Lists all defined presences.

1;presence list

Presence Connect

Connect to a presence.

1;presence connect;network=ircnet;mypresence=mynick

Presence Disconnect

Disconnect a connected presence.

1;presence disconnect;network=ircnet;mypresence=mynick

Presence Remove

Remove a presence.

1;presence remove;network=ircnet;mypresence=mynick

Presence Set

Set various attributes for a presence.

1;presence set;network=ircnet;mypresence=mynick<attributes>


If you wish to set an attribute that has no value, like autoconnect, simply pass ;autoconnect as an attribute. To unset an attribute like this simply use ;autoconnect=

Channel Join

Join a channel.

1;channel join;network=ircnet;mypresence=mynick;channel=#channel

Channel Part

Part a channel.

1;channel part;network=ircnet;mypresence=mynick;channel=#channel

Channel Names

Gets a list of all users on a channel. A list of connected users is sent on a channel join event, so this is only used when a client reconnects to Icecap and needs the list of users in an already connected channel.

1;channel names;network=ircnet;mypresence=mynick;channel=#channel

Channel Change

Change some attribute of the channel.

1;channel change;network=ircnet;mypresence=mynick;channel=#channel;topic=Ehlo World

TODO - will this also do channel modes?


Send a Message.

1;msg;network=ircnet;mypresence=mynick;channel=#channel;msg=hello world
1;msg;network=ircnet;mypresence=mynick;presence=othernick;msg=hello othernick, how do you do?

Use presence= or channel=, depending on if you want to send a private message, or a channel message. Messages, as they contain user input passed directly to Icecap, should have all ; characters escaped to \.

The reply may contain "msg" parameter if some characters got transliterated because they weren't in destination character set. For example:


Event Get

Request old events from Icecap's event cache. See Requesting Old Events

File Send

Send a file over the Icecap connection. See File Transfers

Config Get

Get the config for the specified key.

1;config get;option1

You can also use wildcards:

1;config get;*

Would get all the config values Icecap has.

Optional Attributes

Config Set

Set some config values.

1;config set;option1=a;option2=b

Optional Attributes


Tell Icecap the client is quitting.



Tell Icecap to disconnect from all its connected networks and shut down.




Sent after a network is defined using Network Add.



The gateway is attempting to connect.



The gateway sucessfully connected.



Gateway Message of the Day.

*;gateway_motd;id=100;time=1000000000;network=ircnet;mypresence=mynick;data=MOTD for ircnet


Something about the gateway connection has changed.


Optional Attributes


Synonym of Gateway_changed.

TODO - does this even exist anymore?


Icecap has completely logged into the gateway.


All client commands for a gateway should be deferred until this event is recieved.


The gateway has disconnected.



The connection failed.

TODO - get an example, Icecap seems to crash on connect error now


A user has joined the network


A presence_init is also sent when you connect to a network, right after Gateway_connected. Note the use of the 'own' attribute.



A user has joined the channel.



A user has disconnected from the network, this is usually preceeded by a channel_presence_removed event.



A presence has changed.


Optional Attributes


A user has left the channel.

*;channel_presence_removed;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;presence=otheruser;reason=Read error: 113 (No route to host)

Optional Attributes


A user's mode has changed.


Note: the clients probably only care about the resulting mode parameter, the add and remove stuff is probably only useful for status messages. irc_source_nick is handy when the opping has been done through chanserv


A channel has been joined.


Optional Attributes


A channel has been parted.


Optional Attributes


The channel has changed.

Optional Attributes

2 channel_changed events are sent when a user joins a channel to inform the client of what the topic is, and who changed it and when.

*;channel_changed;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;init;topic=Some Topic;topic_timestamp=0;topic_set_by=


Note that the first one only contains the topic, and the other one contains only the topic timestamp and the user who changed it. Clients can use those lines to print info like the following on connect:

Topic for #channel is Some Topic
Topic for #channel set by othernick at Sun Sep  9 02:46:40 2001

If a channel_changed event with both topic and topic_set_by attributes is recieved, the topic has actually been changed.


*;msg;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;presence=otheruser;address=~otheruser@users;msg=hello world

Optional Attributes

It is possible for messages without nick, address, hostname or channel attributes to be sent, mainly as network service messages. A message with a nick but no channel and no no-autoreply param is probably a private message to you.



IcecapProtocol/Reference (last edited 2009-12-21 12:41:27 by ip70-181-215-71)