diff options
Diffstat (limited to 'jabber.texi')
| -rw-r--r-- | jabber.texi | 3020 |
1 files changed, 3020 insertions, 0 deletions
diff --git a/jabber.texi b/jabber.texi new file mode 100644 index 0000000..128b551 --- /dev/null +++ b/jabber.texi @@ -0,0 +1,3020 @@ +\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 |