3021 lines
111 KiB
Plaintext
3021 lines
111 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename jabber.info
|
|
@settitle jabber.el manual 0.8.0
|
|
@c %**end of header
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* jabber.el: (jabber). Emacs XMPP (Jabber) client
|
|
@end direntry
|
|
|
|
@copying
|
|
This manual is for jabber.el, version 0.8.0.
|
|
|
|
Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 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 instant messaging for XMPP (Jabber)
|
|
@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::
|
|
* Composing messages::
|
|
* File transfer::
|
|
* Services::
|
|
* Personal information::
|
|
* Avatars::
|
|
* Time queries::
|
|
* Useful features::
|
|
* Message history::
|
|
* Typing notifications::
|
|
* 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 an XMPP (Jabber) client running under Emacs. For more
|
|
information on the open instant messaging protocol,
|
|
please visit @uref{http://xmpp.org}.
|
|
|
|
As a XMPP 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 buffers 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 PGP encryption, sending and receiving
|
|
roster items, and various other things.
|
|
|
|
@menu
|
|
* Contacts::
|
|
@end menu
|
|
|
|
@node Contacts, , , Introduction
|
|
@section Contacts
|
|
|
|
@itemize @bullet
|
|
@item
|
|
There is a web page at
|
|
@uref{http://emacs-jabber.sf.net/}.
|
|
|
|
@item
|
|
There is a Sourceforge
|
|
project page at @uref{http://sourceforge.net/projects/emacs-jabber},
|
|
with bug and patch trackers.
|
|
|
|
@item
|
|
There is a mailing list:
|
|
@email{emacs-jabber-general@@lists.sourceforge.net},
|
|
@uref{https://lists.sourceforge.net/lists/listinfo/emacs-jabber-general},
|
|
@uref{http://dir.gmane.org/gmane.emacs.jabber.general}
|
|
|
|
@item
|
|
There is a chat room, @code{jabber.el@@conference.jabber.se}. If you
|
|
have successfully connected, you can join it by typing @kbd{M-x
|
|
jabber-muc-join} and entering the address.
|
|
|
|
@end itemize
|
|
|
|
@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 XMPP 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.
|
|
|
|
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)} or @code{(load "jabber-autoloads")} in your
|
|
@file{.emacs}.
|
|
|
|
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
|
|
* Do you have a Jabber account?::
|
|
* Registering an account::
|
|
* Connecting::
|
|
* Chatting::
|
|
* Presence::
|
|
* Presence subscription::
|
|
* Roster buffer::
|
|
@end menu
|
|
|
|
@node Do you have a Jabber account?, Registering an account, , Basic operation
|
|
@section Do you have a Jabber account?
|
|
|
|
Jabber has become rather popular as an instant messaging technology.
|
|
Several sites use it, but often not under the names ``Jabber'' or
|
|
``XMPP''. Examples:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Google Talk uses Jabber. If you have a Gmail address, you can use it as
|
|
a Jabber ID. @xref{Account settings}, for Google-specific configuration.
|
|
|
|
@item
|
|
LJ Talk (of Livejournal) uses Jabber. Your Jabber ID is
|
|
@samp{@var{ljusername}@@livejournal.com}.
|
|
@end itemize
|
|
|
|
@node Registering an account, Connecting, Do you have a Jabber account?, Basic operation
|
|
@section Registering an account
|
|
|
|
@cindex Registering an account
|
|
|
|
If you do not yet have a Jabber account, you can register one. The
|
|
registration processes for various servers differ, but many servers
|
|
support so-called ``in-band registration'', which is described in this
|
|
section.
|
|
|
|
To register an account, type @kbd{C-u M-x jabber-connect} and enter your
|
|
desired JID in the form @samp{@var{username}@@@var{server}}. You will
|
|
be presented with a registration form to fill out and send. There the
|
|
username you chose will be prefilled. After registration, you can
|
|
connect to the server as usual.
|
|
|
|
@node Connecting, Chatting, Registering an account, Basic operation
|
|
@section Connecting
|
|
|
|
@findex jabber-connect-all
|
|
@findex jabber-connect
|
|
@findex jabber-disconnect-one
|
|
@findex jabber-disconnect
|
|
|
|
@cindex Connecting
|
|
|
|
Now, type @kbd{C-x C-j C-c} and enter your JID and password. If you
|
|
successfully connect, jabber.el will download your roster and display it
|
|
in a buffer called @code{*-jabber-roster-*}.
|
|
|
|
By default, you will appear as ``online'' to your contacts. To change
|
|
this to e.g. ``away'', type @kbd{M-x jabber-send-presence} or @kbd{C-x
|
|
C-j C-p}. @xref{Presence}, for more information.
|
|
|
|
To disconnect, type @kbd{M-x jabber-disconnect} or @kbd{C-x C-j C-d}.
|
|
Use @kbd{M-x jabber-disconnect-one} to disconnect just one account (or just type @kbd{C-u C-x C-j C-d}).
|
|
|
|
If you don't want to type your JID every time you connect, you can save
|
|
it in the variable @code{jabber-account-list}. @xref{Account
|
|
settings}. If you configure more than one account, all of them will be
|
|
connected when you type @kbd{C-x C-j C-c}, as that key is bound to
|
|
@code{jabber-connect-all}. To connect only one account, possibly one
|
|
that's not in your list, type @kbd{M-x jabber-connect} or @kbd{C-u C-x
|
|
C-j C-c}.
|
|
|
|
@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 the function @code{jabber-chat-with}. This function is
|
|
bound to @kbd{C-x C-j C-j} in the global keymap. You will be asked to
|
|
enter a JID in the minibuffer. You can also enter the roster name of
|
|
one of your contacts. All JIDs and names in your roster can be
|
|
tab-completed.
|
|
|
|
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.
|
|
|
|
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}.
|
|
|
|
When you receive a message from someone, you will see a red indicator in
|
|
the mode line. You can click this indicator with the mouse, or type
|
|
@kbd{C-x C-j C-l} to switch to the relevant buffer. @xref{Tracking
|
|
activity}.
|
|
|
|
@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
|
|
|
|
@dfn{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 state (called ``show''),
|
|
status message, and priority.
|
|
|
|
Your show state 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. @xref{Resources and
|
|
priority}.
|
|
|
|
To set your presence, use the function @code{jabber-send-presence}
|
|
(bound to @kbd{C-x C-j C-p}).
|
|
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)}. There are a few shortcuts:
|
|
@table @kbd
|
|
@item C-x C-j C-a
|
|
Send ``away'' presence (with prefix argument, specify status text)
|
|
@item C-x C-j C-x
|
|
Send ``extended away'' presence (with prefix argument, specify status
|
|
text)
|
|
@item C-x C-j C-o
|
|
Send default presence (see below)
|
|
@end table
|
|
|
|
By default, jabber.el sets your presence when you connect. If you
|
|
want it not to do that, remove @code{jabber-send-current-presence}
|
|
from @code{jabber-post-connect-hooks}. 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}.
|
|
|
|
@menu
|
|
* Resources and priority::
|
|
* Directed presence::
|
|
@end menu
|
|
|
|
@node Resources and priority, Directed presence, , Presence
|
|
@subsection Resources and priority
|
|
|
|
@cindex Resource
|
|
@cindex Priority
|
|
|
|
Every connection to an account has a specific name, a @dfn{resource}.
|
|
The account itself has a JID of the form
|
|
@samp{@var{username}@@@var{server}} (a @dfn{bare JID}), but the
|
|
connections have JIDs of the form
|
|
@samp{@var{username}@@@var{server}/@var{resource}} (a @dfn{full JID}).
|
|
You can choose the resource name yourself by entering a JID of the
|
|
latter form at the connection prompt (@pxref{Connecting}), or by
|
|
configuring it in @code{jabber-account-list} (@pxref{Account settings})
|
|
|
|
Each session has a @dfn{priority}. The priority determines what happens
|
|
when a message is sent to the bare JID (i.e. without specifying what
|
|
connection should receive message). Such messages are delivered to the
|
|
connection with the highest non-negative priority value. If there are
|
|
no connections, or if all connections have negative priority, the
|
|
message is either stored on the server for later delivery or bounced to
|
|
the sender, depending on the server configuration.
|
|
|
|
If there are several connections with the same priority, the behaviour
|
|
depends on the server. Some server implementations deliver the message
|
|
to all such connections, while others choose one connection depending on
|
|
certain rules.
|
|
|
|
Note that these rules do not apply when a message is sent to a full
|
|
JID. Such messages are sent to the specified resource, if it is still
|
|
connected, and otherwise treated as messages to the bare JID. In the
|
|
chat buffers of jabber.el, messages are sent to whatever JID the last
|
|
message came from (usually a full JID), or to the bare JID if no message
|
|
has been received yet. Other clients may have different behaviour.
|
|
|
|
@node Directed presence, , Resources and priority, Presence
|
|
@subsection Directed presence
|
|
|
|
@cindex directed presence
|
|
@cindex send directed presence
|
|
@findex jabber-send-directed-presence
|
|
You can send ``directed presence'' with @kbd{M-x
|
|
jabber-send-directed-presence}. This is mostly useful to manage
|
|
transports---sending directed presence is a way to turn them on and
|
|
off. You can also send directed presence to an annoying contact to
|
|
appear as away or offline to that contact. Note, however, that in both
|
|
of these cases, all subscribed entities will get your next global
|
|
presence update.
|
|
|
|
@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. Subscription state is shown in the roster
|
|
display by arrows (@pxref{Customizing the roster buffer}). A
|
|
left-pointing arrow means that the contact can see your presence
|
|
(``from''). A right-pointing arrow means that you can see the contact's
|
|
presence (``to''). The most common case is mutual subscription, a
|
|
double-ended arrow (``both'').
|
|
|
|
When jabber.el receives a presence subscription request, it will present
|
|
it to you in a chat buffer, and offer you to choose subscription mode
|
|
and send a subscription request back to that person. The ``Mutual''
|
|
button accepts the request and sends a reciprocal request.@footnote{If this
|
|
request is superfluous, the server will drop it without bothering the
|
|
contact.} The ``One-way'' button accepts the request, but doesn't ask
|
|
for a subscription in return. The ``Decline'' button declines the
|
|
request.
|
|
|
|
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 or by typing @kbd{e} on a person in the
|
|
roster buffer.
|
|
|
|
@node Roster buffer, , Presence subscription, Basic operation
|
|
@section The roster buffer
|
|
|
|
@cindex Roster buffer, basics
|
|
@cindex Menus
|
|
@cindex Key bindings
|
|
|
|
The roster buffer is called @code{*-jabber-roster-*}. It simply
|
|
contains a list of the contacts on your roster. If you have several
|
|
accounts connected, contacts will be grouped by account.
|
|
|
|
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 are 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.
|
|
|
|
@vindex jabber-roster-show-bindings
|
|
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.
|
|
|
|
@findex jabber-display-roster
|
|
You can call @code{jabber-display-roster} (bound to @kbd{g}) 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.
|
|
|
|
@vindex jabber-show-offline-contacts
|
|
@cindex Hiding offline contacts
|
|
@cindex Offline contacts, hiding
|
|
Please note, that by default offline contacts showed in roster as any
|
|
others. To hide them, you can use @kbd{o} in roster buffer. To
|
|
permanently hide them, customize @code{jabber-show-offline-contacts}
|
|
variable.
|
|
|
|
@node Groupchat, Composing messages, 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-muc-join
|
|
@cindex Joining a groupchat
|
|
@cindex Changing nickname
|
|
@cindex Nickname, changing
|
|
To join a groupchat, type @kbd{M-x jabber-muc-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{Configuration}, for setting default
|
|
nicknames.
|
|
|
|
@cindex Query groupchat
|
|
@vindex jabber-muc-disable-disco-check
|
|
When trying to join a room, jabber.el first sends a service discovery
|
|
info request to the room, to find out whether it exists and what
|
|
features are enabled (in particular whether the room is
|
|
password-protected). However, this can cause problems with some buggy
|
|
MUC services (or services that respond in a way that jabber.el doesn't
|
|
expect). A workaround for that is to set
|
|
@code{jabber-muc-disable-disco-check} to @code{t}; however, the bug should be
|
|
unearthed and fixed.
|
|
|
|
Groupchat messages will be displayed in a buffer called
|
|
@code{*-jabber-groupchat-:-@var{groupchat}-*}. By default, the buffer
|
|
name is based on the JID of the chat room. If you want a shorter name,
|
|
you can add the chat room to your roster and give it a name, using the
|
|
command @kbd{M-x jabber-roster-change}. The groupchat buffer works much
|
|
like the chat buffer. It has its own class of alerts
|
|
(@pxref{Customizing alerts}), and uses activity tracking
|
|
(@pxref{Tracking activity}).
|
|
|
|
@vindex jabber-muc-completion-delimiter
|
|
@vindex jabber-muc-looks-personaling-symbols
|
|
@cindex Groupchat completion
|
|
@cindex Nick completion in groupchat
|
|
Also, to save from repeating unnesesary typing you can press @kbd{Tab}
|
|
key to complete nick of a groupchat member that you are talking with.
|
|
You can customize your form of personal talking in MUC
|
|
(@code{jabber-muc-completion-delimiter}) and form of personal talking to
|
|
you (@code{jabber-muc-looks-personaling-symbols})---see ``jabber-chat''
|
|
customization group. Defaults are sane, so it is unlikely that you would
|
|
want to change this, but... it is Emacs!
|
|
|
|
@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-muc-leave
|
|
To leave a groupchat, type @kbd{M-x jabber-muc-leave}.
|
|
|
|
@findex jabber-muc-get-config
|
|
If you are the owner of a groupchat, you can change its configuration
|
|
by typing @kbd{M-x jabber-muc-get-config}. A configuration form
|
|
will be rendered in new buffer.
|
|
|
|
@findex jabber-muc-names
|
|
@vindex jabber-muc-print-names-format
|
|
To see which people are in a groupchat, type @kbd{M-x
|
|
jabber-muc-names}. This gives a list of nicknames,
|
|
``affiliations'', and possibly JIDs according @code{jabber-muc-print-names-format}, sorted by ``roles''.
|
|
@xref{MUC Administration}, for the meaning of roles and affiliations.
|
|
|
|
|
|
@menu
|
|
* Configuration::
|
|
* Invitations::
|
|
* Private messages::
|
|
* MUC Administration::
|
|
@end menu
|
|
|
|
@node Configuration, Invitations, , Groupchat
|
|
@section Configuration
|
|
|
|
@vindex jabber-muc-default-nicknames
|
|
@vindex jabber-muc-autojoin
|
|
@findex jabber-muc-autojoin
|
|
@cindex Default MUC nickname
|
|
@cindex Autojoin chat rooms
|
|
@cindex Bookmarks, MUC
|
|
@findex jabber-edit-bookmarks
|
|
|
|
You can configure jabber.el to use a certain nickname for a certain
|
|
room, or to automatically join a certain room when you connect. You can
|
|
do this either by storing bookmarks on the server or by setting Emacs
|
|
variables.
|
|
|
|
Type @kbd{M-x jabber-edit-bookmarks} to add bookmarks. You can specify
|
|
the JID of the conference, the name of the conference (not used by
|
|
jabber.el), whether to automatically join the room, your desired
|
|
nickname (or leave empty), and the room password (or leave empty).
|
|
|
|
The default nickname for groupchats is the username part of your JID.
|
|
If you don't use bookmarks, 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.
|
|
|
|
Automatically joining certain rooms when connecting can be accomplished
|
|
by setting @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-hooks}.
|
|
|
|
Please note, that @code{jabber-muc-default-nicknames} and
|
|
@code{jabber-muc-autojoin} are machine-local, but apply to @emph{all}
|
|
accounts---if you connect several accounts, both will try to connect to
|
|
the same chat rooms, or use the same nickname. This will lead to
|
|
confusion.
|
|
|
|
@node Invitations, Private messages, Configuration, 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 Composing messages, File transfer, Groupchat, Top
|
|
@chapter Composing messages
|
|
|
|
@findex jabber-compose
|
|
@cindex composing messages
|
|
@cindex message composition
|
|
|
|
The chat buffer interface can be inconvenient for some purposes. As you
|
|
can't use @kbd{RET} to insert a newline (use @kbd{C-j} for that),
|
|
writing a longer message can be painful. Also, it is not possible to
|
|
include a subject in the message, or send the message to multiple
|
|
recipients.
|
|
|
|
These features are implemented by the message composing tool. Type
|
|
@kbd{M-x jabber-compose} to start it. In the buffer that comes up, you
|
|
can specify recipients, enter a subject, and type your message.
|
|
|
|
@node File transfer, Services, Composing messages, Top
|
|
@chapter File transfer
|
|
|
|
@cindex File transfer
|
|
@cindex Sending files
|
|
|
|
jabber.el has limited support for file transfer. The most important
|
|
limit is that files sent and received are kept in buffers, so Emacs must
|
|
be able to allocate enough memory for the entire file, and the file size
|
|
must be smaller than the maximum buffer size.@footnote{The maximum
|
|
buffer size depends on in the variable @code{most-positive-fixnum}. On
|
|
32-bit systems, this is 128 or 256 megabytes, depending on your
|
|
Emacs version.}
|
|
|
|
jabber.el is able to exchange files with most Jabber clients (and also
|
|
some MSN transports), but notably not with the official Google Talk
|
|
client. The Google Talk client uses a different file transfer protocol
|
|
which, at the time of this release, has not been published.
|
|
|
|
@menu
|
|
* Receiving files::
|
|
* Sending files::
|
|
@end menu
|
|
|
|
@node Receiving files, Sending files, , File transfer
|
|
@section Receiving files
|
|
|
|
Receiving files requires no configuration. When someone wants to send a
|
|
file to you, you are asked (through @code{yes-or-no-p}) whether you want
|
|
to accept the file. If you answer yes, you get to choose where to save
|
|
the file.
|
|
|
|
If the sender's client is correctly configured (this is often not the
|
|
case; see below), the file transfer will start. Currently, the only way
|
|
to watch the progress is to inspect the buffer of the file being
|
|
transfered; @kbd{C-x C-b} is one way of doing that. @xref{List Buffers,
|
|
, Listing Existing Buffers, emacs, GNU Emacs Manual}. When the transfer
|
|
is done, the message ``@var{file} downloaded'' appears in the echo area,
|
|
and the buffer is killed.
|
|
|
|
@c This truly sucks...
|
|
If this doesn't happen, it is most likely the sender's fault. The
|
|
sender needs to have a public IP address, either directly, through port
|
|
forwarding (in which case the client needs to be configured with the
|
|
real public IP address), or through an XEP-0065 proxy. If you have
|
|
activated XML logging (@pxref{Debug options}), you can see the IP
|
|
address that the other client is asking you to connect to there. Often
|
|
you will find that this is an internal IP address (often starts with
|
|
@code{192.168}). See the documentation of the sender's client for
|
|
setting this up.
|
|
|
|
@node Sending files, , Receiving files, File transfer
|
|
@section Sending files
|
|
|
|
@cindex proxy, file transfer
|
|
@cindex file transfer proxy
|
|
@cindex XEP-0065 proxy
|
|
|
|
To send a file to someone, you need an XEP-0065 proxy.@footnote{This
|
|
requirement is not inherent in the protocol, only in the current file
|
|
transfer implementation of jabber.el, and in Emacs versions earlier than
|
|
22.} If your Jabber server hosts such a proxy, it will be found
|
|
automatically, otherwise it needs to be manually configured.
|
|
|
|
You can check whether your Jabber server has a proxy with @kbd{M-x
|
|
jabber-get-disco-items}; see @ref{Service discovery}.
|
|
|
|
@vindex jabber-socks5-proxies
|
|
@findex jabber-socks5-query-all-proxies
|
|
To configure a proxy manually, customize the variable
|
|
@code{jabber-socks5-proxies}. Putting @code{proxy.jabber.se} there
|
|
should work. Type @kbd{M-x jabber-socks5-query-all-proxies} to see if
|
|
the proxies answer.
|
|
|
|
@findex jabber-ft-send
|
|
Now, you can type @kbd{M-x jabber-ft-send} to send a file to someone.
|
|
You need to enter the correct full JID, including resource, to get this
|
|
right. If the contact is logged in with only one client, and you can
|
|
see it online, just typing the JID or roster name is enough. If you run
|
|
the command from a chat buffer, the JID of the contact is given as
|
|
the default value.
|
|
|
|
If the contact has several clients online, you probably want to send the
|
|
file to a particular one. If you run this command from within a chat
|
|
buffer, the default target will be the one that last sent a message to
|
|
you. If you just type a bare JID or a roster name, the client with the
|
|
highest priority will get the file.
|
|
|
|
If the contact accepts the file, and the contact's client succeeds in
|
|
connecting to the proxy, jabber.el will send the file through the
|
|
proxy. During this time, your Emacs will be blocked, so you might want
|
|
to avoid sending large files over slow connections.
|
|
|
|
@node Services, Personal information, File transfer, 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.
|
|
|
|
You can change the buffer name template by customizing
|
|
the variable @code{jabber-browse-buffer-format}.
|
|
|
|
@menu
|
|
* Commands::
|
|
* Your home server::
|
|
* Transports::
|
|
* User directories::
|
|
* MUC services::
|
|
@end menu
|
|
|
|
@node Commands, Your home server, , Services
|
|
@section Commands
|
|
|
|
A small number of commands is used for almost all interaction with
|
|
Jabber services. Essentially, they are all the same: you request a form
|
|
from the server, fill it in, and send it back.
|
|
|
|
Most of these commands are available under the Service menu, which is
|
|
opened by typing @kbd{C-c C-s}. Service discovery is under the Info
|
|
menu instead, which is available under @kbd{C-c C-i}.
|
|
|
|
@menu
|
|
* Registration::
|
|
* Search::
|
|
* Ad-Hoc Commands::
|
|
* Service discovery::
|
|
* Browsing::
|
|
@end menu
|
|
|
|
@node Registration, Search, , Commands
|
|
@subsection Registration
|
|
|
|
@cindex Registration
|
|
@findex jabber-get-register
|
|
|
|
You can get a registration form for a service by typing @kbd{M-x
|
|
jabber-get-register} and entering the JID of the service. On success,
|
|
you get a single-stage form to fill in.
|
|
|
|
There are two buttons at the bottom of the form, ``Submit'' and ``Cancel
|
|
registration''. ``Submit'' does what you would expect it to, but
|
|
``Cancel registration'' cancels any existing registration with the
|
|
service. Whichever of them you choose, you get a message in the echo
|
|
area informing whether the operation succeeded.
|
|
|
|
@node Search, Ad-Hoc Commands, Registration, Commands
|
|
@subsection Search
|
|
|
|
@cindex Search
|
|
@findex jabber-get-search
|
|
|
|
You can get a search form for a service by typing @kbd{M-x
|
|
jabber-get-search}. This gives you a single-stage form to fill in.
|
|
After you press the ``Submit'' button at the bottom, the search results
|
|
will be displayed in the same buffer.
|
|
|
|
@node Ad-Hoc Commands, Service discovery, Search, Commands
|
|
@subsection Ad-Hoc Commands
|
|
|
|
@cindex Ad-Hoc Commands
|
|
@findex jabber-ahc-get-list
|
|
@findex jabber-ahc-execute-command
|
|
|
|
jabber.el supports a subset of XEP-0050, the standard for Ad-Hoc
|
|
Commands. As the name implies, this can be used for just about
|
|
anything. In particular, it is used not only by services, but also by
|
|
clients (e.g. Psi, and jabber.el itself).
|
|
|
|
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.)
|
|
|
|
What happens next depends on the command and the service. In some
|
|
cases, the service just responds that the command has been run. You may
|
|
also get a form to fill out. This form may have multiple stages, in
|
|
which case there are ``Next'' and ``Previous'' buttons for navigating
|
|
between stages. You may also see ``Complete'', which runs the command
|
|
skipping any remaining stages of the form, and ``Cancel'', which cancels
|
|
the command.
|
|
|
|
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 from any JID from
|
|
@code{jabber-account-list}. So, you can add disabled JIDs in
|
|
@code{jabber-account-list} to allow them control your
|
|
presence.@footnote{Most Jabber servers also support kicking a client off
|
|
the net by logging in with another client with exactly the same
|
|
resource.}
|
|
|
|
@node Service discovery, Browsing, Ad-Hoc Commands, Commands
|
|
@subsection Service discovery
|
|
|
|
@cindex Service discovery
|
|
@findex jabber-get-disco-items
|
|
@findex jabber-get-disco-info
|
|
|
|
Service discovery is used to find information about servers, services
|
|
and clients. There are two kinds of requests: find @dfn{info} about a
|
|
Jabber entity---i.e. its identity and supported features---and find
|
|
@dfn{items} related to an entity, where the definition of ``related'' is
|
|
left to the entity itself.
|
|
|
|
The commands to execute such requests are @code{jabber-get-disco-info}
|
|
and @code{jabber-get-disco-items}, respectively. These commands can be
|
|
accessed from the Info menu, which is opened by typing @kbd{C-c C-i}.
|
|
The commands accept a JID and optionally a ``node''.
|
|
|
|
The result of such a command is displayed in a browse buffer. For an
|
|
info request, the result just lists the identities and features of the
|
|
entity. For an item request, the related items are listed. The items
|
|
may be JIDs, or JIDs with a node. If you put point on one of the items,
|
|
its JID and node will be the default value for any Jabber command.
|
|
|
|
If you think that the interface to service discovery is awkward and
|
|
should be replaced with something better, you are completely right.
|
|
|
|
@node Browsing, , Service discovery, Commands
|
|
@subsection Browsing
|
|
|
|
@cindex Browsing
|
|
@findex jabber-get-browse
|
|
|
|
Before service discovery, browsing was the way to find information about
|
|
Jabber entities. Nowadays it is all but superseded, but jabber.el still
|
|
supports it. You can use it by typing @kbd{M-x jabber-get-browse}. It
|
|
works much like service discovery.
|
|
|
|
@node Your home server, Transports, Commands, Services
|
|
@section Your home server
|
|
|
|
@cindex Password change
|
|
@cindex Changing password
|
|
@cindex Account removal
|
|
@cindex Removing an account
|
|
|
|
You can interact with your Jabber server to change your password or
|
|
remove your account. Both of these can be accomplished by typing
|
|
@kbd{M-x jabber-get-register} and typing the JID of your server;
|
|
@pxref{Registration}.
|
|
|
|
|
|
@node Transports, User directories, Your home server, Services
|
|
@section Transports to other IM networks
|
|
|
|
@cindex Gateways
|
|
@cindex Transports
|
|
@cindex MSN transport
|
|
@cindex ICQ transport
|
|
@cindex AIM transport
|
|
|
|
Some Jabber services make it possible to communicate with users on other
|
|
instant messaging networks (e.g. MSN, ICQ, AIM), in effect turning your
|
|
Jabber client into a multi-protocol client. These are called
|
|
@dfn{gateways} or @dfn{transports}. They work by impersonating you on
|
|
the legacy network; therefore you need to provide your username and
|
|
password through registration.
|
|
|
|
@subsection Finding a transport
|
|
|
|
To use such a transport, you first need to find one, obviously.
|
|
Sometimes your home server provides the transports you need, but you are
|
|
not limited to those; in principle you can use any transport on the
|
|
Jabber network. Some transports only accept local users, though.
|
|
|
|
Transports are generally mentioned on the web page of the Jabber server
|
|
in question. You can also find transports from within the client;
|
|
@pxref{Service discovery}.
|
|
|
|
@subsection Registering with a transport
|
|
|
|
To register with a transport, type @kbd{M-x jabber-get-register} and
|
|
enter the JID of the transport. This will open a registration form
|
|
where you get to fill in your login information; @pxref{Registration}.
|
|
You can later use this same form to change the information or cancel
|
|
your registration.
|
|
|
|
After you have registered, the transport will request presence
|
|
subscription. It needs that to know when you are online, and
|
|
synchronize your presence on the legacy network.
|
|
|
|
@subsection Contact list
|
|
|
|
Once you are registered, the transport will transfer the contact list
|
|
from the legacy service. From the Jabber side, it appears as if lots of
|
|
people suddenly request presence subscription to you. This is somewhat
|
|
inconvenient, but it is currently the only way that the transport can
|
|
influence your Jabber contact list, as it is an entity external to your
|
|
server.@footnote{Of course, jabber.el could do more to alleviate this
|
|
inconvenience.}
|
|
|
|
When you have accepted these presence subscriptions, the contacts from
|
|
legacy networks appear as if they were Jabber contacts.
|
|
|
|
@subsection Finding users
|
|
|
|
Some legacy networks have a global database of users, and some
|
|
transports support searching that database. In that case, you can
|
|
search for other users with @kbd{M-x jabber-get-search};
|
|
@pxref{Search}.
|
|
|
|
@node User directories, MUC services, Transports, Services
|
|
@section User directories
|
|
|
|
There are some Jabber user directories, usually abbreviated JUDs. The
|
|
most well-known one is @samp{users.jabber.org}. You can register with
|
|
such a directory to let other people find you (@pxref{Registration}),
|
|
and you can search the directory (@pxref{Search}).
|
|
|
|
@node MUC services, , User directories, Services
|
|
@section MUC services
|
|
|
|
MUC services (Multi-User Chat, chat rooms) are usually not operated by
|
|
these commands, but by commands specific to the MUC protocol;
|
|
@pxref{Groupchat}. However, some MUC services offer nickname
|
|
registration through the registration protocol (@pxref{Registration}),
|
|
and other commands; @pxref{Ad-Hoc Commands}.
|
|
|
|
@node Personal information, Avatars, 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.@footnote{@xref{XEP-0054}.}
|
|
You can get information about a user by running @kbd{M-x
|
|
jabber-vcard-get}, @kbd{M-x jabber-muc-vcard-get} if you in MUC (also
|
|
available in the MUC menu), 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 @samp{[INS]} and @samp{[DEL]} buttons,
|
|
respectively.
|
|
|
|
This is also where you set your avatar (@pxref{Avatars}). The size of
|
|
your avatar file is limited to 8 kilobytes.
|
|
|
|
@node Avatars, Time queries, Personal information, Top
|
|
@chapter Avatars
|
|
|
|
@cindex avatars
|
|
@vindex jabber-vcard-avatars-retrieve
|
|
@vindex jabber-vcard-avatars-publish
|
|
@vindex jabber-avatar-cache-directory
|
|
@vindex jabber-chat-buffer-show-avatar
|
|
|
|
jabber.el supports viewing and publishing avatars according to XEP-0153,
|
|
vCard-Based Avatars. By default, if you have an avatar in your vCard
|
|
(@pxref{Personal information}), it will be published for others to see,
|
|
and if other people publish their avatars, they will be displayed in the
|
|
roster buffer and in the header line of chat buffers, if your Emacs can
|
|
display images. Otherwise, jabber.el will not fetch avatars at all.
|
|
|
|
To disable retrieval of other people's avatars, set
|
|
@code{jabber-vcard-avatars-retrieve} to nil. To disable publishing of
|
|
your own avatar, set @code{jabber-vcard-avatars-publish} to nil. To
|
|
disable avatars in chat buffer header lines, set
|
|
@code{jabber-chat-buffer-show-avatar} to nil.
|
|
|
|
There are a number of restrictions on avatar images in the
|
|
specification. Most of them are not enforced by jabber.el.
|
|
@itemize @bullet
|
|
@item
|
|
The image should be smaller than 8 kilobytes; this is enforced by
|
|
jabber.el.
|
|
@item
|
|
The image height and width should be between 32 and 96 pixels; the
|
|
recommended size is 64 by 64 pixels.
|
|
@item
|
|
The image should be square.
|
|
@item
|
|
The image should be in either PNG, GIF, or JPEG format. (jabber.el will
|
|
behave incorrectly if the image is not in a format supported by Emacs.)
|
|
@end itemize
|
|
|
|
Avatars are cached in the directory specified by
|
|
@code{jabber-avatar-cache-directory}, by default
|
|
@file{~/.emacs.d/jabber-avatar-cache/}.@footnote{The default directory
|
|
used to be @file{~/.jabber-avatars}. If this directory already
|
|
exists, it will be used.} The cache is never cleaned, so you might
|
|
want to do that yourself from time to time.
|
|
|
|
@node Time queries, Useful features, Avatars, Top
|
|
@chapter Time queries
|
|
|
|
@cindex time query
|
|
@findex jabber-get-time
|
|
With @kbd{M-x jabber-get-time}, you can ask what time an entity (client,
|
|
server or component) thinks it is, and what time zone it thinks it is
|
|
in.
|
|
|
|
@cindex last online
|
|
@findex jabber-get-last-online
|
|
You can query a server about when a certain user was last seen online.
|
|
Use @kbd{M-x jabber-get-last-online} for that.
|
|
|
|
@cindex uptime, query
|
|
@cindex idle time, query
|
|
@findex jabber-get-idle-time
|
|
You can also ask a client about how long a user has been idle with
|
|
@kbd{M-x jabber-get-idle-time}. Not all clients answer such queries,
|
|
e.g. jabber.el doesn't. This command can also tell the uptime of a
|
|
server or component.
|
|
|
|
The first of these commands uses the old Entity Time protocol
|
|
(@pxref{XEP-0090}). It has been superseded by XEP-0202, but jabber.el
|
|
doesn't implement the newer protocol yet. The latter two commands use
|
|
the Last Activity protocol (@pxref{XEP-0012}).
|
|
|
|
@node Useful features, Message history, Time queries, 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::
|
|
* Reconnecting::
|
|
* Tracking activity::
|
|
* Watch buddies::
|
|
* Spell checking::
|
|
* Gmail notifications::
|
|
* Saving groups roll state::
|
|
@end menu
|
|
|
|
@node Autoaway, Modeline status, , Useful features
|
|
@section Autoaway
|
|
|
|
@cindex autoaway
|
|
@cindex idle
|
|
@cindex xprintidle
|
|
@vindex jabber-autoaway-method
|
|
@vindex jabber-autoaway-methods
|
|
@findex jabber-current-idle-time
|
|
@findex jabber-xprintidle-program
|
|
@findex jabber-termatime-get-idle-time
|
|
@vindex jabber-autoaway-timeout
|
|
@vindex jabber-autoaway-xa-timeout
|
|
@vindex jabber-autoaway-status
|
|
@vindex jabber-autoaway-xa-status
|
|
@vindex jabber-autoaway-priority
|
|
@vindex jabber-autoaway-xa-priority
|
|
|
|
It is possible to automatically set your status to ``away'' or ``xa''
|
|
when you haven't used your computer for a while. This lets your
|
|
contacts know that you might not answer immediately. You can customize
|
|
timeouts (@code{jabber-autoaway-timeout},
|
|
@code{jabber-autoaway-xa-timeout}), statuses
|
|
(@code{jabber-autoaway-status}, @code{jabber-autoaway-xa-status}) and
|
|
priorityes (@code{jabber-autoaway-priority},
|
|
@code{jabber-autoaway-xa-priority}) to set.
|
|
|
|
To activate this feature, add @code{jabber-autoaway-start} to
|
|
@code{jabber-post-connect-hooks}, e.g:
|
|
@example
|
|
(add-hook 'jabber-post-connect-hooks 'jabber-autoaway-start)
|
|
@end example
|
|
|
|
There are different methods to find how long you have been ``idle''.
|
|
The method(s) to use is specified by @code{jabber-autoaway-methods}
|
|
(obsoleted @code{jabber-autoaway--method} will also work). The value
|
|
of this variable should be a list functions that returns the number of
|
|
seconds you have been idle (or nil on error). Minimum of values,
|
|
returned by these functions, is used as ``idle'' time, so default
|
|
should works well. Three functions are provided (all used by default).
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{jabber-current-idle-time} is used if your Emacs has the
|
|
@code{current-idle-time} function (which was introduced in Emacs 22).
|
|
Note that this method only measures the time since you last interacted
|
|
with Emacs, and thus disregards activity in other programs.
|
|
|
|
@item
|
|
@code{jabber-xprintidle-get-idle-time} uses xprintidle
|
|
@footnote{@uref{http://www.dtek.chalmers.se/~henoch/text/xprintidle.html}}
|
|
program, if found. You can also manually set
|
|
@code{jabber-xprintidle-program} to the correct file path. This method
|
|
uses the same method as
|
|
@uref{http://www.jwz.org/xscreensaver,XScreensaver} to find your idle
|
|
time.
|
|
|
|
@item
|
|
@code{jabber-termatime-get-idle-time} used on GNU/Linux terminals. It
|
|
uses the access time of the terminal device as a measure of idle time.
|
|
|
|
@end itemize
|
|
|
|
@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, Reconnecting, Modeline status, Useful features
|
|
@section Keepalive
|
|
|
|
@cindex Keepalive
|
|
@cindex Detecting lost connections
|
|
|
|
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.
|
|
|
|
On the other hand, the server may want to do the same kind of
|
|
detection, and may expect the client to send something at regular
|
|
intervals.
|
|
|
|
If you want to detect a lost connection earlier, or make sure that the
|
|
server doesn't drop your connection, you can use the
|
|
keepalive functions. These come in two flavours: whitespace pings and
|
|
XMPP pings.
|
|
|
|
@subsection Whitespace pings
|
|
@cindex Whitespace pings
|
|
|
|
A @dfn{whitespace ping} is a single space character sent to the server.
|
|
This is often enough to make NAT devices consider the connection
|
|
``alive'', and likewise for certain Jabber servers, e.g. Openfire. It
|
|
may also make the OS detect a lost connection faster---a TCP connection
|
|
on which no data is sent or received is indistinguishable from a lost
|
|
connection.
|
|
|
|
@findex jabber-whitespace-ping-start
|
|
@findex jabber-whitespace-ping-stop
|
|
Type @kbd{M-x jabber-whitespace-ping-start} to start it, and @kbd{M-x
|
|
jabber-whitespace-ping-stop} to stop it. The former is in
|
|
@code{jabber-post-connect-hooks} by default; @pxref{Hooks}.
|
|
|
|
@vindex jabber-whitespace-ping-interval
|
|
The frequency of whitespace pings is controlled by the variable
|
|
@code{jabber-whitespace-ping-interval}. The default value is once every
|
|
30 seconds.
|
|
|
|
@subsection XMPP pings
|
|
|
|
These functions work by sending a ping request to your server 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).
|
|
|
|
@findex jabber-keepalive-start
|
|
@findex jabber-keepalive-stop
|
|
Type @kbd{M-x jabber-keepalive-start} to start
|
|
it, and @kbd{M-x jabber-keepalive-stop} to stop it. You may want to add
|
|
@code{jabber-keepalive-start} to @code{jabber-post-connect-hooks};
|
|
@pxref{Hooks}.
|
|
|
|
@vindex jabber-keepalive-interval
|
|
@vindex jabber-keepalive-timeout
|
|
You can customize the interval and the timeout with the variables
|
|
@code{jabber-keepalive-interval} and @code{jabber-keepalive-timeout},
|
|
respectively.
|
|
|
|
@findex jabber-ping
|
|
You can also manually ping some client/server by using @kbd{M-x
|
|
jabber-ping}. Note that pong will be displayed according
|
|
@code{jabber-alerts-info-messages-hooks} (default is echo in
|
|
minibuffer).
|
|
|
|
@node Reconnecting, Tracking activity, Keepalive, Useful features
|
|
@section Reconnecting
|
|
|
|
@cindex Reconnect
|
|
@cindex Automatic reconnection
|
|
@vindex jabber-auto-reconnect
|
|
|
|
jabber.el supports automatic reconnection to Jabber server(s) upon lost
|
|
connection. By default it is off. To turn on, customize
|
|
the @code{jabber-auto-reconnect} variable.
|
|
|
|
This is of limited use if you have to type your password every time
|
|
jabber.el reconnects. There are two ways to save your password: you can
|
|
set it in @code{jabber-account-alist} (@pxref{Account settings}), and
|
|
you can use @file{password-cache.el}, which is available in
|
|
recent versions of Gnus and in Emacs 23. Note that you probably want to
|
|
customize @code{password-cache-expiry} if you use the latter.
|
|
|
|
@node Tracking activity, Watch buddies, Reconnecting, 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 @code{jabber-activity-mode} is enabled (by default, it is), Emacs keeps
|
|
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}.
|
|
|
|
To hide activity notifications for some contacts, use
|
|
@code{jabber-activity-banned} variable - just add boring JIDs (as
|
|
regexps) here.
|
|
|
|
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, Gmail notifications, 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, @pxref{Spelling, ,
|
|
Checking and Correcting Spelling, emacs, GNU Emacs Manual}.
|
|
|
|
@node Gmail notifications, Saving groups roll state, Spell checking, Useful features
|
|
@section Gmail notifications
|
|
|
|
@cindex Gmail notifications
|
|
|
|
If you are connected to a Google Talk account, you can receive
|
|
notifications when a new Gmail message arrives. Gmail notifications
|
|
are enabled by adding the following line to your @file{.emacs}:
|
|
|
|
@example
|
|
(add-hook 'jabber-post-connect-hooks 'jabber-gmail-subscribe)
|
|
@end example
|
|
|
|
Default behavior is to display a message that mentions the number of
|
|
received gmails. You can customize this behavior by providing your
|
|
own @code{jabber-gmail-dothreads} function.
|
|
|
|
Example:
|
|
|
|
@example
|
|
(eval-after-load "jabber-gmail"
|
|
'(defun jabber-gmail-dothreads (threads)
|
|
"Process <mail-thread-info/> elements.
|
|
THREADS is a list of XML sexps corresponding to <mail-thread-info/>
|
|
elements.
|
|
See http://code.google.com/apis/talk/jep_extensions/gmail.html#response"
|
|
(osd "gmail: %d" (length threads))))
|
|
|
|
;;; It's usually a good idea to have a shortcut for querying GTalk server.
|
|
(global-set-key (kbd "<f9> g") 'jabber-gmail-query)
|
|
|
|
;;; The definition of `osd' function used by `jabber-gmail-dothreads'.
|
|
;;; `osd_cat' is shipped with the X OSD library
|
|
;;; [http://www.ignavus.net/software.html].
|
|
(if (and (display-graphic-p) (file-executable-p "/usr/bin/osd_cat"))
|
|
(defun osd (fmt &rest args)
|
|
"Display message on X screen."
|
|
(let ((opts "-p bottom -A center -l 1 \
|
|
-f '-adobe-helvetica-bold-r-*-*-24-*-*-*-*-*-iso10646-1'")
|
|
(msg (apply 'format (concat fmt "\n") args)))
|
|
(start-process "osd" nil shell-file-name shell-command-switch
|
|
(format "echo %s | osd_cat %s"
|
|
(shell-quote-argument msg) opts))))
|
|
(defalias 'osd 'message))
|
|
@end example
|
|
|
|
@node Saving groups roll state, , Gmail notifications, Useful features
|
|
@section Saving groups roll state
|
|
|
|
@cindex Saving groups roll state
|
|
|
|
You can save roster's groups rollup/rolldown state between sessions.
|
|
To do this you need to add @code{jabber-roster-save-groups} to
|
|
@code{jabber-pre-disconnect-hook} and
|
|
@code{jabber-roster-restore-groups} to
|
|
@code{jabber-post-connect-hooks}, respectively.
|
|
|
|
State saved in private storage on server-side (for each account). Note
|
|
that state restoring working by rolling up groups, rolled up at state
|
|
saving (by default, all groups rolled down). Also note that at now,
|
|
@code{jabber-pre-disconnect-hook} run only with
|
|
@code{jabber-disconnect} (not with @code{jabber-disconnect-one}).
|
|
|
|
|
|
@node Message history, Typing notifications, Useful features, Top
|
|
@chapter Message history
|
|
|
|
@cindex History
|
|
@cindex Backlog
|
|
@findex jabber-truncate-top
|
|
@findex jabber-truncate-muc
|
|
@findex jabber-truncate-chat
|
|
@vindex jabber-history-enabled
|
|
@vindex jabber-history-muc-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
|
|
@vindex jabber-log-lines-to-keep
|
|
|
|
If you want a record of messages sent and received, set
|
|
@code{jabber-history-enabled} to t. If you also want record MUC
|
|
groupchat messages, set @code{jabber-history-muc-enabled} to t.
|
|
Messages will be saved in one file per contact in the directory
|
|
specified by the variable @code{jabber-history-dir} (the default is
|
|
@file{~/.emacs.d/jabber-history}). If you prefer to store messages
|
|
for all contacts in a single file, set
|
|
@code{jabber-use-global-history} to @code{t} and set
|
|
@code{jabber-global-history-filename} as required.@footnote{Using a
|
|
global history file used to be the default. If the file specified by
|
|
@code{jabber-global-history-filename} exists,
|
|
@code{jabber-use-global-history} will default to @code{t} to support
|
|
existing installations.}
|
|
|
|
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).
|
|
|
|
@findex jabber-chat-display-more-backlog
|
|
If you want to see more messages, use the function
|
|
@code{jabber-chat-display-more-backlog}, available in the Chat menu.
|
|
This is currently the only way to view the message history, apart from
|
|
opening the history files manually.
|
|
|
|
@cindex Rotation of history files
|
|
@cindex History file rotation
|
|
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 @var{history-file} is renamed to
|
|
@file{@var{history-file}-@var{number}}, where @var{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 @samp{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.
|
|
|
|
@cindex Truncate
|
|
@cindex Truncation
|
|
If you also want to keep chat and groupchat buffers from growing too
|
|
much, you can customize @code{jabber-alert-message-hooks} and
|
|
@code{jabber-alert-muc-hooks} by adding truncation upon receiving
|
|
message (@code{jabber-truncate-chat} and @code{jabber-truncate-muc}, respectively).
|
|
The truncation limit may be set by customizing the variable
|
|
@code{jabber-log-lines-to-keep}.
|
|
|
|
@node Typing notifications, Roster import and export, Message history, Top
|
|
@chapter Typing notifications
|
|
|
|
There are two protocols for ``contact is typing'' notifications in
|
|
Jabber. jabber.el supports both of them, displaying various information
|
|
in the header line of chat buffers.
|
|
|
|
@section 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
|
|
|
|
The older protocol is called Message Events (@pxref{XEP-0022}). Besides
|
|
typing notification, it lets you know what happens to the messages you send.
|
|
These states are possible:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@samp{In offline storage} (the user will receive it on next logon)
|
|
|
|
@item
|
|
@samp{Delivered} to user's client (but not necessarily displayed)
|
|
|
|
@item
|
|
@samp{Displayed} to user
|
|
|
|
@item
|
|
User is @samp{typing a message}
|
|
|
|
@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}.
|
|
|
|
@section Chat states
|
|
|
|
@vindex jabber-chatstates-confirm
|
|
|
|
The newer protocol is called Chat States (@pxref{XEP-0085}). Rather
|
|
than dealing with individual messages, it describes the state of the
|
|
chat session between two people. The following states are possible:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Active (the default state, not displayed)
|
|
|
|
@item
|
|
Inactive
|
|
|
|
@item
|
|
Composing
|
|
|
|
@item
|
|
Paused (i.e., taking a short pause in composing)
|
|
|
|
@item
|
|
Gone
|
|
|
|
@end itemize
|
|
|
|
jabber.el can display all five states, but only ever sends ``active''
|
|
and ``composing'' itself.
|
|
|
|
To customize sending of chat states, customize the variable
|
|
@code{jabber-chatstates-confirm}.
|
|
|
|
|
|
@node Roster import and export, XMPP URIs, Typing notifications, 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.
|
|
|
|
For any of these methods, you need to make sure that you are running
|
|
the Emacs server. @xref{Emacs Server, , Using Emacs as a Server,
|
|
emacs, GNU Emacs Manual}, though the simplest way to start it is to
|
|
customize the variable @code{server-mode}.
|
|
|
|
@section GNOME
|
|
|
|
The jabber.el distribution contains a GConf schema which tries to set
|
|
up handling of @samp{xmpp:} URIs. It is installed by @samp{make
|
|
install}. This may or may not work, depending on your GConf
|
|
configuration and other installed applications. To check, try
|
|
running:
|
|
|
|
@example
|
|
gconftool --get /desktop/gnome/url-handlers/xmpp/command
|
|
@end example
|
|
|
|
This should print something like:
|
|
|
|
@example
|
|
/usr/local/libexec/emacs-jabber-uri-handler "%s"
|
|
@end example
|
|
|
|
This setting is picked up by most GNOME or GTK based web browsers,
|
|
including Firefox.
|
|
|
|
@section Mozilla and Unix
|
|
|
|
If you use a Mozilla-based web browser on a Unix-like operating
|
|
system, and the GConf method above doesn't work, you can set it up
|
|
manually by following these steps:
|
|
|
|
@enumerate
|
|
|
|
@item
|
|
Note the path of the @file{emacs-jabber-uri-handler} 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{emacs-jabber-uri-handler}. 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}/emacs-jabber-uri-handler");
|
|
@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::
|
|
* Menu::
|
|
* Customizing the roster buffer::
|
|
* Customizing the chat buffer::
|
|
* Customizing alerts::
|
|
* Hooks::
|
|
* Debug options::
|
|
@end menu
|
|
|
|
@node Account settings, Menu, , Customization
|
|
@section Account settings
|
|
|
|
@cindex Username
|
|
@cindex Resource
|
|
@cindex Password
|
|
@cindex JID
|
|
@cindex Network server
|
|
|
|
@vindex jabber-account-list
|
|
All account settings reside in the variable @code{jabber-account-list}.
|
|
Usually you only need to set the JID, in the form
|
|
@samp{username@@server} (or @samp{username@@server/resource} to use a
|
|
specific resource name). These are the other account options:
|
|
|
|
@table @asis
|
|
@item Disabled
|
|
If the account is disabled, @code{jabber-connect-all} will not attempt
|
|
to connect it. You can still connect it manually with
|
|
@code{jabber-connect}.
|
|
|
|
@item Password
|
|
You can set the password of the account, so you don't have to enter it
|
|
when you connect. Note that it will be stored unencrypted in your
|
|
customization file.
|
|
|
|
@item Network server
|
|
If the JID of the Jabber server is not also its DNS name, you may have
|
|
to enter the real DNS name or IP address of the server here.
|
|
|
|
@item Connection type
|
|
This option specifies whether to use an encrypted connection to the
|
|
server. Usually you want ``STARTTLS'' (@code{starttls}), which means
|
|
that encryption is activated if the server supports it. The other
|
|
possibilities are ``unencrypted'' (@code{network}), which means just
|
|
that, and ``legacy SSL/TLS'' (@code{ssl}), which means that encryption
|
|
is activated on connection.
|
|
|
|
@item Port
|
|
If the Jabber server uses a nonstandard port, specify it here. The
|
|
default is 5222 for STARTTLS and unencrypted connections, and 5223 for
|
|
legacy SSL connections.
|
|
@end table
|
|
|
|
@subsection For Google Talk
|
|
|
|
@cindex Google Talk
|
|
|
|
If you have a very new version of @file{dns.el},@footnote{Specifically,
|
|
you need Emacs 23, or No Gnus 0.3.} you can connect to
|
|
Google Talk just by specifying your Gmail address as JID. Otherwise,
|
|
you also need to set
|
|
``network server'' to @kbd{talk.google.com} and ``connection type'' to
|
|
``legacy SSL''.
|
|
|
|
See also @ref{Gmail notifications}.
|
|
|
|
@subsection Upgrade note
|
|
|
|
Previous versions of jabber.el had the variables @code{jabber-username},
|
|
@code{jabber-server}, @code{jabber-resource} and
|
|
@code{jabber-password}. These are now obsolete and not used.
|
|
|
|
@node Menu, Customizing the roster buffer, Account settings, Customization
|
|
@section Menu
|
|
|
|
@vindex jabber-display-menu
|
|
@cindex Menus
|
|
There is a Jabber menu on the menu bar with some common commands. By
|
|
default, it is displayed only if you are connected, or if you have
|
|
configured any accounts. You can set the variable
|
|
@code{jabber-display-menu} to @code{t} or @code{nil}, to have the menu
|
|
displayed always or never, respectively. The default behaviour
|
|
corresponds to the setting @code{maybe}.
|
|
|
|
@findex jabber-menu
|
|
Earlier, the way to have the menu appear was to call the function
|
|
@code{jabber-menu}. It still works, but is considered obsolete.
|
|
|
|
@node Customizing the roster buffer, Customizing the chat buffer, Menu, Customization
|
|
@section Customizing the roster buffer
|
|
|
|
@cindex Roster buffer, customizing
|
|
|
|
@cindex Sorting the roster
|
|
@vindex jabber-roster-sort-functions
|
|
@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.
|
|
|
|
@vindex jabber-sort-order
|
|
@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.
|
|
|
|
@vindex jabber-show-resources
|
|
@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.
|
|
|
|
@vindex jabber-roster-line-format
|
|
@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 %a
|
|
Avatar of contact, if any
|
|
@item %c
|
|
@samp{*} if the contact is connected, or @samp{ } if not
|
|
@item %u
|
|
Subscription state---see below
|
|
@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 a string ("Online", "Away" etc)
|
|
@item %S
|
|
Status string specified by contact
|
|
@end table
|
|
|
|
@code{jabber-roster-show-title} controls whether to show a "Jabber
|
|
roster" string 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.
|
|
|
|
@code{%u} is replaced by one of the strings given by
|
|
`jabber-roster-subscription-display'.
|
|
|
|
@vindex jabber-resource-line-format
|
|
@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.
|
|
|
|
@vindex jabber-roster-buffer
|
|
@code{jabber-roster-buffer} specifies the name of the roster buffer.
|
|
If you change this, the new name will be used the next time the roster
|
|
is redisplayed.
|
|
|
|
@vindex jabber-roster-show-bindings
|
|
@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 text (i.e. what you write) and foreign text
|
|
(i.e. what other people write).
|
|
|
|
@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
|
|
@vindex jabber-muc-colorize-local
|
|
@vindex jabber-muc-colorize-foreign
|
|
@vindex jabber-muc-nick-saturation
|
|
@vindex jabber-muc-nick-value
|
|
@vindex jabber-muc-participant-colors
|
|
@cindex Nick coloring
|
|
@code{jabber-chat-prompt-local} and @code{jabber-chat-prompt-foreign}
|
|
determine the faces used for the prompts. You can also turn on
|
|
automatic colorization of local (@code{jabber-muc-colorize-local})
|
|
and/or foreign (@code{jabber-muc-colorize-foreign}) prompts. By
|
|
default it is off. You can correct and save for future use auto-generated colors by
|
|
customizing @code{jabber-muc-participant-colors}, @code{jabber-muc-nick-saturation} and
|
|
@code{jabber-muc-nick-value}, if you wish.
|
|
|
|
@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 %u
|
|
The username of the user (i.e. the first part of the JID).
|
|
@item %r
|
|
The resource.
|
|
@item %j
|
|
The bare JID of the user
|
|
@end table
|
|
|
|
@cindex Timestamp format
|
|
@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.
|
|
|
|
@cindex Rare timestamps
|
|
@vindex jabber-print-rare-time
|
|
@vindex jabber-rare-time-format
|
|
@vindex jabber-chat-text-local
|
|
By 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.
|
|
|
|
@cindex Header line of chat buffers
|
|
@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 wrapped.
|
|
|
|
@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
|
|
@noindent
|
|
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. @xref{Contacts}.
|
|
|
|
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 to and from the hook. For other purposes, there
|
|
are corresponding general hooks, that are defvars instead of
|
|
defcustoms, and that are meant to be managed by Lisp code. They have the
|
|
same name as the alert hooks minus the @code{-alert} part,
|
|
e.g. @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
|
|
@subsection Standard alerts
|
|
|
|
@cindex Alerts
|
|
@cindex Scroll
|
|
|
|
Thirteen 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.
|
|
|
|
@cindex Sound effects
|
|
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. You can specify
|
|
specific sound files for contacts matching a regexp in the variables
|
|
@code{jabber-alert-message-wave-alist} and
|
|
@code{jabber-alert-presence-wave-alist}.
|
|
|
|
@cindex Screen terminal manager
|
|
The @code{screen} alerts send a message through the Screen terminal
|
|
manager@footnote{See @uref{http://www.gnu.org/software/screen/}.}. They do no
|
|
harm if called when you don't use Screen.
|
|
|
|
@cindex Tmux terminal manager
|
|
The @code{tmux} alerts send a message through the tmux terminal
|
|
manager@footnote{See @uref{http://tmux.sourceforge.net/}.}.
|
|
|
|
@cindex Ratpoison window manager
|
|
@cindex Window manager, Ratpoison
|
|
The @code{ratpoison} alerts send a message through the Ratpoison
|
|
window manager@footnote{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.
|
|
Emacs doesn't hold on to them, though.
|
|
|
|
@cindex Sawfish window manager
|
|
@cindex Window manager, Sawfish
|
|
The @code{sawfish} alerts send a message through the Sawfish window
|
|
manager.
|
|
|
|
@cindex wmii window manager
|
|
@cindex Window manager, wmii
|
|
The @code{wmii} alerts display a message through the wmii window
|
|
manager.
|
|
|
|
@cindex awesome window manager
|
|
@cindex Window manager, awesome
|
|
The @code{awesome} alerts display a message through the awesome window
|
|
manager. However, to work it needs naughty (i.e.
|
|
@code{require("naughty")} in rc.lua).
|
|
|
|
@cindex xmessage
|
|
@vindex jabber-xmessage-timeout
|
|
The @code{xmessage} alerts send a message through the standard
|
|
@code{xmessage} tool. The variable @code{jabber-xmessage-timeout}
|
|
controls how long the alert appears.
|
|
|
|
@cindex OSD
|
|
The @code{osd} alerts send a message onto your screen using
|
|
XOSD.@footnote{XOSD can be found at
|
|
@uref{http://www.ignavus.net/software.html}. You also need
|
|
@file{osd.el} from @uref{http://www.brockman.se/software/osd.el}.}
|
|
|
|
@cindex notifications.el
|
|
The @code{notifications} alerts send a message using Emacs built-in
|
|
package @file{notifications.el}. Note that @file{notifications.el} first appear in
|
|
Emacs 24.1, so they are disabled by default.
|
|
|
|
@cindex libnotify
|
|
@cindex notification-daemon
|
|
The @code{libnotify} alerts send a message onto your screen using
|
|
@code{notification-daemon}.
|
|
|
|
@cindex Festival speech synthesis
|
|
@cindex Speech synthesis, Festival
|
|
The @code{festival} alerts speak the message using the Emacs interface
|
|
of the Festival speech synthesis system@footnote{See
|
|
@uref{http://www.cstr.ed.ac.uk/projects/festival/}.}.
|
|
|
|
@cindex Autoanswerer
|
|
The @code{autoanswer} alert is kind of special: it will not show you
|
|
message/muc alert, but instead will automaticaly answer to sender. See
|
|
variable `jabber-autoanswer-alist' description for details.
|
|
|
|
@cindex Scroll chat buffers
|
|
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.
|
|
|
|
Also, in MUC you can use a family of so-called ``personal'' alerts.
|
|
They are like other MUC alerts, but fire only on incoming messages
|
|
addresed directly to you (also known as ``private messages''). One
|
|
example of such an alert is @code{jabber-muc-echo-personal}, which shows
|
|
a note for an MUC message only if it was addressed to you.
|
|
|
|
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{JID symbols}),
|
|
@var{oldstatus} and @var{newstatus} are the previous and current
|
|
stati, respectively, and @var{statustext} is the status message if
|
|
provided, otherwise nil.
|
|
|
|
@var{oldstatus} and @var{newstatus} can be one of @code{""}
|
|
(i.e. online), @code{"away"}, @code{"xa"}, @code{"dnd"}, @code{"chat"},
|
|
@code{"error"} and @code{nil} (i.e. offline).
|
|
|
|
@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.
|
|
|
|
Another function, @code{jabber-presence-only-chat-open-message},
|
|
behave just like @code{jabber-presence-default-message}, but only if
|
|
conversation buffer for according JID is already open. Use it to show
|
|
presence notifications only for ``interesting'' contacts.
|
|
|
|
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
|
|
|
|
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{JID symbols}), @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.
|
|
|
|
@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.
|
|
|
|
@node MUC alerts, Info alerts, Message alerts, Customizing alerts
|
|
@subsection MUC alerts
|
|
|
|
@vindex jabber-alert-muc-function
|
|
@vindex jabber-muc-alert-self
|
|
@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.
|
|
|
|
By default, no alert is made for messages from yourself. To change
|
|
that, customize the variable @code{jabber-muc-alert-self}.
|
|
|
|
@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-hooks
|
|
@item jabber-post-connect-hooks
|
|
This hook is called after successful connection and authentication.
|
|
By default it contains @code{jabber-send-current-presence}
|
|
(@pxref{Presence}). The hook functions get the connection object as
|
|
argument.
|
|
|
|
@vindex jabber-lost-connection-hooks
|
|
@item jabber-lost-connection-hooks
|
|
This hook is called when you have been disconnected for unknown
|
|
reasons. Usually this isn't noticed for quite a long time.
|
|
|
|
The hook is called with one argument: the connection object.
|
|
|
|
@vindex jabber-pre-disconnect-hook
|
|
@item jabber-pre-disconnect-hook
|
|
This hook is called just before voluntary disconnection, i.e. in
|
|
@code{jabber-disconnect}, the command to disconnect all accounts. There
|
|
is currently no hook for disconnection of a single account.
|
|
|
|
@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.
|
|
|
|
@vindex jabber-browse-mode-hook
|
|
@item jabber-browse-mode-hook
|
|
This hook is called when a new browse buffer is created.
|
|
|
|
@vindex jabber-roster-mode-hook
|
|
@item jabber-roster-mode-hook
|
|
This hook is called when the roster buffer is created.
|
|
|
|
@end table
|
|
|
|
@node Debug options, , Hooks, Customization
|
|
@section Debug options
|
|
|
|
These settings provide a lot of information which is usually not very
|
|
interesting, but can be useful for debugging various things.
|
|
|
|
@vindex jabber-debug-log-xml
|
|
@cindex XML console
|
|
@code{jabber-debug-log-xml} activates XML console. All XML stanzas
|
|
sent and received are logged in the buffer @code{*-jabber-console-@var{jid}-*}
|
|
(and to specified file if value is string).
|
|
Also this buffer can be used to send XML stanzas manually.
|
|
|
|
@vindex jabber-console-name-format
|
|
Format for console buffer name. %s mean connection jid. Default value is
|
|
@code{*-jabber-console-%s-*}.
|
|
|
|
@vindex jabber-console-truncate-lines
|
|
Maximum number of lines in console buffer. Use this option to prevent
|
|
over bloating size of buffer.
|
|
Set value to 0 if you want to keep all stanzas in buffer, but
|
|
it's not recommended and may be unsafe.
|
|
|
|
@vindex jabber-debug-keep-process-buffers
|
|
Usually, the process buffers for Jabber connections are killed when the
|
|
connection is closed, as they would otherwise just fill up memory.
|
|
However, they might contain information about why the connection was
|
|
lost. To keep process buffers, set
|
|
@code{jabber-debug-keep-process-buffers} to @code{t}.
|
|
|
|
@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
|
|
* Connection object::
|
|
* XML representation::
|
|
* JID symbols::
|
|
* Listening for new requests::
|
|
* Sending new requests::
|
|
* Extending service discovery::
|
|
* Chat printers::
|
|
* Stanza chains::
|
|
@end menu
|
|
|
|
@node Connection object, XML representation, , Hacking and extending
|
|
@section Connection object
|
|
@cindex connection object
|
|
@cindex account object
|
|
@cindex FSM
|
|
|
|
Each Jabber connection is represented by a ``connection object''. This
|
|
object has the form of a finite state machine, and is realized by the
|
|
library @code{fsm}.@footnote{So far, this library is only distributed
|
|
with jabber.el. The author hopes that it could be useful for other
|
|
projects, too.}
|
|
|
|
The various states of this object are defined in @file{jabber-core.el}.
|
|
They describe the way of the connection through the establishing of a
|
|
network connection and authentication, and finally comes to the
|
|
@code{:session-established} state where ordinary traffic takes place.
|
|
|
|
These details are normally opaque to an extension author. As will be
|
|
noted, many functions expect to receive a connection object, and
|
|
functions at extension points generally receive such an object in order
|
|
to pass it on. The following functions simply query the internal state
|
|
of the connection:
|
|
|
|
@defun jabber-connection-jid connection
|
|
The @code{jabber-connection-jid} function returns the full JID of
|
|
@var{connection}, i.e. a string of the form
|
|
@code{"username@@server/resource"}.
|
|
@end defun
|
|
|
|
@defun jabber-connection-bare-jid connection
|
|
The @code{jabber-connection-bare-jid} function returns the bare JID of
|
|
@var{connection}, i.e. a string of the form @code{"username@@server"}.
|
|
@end defun
|
|
|
|
@node XML representation, JID symbols, Connection object, 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.
|
|
|
|
@defun jabber-sexp2xml xml-sexp
|
|
This function takes a tag in list representation, and returns its XML
|
|
representation as a string. You will normally not need to use this
|
|
function directly, but it can be useful to see how your sexps will look
|
|
when sent to the outer, non-Lisp, world.
|
|
@end defun
|
|
|
|
@defun jabber-send-sexp connection sexp
|
|
This function sends @var{sexp}, an XMPP stanza in list representation,
|
|
and sends it over @var{connection}.
|
|
|
|
You will normally use the functions @code{jabber-send-presence},
|
|
@code{jabber-send-message} and @code{jabber-send-iq} instead of this
|
|
function.
|
|
@end defun
|
|
|
|
@node JID symbols, Listening for new requests, XML representation, Hacking and extending
|
|
@section JID symbols
|
|
|
|
@vindex jabber-jid-obarray
|
|
JIDs are sometimes represented as symbols. 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; a string, one of @code{"none"}, @code{"from"},
|
|
@code{"to"} and @code{"both"}
|
|
|
|
@item ask
|
|
The ask state; either @code{nil} or @code{"subscribe"}
|
|
|
|
@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 value for highest-priority connected resource; a string,
|
|
one of @code{""} (i.e. online), @code{"away"}, @code{"xa"},
|
|
@code{"dnd"}, @code{"chat"}, @code{"error"} and @code{nil}
|
|
(i.e. offline)
|
|
|
|
@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, JID symbols, 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 two arguments, the connection object, and
|
|
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{connection} @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.
|
|
You can also use @code{jabber-send-iq-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
|
|
|
|
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{connection} @var{to} @var{type} @var{query}
|
|
@var{success-callback} @var{success-closure}
|
|
@var{failure-callback} @var{failure-closure})
|
|
@end example
|
|
|
|
@var{success-callback} will be called if the response is of type
|
|
@samp{result}, and @var{failure-callback} will be called if the response
|
|
is of type @samp{error}. Both callbacks take three arguments, the
|
|
connection object, the IQ stanza of the response, and the corresponding
|
|
closure item earlier passed to @code{jabber-send-iq}.
|
|
|
|
@findex jabber-report-success
|
|
@findex jabber-process-data
|
|
Two standard callbacks are provided. @code{jabber-report-success} takes
|
|
a string as closure item, and reports success or failure in the echo
|
|
area by appending either @samp{succeeded} or @samp{failed} to the
|
|
string. @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 connection
|
|
"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: @var{reason}'',
|
|
respectively, in the echo area.
|
|
|
|
The protocol ``investigate'' needs to parse results and show them in a
|
|
browse buffer:
|
|
@example
|
|
(jabber-send-iq connection
|
|
"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
|
|
|
|
Service discovery (XEP-0030) is a Jabber protocol for communicating
|
|
features supported by a certain entity, and items affiliated with an
|
|
entity. jabber.el has APIs for both providing and requesting such
|
|
information.
|
|
|
|
|
|
@menu
|
|
* Providing info::
|
|
* Requesting info::
|
|
@end menu
|
|
|
|
@node Providing info, Requesting info, , Extending service discovery
|
|
@subsection Providing info
|
|
|
|
Your new IQ request handlers will likely want to advertise their
|
|
existence through service discovery.
|
|
|
|
@vindex jabber-advertised-features
|
|
To have an additional feature reported in response to disco info
|
|
requests, add a string to @code{jabber-advertised-features}.
|
|
|
|
@vindex jabber-disco-items-nodes
|
|
@vindex jabber-disco-info-nodes
|
|
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 connection object and the entire IQ stanza and returning a
|
|
list; in either case this list contains the XML nodes to include in the
|
|
@code{<query/>} node in the response.
|
|
|
|
@findex jabber-my-jid-p
|
|
The second item is the access control function. An access control
|
|
function receives the connection object and a JID as arguments, 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, or one of the user's configured accounts.
|
|
|
|
@node Requesting info, , Providing info, Extending service discovery
|
|
@subsection Requesting info
|
|
|
|
jabber.el has a facility for requesting disco items and info. All
|
|
positive responses are cached.
|
|
|
|
To request disco items or info from an entity, user one of these
|
|
functions:
|
|
|
|
@defun jabber-disco-get-info jc jid node callback closure-data &optional force
|
|
Get disco information for @var{jid} and @var{node}. A request is sent
|
|
asynchronously on the connection @var{jc}. When the response arrives,
|
|
@var{callback} is called with three arguments: @var{jc},
|
|
@var{closure-data}, and the result. The result may be retrieved from
|
|
the cache, unless @var{force} is non-nil.
|
|
|
|
If the request was successful, or retrieved from cache, it looks like
|
|
@code{(@var{identities} @var{features})}, where @var{identities} and
|
|
@var{features} are lists. Each identity is @code{["@var{name}"
|
|
"@var{category}" "@var{type}"]}, and each feature is a string denoting
|
|
the namespace of the feature.
|
|
|
|
If the request failed, the result is an @code{<error/>} node.
|
|
@end defun
|
|
|
|
@defun jabber-disco-get-items jc jid node callback closure-data &optional force
|
|
Get disco information for @var{jid} and @var{node}. A request is sent
|
|
asynchronously on the connection @var{jc}. When the response arrives,
|
|
@var{callback} is called with three arguments: @var{jc},
|
|
@var{closure-data}, and the result. The result may be retrieved from
|
|
the cache, unless @var{force} is non-nil.
|
|
|
|
If the request was successful, or retrieved from cache, the result is
|
|
a list of items, where each item is @code{["@var{name}" "@var{jid}"
|
|
"@var{node}"]}. The values are either strings or nil.
|
|
|
|
If the request failed, the result is an @code{<error/>} node.
|
|
@end defun
|
|
|
|
If you only want to see what is in the cache, use one of the following
|
|
functions. They don't use a callback, but return the result directly.
|
|
|
|
@defun jabber-disco-get-info-immediately jid node
|
|
Return cached disco information for @var{jid} and @var{node}, or nil
|
|
if the cache doesn't contain this information. The result is the same
|
|
as for @code{jabber-disco-get-info}.
|
|
@end defun
|
|
|
|
@defun jabber-disco-get-items-immediately jid node
|
|
Return cached disco items for @var{jid} and @var{node}, or nil
|
|
if the cache doesn't contain this information. The result is the same
|
|
as for @code{jabber-disco-get-items}.
|
|
@end defun
|
|
|
|
In the future, this facility will be expanded to provide information
|
|
acquired through XEP-0115, Entity capabilities, which is a protocol
|
|
for sending disco information in @code{<presence/>} stanzas.
|
|
|
|
@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. As described in the docstring
|
|
of @code{jabber-chat-printers}, these functions are run in one of two
|
|
modes: @code{printp}, in which they are supposed to return true if
|
|
they would print anything, and @code{insert}, in which they are
|
|
supposed to actually print something, if appropriate, using the
|
|
function @code{insert}.
|
|
|
|
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 connection object and the
|
|
entire XML stanza passed as arguments. Earlier functions can modify
|
|
the stanza to change the behaviour of downstream functions, but
|
|
remember: with great power comes great responsibility.
|
|
|
|
@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
|
|
* XEP-0004:: Data Forms
|
|
* XEP-0012:: Last Activity
|
|
* XEP-0020:: Feature Negotiation
|
|
* XEP-0022:: Message Events
|
|
* XEP-0030:: Service Discovery
|
|
* XEP-0045:: Multi-User Chat
|
|
* XEP-0049:: Private XML Storage
|
|
* XEP-0050:: Ad-Hoc Commands
|
|
* XEP-0054:: vcard-temp
|
|
* XEP-0055:: Jabber Search
|
|
* XEP-0065:: SOCKS5 Bytestreams
|
|
* XEP-0066:: Out of Band Data
|
|
* XEP-0068:: Field Standardization for Data Forms
|
|
* XEP-0077:: In-Band Registration
|
|
* XEP-0078:: Non-SASL Authentication
|
|
* XEP-0082:: Jabber Date and Time Profiles
|
|
* XEP-0085:: Chat State Notifications
|
|
* XEP-0086:: Error Condition Mappings
|
|
* XEP-0090:: Entity Time
|
|
* XEP-0091:: Delayed Delivery
|
|
* XEP-0092:: Software Version
|
|
* XEP-0095:: Stream Initiation
|
|
* XEP-0096:: File Transfer
|
|
* XEP-0146:: Remote Controlling Clients
|
|
* XEP-0153:: vCard-Based Avatars
|
|
* XEP-0199:: XMPP Ping
|
|
* XEP-0245:: The /me Command
|
|
@end menu
|
|
|
|
@node RFC 3920, RFC 3921, , 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, XEP-0004, RFC 3920, 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.
|
|
|
|
Sending ``directed presence'' is supported; however, presence stanzas
|
|
received from contacts not in roster are ignored.
|
|
|
|
Privacy lists are not supported at all.
|
|
|
|
jabber.el doesn't support XMPP-E2E or ``im:'' CPIM URIs.
|
|
|
|
@node XEP-0004, XEP-0012, RFC 3921, Protocol support
|
|
@section XEP-0004 (Data Forms)
|
|
|
|
XEP-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 XEP-0012, XEP-0020, XEP-0004, Protocol support
|
|
@section XEP-0012 (Last Activity)
|
|
|
|
jabber.el can generate all three query types described in the protocol.
|
|
However, it does not answer to such requests.
|
|
|
|
@node XEP-0020, XEP-0022, XEP-0012, Protocol support
|
|
@section XEP-0020 (Feature Negotiation)
|
|
|
|
There are no known limitations or bugs in XEP-0020 support.
|
|
|
|
@node XEP-0022, XEP-0030, XEP-0020, Protocol support
|
|
@section XEP-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 XEP-0030, XEP-0045, XEP-0022, Protocol support
|
|
@section XEP-0030 (Service Discovery)
|
|
|
|
Service discovery is supported, both as client and server. When used in
|
|
the code, service discovery results are cached indefinitely.
|
|
|
|
@node XEP-0045, XEP-0049, XEP-0030, Protocol support
|
|
@section XEP-0045 (Multi-User Chat)
|
|
|
|
jabber.el supports parts of XEP-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 XEP-0049, XEP-0050, XEP-0045, Protocol support
|
|
@section XEP-0049 (Private XML Storage)
|
|
|
|
jabber.el contains an implementation of XEP-0049; It is used
|
|
for bookmarks and roster's groups roll state saving.
|
|
|
|
@node XEP-0050, XEP-0054, XEP-0049, Protocol support
|
|
@section XEP-0050 (Ad-Hoc Commands)
|
|
|
|
jabber.el is probably the first implementation of XEP-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 XEP-0054, XEP-0055, XEP-0050, Protocol support
|
|
@section XEP-0054 (vcard-temp)
|
|
|
|
Both displaying other users' vCards and editing your own vCard are
|
|
supported. The implementation tries to follow the schema in the XEP
|
|
accurately.
|
|
|
|
@node XEP-0055, XEP-0065, XEP-0054, Protocol support
|
|
@section XEP-0055 (Jabber Search)
|
|
|
|
XEP-0055 is supported, both with traditional fields and with Data Forms
|
|
(@pxref{XEP-0004}). As the traditional fields specified by the XEP is a
|
|
subset of those allowed in XEP-0077, handling of those two form types
|
|
are merged. @xref{XEP-0077}.
|
|
|
|
@node XEP-0065, XEP-0066, XEP-0055, Protocol support
|
|
@section XEP-0065 (SOCKS5 Bytestreams)
|
|
|
|
XEP-0065 is supported. 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 XEP-0066, XEP-0068, XEP-0065, Protocol support
|
|
@section XEP-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 XEP. Sending
|
|
such URLs or doing anything with iq stanzas (using the
|
|
@code{jabber:iq:oob} namespace) is not supported.
|
|
|
|
@node XEP-0068, XEP-0077, XEP-0066, Protocol support
|
|
@section XEP-0068 (Field Standardization for Data Forms)
|
|
|
|
XEP-0068 is only used in the context of creating a new Jabber account,
|
|
to prefill the username field of the registration form.
|
|
|
|
@node XEP-0077, XEP-0078, XEP-0068, Protocol support
|
|
@section XEP-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 XEP-0078, XEP-0082, XEP-0077, Protocol support
|
|
@section XEP-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 XEP-0082, XEP-0085, XEP-0078, Protocol support
|
|
@section XEP-0082 (Jabber Date and Time Profiles)
|
|
|
|
The DateTime profile of XEP-0082 is supported. Currently this is only
|
|
used for file transfer.
|
|
|
|
@node XEP-0085, XEP-0086, XEP-0082, Protocol support
|
|
@section XEP-0085 (Chat State Notifications)
|
|
|
|
XEP-0085 is partially supported. Currently only active/composing
|
|
notifications are @emph{sent} though all five notifications are handled on
|
|
receipt.
|
|
|
|
@node XEP-0086, XEP-0090, XEP-0085, Protocol support
|
|
@section XEP-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 XEP-0090, XEP-0091, XEP-0086, Protocol support
|
|
@section XEP-0090 (Entity Time)
|
|
|
|
jabber.el can query other entities for their time, and return the
|
|
current time to those who ask.
|
|
|
|
@node XEP-0091, XEP-0092, XEP-0090, Protocol support
|
|
@section XEP-0091 (Delayed Delivery)
|
|
|
|
The time specified on delayed incoming messages is interpreted, and
|
|
displayed in chat buffers instead of the current time.
|
|
|
|
@node XEP-0092, XEP-0095, XEP-0091, Protocol support
|
|
@section XEP-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 XEP-0095, XEP-0096, XEP-0092, Protocol support
|
|
@section XEP-0095 (Stream Initiation)
|
|
|
|
XEP-0095 is supported, both incoming and outgoing, except that jabber.el
|
|
doesn't check service discovery results before sending a stream
|
|
initiation request.
|
|
|
|
@node XEP-0096, XEP-0146, XEP-0095, Protocol support
|
|
@section XEP-0096 (File Transfer)
|
|
|
|
Both sending and receiving files is supported. If a suitable program is
|
|
found, MD5 hashes of outgoing files are calculated and sent. However,
|
|
hashes of received files are not checked. Ranged transfers are not
|
|
supported. In-band bytestreams are not yet supported, even though
|
|
XEP-0096 requires them.
|
|
|
|
@node XEP-0146, XEP-0153, XEP-0096, Protocol support
|
|
@section XEP-0146 (Remote Controlling Clients)
|
|
|
|
The ``set-status'' command in XEP-0146 is supported.
|
|
|
|
@node XEP-0153, XEP-0199, XEP-0146, Protocol support
|
|
@section XEP-0153 (vCard-Based Avatars)
|
|
|
|
vCard-based avatars are supported, both publishing and displaying. The
|
|
pixel size limits on avatars are not enforced.
|
|
|
|
@node XEP-0199, XEP-0245, XEP-0153, Protocol support
|
|
@section XEP-0199 (XMPP Ping)
|
|
|
|
XEP-0199 is fully supported.
|
|
|
|
@node XEP-0245, ,XEP-0199, Protocol support
|
|
@section XEP-0245 (/me Command)
|
|
|
|
XEP-0245 is partially supported (except XHTML-IM).
|
|
|
|
@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
|