emacs-jabber/jabber.texi

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

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

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

Copyright @copyright{} 2004 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::                    
* Modeline status::             
* Keepalive::                   
* Customization::               
* Hacking and extending::       
* 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 SSL, STARTTLS, GPG, advanced MUC
features, 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@@charente.de}).  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.

@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}.  If for some reason
the JID of your server is not the same as its network name, change
@code{jabber-network-server} also.  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}.  If the server supports in-band registration, you
will be presented with a registration form to fill out and send.
There you will have to enter your username again.  Enter the same
username in both places, 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}.

@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.

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
@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.

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

@cindex Roster buffer
@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.

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
@findex jabber-groupchat-join
@findex jabber-groupchat-leave
@findex jabber-groupchat-get-config

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.

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.

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

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

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.

Currently, there is no user-friendly way to see which people are in a
groupchat.  A possible workaround is to add the groupchat to your
roster before you join it; that way the participants will show up as
resources of a user.

@node Services, Modeline status, 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.  They have the same keybindings as
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.

To start browsing, type @kbd{M-x jabber-get-browse} and enter the JID
you want to browse.  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.

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

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

@cindex Registration
@cindex Cancelling registration
@cindex Changing password
@cindex Gateway registration
@cindex Password change
@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, as jabber.el doesn't support
encryption yet, 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.  However, at the time of this writing it seems that
jabber.el is the only implementation.

Currently, ad-hoc commands are used 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 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 Modeline status, Keepalive, Services, Top
@chapter Modeline status

@cindex modeline
@findex jabber-mode-line-mode
@vindex jabber-mode-line-mode

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 six numbers indicating the number of chatty, online, away,
extended away, dnd, and offline contacts, respectively.

@node Keepalive, Customization, Modeline status, Top
@chapter Keepalive

@cindex keepalive
@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 Customization, Hacking and extending, Keepalive, 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
* Connection settings::         
* Customizing the roster buffer::  
* Customizing the chat buffer::  
* Customizing alerts::          
* Hooks::                       
* Debug options::               
@end menu

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

@vindex jabber-username
@vindex jabber-server
@vindex jabber-network-server
@vindex jabber-port
@vindex jabber-password
@vindex jabber-resource
@vindex jabber-default-priority
@vindex jabber-nickname

@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-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.  This
is 5222 in almost all cases.

@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 Customizing the roster buffer, Customizing the chat buffer, Connection settings, Customization
@section Customizing the roster buffer

@vindex jabber-sort-order
@vindex jabber-show-resources
@vindex jabber-roster-line-format
@vindex jabber-resource-line-format
@vindex jabber-roster-buffer

@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:

@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.

@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.

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

@vindex jabber-chat-time-format
@vindex jabber-chat-local-prompt-format
@vindex jabber-chat-foreign-prompt-format
@vindex jabber-chat-prompt-local
@vindex jabber-chat-prompt-foreign
@vindex jabber-chat-header-line-format

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.

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

@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

@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}.

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}.

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

@cindex Alert hooks

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.

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.  Either submit them to the
Sourceforge patch tracker, or contact us directly.

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

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

Six alerts are already written for all three 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 enabled 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.

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}.@footnote{In jabber.el
0.4, ratpoison alerts were sent synchronously, which meant that Emacs
would stall if ratpoison wasn't there to answer.}

All these functions are in the @file{jabber-alert.el} file.  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-alerts-presence-message-function
@findex jabber-presence-default-message

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

@example
(@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, Info alerts, Presence alerts, Customizing alerts
@subsection Message alerts

@vindex jabber-alerts-message-function
@findex jabber-message-default-message

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

@example
(@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 Info alerts,  , Message alerts, Customizing alerts
@subsection Info alerts

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

Info alerts are sadly underdeveloped.  The message function,
@code{jabber-alerts-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

@vindex jabber-post-connect-hook
@vindex jabber-pre-disconnect-hook
@vindex jabber-post-disconnect-hook
@vindex jabber-lost-connection-hook

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

@table @code
@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}).

@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.

@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.

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

@end table

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

@vindex jabber-debug-log-xml

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, Concept index, 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::  
* 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.

@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, Stanza chains, 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 Stanza chains,  , Extending service discovery, 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}.  Normally
those lists contain only the functions jabber.el needs to do its job,
i.e. @code{jabber-process-message}, @code{jabber-process-iq} and
@code{jabber-process-presence}, respectively.

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 Concept index, Function index, Hacking and extending, 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