View source for Irc: urls in Mozilla

{{notice|RFC by by a Chatzilla developer; implemented in Mibbit.}}

== Introduction==

Off the top of my head, here is the syntax of an <tt>irc:</tt> url, as implemented in ChatZilla. This syntax is derived from the draft RFC, "[http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt irc: URL scheme]" by Mandar Mirashi, August 29, 1996.

If you find a discrepancy or notice a problem, please [https://bugzilla.mozilla.org/enter_bug.cgi?product=Other Applications&Component=Chatzilla file a bug against ChatZilla]. The code responsible for parsing <tt>irc:</tt> urls lives in a function called [http://lxr.mozilla.org/mozilla/source/extensions/irc/xul/content/static.js#551 parseIRCURL()] in [http://lxr.mozilla.org/mozilla/source/extensions/irc/xul/content/static.js extensions/irc/xul/content/static.js]. The code that navigates to an irc: url is just below it, in a function called [http://lxr.mozilla.org/mozilla/source/extensions/irc/xul/content/static.js#670 gotoIRCURL()]. Please feel free to provide patches with your bug reports (it's just JavaScript, after all!)

== Syntax ==

<tt> irc:[&lt;'''connect-to'''&gt;[(/&lt;'''target'''&gt;[&lt;'''modifiers'''&gt;][&lt;'''query-string'''&gt;]|&lt;'''modifiers'''&gt;)]] </tt>

<tt>&lt;'''connect-to'''&gt;</tt> can be either an IRC server name or an IRC network from ChatZilla's list (see the '''/networks''' command.) If <tt>&lt;'''connect-to'''&gt;</tt> 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 <tt>,isserver</tt> modifier can be used to force <tt>&lt;'''connect-to'''&gt;</tt> to be interpreted as a server.

<tt>&lt;'''target'''&gt;</tt> 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 ('&amp;') 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 <tt>,isnick</tt> modifier forces the target to be interpreted as a nickname instead of a channel.

<tt>&lt;'''modifiers'''&gt;</tt> are used to control how the <tt>irc:</tt> URL is interpreted. They should appear immediately before the <tt>&lt;'''query-string'''&gt;</tt> 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:

{| width="75%" border="1" cellpadding="3"
| <tt>,isnick</tt>
| Force <tt>&lt;'''target'''&gt;</tt> to be interpreted as a nickname.
|-
| <tt>,isserver</tt>
| Force <tt>&lt;'''connect-to'''&gt;</tt> to be interpreted as a server.
|-
| <tt>,needkey</tt>
| <tt>&lt;'''target'''&gt;</tt> requires a key from the user. <tt>&lt;'''target'''&gt;</tt> must be a channel for this modifier to make sense.
|-
| <tt>,needpass</tt>
| <tt>&lt;'''connect-to'''&gt;</tt> requires a password from the user.
|}

As is customary for http: urls, <tt>&lt;'''query-string'''&gt;</tt> is a question mark ('?') character followed by name value pairs, each separated by an ampersand ('&amp;') character. Currently the following variables are supported:

{| width="75%" border="1" cellpadding="3"
| <tt>msg=&lt;msg-text&gt;</tt>
| ChatZilla will send the text <tt>&lt;'''msg-text'''&gt;</tt> to the target after connecting.
|-
| <tt>key=&lt;channel-key&gt;</tt>
| ChatZilla will use the key <tt>&lt;'''channel-key'''&gt;</tt> to join the channel. Implies <tt>,needkey</tt>.
|-
| <tt>pass=&lt;server-pass&gt;</tt>
| ChatZilla will use the password <tt>&lt;'''server-pass'''&gt;</tt> when signing on to the server. Implies <tt>,needpass</tt>.
|-
| <tt>charset=&lt;charset&gt;</tt>
| ChatZilla will use the character set <tt>&lt;'''charset'''&gt;</tt> to encode and decode messages to the channel.
|}

Sample <tt>irc:</tt> 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:<br /> Starts ChatZilla and connects to any default urls.

irc://moznet/, irc://moznet<br /> Connect to the network named "moznet". Trailing forward slash ('/') characters are not significant.

irc://irc.dal.net/<br /> 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'''<br /> Connect to the server named "myserver". The <tt>,isserver</tt> modifier forces "myserver" to be interpreted as a server.

'''irc://myserver:6667/'''<br /> Connect to the server named "myserver" on port 6667. The presence of a port in the <tt>&lt;'''connect-to'''&gt;</tt> portion forces ChatZilla to interpret "myserver" as a server. The <tt>,isserver</tt> modifier is not required here.

== Joining Channels ==

irc://moznet/#mozillazine, irc://moznet/mozillazine<br /> 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<br /> Connect to the network named "moznet", and join the channel named "&amp;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<br /> 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 am reading the irc: url document irc://moznet/chatzilla? msg=I am reading the irc: url document]<br /> 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<br /> 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 <tt>WHO</tt> information for the user when the query view is opened.

irc://moznet/mozbot,isnick?msg=uuid<br /> 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?'''<br /> 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<br /> 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'''<br /> 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 <tt>,isserver</tt> 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.

[mailto:rginda@netscape.com Robert Ginda]

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

[[Category:Specifications]]
[[Category:IRC]]
{{DEFAULTSORT:Irc: Urls In Mozilla}}