2004-01-15 00:11:04 +00:00
|
|
|
\input texinfo @c -*-texinfo-*-
|
2004-03-23 21:24:28 +00:00
|
|
|
@c $Id: jabber.texi,v 1.10 2004/03/23 21:24:28 legoscia Exp $
|
2004-01-15 00:11:04 +00:00
|
|
|
@c %**start of header
|
|
|
|
@setfilename jabber.info
|
2004-03-23 21:24:28 +00:00
|
|
|
@settitle jabber.el manual 0.5
|
2004-01-15 00:11:04 +00:00
|
|
|
@c %**end of header
|
|
|
|
@syncodeindex fn cp
|
|
|
|
|
|
|
|
@dircategory Emacs
|
|
|
|
@direntry
|
|
|
|
* jabber.el: (jabber). Emacs Jabber client
|
|
|
|
@end direntry
|
|
|
|
|
|
|
|
@copying
|
2004-03-23 21:24:28 +00:00
|
|
|
This manual is for jabber.el, version 0.5.
|
2004-01-15 00:11:04 +00:00
|
|
|
|
|
|
|
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
|
2004-02-02 22:56:55 +00:00
|
|
|
@title jabber.el
|
|
|
|
@subtitle where Emacs and Jabber meet
|
|
|
|
@author by Magnus Henoch and Tom Berger
|
2004-01-15 00:11:04 +00:00
|
|
|
|
|
|
|
@page
|
|
|
|
@vskip 0pt plus 1filll
|
|
|
|
@insertcopying
|
|
|
|
@end titlepage
|
|
|
|
|
|
|
|
@contents
|
|
|
|
|
|
|
|
@ifnottex
|
|
|
|
@node Top, Introduction, (dir), (dir)
|
|
|
|
@top jabber.el manual
|
|
|
|
|
|
|
|
@insertcopying
|
|
|
|
|
|
|
|
@end ifnottex
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Introduction::
|
2004-01-29 13:04:21 +00:00
|
|
|
* Basic operation::
|
|
|
|
* Groupchat::
|
|
|
|
* Services::
|
|
|
|
* Customization::
|
|
|
|
* Hacking and extending::
|
2004-01-15 00:11:04 +00:00
|
|
|
* Index::
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Introduction, Basic operation, Top, Top
|
2004-01-15 00:11:04 +00:00
|
|
|
@chapter Introduction
|
|
|
|
|
|
|
|
jabber.el is a Jabber client running under Emacs. For more
|
|
|
|
information on the open-protocol instant messaging network Jabber,
|
2004-01-30 21:25:13 +00:00
|
|
|
please visit @uref{http://www.jabber.org}.
|
2004-01-15 00:11:04 +00:00
|
|
|
|
|
|
|
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).
|
|
|
|
|
|
|
|
Main unfeatures of jabber.el are SASL, SSL and TLS. Beyond that,
|
|
|
|
there is nearly no support for advanced MUC features required for
|
|
|
|
moderation and other things.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@menu
|
|
|
|
* Contact::
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Contact, , Introduction, Introduction
|
|
|
|
@section Contact
|
2004-01-15 00:11:04 +00:00
|
|
|
|
|
|
|
jabber.el is developed by Tom Berger (e-mail
|
2004-01-29 13:04:21 +00:00
|
|
|
@email{object@@intellectronica.net}, JID @code{object@@jabber.org.uk}) and
|
2004-01-15 00:11:04 +00:00
|
|
|
Magnus Henoch (e-mail @email{mange@@freemail.hu}, JID
|
2004-01-29 13:04:21 +00:00
|
|
|
@code{legoscia@@charente.de}). There is a web page at
|
2004-01-30 21:25:13 +00:00
|
|
|
@uref{http://intellectronica.net/emacs-jabber/}, and a Sourceforge
|
|
|
|
project page at @uref{http://sourceforge.net/projects/emacs-jabber}.
|
2004-01-15 00:11:04 +00:00
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@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::
|
2004-01-30 21:25:13 +00:00
|
|
|
* Roster buffer::
|
2004-01-29 13:04:21 +00:00
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Connecting, Chatting, Basic operation, Basic operation
|
|
|
|
@section Connecting
|
|
|
|
|
|
|
|
@findex jabber-connect
|
|
|
|
@findex jabber-disconnect
|
|
|
|
@cindex Connecting
|
|
|
|
@cindex Registering with server
|
2004-01-15 00:11:04 +00:00
|
|
|
|
|
|
|
I'll assume that you have already successfully installed jabber.el; if
|
|
|
|
not, consult the @file{README} file. Also, make sure you have
|
2004-03-23 21:24:28 +00:00
|
|
|
@code{(require 'jabber)} in your @file{.emacs}.
|
2004-01-15 00:11:04 +00:00
|
|
|
|
|
|
|
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-*}.
|
|
|
|
|
|
|
|
Now that you are connected, you can send @dfn{initial presence}. This
|
|
|
|
means sending a notification of you being online to everyone on your
|
|
|
|
roster. You don't have to do that, and if you don't noone can see
|
|
|
|
that you are online. This is usually not what you want, but it is
|
|
|
|
occasionally useful. To send presence, type @kbd{M-x
|
|
|
|
jabber-send-presence}. You will be asked three questions; the
|
|
|
|
defaults will do for now. @xref{Presence}, for more information.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
To disconnect, type @kbd{M-x jabber-disconnect}.
|
|
|
|
|
|
|
|
@node Chatting, Presence, Connecting, Basic operation
|
|
|
|
@section Chatting
|
|
|
|
|
|
|
|
@cindex Chatting
|
|
|
|
|
2004-01-15 00:11:04 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
Now, try opening a chat with someone. In the default configuration,
|
|
|
|
you will hear a beep and see ``Message from @var{person}'' in the echo
|
|
|
|
area. This is exactly the same message you receive if the other
|
|
|
|
person sends a message to you. In any case, go to the buffer
|
|
|
|
@code{*-jabber-chat-:-@var{person}-*} and start chatting. Most
|
|
|
|
normal keystrokes open the minibuffer where you can type a message.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Presence, Presence subscription, Chatting, Basic operation
|
|
|
|
@section Presence
|
|
|
|
|
|
|
|
@cindex Presence
|
|
|
|
@cindex Sending presence
|
|
|
|
@findex jabber-send-presence
|
|
|
|
|
|
|
|
``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)}.
|
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
With jabber.el, you can set your presence remotely. @ref{Ad-Hoc Commands}.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
@node Presence subscription, Roster buffer, Presence, Basic operation
|
2004-01-29 13:04:21 +00:00
|
|
|
@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.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
@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,
|
2004-02-16 21:03:17 +00:00
|
|
|
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.
|
2004-01-30 21:25:13 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Groupchat, Services, Basic operation, Top
|
|
|
|
@chapter Groupchat
|
|
|
|
|
|
|
|
@cindex Groupchat
|
|
|
|
@cindex MUC
|
|
|
|
@findex jabber-groupchat-join
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-02-03 13:22:26 +00:00
|
|
|
Currently, there is no user-friendly way to see which people are in a
|
|
|
|
groupchat. If you really want to know, set @code{jabber-debug} to
|
|
|
|
@code{t} and look in the buffer @code{*-jabber-xml-log-*}.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Services, Customization, Groupchat, Top
|
|
|
|
@chapter Services
|
|
|
|
|
|
|
|
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::
|
2004-03-23 21:24:28 +00:00
|
|
|
* Ad-Hoc Commands::
|
2004-01-29 13:04:21 +00:00
|
|
|
@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
|
|
|
|
service.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
@node Searching, Ad-Hoc Commands, Registering, Services
|
2004-01-29 13:04:21 +00:00
|
|
|
@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.
|
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
@node Ad-Hoc Commands, , Searching, Services
|
|
|
|
@section Ad-Hoc Commands
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
jabber.el currently doesn't parse @code{<action/>} tags, which will
|
|
|
|
cause confusing behaviour for multi-step commands.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Customization, Hacking and extending, Services, Top
|
|
|
|
@chapter Customization
|
2004-01-15 00:11:04 +00:00
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
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 alerts::
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Connection settings, Customizing the roster buffer, Customization, Customization
|
|
|
|
@section Connection settings
|
|
|
|
|
|
|
|
@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 alerts, Connection settings, Customization
|
|
|
|
@section Customizing the roster buffer
|
|
|
|
|
|
|
|
@code{jabber-debug} toggles extended debug output. Currently, this
|
|
|
|
means two things. In the roster buffer, you can see the properties of
|
|
|
|
each contact. All XML stanzas sent and received are logged in the
|
|
|
|
buffer @code{*-jabber-xml-log-*} in list format. @xref{XML
|
|
|
|
representation}.
|
|
|
|
|
|
|
|
@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.
|
|
|
|
|
|
|
|
@node Customizing alerts, , Customizing the roster buffer, Customization
|
|
|
|
@section Customizing alerts
|
|
|
|
|
|
|
|
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
|
2004-02-02 22:56:55 +00:00
|
|
|
section and just read @ref{Standard alerts}.
|
2004-01-30 21:25:13 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-02-03 12:33:27 +00:00
|
|
|
Alert hook contributions are very welcome. Either submit them to the
|
|
|
|
Sourceforge patch tracker, or contact us directly.
|
2004-01-30 21:25:13 +00:00
|
|
|
|
|
|
|
@menu
|
2004-02-02 22:56:55 +00:00
|
|
|
* Standard alerts::
|
2004-01-30 21:25:13 +00:00
|
|
|
* 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.
|
|
|
|
|
2004-03-02 13:08:25 +00:00
|
|
|
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.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
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
|
2004-02-11 21:37:28 +00:00
|
|
|
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.}
|
2004-01-30 21:25:13 +00:00
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
All these functions are in the @file{jabber-alert.el} file. You can
|
|
|
|
use them as templates or inspiration for your own alerts.
|
2004-01-30 21:25:13 +00:00
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
@node Presence alerts, Message alerts, Standard alerts, Customizing alerts
|
2004-01-30 21:25:13 +00:00
|
|
|
@subsection Presence alerts
|
|
|
|
|
|
|
|
Set @code{jabber-alerts-presence-message-function} to your desired
|
2004-02-03 12:33:27 +00:00
|
|
|
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.
|
2004-01-30 21:25:13 +00:00
|
|
|
|
|
|
|
@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
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
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
|
2004-02-03 12:33:27 +00:00
|
|
|
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.
|
2004-02-02 22:56:55 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
@node Info alerts, , Message alerts, Customizing alerts
|
|
|
|
@subsection Info alerts
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
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.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Hacking and extending, Index, Customization, Top
|
|
|
|
@chapter Hacking and extending
|
2004-01-15 00:11:04 +00:00
|
|
|
|
2004-02-03 12:33:27 +00:00
|
|
|
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.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
@menu
|
|
|
|
* XML representation::
|
|
|
|
* Roster structure::
|
|
|
|
* Listening for new requests::
|
|
|
|
* Sending new requests::
|
2004-03-23 21:24:28 +00:00
|
|
|
* Extending service discovery::
|
2004-01-30 21:25:13 +00:00
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node XML representation, Roster structure, Hacking and extending, Hacking and extending
|
|
|
|
@section XML representation
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
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.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
@node Roster structure, Listening for new requests, XML representation, Hacking and extending
|
|
|
|
@section Roster structure
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
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}.
|
|
|
|
|
2004-01-30 21:25:13 +00:00
|
|
|
@node Listening for new requests, Sending new requests, Roster structure, Hacking and extending
|
|
|
|
@section Listening for new requests
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
@findex jabber-send-iq
|
|
|
|
@findex jabber-process-iq
|
2004-03-23 21:24:28 +00:00
|
|
|
@findex jabber-signal-error
|
2004-02-02 22:56:55 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
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
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
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.
|
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
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
|
2004-01-30 21:25:13 +00:00
|
|
|
@section Sending new requests
|
|
|
|
|
2004-02-02 22:56:55 +00:00
|
|
|
@findex jabber-send-iq
|
|
|
|
@findex jabber-process-iq
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-03-23 21:24:28 +00:00
|
|
|
@node Extending service discovery, , Sending new requests, Hacking and extending
|
|
|
|
@section Service discovery
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-01-29 13:04:21 +00:00
|
|
|
@node Index, , Hacking and extending, Top
|
2004-01-15 00:11:04 +00:00
|
|
|
@unnumbered Index
|
|
|
|
|
|
|
|
@printindex cp
|
|
|
|
|
|
|
|
@bye
|