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

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

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>

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?

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

Config Set

Set some config values.

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

Optional Attributes

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

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

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

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

Channel_deinit

A channel has been parted.

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

Optional Attributes

Channel_changed

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=

*;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

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

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