# XMPP Protocol Initiation URI Syntax.

## Specifications

You can put an url in a web page to launch The Coccinella. Use a link: xmpp:matben@athlon.se This works presently only on Windows and on unix systems with the KDE environment:

- On Windows you need to launch Coccinella at least once with administrator privilegies to make it work.
- On KDE systems it writes a file ~/.kde/share/services/xmpp.protocol the first time Coccinella is launched, which is in turn used by KDE to communicate with The Coccinella. It seems that the desktop environment caches this info so a second login may be necessary for this to take effect. Not all web browsers seem to understand the KDE desktop but at least Konqueror does.

Note that the JID you supplu in the uri is not your own login JID but the target address for any action specified. The login uses the active profile in the application, not the JID in the uri!

The definition of the uri syntax is found in RFC 4622 from http://www.ietf.org/. If you use non US-ascii characters make sure the JID is encoded according to the reference above.

The other specifications can be found at

- http://www.jabber.org/jeps/jep-0147.html
- http://www.jabber.org/registrar/querytypes.html

You can also launch The Coccinella using the switch -uri: set argv `-uri xmpp:marilu@l4l.be?...` from the console or terminal.

The specification does only specify the syntax used, and is considered to be generic. The syntax is:

    xmppuri   = "xmpp" ":" hierxmpp [ "?" querycomp ] [ "#" fragment ]
    hierxmpp  = authpath / pathxmpp
    authpath  = "//" authxmpp [ "/" pathxmpp ]
    authxmpp  = nodeid "@" host
    pathxmpp  = [ nodeid "@" ] host [ "/" resid ]
    querycomp = querytype [ *pair ]
    pair      = ";" key "=" value

Note that the form with an `authpath` is not recomended. The following XMPP IRI/URI signals the processing application to authenticate as "guest@example.com" and to send a message to "support@example.com":

          xmpp://guest@example.com/support@example.com?message

By contrast, the following XMPP IRI/URI signals the processing application to authenticate as its configured default account and to send a message to "support@example.com":

          xmpp:support@example.com?message

In addition to the standards described above, there are currently a few additions which may change later. For any querytype you may specify the following key-value pairs:

    "ssl"           0|1
    "priority"      integer
    "invisible"     0|1
    "ip"            network domain name or number
    "sasl"          0|1

For the `join` type the following key-value pair has been added: (note that the JID you specify here must be room/nickname):

    "xmlns"         "whiteboard"

The server must support the disco method for service discovery, and the groupchat must be of the MUC type. All modern servers comply with this.

## Examples

### 01 Perform a Coccinella login ## xmpp:admin_user_node@example.com

Perform a Coccinella login using your current selected profile. This is not very useful since there is no query type. The JID you specify is supposed to be the target of your action, or query, but since this is missing, it just performs a standard login.

### 02 Prepare to send an instant message ## xmpp:contact_user_node@example.com

Prepare to send a "Hello World" message to mickey@example.com: xmpp:mickey@example.com?message;subject=Hi;body=Hello%20World.

Note that the same presumption of the current selected profile is providing the necessary authentication for this activity on the server. Valid in all cases below!

### 03 Prepare to start a chat session ## xmpp:contact_user_node@example.com

Prepare to start a chat session with mickey@example.com: xmpp:mickey@example.com?message;subject=Hi;body=Hello%20World;type=chat.

### 04 Enter a chat room ## xmpp:roomname@conference.example.com/nickname

Enter the sss chat room using nickname Terry: xmpp:sss@conference.example.com/Terry?join.

Note that the same presumption of the current selected profile is providing the necessary authentication for this activity on the server. Now, moreover, the server-side rule that the owner of a room has automatic access irrespective of password also is at play here because the 'sss' room requires a password.

### 05 Start a whiteboard session ## xmpp:roomname@conference.example.com/nickname

Start a whiteboard session in the sss chat room with nickname Terry: xmpp:sss@conference.example.com/Terry?join;xmlns=whiteboard.

Again, this works because Terry owns 'sss', or actually, the JID behind Terry owns the room. However, most rooms are not password protected, hence no password key is necessary.