irc: urls in Mozilla
Off the top of my head, here is the syntax of an irc: url, as implemented in ChatZilla. This syntax is derived from the draft RFC, "irc: URL scheme" by Mandar Mirashi, August 29, 1996.
If you find a discrepancy or notice a problem, please file a bug against ChatZilla. The code responsible for parsing irc: urls lives in a function called parseIRCURL() in extensions/irc/xul/content/static.js. The code that navigates to an irc: url is just below it, in a function called gotoIRCURL(). Please feel free to provide patches with your bug reports (it's just JavaScript, after all!)
Syntax
irc:[<connect-to>[(/<target>[<modifiers>][<query-string>]|<modifiers>)]]
<connect-to> can be either an IRC server name or an IRC network from ChatZilla's list (see the /networks command.) If <connect-to> contains any period ('.') characters or has a port (specified as hostname:port), it is interpreted as if it were a server name. Otherwise it is interpreted as a network name. The ,isserver modifier can be used to force <connect-to> to be interpreted as a server.
<target> can be a channel name or user nickname. As with ChatZilla's /join command, channels are assumed to start with the pound character ('#') unless a pound, ampersand ('&') or plus ('+') character is specifically included. The pound and ampersand characters MUST be escaped if they are provided. The plus character does not need to be escaped. The ,isnick modifier forces the target to be interpreted as a nickname instead of a channel.
<modifiers> are used to control how the irc: URL is interpreted. They should appear immediately before the <query-string> portion of the URL if one is included, or at the end if not. All modifiers start with a comma (',') character. Order of modifiers is not significant. The modifiers are as follows:
| ,isnick | Force <target> to be interpreted as a nickname. |
| ,isserver | Force <connect-to> to be interpreted as a server. |
| ,needkey | <target> requires a key from the user. <target> must be a channel for this modifier to make sense. |
| ,needpass | <connect-to> requires a password from the user. |
As is customary for http: urls, <query-string> is a question mark ('?') character followed by name value pairs, each separated by an ampersand ('&') character. Currently the following variables are supported:
| msg=<msg-text> | ChatZilla will send the text <msg-text> to the target after connecting. |
| key=<channel-key> | ChatZilla will use the key <channel-key> to join the channel. Implies ,needkey. |
| pass=<server-pass> | ChatZilla will use the password <server-pass> when signing on to the server. Implies ,needpass. |
| charset=<charset> | ChatZilla will use the character set <charset> to encode and decode messages to the channel. |
Sample irc: urls follow. All of these URLS will start ChatZilla if it is not started. If the URL points to a target the user is already attached to, ChatZilla will just switch to the appropriate view.
Basics
irc:
Starts ChatZilla and connects to any default urls.
irc://moznet/,
irc://moznet
Connect to the network named "moznet". Trailing forward slash ('/')
characters are not significant.
irc://irc.dal.net/
Connect to the server named "irc.dalnet.org". ChatZilla automatically
interprets "irc.dalnet.org" as a server (instead of a network name)
because it contains the period ('.') character.
irc://myserver/,isserver
Connect to the server named "myserver". The ,isserver
modifier forces "myserver" to be interpreted as a server.
irc://myserver:6667/
Connect to the server named "myserver" on port 6667. The
presence of a port in the <connect-to>
portion forces ChatZilla to interpret "myserver" as a server.
The ,isserver modifier is not required here.
Joining Channels
irc://moznet/%23mozillazine,
irc://moznet/mozillazine
Connect to the network named "moznet", and join the channel named
"#mozillazine". Notice that in the first URL, the # is encoded as
%23, while the second URL depends on ChatZilla to add this character.
irc://moznet/%26local
Connect to the network named "moznet", and join the channel named
"&local". The ampersand character is encoded as %26. Most irc servers
use the ampersand prefix to indicate that the channel is only visible
on the local server, and not to the rest of the IRC network to which
it is connected.
irc://somenet/+modeless
Connect to the network named "somenet", and join the modeless
channel named "+modeless". Not all servers support modeless channels
(those starting with the plus character.) Modeless channels have no
channel operators.
irc://moznet/chatzilla? msg=I%20am%20reading%20the%20irc%3A%20url%20document
Connect to the network named "moznet", and join the channel named
"#chatzilla". After joining, send the text "I am reading the
irc: url document" to the channel.
Querying Users
irc://moznet/mozbot,isnick
Connect to the network named "moznet", and open a private chat with
the user named "mozbot". There is no way to guarantee the identity of
mozbot (any user could be using the nickname), however, ChatZilla will
display WHO information for the user when the query view is
opened.
irc://moznet/mozbot,isnick?msg=uuid
Connect to the network named "moznet", and open a private chat with
the user named "mozbot", and send the private message "uuid".
irc://myserver/kilroy,isserver,isnick?msg=are%20you%20here%3F
Connect to the server named "myserver", and open a private chat with
the user named "kilroy", and send the private message
"are you here?".
Password Protected Servers, Keyed Channels
irc://moznet/sekret,needkey
Connect to the network named "moznet" and join the keyed channel named
"#sekret". The user will be prompted for the key before joining.
irc://myprivateserver/opers,isserver,needpass,needkey
Causes ChatZilla to prompt the user for a password used to connect to the
server named "myprivateserver", and once properly connected, ask for a
key for the channel "#opers". Notice that the ,isserver
modifier is used to force "myprivateserver" to be interpreted as a
server name. The order of the modifiers does not matter, as long as the
target name ("opers", in this example) comes first.