Irc: urls in Mozilla

From Mibbit Wiki
Revision as of 17:01, 24 January 2009 by Havvy (Talk | contribs)

Jump to: navigation, search
RFC by by a Chatzilla developer; implemented in Mibbit.

Introduction

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 Applications&Component=Chatzilla 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/#mozillazine, 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 #, while the second URL depends on ChatZilla to add this character.

irc://moznet/&local
Connect to the network named "moznet", and join the channel named "&local". The ampersand character is encoded as &. 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.

am reading the irc: url document irc://moznet/chatzilla? msg=I am reading the irc: url document
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 you here?
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.

Robert Ginda

(By Robert Ginda, copywrited under the Creative Commons license.