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.

Commands

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

charset = The character set to use eg. iso-8859-1

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;host=irc.ircnet.org

Optional Parameters

port - The port used for connection, defaults to the protocol default. Can be a single number or a range or a list like "500-564,605"
password - The connection password, if one is needed.
priority - 0 is default, > 0 is lower, < 0 is higher priority.

Gateway List

Lists all defined gateways.

1;gateway list

Channel List

Lists all defined channels

1;channel list

Optional Parameters

network - The network you want the channellist from (not implemented yet)

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

autoconnect - whether to autoconnect, this defaults to on.

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>

Attributes

autoconnect

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?

Messages

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:

1;msg;network=ircnet;mypresence=mynick;channel=#channel;msg=50€
1;+;id=123;msg=50EUR

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

TODO - I remember some crazy Profile and some other attribute you could use, but never figured out what they were for...

Config Set

Set some config values.

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

Optional Attributes

TODO - I remember some crazy Profile and some other attribute you could use, but never figured out what they were for...

Quit

Tell Icecap the client is quitting.

1;quit

Shutdown

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

1;shutdown

Events

Network_init

Sent after a network is defined using Network Add.

*;network_init;id=100;time=1000000000;network=ircnet;protocol=irc

Gateway_connecting

The gateway is attempting to connect.

*;gateway_connecting;id=100;time=1000000000;network=ircnet;mypresence=mynick;ip=192.168.0.1;port=6667

Gateway_connected

The gateway sucessfully connected.

*;gateway_connected;id=100;time=1000000000;network=ircnet;mypresence=mynick;charset=iso-8859-1;ip=192.168.0.1;port=6667

Gateway_motd

Gateway Message of the Day.

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

Gateway_changed

Something about the gateway connection has changed.

*;gateway_changed;id=100;time=1000000000;network=ircnet;mypresence=mynick;irc_mode=e

Optional Attributes

irc_mode - The IRC mode for your connection
TODO - Are there any others yet?

Gwconn_changed

Synonym of Gateway_changed.

TODO - does this even exist anymore?

Gateway_logged_in

Icecap has completely logged into the gateway.

*;gateway_logged_in;id=100;time=1000000000;network=ircnet;mypresence=mynick

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

Gateway_disconnected

The gateway has disconnected.

*;gateway_disconnected;id=100;time=1000000000;network=ircnet;mypresence=mynick

Gateway_connect_failed

The connection failed.

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

Presence_init

A user has joined the network

*;presence_init;id=100;time=1000000000;mypresence=mynick;presence=otheruser;network=ircnet

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

*;presence_init;id=100;time=1000000000;own;mypresence=mynick;presence=mynick;network=ircnet

Channel_presence_added

A user has joined the channel.

*;channel_presence_added;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;presence=otheruser

Presence_deinit

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

*;presence_deinit;id=100;time=1000000000;network=ircnet;mypresence=mynick;presence=otheruser

Presence_changed

A presence has changed.

*;presence_changed;id=100;time=1000000000;network=ircnet;mypresence=mynick;presence=mynick;name=mynick2

Optional Attributes

name - The user's new name.

Channel_presence_removed

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

reason - The quit message or the disconnect error
type - The type of removal [quit, kick], if omitted its a normal part

Channel_presence_mode_changed

A user's mode has changed.

*;channel_presence_mode_changed;id=1;time=1;network=ircnet;mypresence=mynick;channel=#channel;presence=somebody;irc_source_nick=ChanServ;add=op;irc_add=@;mode=op;irc_mode=@

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

Channel_init

A channel has been joined.

*;channel_init;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;init

Optional Attributes

init - TODO - what does init mean in this context?

Channel_deinit

A channel has been parted.

*;channel_deinit;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;deinit

Optional Attributes

deinit - TODO - what does deinit mean in this context?

Channel_changed

The channel has changed.

Optional Attributes

topic - The channel topic
topic_timestamp - The timestamp of when the topic was changed last
topic_set_by - The user who last changed the topic
initial_presences_added - After a channel join, a channel_changed is sent with this parameter to tell the client that all the users have been passed to the client and the client can now draw the userlist. TODO - is this still the case?
TODO - Are channel modes also sent this way?

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=

*;channel_changed;id=100;time=1000000000;network=ircnet;mypresence=mynick;channel=#channel;init;topic_timestamp=1000000000;topic_set_by=othernick

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

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

Optional Attributes

channel - The destination channel
no-autoreply - The message is from network services...?
presence - The sender of the message
address - The address of the sender

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.

Replies

TODO