emacs-jabber/jabber.texi

\input texinfo          @c -*-texinfo-*-
@c %**start of header
@setfilename jabber.info
@settitle jabber.el manual 0.7
@c %**end of header

@dircategory Emacs
@direntry
* jabber.el: (jabber).             Emacs Jabber client
@end direntry

@copying
This manual is for jabber.el, version 0.7.

Copyright @copyright{} 2004, 2005 Magnus Henoch, Tom Berger.

@quotation
Permission is granted to make and distribute verbatim copies or
modified versions of this manual, provided the copyright notice and
this permission notice are preserved on all copies.
@end quotation
@end copying

@titlepage
@title jabber.el
@subtitle where Emacs and Jabber meet
@author by Magnus Henoch and Tom Berger

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top jabber.el manual

@insertcopying

@end ifnottex

@menu
* Introduction::                
* Basic operation::             
* Groupchat::                   
* Services::                    
* Personal information::        
* Useful features::             
* Message history::             
* Message events::              
* Roster import and export::    
* XMPP URIs::                   
* Customization::               
* Hacking and extending::       
* Protocol support::            
* Concept index::               
* Function index::              
* Variable index::              
@end menu


@node Introduction, Basic operation, Top, Top
@chapter Introduction

jabber.el is a Jabber client running under Emacs.  For more
information on the open-protocol instant messaging network Jabber,
please visit @uref{http://www.jabber.org}.

As a Jabber client, jabber.el is mostly just a face in the crowd,
except that it uses buffers where GUI clients have windows.  There is
a roster buffer, and to chat with someone you open a chat buffer, and
there are browse buffers (increasingly inexactly named) for
interaction with servers and services.  Then again, jabber.el delivers
excellent console performance and customizable hooks (if you have
speech synthesizer software, hook it up to your presence alerts).

jabber.el does not yet support GPG, sending and receiving
roster items, and various other things.

@menu
* Contact::                     
@end menu

@node Contact,  , Introduction, Introduction
@section Contact

jabber.el is developed by Tom Berger (e-mail
@email{object@@intellectronica.net}, JID @code{object@@jabber.org.uk}) and
Magnus Henoch (e-mail @email{mange@@freemail.hu}, JID
@code{legoscia@@jabber.cd.chalmers.se}).  There is a web page at
@uref{http://intellectronica.net/emacs-jabber/}, and a Sourceforge
project page at @uref{http://sourceforge.net/projects/emacs-jabber}.

@node Basic operation, Groupchat, Introduction, Top
@chapter Basic operation

This chapter is intended as an introduction to basic usage of
jabber.el.  If you have used Jabber before and are familiar with the
terminology, you might find it a bit too basic --- in that case, just
skim it, making sure to pick up the commands mentioned.

There are a handful of global keybindings for common commands.  They
start with @kbd{C-x C-j}, and you can get a list of them by typing
@kbd{C-x C-j C-h}.

@menu
* Connecting::                  
* Chatting::                    
* Presence::                    
* Presence subscription::       
* Roster buffer::               
@end menu

@node Connecting, Chatting, Basic operation, Basic operation
@section Connecting

@findex jabber-connect
@findex jabber-disconnect

@cindex Connecting
@cindex Registering an account

I'll assume that you have already successfully installed jabber.el; if
not, consult the @file{README} file.  Also, make sure you have
@code{(require 'jabber)} in your @file{.emacs}.

Now, type @kbd{M-x jabber-customize}.  This brings up a customize
buffer for jabber.el.  The most important variables to customize are
@code{jabber-username} and
@code{jabber-server}.@footnote{@xref{Connection settings}, for other
things you might have to change.}  Save your changes, and type
@kbd{M-x jabber-connect} to connect.

If you do not yet have a Jabber account, you can register one.  Enter
your desired username for @code{jabber-username} and the server you wish
to use for @code{jabber-server}, save, and type @kbd{C-u M-x
jabber-connect} or @kbd{C-u C-x C-j C-c}.  If the server supports
in-band registration, you will be presented with a registration form to
fill out and send.  There the username you chose will be prefilled.
Don't change it, otherwise jabber.el will be confused.

If you successfully connect, jabber.el will download your roster and
display it in a buffer called @code{*-jabber-*}.

By default, you will appear as ``online'' to your contacts.  To change
this to e.g. ``away'', type @kbd{M-x jabber-send-presence}.
@xref{Presence}, for more information.

To disconnect, type @kbd{M-x jabber-disconnect} or @kbd{C-x C-j C-d}.

@node Chatting, Presence, Connecting, Basic operation
@section Chatting

@cindex Chatting
@findex jabber-chat-with

There are several ways to open a chat buffer.  The shortest way is to
put point over the person you want to chat with in the roster display
and hit RET.

You can also use menus to access commands.  In the roster display, you
can access several menus through keystrokes or mouse clicks.  You can
bring one big menu up by pressing the second mouse button, or you can
bring up the ``chat menu'' by typing @kbd{C-c C-c}.  If you do the
latter while point is on a roster entry, that entry will be the
default value when you are asked for whom to chat with.

You can also use the function @code{jabber-chat-with}, which is what the
menu item is bound to.  This function is bound to @kbd{C-x C-j C-j} in
the global keymap.

Now, try opening a chat with someone.  A buffer named
@code{*-jabber-chat-:-@var{person}-*} will be created and selected.
Type your message at the end of the buffer, and hit @kbd{RET} to send
it.  To include a newline in your message, use @kbd{C-j}.

@node Presence, Presence subscription, Chatting, Basic operation
@section Presence

@cindex Presence
@cindex Sending presence
@findex jabber-send-presence
@findex jabber-send-default-presence
@vindex jabber-default-show
@vindex jabber-default-status
@vindex jabber-default-priority

``Presence'' is the Jabber term for letting other people know that you
are online, and additionally how ``available'' you are.  There are
three elements to presence: availability status (called ``show''),
status message, and priority.

Your show status may either be empty (meaning simply ``online''), or
one of @code{away}, @code{xa}, @code{dnd} and @code{chat}, meaning
``away'', ``extended away'' (i.e. away for an extended period), ``do
not disturb'', and ``free for chat'', respectively.  This information
is available to everyone subscribing to your presence, but technically
it does not restrict anyone's actions.  You can chat with people even
if you claim to be away.

The status message is a short text complementing your show status,
such as ``at home'', ``working'', ``phone'', ``playing games'' or
whatever you want.  It is sent to everyone subscribing to your
presence, but not all clients prominently display it to the user.

The priority is only interesting if you are running more than one
Jabber client at a time accessing the same account.  In that case,
messages sent to you without an indication of which client to send to
are sent to the client with the highest priority.

To set your presence, use the function @code{jabber-send-presence}.
It can be called both interactively and in Lisp code.  For the latter
case, use something like @code{(jabber-send-presence "away" "idle for
10 minutes" 10)}.

By default, jabber.el sets your presence when you connect.  If you
want it not to do that, remove @code{jabber-send-default-presence}
from @code{jabber-post-connect-hook}.  If you want to change the
presence that is sent, change the variables
@code{jabber-default-show}, @code{jabber-default-status} and
@code{jabber-default-priority}.

With jabber.el, you can set your presence remotely.  @xref{Ad-Hoc Commands}.

@node Presence subscription, Roster buffer, Presence, Basic operation
@section Presence subscription

@cindex Presence subscription
@cindex Subscribing to someone's presence
@findex jabber-send-subscription-request

Having permission to view the presence status of a person is called
@dfn{subscribing to his presence}.  Presence subscription between two
persons can be asymmetric.

When jabber.el receives a presence subscription request, it will
present it to you in an alert requiring immediate response, and offer
you to send a subscription request back to that person.

To request subscription to someone, type @kbd{M-x
jabber-send-subscription-request}.  You will be prompted for the JID
to send it to.  This command can also be accessed through the Roster
menu, by typing @kbd{C-c C-r} in the roster buffer.  After that, you
will probably want to give the contact a more readable name.  The
command for that is @code{jabber-roster-change}, which is also available
in the Roster menu.

@node Roster buffer,  , Presence subscription, Basic operation
@section The roster buffer

@cindex Roster buffer, basics
@cindex Menus
@cindex Key bindings
@findex jabber-display-roster

The roster buffer is called @code{*-jabber-*}.  It simply contains a
list of the contacts on your roster.

In the roster buffer, any command which requires a JID will default to
the JID under point when called.  These commands can be called through
either keyboard menus or mouse menus.  To open a menu with the mouse,
simply press the second mouse button over the JID in
question.@footnote{For some reason, mouse menus don't work in XEmacs.
Patches welcome.}  This will bring up a menu with all available
actions.  The keyboard menus are split into categories: Chat, Roster,
Information, MUC (Multi-User Chat, or groupchat) and Services, opened
by @kbd{C-c C-c}, @kbd{C-c C-r}, @kbd{C-c C-i}, @kbd{C-c C-m} and
@kbd{C-c C-s}, respectively.

A list of keybindings is displayed at the top of the roster buffer.
You can turn it off by setting @code{jabber-roster-show-bindings} to
nil.

You can call @code{jabber-display-roster} to redisplay your roster
according to changed preferences (@pxref{Customizing the roster
buffer}).  This will not refetch your roster from the server.
Refetching the roster is usually not needed, since updates are pushed
to clients automatically.

You can choose not to have the roster updated automatically on
presence changes (@pxref{Presence alerts}).  In that case, you need to
call @code{jabber-display-roster} manually.

@node Groupchat, Services, Basic operation, Top
@chapter Groupchat

@cindex Groupchat
@cindex MUC
@cindex Chatrooms

The groupchat menu can be accessed by typing @kbd{C-c C-m} in the
roster buffer.  You can also type the commands directly, as will be
shown here.

@findex jabber-groupchat-join
@cindex Joining a groupchat
@cindex Changing nickname
@cindex Nickname, changing 
To join a groupchat, type @kbd{M-x jabber-groupchat-join}.  You will
be prompted for the groupchat to join, and your nickname in the
groupchat.  This nickname doesn't need to have any correlation to your
JID; in fact, groupchats are usually (but not always) configured such
that only moderators can see your JID.  You can change your nickname
with @kbd{M-x jabber-muc-nick}.  @xref{Automation}, for setting default 
nicknames.

Groupchat messages will be displayed in a buffer called
@code{*-jabber-groupchat-:-@var{groupchat}-*}.  It works much like the
chat buffer.

@cindex Topic, MUC
@findex jabber-muc-set-topic
To change the topic of a groupchat, type @kbd{M-x jabber-muc-set-topic}.
The current topic is shown in the header line.

@findex jabber-groupchat-leave
To leave a groupchat, type @kbd{M-x jabber-groupchat-leave}.

@findex jabber-groupchat-get-config
If you are the owner of a groupchat, you can change its configuration
by typing @kbd{M-x jabber-groupchat-get-config}.  A configuration form
will be rendered in new buffer.

@findex jabber-muc-names
To see which people are in a groupchat, type @kbd{M-x
jabber-muc-names}.  This gives a list of nicknames, ``roles'',
``affiliations'', and possibly JIDs.  @xref{MUC Administration}, for
the meaning of roles and affiliations.


@menu
* Automation::                  
* Invitations::                 
* Private messages::            
* MUC Administration::          
@end menu

@node Automation, Invitations, Groupchat, Groupchat
@section Automation

@vindex jabber-muc-default-nicknames
@vindex jabber-muc-autojoin
@findex jabber-muc-autojoin
@cindex Default MUC nickname
@cindex Autojoin chat rooms

You can select a default nickname by setting @code{jabber-nickname}.
Additionally, you can set different nicknames for different groups, by
customizing @code{jabber-muc-default-nicknames}.  There you specify
the JID of the group, and your preferred nickname.

If you want to automatically join certain rooms when connecting, you
can set @code{jabber-muc-autojoin} to a list containing the JIDs of
the rooms you want to enter.  To disable this feature, remove
@code{jabber-muc-autojoin} from @code{jabber-post-connect-hook}.

@node Invitations, Private messages, Automation, Groupchat
@section Invitations

@cindex Invitations
@findex jabber-muc-invite

You can invite someone to a groupchat with @kbd{M-x jabber-muc-invite}
(also available in the MUC menu).  Pay attention to the order of the
arguments --- as both users and rooms are just JIDs, it is technically
possible to invite a room to a user, but that's probably not what you
want.

When you receive an invitation, it appears in the chat buffer along
with two buttons, ``Accept'' and ``Decline''.  Pressing ``Accept''
enters the room, as you would expect.  Pressing ``Decline'' gives you
an opportunity to state the reason why you're not joining.

@node Private messages, MUC Administration, Invitations, Groupchat
@section Private messages

@cindex Private MUC messages
@findex jabber-muc-private

You can open a private chat with a participant in a chat room with
@kbd{M-x jabber-muc-private} (or by using the MUC menu).  This creates
a buffer with the name
@code{*-jabber-muc-priv-@var{group}-@var{nickname}-*} (customizable by
@code{jabber-muc-private-buffer-format}), which behaves mostly like an
ordinary chat buffer.  This buffer will also be created if someone
sends a private message to you.

Private MUC messages use the same alerts as normal chat messages.
@xref{Message alerts}.

@node MUC Administration,  , Private messages, Groupchat
@section Administration

Administration of a MUC room mostly consists of managing roles and
affiliations.  Roles are temporary, and apply until the user leaves the
room.  Affiliations are permanent, and based on JIDs.

@subsection Roles

@findex jabber-muc-set-role
@cindex Kicking, MUC
@cindex Voice, MUC
@cindex Moderator, MUC
@cindex Roles, MUC
If you have moderator privileges, you can change the role of a
participant with @kbd{M-x jabber-muc-set-role}.  Kicking means setting
the role to ``none''.  Granting and revoking voice are ``participant''
and ``visitor'', respectively.  ``moderator'' gives moderator
privileges, obviously.

The possible roles are:

@table @samp
@item moderator
Has voice, can change other people's roles.

@item participant
Has voice.

@item visitor
Doesn't have voice (can't send messages to everyone, but can send
private messages)

@item none
Not in room.
@end table

@subsection Affiliations

@findex jabber-muc-set-affiliation
@cindex Affiliations, MUC
@cindex Banning, MUC
If you have admin or owner privileges, you can change the affiliation of
a user with @kbd{M-x jabber-muc-set-affiliation}.  Affiliation is
persistent, and based on JIDs.  Depending of your affiliation and the
MUC implementation, you might not be allowed to perform all kinds of
changes, and maybe not in one step.

Affiliations are:

@table @samp
@item owner
Can destroy room, appoint admins, make people members, ban people.

@item admin
Can make people members or ban people.

@item member
Can enter the room, and has voice by default.

@item none
Rights depend on room configuration.  The room might be members-only, or
grant voice only to members.

@item outcast
Banned from the room
@end table



@node Services, Personal information, Groupchat, Top
@chapter Services

@cindex Browse buffers

Not every Jabber entity is a physical person.  There are many
automatic entities, called servers, services, components, agents,
transports and other names.  The use of these is described here.

The functions described in this chapter use @dfn{browse buffers}.
Browse buffers are named @code{*-jabber-browse-:-@var{service}-*},
sometimes with a numerical suffix.  The different menus have the same
keybindings as in the roster buffer, and if you call a function
operating on a JID while point is over a JID, that JID will be the
default value, so you don't have to type it or copy it yourself.

@menu
* Service discovery and browsing::  
* Registering::                 
* Searching::                   
* Ad-Hoc Commands::             
@end menu

@node Service discovery and browsing, Registering, Services, Services
@section Service discovery and browsing

@cindex Service discovery
@cindex Browsing
@findex jabber-get-browse
@findex jabber-get-disco-items
@findex jabber-get-disco-info

To find services you want to use, you need to discover them first.
This can be done with either service discovery or browsing.  Service
discovery is the newer and preferred protocol, while browsing is still
used by much software.  The use of both is very similar.

The most common use of service discovery is to browse your home
server, to see what services are provided locally.  Note, however,
that this is no restriction; you can use services from all over the
network.

For service discovery there are two commands,
@code{jabber-get-disco-items} and @code{jabber-get-disco-info},
depending on whether you want information about that specific JID or
about services related to it, respectively.  To start browsing, type
@kbd{M-x jabber-get-browse} and enter the JID you want to browse.

These commands can be accessed from the Info menu, which is opened by
typing @kbd{C-c C-i}.

If you think that the interface to service discovery is awkward and
should be replaced with something better, you are completely right.

@node Registering, Searching, Service discovery and browsing, Services
@section Registering

@cindex Registration
@cindex Cancelling registration
@cindex Changing password
@cindex Gateway registration
@cindex Password change
@cindex Account removal
@cindex Removing an account
@findex jabber-get-register

Some services, in particular user directories and gateways to legacy
IM systems, require registration.  To register with such a service,
either type @kbd{M-x jabber-get-register} or select it from the
Service menu, which is opened by typing @kbd{C-c C-s}.  You have to
know the service's JID, possibly from service discovery.
(@pxref{Service discovery and browsing})

This is also the way to change your registration details, e.g. your
password --- just ask to register with that service again.  To change
the password of your Jabber account, ask to register with your Jabber
server.

Please note that any passwords sent in this way will be sent in
cleartext to your Jabber server, unless you have enabled SSL encryption
(@pxref{Connection settings}), and possibly sent in cleartext from your
server to the server hosting the service.

jabber.el will then request a registration form from that service.  If
for some reason the service does not answer (maybe network problems,
or some services neither support registration nor report errors about
that) that will be the last thing you saw about it.  jabber.el will
not report timeout errors, but rather simply wait until you shut it
down.

Once the response arrives, the form will be rendered in a browse
buffer.  Just fill out the fields, and hit Submit.  You will receive
confirmation of your registration in the echo area.

To cancel an existing registration (and also for cancelling your
Jabber account, if you sent a registration request to your server),
hit Cancel.  The unregistration will be confirmed in the echo area.

@node Searching, Ad-Hoc Commands, Registering, Services
@section Searching

@cindex Searching
@findex jabber-get-search

Some services, notably user directories and gateways to legacy IM
systems, allow searching.  Searching in Jabber generally means
searching for someone's JID, but the protocol is general enough to
support most databases.

To search a service, either type @kbd{M-x jabber-get-search} or select
it from the Service menu, which is opened by typing @kbd{C-c C-s}.

Just like with registration, this command sends a request for a search
form, and displays it if and when the response arrives.  Enter your
search and submit it.  Search results will be displayed in a different
browse buffer.

@node Ad-Hoc Commands,  , Searching, Services
@section Ad-Hoc Commands

@cindex Ad-Hoc Commands
@findex jabber-ahc-get-list
@findex jabber-ahc-execute-command

jabber.el supports a subset of JEP-0050, the standard for Ad-Hoc
Commands.  As the name implies, this can be used for just about
anything.  It has been used for remote-controlling clients (e.g. Psi),
and administering services (e.g. PyMSNt).

Currently, jabber.el uses ad-hoc commands for setting presence remotely.
If you realize that you forgot to set your client to ``away'' with a low
priority, you can do it remotely.@footnote{Most Jabber servers also
support kicking a client off the net by logging in with another client
with exactly the same resource.}

The commands for executing ad-hoc commands are available under the
Service menu, which is opened by typing @kbd{C-c C-s}.

To find which commands are available, run ``Request command-list''
(@code{jabber-ahc-get-list}).@footnote{This is the same thing as a
disco items request to the node
@code{http://jabber.org/protocol/commands}.}

To run a command from the list, put point over it and run ``Execute
command'' (@code{jabber-ahc-execute-command}), accepting the defaults
for JID and node.  (If you already know those, you could of course
enter them yourself)  The form you get should hopefully be
self-explanatory.

@node Personal information, Useful features, Services, Top
@chapter Personal information

@cindex vCard
@cindex Personal information
@findex jabber-vcard-get
@findex jabber-vcard-edit

The Jabber way of handling personal information (name, addresses,
phone numbers, etc) is ``vCards'' encoded in XML.  You can get
information about a user by running @kbd{M-x jabber-vcard-get}, and
you can edit your own information by running @kbd{M-x
jabber-vcard-edit}.

The form for editing your information can be slightly confusing ---
you are allowed to enter any number of addresses, phone numbers and
e-mail addresses, each of which has a set of orthogonal properties.
You can add and remove items with the [INS] and [DEL] buttons,
respectively.

@node Useful features, Message history, Personal information, Top
@chapter Useful features

jabber.el includes a number of features meant to improve the user
interface and do other useful things.

@menu
* Autoaway::                    
* Modeline status::             
* Keepalive::                   
* Tracking activity::           
* Watch buddies::               
* Spell checking::              
@end menu

@node Autoaway, Modeline status, Useful features, Useful features
@section Autoaway

@cindex autoaway
@cindex idle
@cindex xprintidle
@vindex jabber-autoaway-method

It is possible to automatically set your status to ``away'' when you
haven't used your computer for a while.  This lets your contacts know
that you might not answer immediately.

To activate this feature, add @code{jabber-autoaway-start} to
@code{jabber-post-connect-hook}, e.g:
@example
(add-hook 'jabber-post-connect-hook 'jabber-autoaway-start)
@end example

There are different methods to find how long you have been ``idle''.
The method to use is specified by @code{jabber-autoaway-method}.  The
value of this variable should be a function that returns the number of
seconds you have been idle.  Three functions are provided.

If you are running Emacs 22 and thus have the @code{current-idle-time}
function, it is used by default.  Note that this method only measures
the time since you last interacted with Emacs, and thus disregards
activity in other programs.

If you are using the X Window System, you can use the
@uref{http://www.dtek.chalmers.se/~henoch/text/xprintidle.html,
xprintidle} program.  Make sure that @code{jabber-xprintidle-program} is
set to the correct file name.  This uses the same method as XScreensaver
to find your idle time.

If you are using Emacs on a GNU/Linux terminal, the function
@code{jabber-termatime-get-idle-time} is used by default.

@node Modeline status, Keepalive, Autoaway, Useful features
@section Modeline status

@cindex Modeline
@findex jabber-mode-line-mode
@vindex jabber-mode-line-mode
@vindex jabber-mode-line-compact

By typing @kbd{M-x jabber-mode-line-mode} you toggle display of some
status in mode lines.  The information is your own presence status,
and some numbers showing the status of your roster contacts.  By
default, there are three numbers, for ``online'' (chatty and online),
``away'' (away, extended away and do not disturb) and offline
contacts.

If you set @code{jabber-mode-line-compact} to nil, you get a complete
breakdown of presence status.  That gives you six numbers indicating
the number of chatty, online, away, extended away, dnd, and offline
contacts, respectively.

@node Keepalive, Tracking activity, Modeline status, Useful features
@section Keepalive

@cindex Keepalive
@cindex Detecting lost connections
@findex jabber-keepalive-start
@findex jabber-keepalive-stop
@vindex jabber-keepalive-interval
@vindex jabber-keepalive-timeout

Sometimes network connections are lost without you noticing.  This is
especially true with Jabber, as it is quite reasonable to keep the
connection open for a long time without either sending or receiving
any data.

If you want to detect a lost connection earlier, you can use the
keepalive functions.  Type @kbd{M-x jabber-keepalive-start} to start
it, and @kbd{M-x jabber-keepalive-stop} to stop it.

These functions work by asking your server for the time once in a
while (by default every ten minutes), and considering the connection
lost if the server doesn't answer within reasonable time (by default
20 seconds).

You can customize the interval and the timeout with the variables
@code{jabber-keepalive-interval} and @code{jabber-keepalive-timeout},
respectively.

@node Tracking activity, Watch buddies, Keepalive, Useful features
@section Tracking activity

@cindex Activity
@findex jabber-activity-mode
@vindex jabber-activity-make-strings
@vindex jabber-activity-query-unread
@vindex jabber-activity-count-in-title
@vindex jabber-activity-count-in-title-format

When you're working on something important you might want to delay
responding to incoming messages.  However, when you're done working,
will you remember them?  If you're anything like me, you'll have a lot
of buffers in your Emacs session, and a jabber chat buffer can easily
get lost.

When you type @kbd{M-x jabber-activity-mode} Emacs starts keeping
track of the buddies which have messaged you since last you visited
their buffer, and will display them in mode line.  As soon as you
visit their buffer they disappear from the mode line, indicating that
you've read their message.

If your mode line fills over because of these notifications, you can
customize @code{jabber-activity-make-strings} to shorten them to the
shortest possibly unambiguous form.

If you try to exit Emacs while you still have unread messages, you
will be notified and asked about this.  If you don't like that, set
@code{jabber-activity-query-unread} to nil.

If you want to display the number of unread buffers in the frame title,
set @code{jabber-activity-count-in-title} to t.  The format of the
number can be changed through
@code{jabber-activity-count-in-title-format}.

For complete customizability, write a hook function for
@code{jabber-activity-update-hook}.  From that function, you can take
action based on @code{jabber-activity-jids},
@code{jabber-activity-mode-string}, and
@code{jabber-activity-count-string}.

@node Watch buddies, Spell checking, Tracking activity, Useful features
@section Watch buddies

@cindex Watch
@cindex Online notifications
@findex jabber-watch-add
@findex jabber-watch-remove

Sometimes you might be waiting for a certain person to come online,
and you don't want that occasion to get lost in the noise.  To get an
obtrusive message when that happens, type @kbd{M-x jabber-watch-add}
and select the person in question.  You can enter a comment, to
remember why you added the watch.

You will get a message whenever that person goes from offline to
online.  jabber.el will remember this for the rest of your Emacs
session (it's not saved to disk, though), but if you want to get rid
of it, type @kbd{M-x jabber-watch-remove}.

@node Spell checking,  , Watch buddies, Useful features
@section Spell checking

@cindex flyspell
@cindex Spell checking

You can activate spell checking in a chat buffer with @kbd{M-x
flyspell-mode}.  It will check only what you are currently writing, not
what you receive or what you have already sent.  You may want to add
@code{flyspell-mode} to @code{jabber-chat-mode-hook}.

For more information about Emacs spell checking, @xref{Spelling, ,
Checking and Correcting Spelling, emacs, GNU Emacs Manual}.

@node Message history, Message events, Useful features, Top
@chapter Message history

@cindex History
@cindex Backlog
@cindex Rotation
@vindex jabber-history-enabled
@vindex jabber-global-history-filename
@vindex jabber-use-global-history
@vindex jabber-history-dir
@vindex jabber-history-enable-rotation
@vindex jabber-history-size-limit
@vindex jabber-backlog-number
@vindex jabber-backlog-days

If you want a record of messages sent and received, set
@code{jabber-history-enabled} to t.  By default all messages to will
be saved to a global history file specified by
@code{jabber-global-history-filename}
(@file{~/.jabber_global_message_log} by default).  If you prefer to
store your chats' history in per-contact files, you can set the
@code{jabber-use-global-history} variable to @code{nil}.  When using
per-contact history, files are named by the contact JID and saved
under the directory specified by the variable
@code{jabber-history-dir} (default is @file{~/.emacs-jabber}).

There is no facility for reading old messages yet, but just reading
the file as text should be enough for many purposes.

When you open a new chat buffer and have entries in your history file,
the last few messages you recently exchanged with the contact in
question will be inserted.  You can control how many messages with
@code{jabber-backlog-number} (by default 10), and how old messages
with @code{jabber-backlog-days} (by default 3 days).

If you worry about your history file(s) size, you can enable history
rotation feature by setting the variable
@code{jabber-history-enable-rotation} to @code{t} (default is
@code{nil}).  This feature ``rotates'' your history files according to
the following rule: When @code{jabber-history-size-limit} (in
kilobytes) is reached, the history file is renamed to
<history-file>-<number>, where <number> is 1 or the smallest number
after the last rotation.  For example, suppose you set the
@code{jabber-history-size-limit} variable to 512 and you chat with
your buddy foo@@jabber.server using the per-contact strategy to store
history files.  So, when the history file (@file{foo@@jabber-server})
reaches 512K bytes, it will be renamed to @file{foo@@jabber-server-1}
and @file{foo@@jabber-server} will be set empty. Next time
@file{foo@@jabber-server} grows to 512K bytes, it will be saved as
@file{foo@@jabber-server-2} and so on.  Although the example was
presented with the per-contact history file strategy, history rotation
works for both per-contact and global history logging strategies.


@node Message events, Roster import and export, Message history, Top
@chapter Message events

@cindex Composing
@cindex Delivered
@cindex Displayed
@vindex jabber-events-request-these
@vindex jabber-events-confirm-delivered
@vindex jabber-events-confirm-displayed
@vindex jabber-events-confirm-composing

In the status line of the chat buffer, you can sometimes see
notifications about the progress of the message you just sent.  These
states are possible:

@itemize @bullet
@item
Delivered to offline storage (the user will receive it on next logon)

@item
Delivered to user's client (but not necessarily displayed)

@item
Displayed to user

@item
User is composing a reply

@end itemize

The first state is only reported by servers; the other three are
reported by clients.  jabber.el can report all three of them, and can
display all four; not all clients support all states, though.

If you don't want jabber.el to send out this information about you, set
the variables @code{jabber-events-confirm-delivered},
@code{jabber-events-confirm-displayed}, and/or
@code{jabber-events-confirm-composing} to nil.  You can make jabber.el
not to request such information by customizing
@code{jabber-events-request-these}.

@node Roster import and export, XMPP URIs, Message events, Top
@chapter Roster import and export

@findex jabber-export-roster
@findex jabber-import-roster
@cindex Export roster
@cindex Import roster

Your roster is saved on the Jabber server, and usually not in the
client.  However, you might want to save the roster to a file anyway.
The most common reason for this is probably to copy it to another
account.

To export your roster to a file, type @kbd{M-x jabber-export-roster}.
A buffer will appear in which you can edit the data to be exported.
Changes done in that buffer will not affect your real roster.

To import your roster from a file, type @kbd{M-x jabber-import-roster}.
You will be able to edit the data before importing it.  Items not in the
roster will be added; items in the roster will be modified to match
imported data.  Subscriptions will be updated.

The format of the roster files is the XML used by roster pushes in the
XMPP protocol, in UTF-8 encoding.

@node XMPP URIs, Customization, Roster import and export, Top
@chapter XMPP URIs

@cindex URIs
@cindex URLs
@cindex links
@cindex xmpp: links
@cindex Mozilla integration
@cindex web browser integration
@cindex browser integration
@findex jabber-handle-uri

Many web page authors use links starting with @samp{xmpp:} for JIDs.
Your web browser could be made to pass such links to jabber.el, so that
such links are actually useful and not just decoration.  How to do that
depends on your operating system and web browser.

@section Mozilla and Unix

If you use a Mozilla-based web browser on a Unix-like operating system,
follow these steps.

@enumerate
@item
Make sure you are running the Emacs server.  @xref{Emacs Server, , Using
Emacs as a Server, emacs, GNU Emacs Manual}.

@item
Note the path of the @file{xmppuri.sh} file in the jabber.el
distribution, and make sure it is executable.

@item
Set the Mozilla preference @samp{network.protocol-handler.app.xmpp} to
the path of @file{xmppuri.sh}.  There are two ways to do this:

@itemize
@item
Go to the URL @samp{about:config}, right-click in the list, choose ``New
string'', and enter @samp{network.protocol-handler.app.xmpp} and the
path in the following dialogs.

@item
Open or create the file @file{user.js} in your Mozilla profile directory
(in the same directory as @file{prefs.js}), and add the following line:

@example
user_pref("network.protocol-handler.app.xmpp", "@var{/path/to}/xmppuri.sh");
@end example

Restart Mozilla for this change to take effect.
@end itemize
@end enumerate

@section Other systems

If you know how to pass an XMPP URI from your browser to the function
@code{jabber-handle-uri}, your contribution for this section would be
appreciated.

@node Customization, Hacking and extending, XMPP URIs, Top
@chapter Customization

@findex jabber-customize
@cindex Customization

jabber.el is intended to be customizable for many tastes.  After all,
this is Emacs.  To open a customization buffer for jabber.el, type
@kbd{M-x jabber-customize}.

@menu
* Account settings::            
* Connection settings::         
* Miscellaneous settings::      
* Customizing the roster buffer::  
* Customizing the chat buffer::  
* Customizing alerts::          
* Hooks::                       
* Debug options::               
@end menu

@node Account settings, Connection settings, Customization, Customization
@section Account settings

@vindex jabber-username
@vindex jabber-server
@vindex jabber-password
@vindex jabber-resource
@vindex jabber-default-priority
@vindex jabber-nickname
@cindex Username
@cindex Resource

@code{jabber-username} is the username part of your JID.

@code{jabber-server} is the JID of your server, i.e. the hostname part
of your JID.  This is usually, but not necessarily, the same as the
hostname of the server.

@code{jabber-password} is your password.  You have the option to set
it here, in which case it will be stored in cleartext in your
@file{.emacs} file.  If this is set to @code{nil}, you will be prompted for
your password every time you connect.

@code{jabber-resource} is the resource you want to log in under.  This
only matters if you are connected to the same account from different
clients or different computers, since each connection must have a
unique resource.  You might want to set this to your hostname.

@code{jabber-default-priority} is the default priority sent with your
presence.  Regardless of what you have here, you can change your
priority during a session with @code{jabber-send-presence}.
@xref{Presence}, for more information on priority.

@code{jabber-nickname} is your default nickname for groupchats.

@node Connection settings, Miscellaneous settings, Account settings, Customization
@section Connection settings

@vindex jabber-network-server
@vindex jabber-port
@vindex jabber-connection-type
@vindex jabber-connection-ssl-program
@cindex Connection settings
@cindex Network settings
@cindex SSL
@cindex TLS
@cindex STARTTLS
@cindex SRV records

@code{jabber-network-server} is the hostname or IP address of your
server.  If it is set to @code{nil}, jabber.el will use the name in
@code{jabber-server}.

@code{jabber-port} is the TCP port of the server to connect to.  If
@code{nil}, the default port is selected based on the chosen
connection method.

If both @code{jabber-network-server} and @code{jabber-port} are nil, and
a sufficiently modern @code{dns.el} is available, jabber.el will use SRV
records to find the right hostname and port.

@code{jabber-connection-type} specifies what kind of connection to
use.  @code{network} means normal unencrypted network connection
(usually on port 5222), and @code{ssl} means encrypted connection
through GnuTLS or OpenSSL (port 5223), while @code{starttls} will
initiate an unencrypted connection and switch to encrypted if offered
by the server.  You can change the settings of the encryption program
through @kbd{M-x customize-group RET tls}, @kbd{M-x customize-group RET starttls}
or @kbd{M-x customize-group RET ssl}, respectively.

@cindex GnuTLS
@cindex OpenSSL
By default, GnuTLS will be used if the @code{tls} library is available,
and if that fails, OpenSSL will be used if the @code{ssl} library is
available.  You can force the use of either program by setting
@code{jabber-connection-ssl-program} to @code{gnutls} or @code{openssl},
respectively.  If you use @code{starttls} the library with the same name is
required, and it depends on the GnuTLS command line client.

@node Miscellaneous settings, Customizing the roster buffer, Connection settings, Customization
@section Miscellaneous settings

@findex jabber-menu
@cindex Menus

If you want a Jabber menu on the menu bar with some common commands,
type @kbd{M-x jabber-menu}.  You can remove it again with @kbd{C-u M-x
jabber-menu}.  Unfortunately, this cannot be changed through Customize
settings, so you need to add @code{(jabber-menu)} to your @file{.emacs}
to enable it permanently.

@node Customizing the roster buffer, Customizing the chat buffer, Miscellaneous settings, Customization
@section Customizing the roster buffer

@vindex jabber-roster-sort-functions
@vindex jabber-sort-order
@vindex jabber-show-resources
@vindex jabber-roster-line-format
@vindex jabber-resource-line-format
@vindex jabber-roster-buffer
@vindex jabber-roster-show-bindings
@cindex Roster buffer, customizing

@cindex Sorting the roster
@code{jabber-roster-sort-functions} controls how roster items are
sorted.  By default, contacts are sorted first by presence, and then
alphabetically by displayed name.

@code{jabber-sort-order} controls how roster items are sorted by
presence.  It is a list containing strings corresponding to show
status (@pxref{Presence}) or @code{nil}, which represents offline.

@code{jabber-show-resources} controls when your contacts' resources
are shown in the roster buffer.  The default is to show resources when
a contact has more than one connected resource.

@code{jabber-roster-line-format} specifies how the entry for each
contact looks.  It is a string where some characters are special if
preceded by a percent sign:

@table @code
@item %c
"*" if the contact is connected, or " " if not
@item %n
Nickname of contact, or JID if no nickname
@item %j
Bare JID of contact (without resource)
@item %r
Highest-priority resource of contact
@item %s
Availability of contact as string ("Online", "Away" etc)
@item %S
Status string specified by contact
@end table

@code{jabber-resource-line-format} is nearly identical, except that
the values correspond to the values of the resource in question, and
that the @code{%p} escape is available, which inserts the priority of
the resource.

@code{jabber-roster-buffer} specifies the name of the roster buffer.
If you change this, the new name will be used the next time you
connect.

@code{jabber-roster-show-bindings} controls whether to show a list of
keybindings at the top of the roster buffer.  You need to run @kbd{M-x
jabber-display-roster} after changing this variable to update the display.

@node Customizing the chat buffer, Customizing alerts, Customizing the roster buffer, Customization
@section Customizing the chat buffer

@cindex Chat buffer
@cindex Timestamps
@cindex Faces, chat buffer

You can customize the look of the prompts in the chat buffer.  There
are separate settings for local (i.e. your own messages) and foreign
prompts.

@vindex jabber-chat-text-local
@vindex jabber-chat-text-foreign
@code{jabber-chat-text-local} and @code{jabber-chat-text-foreign}
determine the faces used for chat messages.

@vindex jabber-chat-prompt-local
@vindex jabber-chat-prompt-foreign
@code{jabber-chat-prompt-local} and @code{jabber-chat-prompt-foreign}
determine the faces used for the prompts.

@vindex jabber-chat-local-prompt-format
@vindex jabber-chat-foreign-prompt-format
@code{jabber-chat-local-prompt-format} and
@code{jabber-chat-foreign-prompt-format} determine what text is
displayed in the prompts.  They are format strings, with the following
special sequences defined:

@table @code
@item %t
The time when the message was sent or received
@item %n
The nickname of the user.  For the foreign prompt, this is the name of
the contact in the roster, or the JID if no name set.  For the local
prompt, this is the username part of your JID.
@item %j
The bare JID of the user
@end table

@vindex jabber-chat-time-format
@code{jabber-chat-time-format} defines how @code{%t} shows time.  Its
format is identical to that passed to @code{format-time-string}.
@xref{Time Conversion, , Time Conversion, elisp, GNU Emacs Lisp
Reference Manual}.

@vindex jabber-chat-delayed-time-format
@code{jabber-chat-delayed-time-format} is used instead of
@code{jabber-chat-time-format} for delayed messages (messages sent while
you were offline, or fetched from history).  This way you can have short
timestamps everywhere except where you need long ones.  You can always
see the complete timestamp in a tooltip by hovering over the prompt with
the mouse.

@vindex jabber-print-rare-time
@vindex jabber-rare-time-format
@vindex jabber-chat-text-localBy default, timestamps are printed in the chat buffer every hour (at
``rare'' times).  This can be toggled with
@code{jabber-print-rare-time}.  You can customize the displayed time by
setting @code{jabber-rare-time-format}.  Rare timestamps will be printed
whenever time formatted by that format string would change.

@vindex jabber-chat-header-line-format
@vindex jabber-muc-header-line-format
You can also customize the header line of chat buffers, by modifying
the variable @code{jabber-chat-header-line-format}.  The format of
that variable is the same as that of @code{mode-line-format} and
@code{header-line-format}.  @xref{Mode Line Format, , Mode-Line
Format, elisp, GNU Emacs Lisp Reference Manual}.  For MUC buffers,
@code{jabber-muc-header-line-format} is used instead.

@vindex jabber-chat-fill-long-lines
@cindex Filling long lines in chat buffer
The variable @code{jabber-chat-fill-long-lines} controls whether long
lines in the chat buffer are filled.

@node Customizing alerts, Hooks, Customizing the chat buffer, Customization
@section Customizing alerts

@cindex Alert hooks
@findex define-jabber-alert

When an event happens (currently including presence changes, incoming
messages, and completed queries) you will usually want to be
notified.  Since tastes in this area vary wildly, these alerts are
implemented as hooks, so you can choose which ones you want, or write
your own if none fit.

Actually, if you don't want to write your own, stop reading this
section and just read @ref{Standard alerts}.

Many kinds of alerts consist in displaying a text message through a
certain mechanism.  This text message is provided by a function which
you can rewrite or replace.  If this function returns @code{nil}, no
message is displayed, and non-textual alerts refrain from action.

If you want to write alert hooks that do nothing except displaying the
supplied message in some way, use the macro
@code{define-jabber-alert}.  For example, if @var{foo} is a function
that takes a string as an argument, write
@example
(define-jabber-alert foo
  "Display a message in a fooish way"
  'foo)
@end example
and all details will be taken care of for you.

The hooks take different arguments depending on category.  However,
they all have in common that the last argument is the result of the
message function.  The message function for each category takes the
same arguments as the corresponding hooks, except for that last
argument.

Alert hook contributions are very welcome.  You can send them to the
mailing list, or to the Sourceforge patch tracker.

Alert hooks are meant for optional UI things, that are subject to
varying user tastes, and that can be toggled by simply adding or
removing the function from/to the hook.  For other things, there are
corresponding general hooks, that are defvars instead of defcustoms, and
that are to be managed by Lisp code.  They have the same name as the
alert hooks minus the @code{-alert} part,
i.e. @code{jabber-message-hooks} vs @code{jabber-alert-message-hooks},
etc.

@menu
* Standard alerts::             
* Presence alerts::             
* Message alerts::              
* MUC alerts::                  
* Info alerts::                 
@end menu

@node Standard alerts, Presence alerts, Customizing alerts, Customizing alerts
@subsection Standard alerts

@cindex Alerts
@cindex Scroll

Eight alerts are already written for all four alert categories.  These
all obey the result from the corresponding message function.

The @code{beep} alerts simply sound the terminal bell by calling
@code{ding}.  They are disabled by default.

The @code{echo} alerts display a message in the echo area by calling
@code{message}.  They are enabled by default.

The @code{switch} alerts switch to the buffer where the event occurred
(chat buffer for incoming messages, roster buffer for presence
changes, browse buffer for completed queries).  They are disabled by
default.  Take care when using them, as they may interrupt your
editing.

The @code{display} alerts display but do not select the buffer in
question, using the function @code{display-buffer}.  @xref{Choosing
Window, , Choosing a Window for Display, elisp, GNU Emacs Lisp
Reference Manual}, for information about customizing its behaviour.
This is enabled by default for info requests.

The @code{wave} alerts play a sound file by calling
@code{play-sound-file}.  No sound files are provided.  To use this,
enter the names of the sound files in
@code{jabber-alert-message-wave}, @code{jabber-alert-presence-wave}
and @code{jabber-alert-info-wave}, respectively.

The @code{screen} alerts send a message through the Screen terminal
manager (see @uref{http://www.gnu.org/software/screen/}).  They do no
harm if called when you don't use Screen.

The @code{ratpoison} alerts send a message through the Ratpoison
window manager (see @uref{http://ratpoison.sourceforge.net/}).  They
do no harm if used when you're not running X, but if you are running X
with another window manager, the ratpoison processes will never exit.
You can look at them with @code{list-processes}.

The @code{sawfish} alerts send a message through the Sawfish window
manager.

The @code{festival} alerts speak the message using the Emacs interface
of the Festival speech synthesis system (see
@uref{http://www.cstr.ed.ac.uk/projects/festival/}).

Additionally, for one-to-one and MUC messages, there are @code{scroll}
alerts (enabled by default), that aim to do the right thing with chat
buffers that are visible but not active.  Sometimes you want point to
scroll down, and sometimes not.  These functions should do what you
mean; if they don't, it's a bug.

Some of these functions are in the @file{jabber-alert.el} file, and the
others are in their own files.  You can use them as templates or
inspiration for your own alerts.

@node Presence alerts, Message alerts, Standard alerts, Customizing alerts
@subsection Presence alerts

@vindex jabber-alert-presence-message-function
@findex jabber-presence-default-message

Set @code{jabber-alert-presence-message-function} to your desired
function.  This function should look like:

@example
(defun @var{function} (@var{who} @var{oldstatus} @var{newstatus} @var{statustext})
   ...
   )
@end example

@var{who} is the JID symbol (@pxref{Roster structure}),
@var{oldstatus} and @var{newstatus} are the previous and current
stati, respectively, and @var{statustext} is the status message if
provided, otherwise nil.

@var{newstatus} can also be one of @code{"subscribe"},
@code{"subscribed"}, @code{"unsubscribe"} and @code{"unsubscribed"}.

The default function, @code{jabber-presence-default-message}, returns
@code{nil} if @var{oldstatus} and @var{newstatus} are the same, and in
other cases constructs a message from the given data.

All presence alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.  This last argument is usually the only one they use.

@node Message alerts, MUC alerts, Presence alerts, Customizing alerts
@subsection Message alerts

@vindex jabber-alert-message-function
@findex jabber-message-default-message
@vindex jabber-message-alert-same-buffer

If you don't want message alerts when the chat buffer in question is
already the current buffer, set @code{jabber-message-alert-same-buffer}
to nil.  This affects the behaviour of the default message function, so
you'll have to reimplement this functionality if you write your own
message function.

Set @code{jabber-alert-message-function} to your desired
function.@footnote{Logically it should be
@code{jabber-alert-message-message-function}, but that would be
really ugly.}  This function should look like:

@example
(defun @var{function} (@var{from} @var{buffer} @var{text})
   ...
   )
@end example

@var{from} is the JID symbol (@pxref{Roster structure}), @var{buffer}
is the buffer where the message is displayed, and @var{text} is the
text of the message.

The default function, @code{jabber-message-default-message}, returns
``Message from @var{person}'', where @var{person} is the name of the
person if specified in the roster, otherwise the JID.

All message alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.

@node MUC alerts, Info alerts, Message alerts, Customizing alerts
@subsection MUC alerts

@vindex jabber-alert-muc-function
@findex jabber-muc-default-message

Set @code{jabber-alert-muc-function} to your desired
function.  This function should look like:

@example
(defun @var{function} (@var{nick} @var{group} @var{buffer} @var{text})
   ...
   )
@end example

@var{nick} is the nickname, @var{group} is the JID of the group,
@var{buffer} is the buffer where the message is displayed, and
@var{text} is the text of the message.

The default function, @code{jabber-muc-default-message}, returns
``Message from @var{nick} in @var{group}'' or ``Message in
@var{group}'', the latter for messages from the room itself.

All MUC alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.

@node Info alerts,  , MUC alerts, Customizing alerts
@subsection Info alerts

@vindex jabber-alert-info-message-function
@findex jabber-info-default-message

Info alerts are sadly underdeveloped.  The message function,
@code{jabber-alert-info-message-function}, takes two arguments,
@var{infotype} and @var{buffer}.  @var{buffer} is the buffer where
something happened, and @var{infotype} is either @code{'roster} for
roster updates, or @code{'browse} for anything that uses the browse
buffer (basically anything except chatting).

The info alert hooks take an extra argument, as could be expected.

@node Hooks, Debug options, Customizing alerts, Customization
@section Hooks

jabber.el provides various hooks that you can use for whatever
purpose.

@table @code
@vindex jabber-post-connect-hook
@item jabber-post-connect-hook
This hook is called after successful connection and authentication.
By default it contains @code{jabber-send-default-presence}
(@pxref{Presence}).

@vindex jabber-lost-connection-hook
@item jabber-lost-connection-hook
This hook is called when you have been disconnected for unknown
reasons.  Usually this isn't noticed for quite a long time.

@vindex jabber-pre-disconnect-hook
@item jabber-pre-disconnect-hook
This hook is called just before voluntary disconnection.  This might
be due to failed authentication, so check
@code{*jabber-authenticated*} if you want to send a stanza.

@vindex jabber-post-disconnect-hook
@item jabber-post-disconnect-hook
This hook is called after disconnection of any kind, possibly just
after @code{jabber-lost-connection-hook}.

@vindex jabber-chat-mode-hook
@item jabber-chat-mode-hook
This hook is called when a new chat buffer is created.

@end table

@node Debug options,  , Hooks, Customization
@section Debug options

@vindex jabber-debug-log-xml
@cindex XML log

These settings provide a lot of information which is usually not very
interesting, but can be useful for debugging various things.

@code{jabber-debug-log-xml} activates XML logging.  All XML stanzas
sent and received are logged in the buffer @code{*-jabber-xml-log-*}
in list format.  @xref{XML representation}.

@node Hacking and extending, Protocol support, Customization, Top
@chapter Hacking and extending

This part of the manual is an attempt to explain parts of the source
code.  It is not meant to discourage you from reading the code
yourself and trying to figure it out, but as a guide on where to
look.  Knowledge of Jabber protocols is assumed.

@menu
* XML representation::          
* Roster structure::            
* Listening for new requests::  
* Sending new requests::        
* Extending service discovery::  
* Chat printers::               
* Stanza chains::               
@end menu

@node XML representation, Roster structure, Hacking and extending, Hacking and extending
@section XML representation

@cindex XML representation

The XML representation is the one generated by @file{xml.el} in Emacs,
namely the following.  Each tag is a list.  The first element of the
list is a symbol, the name of which is the name of the tag.  The
second element is an alist of attributes, where the keys are the
attribute names in symbol form, and the values are strings.  The
remaining elements are the tags and data contained within the tag.

For example,
@example
<foo bar='baz'>
<frobozz/>Fnord
</foo>
@end example
is represented as
@example
(foo ((bar . "baz")) (frobozz nil "") "Fnord
")
@end example

Note the empty string as the third element of the @code{frobozz}
list.  It is not present in newer (post-21.3) versions of
@file{xml.el}, but it's probably best to assume it might be there.

If you want to see what an XML tag would look like, use
@code{jabber-sexp2xml}, which takes a tag and returns a string.  You
will usually not need it in your code, as you can use
@code{jabber-send-sexp} to send away your tags to the server.

@node Roster structure, Listening for new requests, XML representation, Hacking and extending
@section Roster structure

@vindex *jabber-roster*
@vindex jabber-jid-obarray

Roster entries are contained in the list @code{*jabber-roster*}.

A roster entry is a symbol.  Its name is the JID, and it is interned
in @code{jabber-jid-obarray}.  A roster entry can have the following
properties:

@table @code
@item xml
The XML tag received from the server on roster update

@item name
The name of the roster item (just like the XML attribute)

@item subscription
The subscription state (also copied)

@item ask
The ask state (copied)

@item groups
A list of strings (possibly empty) containing all the groups the
contact is in

@item connected
Boolean, true if any resource is connected

@item show
Presence show status for highest-priority connected resource

@item status
Presence status message for highest-priority connected resource

@item resources
Alist.  Keys are strings (resource names), values are plists with
properties @code{connected}, @code{show}, @code{status} and
@code{priority}.

@end table

Incoming presence information is inserted in @code{resources}, and the
information from the resource with the highest priority is inserted in
@code{show} and @code{status} by the function
@code{jabber-prioritize-resources}.

@node Listening for new requests, Sending new requests, Roster structure, Hacking and extending
@section Listening for new requests

@findex jabber-send-iq
@findex jabber-process-iq
@findex jabber-signal-error
@vindex jabber-iq-get-xmlns-alist
@vindex jabber-iq-set-xmlns-alist

To listen for new IQ requests, add the appropriate entry in
@code{jabber-iq-get-xmlns-alist} or @code{jabber-iq-set-xmlns-alist}.
The key is the namespace of the request, and the value is a function
that takes one argument, the entire IQ stanza in list format.
@code{jabber-process-iq} reads these alists to determine which
function to call on incoming packets.

For example, the Ad-Hoc Commands module contains the following:

@example
(add-to-list 'jabber-iq-set-xmlns-alist
	     (cons "http://jabber.org/protocol/commands" 'jabber-ahc-process))
@end example

To send a response to an IQ request, use @samp{(jabber-send-iq
@var{sender} "result" @var{query} nil nil nil nil @var{id})}, where
@var{query} is the query in list format.  @code{jabber-send-iq} will
encapsulate the query in an IQ packet with the specified id.

To return an error to the Jabber entity that sent the query, use
@code{jabber-signal-error}.  The signal is caught by
@code{jabber-process-iq}, which takes care of sending the error.

@node Sending new requests, Extending service discovery, Listening for new requests, Hacking and extending
@section Sending new requests

@findex jabber-send-iq
@findex jabber-process-iq
@findex jabber-report-success
@findex jabber-process-data

To send an IQ request, use @code{jabber-send-iq}.  It will generate an
id, and create a mapping for it for use when the response comes.  The
syntax is:

@example
(jabber-send-iq @var{to} @var{type} @var{query}
                @var{success-callback} @var{success-closure}
                @var{failure-callback} @var{failure-closure})
@end example

Both callbacks take two arguments, the IQ stanza returned and the
closure item mentioned here.

Two standard callbacks are provided.  @code{jabber-report-success}
takes a string as closure item, and reports success or failure in the
echo area.  @code{jabber-process-data} prepares a browse buffer.  If
its closure argument is a function, it calls that function with point
in this browse buffer.  If it's a string, it prints that string along
with the error message in the IQ response.  If it's anything else
(e.g. @code{nil}), it just dumps the XML in the browse buffer.

Examples follow.  This is the hypothetical Jabber protocol ``frob'',
for which only success report is needed:
@example
(jabber-send-iq "someone@@somewhere.org" "set"
                '(query ((xmlns . "frob")))
                'jabber-report-success "Frobbing"
                'jabber-report-success "Frobbing")
@end example
This will print ``Frobbing succeeded'' or ``Frobbing failed: reason'',
respectively, in the echo area.

The protocol ``investigate'' needs to parse results and show them in a
browse buffer:
@example
(jabber-send-iq "someone@@somewhere.org" "get"
                '(query ((xmlns . "investigate")))
                'jabber-process-data 'jabber-process-investigate
                'jabber-process-data "Investigation failed")
@end example
Of course, the previous example could have used
@code{jabber-report-success} for the error message.  It's a matter of
UI taste.

@node Extending service discovery, Chat printers, Sending new requests, Hacking and extending
@section Service discovery

@vindex jabber-advertised-features
@vindex jabber-disco-items-nodes
@vindex jabber-disco-info-nodes
@findex jabber-my-jid-p

Your new handlers will likely want to advertise their existence
through service discovery.

To have an additional feature reported in response to disco info
requests, add a string to @code{jabber-advertised-features}.

By default, the service discovery functions reject all requests
containing a node identifier with an ``Item not found'' error.  To
make them respond, add the appropriate entries to
@code{jabber-disco-items-nodes} and @code{jabber-disco-info-nodes}.
Both variables work in the same way.  They are alists, where the keys
are the node names, and the values are lists of two items.

The first item is the data to return --- either a list or a function
taking the entire IQ stanza and returning a list, this list containing
the XML nodes to include in the @code{<query/>} node in the response.

The second item is the access control function.  An access control
function receives the JID as its only argument, and returns non-nil if
access is to be granted.  If nil is specified instead of a function,
access is always granted.  One such function is provided,
@code{jabber-my-jid-p}, which grants access for JIDs where the
username and server (not necessarily resource) are equal to those of
the user.

@node Chat printers, Stanza chains, Extending service discovery, Hacking and extending
@section Chat printers

@vindex jabber-chat-printers
@vindex jabber-muc-printers
@vindex jabber-body-printers
@cindex Chat printers
@cindex Body printers

Chat printers are functions that print a certain aspect of an incoming
message in a chat buffer.  Included are functions for printing subjects
(@code{jabber-chat-print-subject}), bodies
(@code{jabber-chat-print-body}, and @code{jabber:x:oob}-style URLs
(@code{jabber-chat-print-url}).  The functions in
@code{jabber-chat-printers} are called in order, with the entire
@code{<message/>} stanza as argument, and are expected to call
@code{insert} if they have anything to add.

For MUC, the functions in @code{jabber-muc-printers} are prepended to
those in @code{jabber-chat-printers}.

Body printers are a subgroup of chat printers.  They are exclusive; only
one of them applies to any given message.  The idea is that
``higher-quality'' parts of the message override pieces included for
backwards compatibility.  Included are @code{jabber-muc-print-invite}
and @code{jabber-chat-normal-body}; functions for XHTML-IM and PGP
encrypted messages may be written in the future.  The functions in
@code{jabber-body-printers} are called in order until one of them
returns non-nil.

@node Stanza chains,  , Chat printers, Hacking and extending
@section Stanza chains

@vindex jabber-message-chain
@vindex jabber-iq-chain
@vindex jabber-presence-chain

If you really need to get under the skin of jabber.el, you can add
functions to the lists @code{jabber-message-chain},
@code{jabber-iq-chain} and @code{jabber-presence-chain}.  The functions
in these lists will be called in order when an XML stanza of the
corresponding type arrives, with the entire XML stanza passed as the
only argument.  Earlier functions can modify the stanza to change the
behaviour of downstream functions.

@node Protocol support, Concept index, Hacking and extending, Top
@appendix Protocol support

@cindex Supported protocols

These are the protocols currently supported (in full or partially) by
jabber.el.

@menu
* RFC 3920 (XMPP-CORE)::        
* RFC 3921 (XMPP-IM)::          
* JEP-0004 (Data Forms)::       
* JEP-0020 (Feature Negotiation)::  
* JEP-0022 (Message Events)::   
* JEP-0030 (Service Discovery)::  
* JEP-0045 (Multi-User Chat)::  
* JEP-0050 (Ad-Hoc Commands)::  
* JEP-0054 (vcard-temp)::       
* JEP-0055 (Jabber Search)::    
* JEP-0065 (SOCKS5 Bytestreams)::  
* JEP-0066 (Out of Band Data)::  
* JEP-0068 (Field Standardization for Data Forms)::  
* JEP-0077 (In-Band Registration)::  
* JEP-0078 (Non-SASL Authentication)::  
* JEP-0082 (Jabber Date and Time Profiles)::  
* JEP-0086 (Error Condition Mappings)::  
* JEP-0091 (Delayed Delivery)::  
* JEP-0092 (Software Version)::  
* JEP-0095 (Stream Initiation)::  
* JEP-0096 (File Transfer)::    
* JEP-0146 (Remote Controlling Clients)::  
@end menu

@node RFC 3920 (XMPP-CORE), RFC 3921 (XMPP-IM), Protocol support, Protocol support
@section RFC 3920 (XMPP-CORE)

Most of RFC 3920 is supported, with the following exceptions.

SASL is supported only when an external SASL library from FLIM or Gnus
is present.  As SASL is an essential part to XMPP, jabber.el will send
pre-XMPP stream headers if it is not available.

None of the stringprep profiles are implemented.  jabber.el changes
JIDs to lowercase internally; that's all.

jabber.el doesn't interpret namespace prefixes.

The @code{xml:lang} attribute is neither interpreted nor generated.

SRV records are used if a modern version of @code{dns.el} is installed.

@node RFC 3921 (XMPP-IM), JEP-0004 (Data Forms), RFC 3920 (XMPP-CORE), Protocol support
@section RFC 3921 (XMPP-IM)

Most of RFC 3921 is supported, with the following exceptions.

Messages of type ``headline'' are not treated in any special way.

The @code{<thread/>} element is not used or generated.

Neither sending nor receiving ``directed presence'' is supported.

Privacy lists are not supported at all.

jabber.el doesn't support XMPP-E2E or ``im:'' CPIM URIs.

@node JEP-0004 (Data Forms), JEP-0020 (Feature Negotiation), RFC 3921 (XMPP-IM), Protocol support
@section JEP-0004 (Data Forms)

JEP-0004 support is good enough for many purposes.  Limitations are
the following.

Forms in incoming messages are not interpreted.  See each specific
protocol for whether forms are accepted in that context.

``Cancel'' messages are probably not consistently generated when they
should be.  This is partly a paradigm clash, as jabber.el doesn't use
modal dialog boxes but buffers which can easily be buried.

@code{<required/>} elements are not enforced.

The field types ``jid-single'', ``jid-multi'' and ``list-multi'' are
not implemented, due to programmer laziness.  Let us know if you need
them.

@node JEP-0020 (Feature Negotiation), JEP-0022 (Message Events), JEP-0004 (Data Forms), Protocol support
@section JEP-0020 (Feature Negotiation)

There are no known limitations or bugs in JEP-0020 support.

@node JEP-0022 (Message Events), JEP-0030 (Service Discovery), JEP-0020 (Feature Negotiation), Protocol support
@section JEP-0022 (Message Events)

jabber.el understands all four specified kinds of message events
(offline, delivered, displayed, and composing) and by default requests
all of them.  It also reports those three events that make sense for
clients.

@node JEP-0030 (Service Discovery), JEP-0045 (Multi-User Chat), JEP-0022 (Message Events), Protocol support
@section JEP-0030 (Service Discovery)

Service discovery is supported, both as client and server, with the
following limitations.  Currently, the client part is not used by any
code, but is provided only as a user tool.  The user interface is not
appealing.

Publishing items is not supported.

@node JEP-0045 (Multi-User Chat), JEP-0050 (Ad-Hoc Commands), JEP-0030 (Service Discovery), Protocol support
@section JEP-0045 (Multi-User Chat)

jabber.el supports parts of JEP-0045.  Entering, leaving and chatting
work.  So do invitations and private messages.  Room configuration is
supported.  Changing roles of participants (basic moderation) is
implemented, as is changing affiliations, but requesting affiliation
lists is not yet supported.

@node JEP-0050 (Ad-Hoc Commands), JEP-0054 (vcard-temp), JEP-0045 (Multi-User Chat), Protocol support
@section JEP-0050 (Ad-Hoc Commands)

jabber.el is probably the first implementation of JEP-0050 (see
@uref{http://article.gmane.org/gmane.network.jabber.devel/21413, post
on jdev from 2004-03-10}).  Both the client and server parts are
supported.

@node JEP-0054 (vcard-temp), JEP-0055 (Jabber Search), JEP-0050 (Ad-Hoc Commands), Protocol support
@section JEP-0054 (vcard-temp)

Both displaying other users' vCards and editing your own vCard are
supported.  The implementation tries to follow the schema in the JEP
accurately.

@node JEP-0055 (Jabber Search), JEP-0065 (SOCKS5 Bytestreams), JEP-0054 (vcard-temp), Protocol support
@section JEP-0055 (Jabber Search)

JEP-0055 is supported, both with traditional fields and with Data
Forms (@pxref{JEP-0004 (Data Forms)}).  As the traditional fields
specified by the JEP is a subset of those allowed in JEP-0077,
handling of those two form types are merged.  @ref{JEP-0077 (In-Band
Registration)}.

@node JEP-0065 (SOCKS5 Bytestreams), JEP-0066 (Out of Band Data), JEP-0055 (Jabber Search), Protocol support
@section JEP-0065 (SOCKS5 Bytestreams)

JEP-0065 support seems to work, but it is not yet enabled by default.

Currently jabber.el cannot act as a server, not even on on Emacsen
that support server sockets (GNU Emacs 22 and up).  Therefore it
relies on proxies.  Proxies have to be entered and queried manually.

Psi's ``fast mode''
(@uref{http://delta.affinix.com/specs/stream.html}), which gives
greater flexibility with regards to NAT, is not implemented.

@node JEP-0066 (Out of Band Data), JEP-0068 (Field Standardization for Data Forms), JEP-0065 (SOCKS5 Bytestreams), Protocol support
@section JEP-0066 (Out of Band Data)

jabber.el will display URLs sent in message stanzas qualified by
the @code{jabber:x:oob} namespace, as described in this JEP.  Sending
such URLs or doing anything with iq stanzas (using the
@code{jabber:iq:oob} namespace) is not supported.

@node JEP-0068 (Field Standardization for Data Forms), JEP-0077 (In-Band Registration), JEP-0066 (Out of Band Data), Protocol support
@section JEP-0068 (Field Standardization for Data Forms)

JEP-0068 is only used in the context of creating a new Jabber account,
to prefill the username field of the registration form.

@node JEP-0077 (In-Band Registration), JEP-0078 (Non-SASL Authentication), JEP-0068 (Field Standardization for Data Forms), Protocol support
@section JEP-0077 (In-Band Registration)

In-band registration is supported for all purposes.  That means
registering a new Jabber account, changing Jabber password, removing a
Jabber account, registering with a service, and cancelling
registration to a service.  Data forms are supported as well.  URL
redirections are not.

jabber.el will not prevent or alert a user trying to change a password
over an unencrypted connection.

@node JEP-0078 (Non-SASL Authentication), JEP-0082 (Jabber Date and Time Profiles), JEP-0077 (In-Band Registration), Protocol support
@section JEP-0078 (Non-SASL Authentication)

Non-SASL authentication is supported, both plaintext and digest.
Digest is preferred, and a warning is displayed to the user if only
plaintext is available.

@node JEP-0082 (Jabber Date and Time Profiles), JEP-0086 (Error Condition Mappings), JEP-0078 (Non-SASL Authentication), Protocol support
@section JEP-0082 (Jabber Date and Time Profiles)

The DateTime profile of JEP-0082 is supported.  Currently this is only
used for file transfer.

@node JEP-0086 (Error Condition Mappings), JEP-0091 (Delayed Delivery), JEP-0082 (Jabber Date and Time Profiles), Protocol support
@section JEP-0086 (Error Condition Mappings)

Legacy errors are interpreted, but never generated.  XMPP style error
messages take precedence when errors are reported to the user.

@node JEP-0091 (Delayed Delivery), JEP-0092 (Software Version), JEP-0086 (Error Condition Mappings), Protocol support
@section JEP-0091 (Delayed Delivery)

The time specified on delayed incoming messages is interpreted, and
displayed in chat buffers instead of the current time.

@node JEP-0092 (Software Version), JEP-0095 (Stream Initiation), JEP-0091 (Delayed Delivery), Protocol support
@section JEP-0092 (Software Version)

The user can request the version of any entity.  jabber.el answers
version requests to anyone, giving ``jabber.el'' as name, and the
Emacs version as OS.

@node JEP-0095 (Stream Initiation), JEP-0096 (File Transfer), JEP-0092 (Software Version), Protocol support
@section JEP-0095 (Stream Initiation)

JEP-0095 is supported, both incoming and outgoing, with the following
exceptions.  It is not enabled by default, as it hasn't received much
testing.

jabber.el doesn't check service discovery results before sending a
stream initiation request.

@node JEP-0096 (File Transfer), JEP-0146 (Remote Controlling Clients), JEP-0095 (Stream Initiation), Protocol support
@section JEP-0096 (File Transfer)

Both sending and receiving files is supported, though not enabled by
default.  The following limitations apply.

The hash of a file being sent is not calculated and sent in the
request.

Ranged transfers are not supported.

In-band bytestreams are not yet supported, even though JEP-0096
requires them.

@node JEP-0146 (Remote Controlling Clients),  , JEP-0096 (File Transfer), Protocol support
@section JEP-0146 (Remote Controlling Clients)

The ``set-status'' command in JEP-0146 is supported.

@node Concept index, Function index, Protocol support, Top
@unnumbered Concept index

@printindex cp

@node Function index, Variable index, Concept index, Top
@unnumbered Function index

@printindex fn

@node Variable index,  , Function index, Top
@unnumbered Variable index

@printindex vr

@bye

@ignore
   arch-tag: 995bf3da-0e87-4b15-895a-1e85fac139a2
@end ignore