1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename jabber.info 4@settitle jabber.el manual 0.8.0 5@c %**end of header 6 7@dircategory Emacs 8@direntry 9* jabber.el: (jabber). Emacs Jabber client 10@end direntry 11 12@copying 13This manual is for jabber.el, version 0.8.0. 14 15Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 Magnus Henoch, Tom Berger. 16 17@quotation 18Permission is granted to make and distribute verbatim copies or 19modified versions of this manual, provided the copyright notice and 20this permission notice are preserved on all copies. 21@end quotation 22@end copying 23 24@titlepage 25@title jabber.el 26@subtitle instant messaging for Jabber 27@author by Magnus Henoch and Tom Berger 28 29@page 30@vskip 0pt plus 1filll 31@insertcopying 32@end titlepage 33 34@contents 35 36@ifnottex 37@node Top, Introduction, (dir), (dir) 38@top jabber.el manual 39 40@insertcopying 41 42@end ifnottex 43 44@menu 45* Introduction:: 46* Basic operation:: 47* Groupchat:: 48* Composing messages:: 49* File transfer:: 50* Services:: 51* Personal information:: 52* Avatars:: 53* Time queries:: 54* Useful features:: 55* Message history:: 56* Typing notifications:: 57* Roster import and export:: 58* XMPP URIs:: 59* Customization:: 60* Hacking and extending:: 61* Protocol support:: 62* Concept index:: 63* Function index:: 64* Variable index:: 65@end menu 66 67 68@node Introduction, Basic operation, Top, Top 69@chapter Introduction 70 71jabber.el is a Jabber client running under Emacs. For more 72information on the open-protocol instant messaging network Jabber, 73please visit @uref{http://www.jabber.org}. 74 75As a Jabber client, jabber.el is mostly just a face in the crowd, 76except that it uses buffers where GUI clients have windows. There is 77a roster buffer, and to chat with someone you open a chat buffer, and 78there are buffers for 79interaction with servers and services. Then again, jabber.el delivers 80excellent console performance and customizable hooks (if you have 81speech synthesizer software, hook it up to your presence alerts). 82 83jabber.el does not yet support PGP encryption, sending and receiving 84roster items, and various other things. 85 86@menu 87* Contacts:: 88@end menu 89 90@node Contacts, , , Introduction 91@section Contacts 92 93@itemize @bullet 94@item 95There is a web page at 96@uref{http://emacs-jabber.sf.net/}. 97 98@item 99There is a Sourceforge 100project page at @uref{http://sourceforge.net/projects/emacs-jabber}, 101with bug and patch trackers. 102 103@item 104There is a mailing list: 105@email{emacs-jabber-general@@lists.sourceforge.net}, 106@uref{https://lists.sourceforge.net/lists/listinfo/emacs-jabber-general}, 107@uref{http://dir.gmane.org/gmane.emacs.jabber.general} 108 109@item 110There is a chat room, @code{jabber.el@@conference.jabber.se}. If you 111have successfully connected, you can join it by typing @kbd{M-x 112jabber-muc-join} and entering the address. 113 114@end itemize 115 116@node Basic operation, Groupchat, Introduction, Top 117@chapter Basic operation 118 119This chapter is intended as an introduction to basic usage of 120jabber.el. If you have used Jabber before and are familiar with the 121terminology, you might find it a bit too basic---in that case, just 122skim it, making sure to pick up the commands mentioned. 123 124I'll assume that you have already successfully installed jabber.el; if 125not, consult the @file{README} file. Also, make sure you have 126@code{(require 'jabber)} or @code{(load "jabber-autoloads")} in your 127@file{.emacs}. 128 129There are a handful of global keybindings for common commands. They 130start with @kbd{C-x C-j}, and you can get a list of them by typing 131@kbd{C-x C-j C-h}. 132 133@menu 134* Do you have a Jabber account?:: 135* Registering an account:: 136* Connecting:: 137* Chatting:: 138* Presence:: 139* Presence subscription:: 140* Roster buffer:: 141@end menu 142 143@node Do you have a Jabber account?, Registering an account, , Basic operation 144@section Do you have a Jabber account? 145 146Jabber has become rather popular as an instant messaging technology. 147Several sites use it, but often not under the names ``Jabber'' or 148``XMPP''. Examples: 149 150@itemize @bullet 151@item 152Google Talk uses Jabber. If you have a Gmail address, you can use it as 153a Jabber ID. @xref{Account settings}, for Google-specific configuration. 154 155@item 156LJ Talk (of Livejournal) uses Jabber. Your Jabber ID is 157@samp{@var{ljusername}@@livejournal.com}. 158@end itemize 159 160@node Registering an account, Connecting, Do you have a Jabber account?, Basic operation 161@section Registering an account 162 163@cindex Registering an account 164 165If you do not yet have a Jabber account, you can register one. The 166registration processes for various servers differ, but many servers 167support so-called ``in-band registration'', which is described in this 168section. 169 170To register an account, type @kbd{C-u M-x jabber-connect} and enter your 171desired JID in the form @samp{@var{username}@@@var{server}}. You will 172be presented with a registration form to fill out and send. There the 173username you chose will be prefilled. After registration, you can 174connect to the server as usual. 175 176@node Connecting, Chatting, Registering an account, Basic operation 177@section Connecting 178 179@findex jabber-connect-all 180@findex jabber-connect 181@findex jabber-disconnect-one 182@findex jabber-disconnect 183 184@cindex Connecting 185 186Now, type @kbd{C-x C-j C-c} and enter your JID and password. If you 187successfully connect, jabber.el will download your roster and display it 188in a buffer called @code{*-jabber-roster-*}. 189 190By default, you will appear as ``online'' to your contacts. To change 191this to e.g. ``away'', type @kbd{M-x jabber-send-presence} or @kbd{C-x 192C-j C-p}. @xref{Presence}, for more information. 193 194To disconnect, type @kbd{M-x jabber-disconnect} or @kbd{C-x C-j C-d}. 195Use @kbd{M-x jabber-disconnect-one} to disconnect just one account (or just type @kbd{C-u C-x C-j C-d}). 196 197If you don't want to type your JID every time you connect, you can save 198it in the variable @code{jabber-account-list}. @xref{Account 199settings}. If you configure more than one account, all of them will be 200connected when you type @kbd{C-x C-j C-c}, as that key is bound to 201@code{jabber-connect-all}. To connect only one account, possibly one 202that's not in your list, type @kbd{M-x jabber-connect} or @kbd{C-u C-x 203C-j C-c}. 204 205@node Chatting, Presence, Connecting, Basic operation 206@section Chatting 207 208@cindex Chatting 209@findex jabber-chat-with 210 211There are several ways to open a chat buffer. The shortest way is to 212put point over the person you want to chat with in the roster display 213and hit RET. 214 215You can also use the function @code{jabber-chat-with}. This function is 216bound to @kbd{C-x C-j C-j} in the global keymap. You will be asked to 217enter a JID in the minibuffer. You can also enter the roster name of 218one of your contacts. All JIDs and names in your roster can be 219tab-completed. 220 221You can also use menus to access commands. In the roster display, you 222can access several menus through keystrokes or mouse clicks. You can 223bring one big menu up by pressing the second mouse button, or you can 224bring up the ``chat menu'' by typing @kbd{C-c C-c}. If you do the 225latter while point is on a roster entry, that entry will be the 226default value when you are asked for whom to chat with. 227 228Now, try opening a chat with someone. A buffer named 229@code{*-jabber-chat-:-@var{person}-*} will be created and selected. 230Type your message at the end of the buffer, and hit @kbd{RET} to send 231it. To include a newline in your message, use @kbd{C-j}. 232 233When you receive a message from someone, you will see a red indicator in 234the mode line. You can click this indicator with the mouse, or type 235@kbd{C-x C-j C-l} to switch to the relevant buffer. @xref{Tracking 236activity}. 237 238@node Presence, Presence subscription, Chatting, Basic operation 239@section Presence 240 241@cindex Presence 242@cindex Sending presence 243@findex jabber-send-presence 244@findex jabber-send-default-presence 245@vindex jabber-default-show 246@vindex jabber-default-status 247@vindex jabber-default-priority 248 249@dfn{Presence} is the Jabber term for letting other people know that you 250are online, and additionally how ``available'' you are. There are 251three elements to presence: availability state (called ``show''), 252status message, and priority. 253 254Your show state may either be empty (meaning simply ``online''), or 255one of @code{away}, @code{xa}, @code{dnd} and @code{chat}, meaning 256``away'', ``extended away'' (i.e. away for an extended period), ``do 257not disturb'', and ``free for chat'', respectively. This information 258is available to everyone subscribing to your presence, but technically 259it does not restrict anyone's actions. You can chat with people even 260if you claim to be away. 261 262The status message is a short text complementing your show status, 263such as ``at home'', ``working'', ``phone'', ``playing games'' or 264whatever you want. It is sent to everyone subscribing to your 265presence, but not all clients prominently display it to the user. 266 267The priority is only interesting if you are running more than one Jabber 268client at a time accessing the same account. @xref{Resources and 269priority}. 270 271To set your presence, use the function @code{jabber-send-presence} 272(bound to @kbd{C-x C-j C-p}). 273It can be called both interactively and in Lisp code. For the latter 274case, use something like @code{(jabber-send-presence "away" "idle for 27510 minutes" 10)}. There are a few shortcuts: 276@table @kbd 277@item C-x C-j C-a 278Send ``away'' presence (with prefix argument, specify status text) 279@item C-x C-j C-x 280Send ``extended away'' presence (with prefix argument, specify status 281text) 282@item C-x C-j C-o 283Send default presence (see below) 284@end table 285 286By default, jabber.el sets your presence when you connect. If you 287want it not to do that, remove @code{jabber-send-current-presence} 288from @code{jabber-post-connect-hooks}. If you want to change the 289presence that is sent, change the variables 290@code{jabber-default-show}, @code{jabber-default-status} and 291@code{jabber-default-priority}. 292 293With jabber.el, you can set your presence remotely. @xref{Ad-Hoc Commands}. 294 295@menu 296* Resources and priority:: 297* Directed presence:: 298@end menu 299 300@node Resources and priority, Directed presence, , Presence 301@subsection Resources and priority 302 303@cindex Resource 304@cindex Priority 305 306Every connection to an account has a specific name, a @dfn{resource}. 307The account itself has a JID of the form 308@samp{@var{username}@@@var{server}} (a @dfn{bare JID}), but the 309connections have JIDs of the form 310@samp{@var{username}@@@var{server}/@var{resource}} (a @dfn{full JID}). 311You can choose the resource name yourself by entering a JID of the 312latter form at the connection prompt (@pxref{Connecting}), or by 313configuring it in @code{jabber-account-list} (@pxref{Account settings}) 314 315Each session has a @dfn{priority}. The priority determines what happens 316when a message is sent to the bare JID (i.e. without specifying what 317connection should receive message). Such messages are delivered to the 318connection with the highest non-negative priority value. If there are 319no connections, or if all connections have negative priority, the 320message is either stored on the server for later delivery or bounced to 321the sender, depending on the server configuration. 322 323If there are several connections with the same priority, the behaviour 324depends on the server. Some server implementations deliver the message 325to all such connections, while others choose one connection depending on 326certain rules. 327 328Note that these rules do not apply when a message is sent to a full 329JID. Such messages are sent to the specified resource, if it is still 330connected, and otherwise treated as messages to the bare JID. In the 331chat buffers of jabber.el, messages are sent to whatever JID the last 332message came from (usually a full JID), or to the bare JID if no message 333has been received yet. Other clients may have different behaviour. 334 335@node Directed presence, , Resources and priority, Presence 336@subsection Directed presence 337 338@cindex directed presence 339@cindex send directed presence 340@findex jabber-send-directed-presence 341You can send ``directed presence'' with @kbd{M-x 342jabber-send-directed-presence}. This is mostly useful to manage 343transports---sending directed presence is a way to turn them on and 344off. You can also send directed presence to an annoying contact to 345appear as away or offline to that contact. Note, however, that in both 346of these cases, all subscribed entities will get your next global 347presence update. 348 349@node Presence subscription, Roster buffer, Presence, Basic operation 350@section Presence subscription 351 352@cindex Presence subscription 353@cindex Subscribing to someone's presence 354@findex jabber-send-subscription-request 355 356Having permission to view the presence status of a person is called 357@dfn{subscribing to his presence}. Presence subscription between two 358persons can be asymmetric. Subscription state is shown in the roster 359display by arrows (@pxref{Customizing the roster buffer}). A 360left-pointing arrow means that the contact can see your presence 361(``from''). A right-pointing arrow means that you can see the contact's 362presence (``to''). The most common case is mutual subscription, a 363double-ended arrow (``both''). 364 365When jabber.el receives a presence subscription request, it will present 366it to you in a chat buffer, and offer you to choose subscription mode 367and send a subscription request back to that person. The ``Mutual'' 368button accepts the request and sends a reciprocal request.@footnote{If this 369request is superfluous, the server will drop it without bothering the 370contact.} The ``One-way'' button accepts the request, but doesn't ask 371for a subscription in return. The ``Decline'' button declines the 372request. 373 374To request subscription to someone, type @kbd{M-x 375jabber-send-subscription-request}. You will be prompted for the JID 376to send it to. This command can also be accessed through the Roster 377menu, by typing @kbd{C-c C-r} in the roster buffer. After that, you 378will probably want to give the contact a more readable name. The 379command for that is @code{jabber-roster-change}, which is also 380available in the Roster menu or by typing @kbd{e} on a person in the 381roster buffer. 382 383@node Roster buffer, , Presence subscription, Basic operation 384@section The roster buffer 385 386@cindex Roster buffer, basics 387@cindex Menus 388@cindex Key bindings 389 390The roster buffer is called @code{*-jabber-roster-*}. It simply 391contains a list of the contacts on your roster. If you have several 392accounts connected, contacts will be grouped by account. 393 394In the roster buffer, any command which requires a JID will default to 395the JID under point when called. These commands can be called through 396either keyboard menus or mouse menus. To open a menu with the mouse, 397simply press the second mouse button over the JID in 398question.@footnote{For some reason, mouse menus don't work in XEmacs. 399Patches are welcome.} This will bring up a menu with all available 400actions. The keyboard menus are split into categories: Chat, Roster, 401Information, MUC (Multi-User Chat, or groupchat) and Services, opened 402by @kbd{C-c C-c}, @kbd{C-c C-r}, @kbd{C-c C-i}, @kbd{C-c C-m} and 403@kbd{C-c C-s}, respectively. 404 405@vindex jabber-roster-show-bindings 406A list of keybindings is displayed at the top of the roster buffer. 407You can turn it off by setting @code{jabber-roster-show-bindings} to 408nil. 409 410@findex jabber-display-roster 411You can call @code{jabber-display-roster} (bound to @kbd{g}) to 412redisplay your roster according to changed preferences 413(@pxref{Customizing the roster buffer}). This will not refetch your 414roster from the server. Refetching the roster is usually not needed, 415since updates are pushed to clients automatically. 416 417You can choose not to have the roster updated automatically on 418presence changes (@pxref{Presence alerts}). In that case, you need to 419call @code{jabber-display-roster} manually. 420 421@vindex jabber-show-offline-contacts 422@cindex Hiding offline contacts 423@cindex Offline contacts, hiding 424Please note, that by default offline contacts showed in roster as any 425others. To hide them, you can use @kbd{o} in roster buffer. To 426permanently hide them, customize @code{jabber-show-offline-contacts} 427variable. 428 429@node Groupchat, Composing messages, Basic operation, Top 430@chapter Groupchat 431 432@cindex Groupchat 433@cindex MUC 434@cindex Chatrooms 435 436The groupchat menu can be accessed by typing @kbd{C-c C-m} in the 437roster buffer. You can also type the commands directly, as will be 438shown here. 439 440@findex jabber-muc-join 441@cindex Joining a groupchat 442@cindex Changing nickname 443@cindex Nickname, changing 444To join a groupchat, type @kbd{M-x jabber-muc-join}. You will 445be prompted for the groupchat to join, and your nickname in the 446groupchat. This nickname doesn't need to have any correlation to your 447JID; in fact, groupchats are usually (but not always) configured such 448that only moderators can see your JID. You can change your nickname 449with @kbd{M-x jabber-muc-nick}. @xref{Configuration}, for setting default 450nicknames. 451 452@cindex Query groupchat 453@vindex jabber-muc-disable-disco-check 454When trying to join a room, jabber.el first sends a service discovery 455info request to the room, to find out whether it exists and what 456features are enabled (in particular whether the room is 457password-protected). However, this can cause problems with some buggy 458MUC services (or services that respond in a way that jabber.el doesn't 459expect). A workaround for that is to set 460@code{jabber-muc-disable-disco-check} to @code{t}; however, the bug should be 461unearthed and fixed. 462 463Groupchat messages will be displayed in a buffer called 464@code{*-jabber-groupchat-:-@var{groupchat}-*}. By default, the buffer 465name is based on the JID of the chat room. If you want a shorter name, 466you can add the chat room to your roster and give it a name, using the 467command @kbd{M-x jabber-roster-change}. The groupchat buffer works much 468like the chat buffer. It has its own class of alerts 469(@pxref{Customizing alerts}), and uses activity tracking 470(@pxref{Tracking activity}). 471 472@vindex jabber-muc-completion-delimiter 473@vindex jabber-muc-looks-personaling-symbols 474@cindex Groupchat completion 475@cindex Nick completion in groupchat 476Also, to save from repeating unnesesary typing you can press @kbd{Tab} 477key to complete nick of a groupchat member that you are talking with. 478You can customize your form of personal talking in MUC 479(@code{jabber-muc-completion-delimiter}) and form of personal talking to 480you (@code{jabber-muc-looks-personaling-symbols})---see ``jabber-chat'' 481customization group. Defaults are sane, so it is unlikely that you would 482want to change this, but... it is Emacs! 483 484@cindex Topic, MUC 485@findex jabber-muc-set-topic 486To change the topic of a groupchat, type @kbd{M-x jabber-muc-set-topic}. 487The current topic is shown in the header line. 488 489@findex jabber-muc-leave 490To leave a groupchat, type @kbd{M-x jabber-muc-leave}. 491 492@findex jabber-muc-get-config 493If you are the owner of a groupchat, you can change its configuration 494by typing @kbd{M-x jabber-muc-get-config}. A configuration form 495will be rendered in new buffer. 496 497@findex jabber-muc-names 498@vindex jabber-muc-print-names-format 499To see which people are in a groupchat, type @kbd{M-x 500jabber-muc-names}. This gives a list of nicknames, 501``affiliations'', and possibly JIDs according @code{jabber-muc-print-names-format}, sorted by ``roles''. 502@xref{MUC Administration}, for the meaning of roles and affiliations. 503 504 505@menu 506* Configuration:: 507* Invitations:: 508* Private messages:: 509* MUC Administration:: 510@end menu 511 512@node Configuration, Invitations, , Groupchat 513@section Configuration 514 515@vindex jabber-muc-default-nicknames 516@vindex jabber-muc-autojoin 517@findex jabber-muc-autojoin 518@cindex Default MUC nickname 519@cindex Autojoin chat rooms 520@cindex Bookmarks, MUC 521@findex jabber-edit-bookmarks 522 523You can configure jabber.el to use a certain nickname for a certain 524room, or to automatically join a certain room when you connect. You can 525do this either by storing bookmarks on the server or by setting Emacs 526variables. 527 528Type @kbd{M-x jabber-edit-bookmarks} to add bookmarks. You can specify 529the JID of the conference, the name of the conference (not used by 530jabber.el), whether to automatically join the room, your desired 531nickname (or leave empty), and the room password (or leave empty). 532 533The default nickname for groupchats is the username part of your JID. 534If you don't use bookmarks, you can set different nicknames for 535different groups by customizing @code{jabber-muc-default-nicknames}. 536There you specify the JID of the group, and your preferred nickname. 537 538Automatically joining certain rooms when connecting can be accomplished 539by setting @code{jabber-muc-autojoin} to a list containing the JIDs of 540the rooms you want to enter. To disable this feature, remove 541@code{jabber-muc-autojoin} from @code{jabber-post-connect-hooks}. 542 543Please note, that @code{jabber-muc-default-nicknames} and 544@code{jabber-muc-autojoin} are machine-local, but apply to @emph{all} 545accounts---if you connect several accounts, both will try to connect to 546the same chat rooms, or use the same nickname. This will lead to 547confusion. 548 549@node Invitations, Private messages, Configuration, Groupchat 550@section Invitations 551 552@cindex Invitations 553@findex jabber-muc-invite 554 555You can invite someone to a groupchat with @kbd{M-x jabber-muc-invite} 556(also available in the MUC menu). Pay attention to the order of the 557arguments---as both users and rooms are just JIDs, it is technically 558possible to invite a room to a user, but that's probably not what you 559want. 560 561When you receive an invitation, it appears in the chat buffer along 562with two buttons, ``Accept'' and ``Decline''. Pressing ``Accept'' 563enters the room, as you would expect. Pressing ``Decline'' gives you 564an opportunity to state the reason why you're not joining. 565 566@node Private messages, MUC Administration, Invitations, Groupchat 567@section Private messages 568 569@cindex Private MUC messages 570@findex jabber-muc-private 571 572You can open a private chat with a participant in a chat room with 573@kbd{M-x jabber-muc-private} (or by using the MUC menu). This creates 574a buffer with the name 575@code{*-jabber-muc-priv-@var{group}-@var{nickname}-*} (customizable by 576@code{jabber-muc-private-buffer-format}), which behaves mostly like an 577ordinary chat buffer. This buffer will also be created if someone 578sends a private message to you. 579 580Private MUC messages use the same alerts as normal chat messages. 581@xref{Message alerts}. 582 583@node MUC Administration, , Private messages, Groupchat 584@section Administration 585 586Administration of a MUC room mostly consists of managing roles and 587affiliations. Roles are temporary, and apply until the user leaves the 588room. Affiliations are permanent, and based on JIDs. 589 590@subsection Roles 591 592@findex jabber-muc-set-role 593@cindex Kicking, MUC 594@cindex Voice, MUC 595@cindex Moderator, MUC 596@cindex Roles, MUC 597If you have moderator privileges, you can change the role of a 598participant with @kbd{M-x jabber-muc-set-role}. Kicking means setting 599the role to ``none''. Granting and revoking voice are ``participant'' 600and ``visitor'', respectively. ``moderator'' gives moderator 601privileges, obviously. 602 603The possible roles are: 604 605@table @samp 606@item moderator 607Has voice, can change other people's roles. 608 609@item participant 610Has voice. 611 612@item visitor 613Doesn't have voice (can't send messages to everyone, but can send 614private messages) 615 616@item none 617Not in room. 618@end table 619 620@subsection Affiliations 621 622@findex jabber-muc-set-affiliation 623@cindex Affiliations, MUC 624@cindex Banning, MUC 625If you have admin or owner privileges, you can change the affiliation of 626a user with @kbd{M-x jabber-muc-set-affiliation}. Affiliation is 627persistent, and based on JIDs. Depending of your affiliation and the 628MUC implementation, you might not be allowed to perform all kinds of 629changes, and maybe not in one step. 630 631Affiliations are: 632 633@table @samp 634@item owner 635Can destroy room, appoint admins, make people members, ban people. 636 637@item admin 638Can make people members or ban people. 639 640@item member 641Can enter the room, and has voice by default. 642 643@item none 644Rights depend on room configuration. The room might be members-only, or 645grant voice only to members. 646 647@item outcast 648Banned from the room. 649@end table 650 651 652@node Composing messages, File transfer, Groupchat, Top 653@chapter Composing messages 654 655@findex jabber-compose 656@cindex composing messages 657@cindex message composition 658 659The chat buffer interface can be inconvenient for some purposes. As you 660can't use @kbd{RET} to insert a newline (use @kbd{C-j} for that), 661writing a longer message can be painful. Also, it is not possible to 662include a subject in the message, or send the message to multiple 663recipients. 664 665These features are implemented by the message composing tool. Type 666@kbd{M-x jabber-compose} to start it. In the buffer that comes up, you 667can specify recipients, enter a subject, and type your message. 668 669@node File transfer, Services, Composing messages, Top 670@chapter File transfer 671 672@cindex File transfer 673@cindex Sending files 674 675jabber.el has limited support for file transfer. The most important 676limit is that files sent and received are kept in buffers, so Emacs must 677be able to allocate enough memory for the entire file, and the file size 678must be smaller than the maximum buffer size.@footnote{The maximum 679buffer size depends on in the variable @code{most-positive-fixnum}. On 68032-bit systems, this is 128 or 256 megabytes, depending on your 681Emacs version.} 682 683jabber.el is able to exchange files with most Jabber clients (and also 684some MSN transports), but notably not with the official Google Talk 685client. The Google Talk client uses a different file transfer protocol 686which, at the time of this release, has not been published. 687 688@menu 689* Receiving files:: 690* Sending files:: 691@end menu 692 693@node Receiving files, Sending files, , File transfer 694@section Receiving files 695 696Receiving files requires no configuration. When someone wants to send a 697file to you, you are asked (through @code{yes-or-no-p}) whether you want 698to accept the file. If you answer yes, you get to choose where to save 699the file. 700 701If the sender's client is correctly configured (this is often not the 702case; see below), the file transfer will start. Currently, the only way 703to watch the progress is to inspect the buffer of the file being 704transfered; @kbd{C-x C-b} is one way of doing that. @xref{List Buffers, 705, Listing Existing Buffers, emacs, GNU Emacs Manual}. When the transfer 706is done, the message ``@var{file} downloaded'' appears in the echo area, 707and the buffer is killed. 708 709@c This truly sucks... 710If this doesn't happen, it is most likely the sender's fault. The 711sender needs to have a public IP address, either directly, through port 712forwarding (in which case the client needs to be configured with the 713real public IP address), or through an XEP-0065 proxy. If you have 714activated XML logging (@pxref{Debug options}), you can see the IP 715address that the other client is asking you to connect to there. Often 716you will find that this is an internal IP address (often starts with 717@code{192.168}). See the documentation of the sender's client for 718setting this up. 719 720@node Sending files, , Receiving files, File transfer 721@section Sending files 722 723@cindex proxy, file transfer 724@cindex file transfer proxy 725@cindex XEP-0065 proxy 726 727To send a file to someone, you need an XEP-0065 proxy.@footnote{This 728requirement is not inherent in the protocol, only in the current file 729transfer implementation of jabber.el, and in Emacs versions earlier than 73022.} If your Jabber server hosts such a proxy, it will be found 731automatically, otherwise it needs to be manually configured. 732 733You can check whether your Jabber server has a proxy with @kbd{M-x 734jabber-get-disco-items}; see @ref{Service discovery}. 735 736@vindex jabber-socks5-proxies 737@findex jabber-socks5-query-all-proxies 738To configure a proxy manually, customize the variable 739@code{jabber-socks5-proxies}. Putting @code{proxy.jabber.se} there 740should work. Type @kbd{M-x jabber-socks5-query-all-proxies} to see if 741the proxies answer. 742 743@findex jabber-ft-send 744Now, you can type @kbd{M-x jabber-ft-send} to send a file to someone. 745You need to enter the correct full JID, including resource, to get this 746right. If the contact is logged in with only one client, and you can 747see it online, just typing the JID or roster name is enough. If you run 748the command from a chat buffer, the JID of the contact is given as 749the default value. 750 751If the contact has several clients online, you probably want to send the 752file to a particular one. If you run this command from within a chat 753buffer, the default target will be the one that last sent a message to 754you. If you just type a bare JID or a roster name, the client with the 755highest priority will get the file. 756 757If the contact accepts the file, and the contact's client succeeds in 758connecting to the proxy, jabber.el will send the file through the 759proxy. During this time, your Emacs will be blocked, so you might want 760to avoid sending large files over slow connections. 761 762@node Services, Personal information, File transfer, Top 763@chapter Services 764 765@cindex Browse buffers 766 767Not every Jabber entity is a physical person. There are many 768automatic entities, called servers, services, components, agents, 769transports and other names. The use of these is described here. 770 771The functions described in this chapter use @dfn{browse buffers}. 772Browse buffers are named @code{*-jabber-browse-:-@var{service}-*}, 773sometimes with a numerical suffix. The different menus have the same 774keybindings as in the roster buffer, and if you call a function 775operating on a JID while point is over a JID, that JID will be the 776default value, so you don't have to type it or copy it yourself. 777 778You can change the buffer name template by customizing 779the variable @code{jabber-browse-buffer-format}. 780 781@menu 782* Commands:: 783* Your home server:: 784* Transports:: 785* User directories:: 786* MUC services:: 787@end menu 788 789@node Commands, Your home server, , Services 790@section Commands 791 792A small number of commands is used for almost all interaction with 793Jabber services. Essentially, they are all the same: you request a form 794from the server, fill it in, and send it back. 795 796Most of these commands are available under the Service menu, which is 797opened by typing @kbd{C-c C-s}. Service discovery is under the Info 798menu instead, which is available under @kbd{C-c C-i}. 799 800@menu 801* Registration:: 802* Search:: 803* Ad-Hoc Commands:: 804* Service discovery:: 805* Browsing:: 806@end menu 807 808@node Registration, Search, , Commands 809@subsection Registration 810 811@cindex Registration 812@findex jabber-get-register 813 814You can get a registration form for a service by typing @kbd{M-x 815jabber-get-register} and entering the JID of the service. On success, 816you get a single-stage form to fill in. 817 818There are two buttons at the bottom of the form, ``Submit'' and ``Cancel 819registration''. ``Submit'' does what you would expect it to, but 820``Cancel registration'' cancels any existing registration with the 821service. Whichever of them you choose, you get a message in the echo 822area informing whether the operation succeeded. 823 824@node Search, Ad-Hoc Commands, Registration, Commands 825@subsection Search 826 827@cindex Search 828@findex jabber-get-search 829 830You can get a search form for a service by typing @kbd{M-x 831jabber-get-search}. This gives you a single-stage form to fill in. 832After you press the ``Submit'' button at the bottom, the search results 833will be displayed in the same buffer. 834 835@node Ad-Hoc Commands, Service discovery, Search, Commands 836@subsection Ad-Hoc Commands 837 838@cindex Ad-Hoc Commands 839@findex jabber-ahc-get-list 840@findex jabber-ahc-execute-command 841 842jabber.el supports a subset of XEP-0050, the standard for Ad-Hoc 843Commands. As the name implies, this can be used for just about 844anything. In particular, it is used not only by services, but also by 845clients (e.g. Psi, and jabber.el itself). 846 847To find which commands are available, run ``Request command list'' 848(@code{jabber-ahc-get-list}).@footnote{This is the same thing as a 849disco items request to the node 850@code{http://jabber.org/protocol/commands}.} 851 852To run a command from the list, put point over it and run ``Execute 853command'' (@code{jabber-ahc-execute-command}), accepting the defaults 854for JID and node. (If you already know those, you could of course 855enter them yourself.) 856 857What happens next depends on the command and the service. In some 858cases, the service just responds that the command has been run. You may 859also get a form to fill out. This form may have multiple stages, in 860which case there are ``Next'' and ``Previous'' buttons for navigating 861between stages. You may also see ``Complete'', which runs the command 862skipping any remaining stages of the form, and ``Cancel'', which cancels 863the command. 864 865Currently, jabber.el uses ad-hoc commands for setting presence remotely. 866If you realize that you forgot to set your client to ``away'' with a low 867priority, you can do it remotely from any JID from 868@code{jabber-account-list}. So, you can add disabled JIDs in 869@code{jabber-account-list} to allow them control your 870presence.@footnote{Most Jabber servers also support kicking a client off 871the net by logging in with another client with exactly the same 872resource.} 873 874@node Service discovery, Browsing, Ad-Hoc Commands, Commands 875@subsection Service discovery 876 877@cindex Service discovery 878@findex jabber-get-disco-items 879@findex jabber-get-disco-info 880 881Service discovery is used to find information about servers, services 882and clients. There are two kinds of requests: find @dfn{info} about a 883Jabber entity---i.e. its identity and supported features---and find 884@dfn{items} related to an entity, where the definition of ``related'' is 885left to the entity itself. 886 887The commands to execute such requests are @code{jabber-get-disco-info} 888and @code{jabber-get-disco-items}, respectively. These commands can be 889accessed from the Info menu, which is opened by typing @kbd{C-c C-i}. 890The commands accept a JID and optionally a ``node''. 891 892The result of such a command is displayed in a browse buffer. For an 893info request, the result just lists the identities and features of the 894entity. For an item request, the related items are listed. The items 895may be JIDs, or JIDs with a node. If you put point on one of the items, 896its JID and node will be the default value for any Jabber command. 897 898If you think that the interface to service discovery is awkward and 899should be replaced with something better, you are completely right. 900 901@node Browsing, , Service discovery, Commands 902@subsection Browsing 903 904@cindex Browsing 905@findex jabber-get-browse 906 907Before service discovery, browsing was the way to find information about 908Jabber entities. Nowadays it is all but superseded, but jabber.el still 909supports it. You can use it by typing @kbd{M-x jabber-get-browse}. It 910works much like service discovery. 911 912@node Your home server, Transports, Commands, Services 913@section Your home server 914 915@cindex Password change 916@cindex Changing password 917@cindex Account removal 918@cindex Removing an account 919 920You can interact with your Jabber server to change your password or 921remove your account. Both of these can be accomplished by typing 922@kbd{M-x jabber-get-register} and typing the JID of your server; 923@pxref{Registration}. 924 925 926@node Transports, User directories, Your home server, Services 927@section Transports to other IM networks 928 929@cindex Gateways 930@cindex Transports 931@cindex MSN transport 932@cindex ICQ transport 933@cindex AIM transport 934 935Some Jabber services make it possible to communicate with users on other 936instant messaging networks (e.g. MSN, ICQ, AIM), in effect turning your 937Jabber client into a multi-protocol client. These are called 938@dfn{gateways} or @dfn{transports}. They work by impersonating you on 939the legacy network; therefore you need to provide your username and 940password through registration. 941 942@subsection Finding a transport 943 944To use such a transport, you first need to find one, obviously. 945Sometimes your home server provides the transports you need, but you are 946not limited to those; in principle you can use any transport on the 947Jabber network. Some transports only accept local users, though. 948 949Transports are generally mentioned on the web page of the Jabber server 950in question. You can also find transports from within the client; 951@pxref{Service discovery}. 952 953@subsection Registering with a transport 954 955To register with a transport, type @kbd{M-x jabber-get-register} and 956enter the JID of the transport. This will open a registration form 957where you get to fill in your login information; @pxref{Registration}. 958You can later use this same form to change the information or cancel 959your registration. 960 961After you have registered, the transport will request presence 962subscription. It needs that to know when you are online, and 963synchronize your presence on the legacy network. 964 965@subsection Contact list 966 967Once you are registered, the transport will transfer the contact list 968from the legacy service. From the Jabber side, it appears as if lots of 969people suddenly request presence subscription to you. This is somewhat 970inconvenient, but it is currently the only way that the transport can 971influence your Jabber contact list, as it is an entity external to your 972server.@footnote{Of course, jabber.el could do more to alleviate this 973inconvenience.} 974 975When you have accepted these presence subscriptions, the contacts from 976legacy networks appear as if they were Jabber contacts. 977 978@subsection Finding users 979 980Some legacy networks have a global database of users, and some 981transports support searching that database. In that case, you can 982search for other users with @kbd{M-x jabber-get-search}; 983@pxref{Search}. 984 985@node User directories, MUC services, Transports, Services 986@section User directories 987 988There are some Jabber user directories, usually abbreviated JUDs. The 989most well-known one is @samp{users.jabber.org}. You can register with 990such a directory to let other people find you (@pxref{Registration}), 991and you can search the directory (@pxref{Search}). 992 993@node MUC services, , User directories, Services 994@section MUC services 995 996MUC services (Multi-User Chat, chat rooms) are usually not operated by 997these commands, but by commands specific to the MUC protocol; 998@pxref{Groupchat}. However, some MUC services offer nickname 999registration through the registration protocol (@pxref{Registration}), 1000and other commands; @pxref{Ad-Hoc Commands}. 1001 1002@node Personal information, Avatars, Services, Top 1003@chapter Personal information 1004 1005@cindex vCard 1006@cindex Personal information 1007@findex jabber-vcard-get 1008@findex jabber-vcard-edit 1009 1010The Jabber way of handling personal information (name, addresses, phone 1011numbers, etc) is ``vCards'' encoded in XML.@footnote{@xref{XEP-0054}.} 1012You can get information about a user by running @kbd{M-x 1013jabber-vcard-get}, @kbd{M-x jabber-muc-vcard-get} if you in MUC (also 1014available in the MUC menu), and you can edit your own information by 1015running @kbd{M-x jabber-vcard-edit}. 1016 1017The form for editing your information can be slightly confusing---you 1018are allowed to enter any number of addresses, phone numbers and e-mail 1019addresses, each of which has a set of orthogonal properties. You can 1020add and remove items with the @samp{[INS]} and @samp{[DEL]} buttons, 1021respectively. 1022 1023This is also where you set your avatar (@pxref{Avatars}). The size of 1024your avatar file is limited to 8 kilobytes. 1025 1026@node Avatars, Time queries, Personal information, Top 1027@chapter Avatars 1028 1029@cindex avatars 1030@vindex jabber-vcard-avatars-retrieve 1031@vindex jabber-vcard-avatars-publish 1032@vindex jabber-avatar-cache-directory 1033@vindex jabber-chat-buffer-show-avatar 1034 1035jabber.el supports viewing and publishing avatars according to XEP-0153, 1036vCard-Based Avatars. By default, if you have an avatar in your vCard 1037(@pxref{Personal information}), it will be published for others to see, 1038and if other people publish their avatars, they will be displayed in the 1039roster buffer and in the header line of chat buffers, if your Emacs can 1040display images. Otherwise, jabber.el will not fetch avatars at all. 1041 1042To disable retrieval of other people's avatars, set 1043@code{jabber-vcard-avatars-retrieve} to nil. To disable publishing of 1044your own avatar, set @code{jabber-vcard-avatars-publish} to nil. To 1045disable avatars in chat buffer header lines, set 1046@code{jabber-chat-buffer-show-avatar} to nil. 1047 1048There are a number of restrictions on avatar images in the 1049specification. Most of them are not enforced by jabber.el. 1050@itemize @bullet 1051@item 1052The image should be smaller than 8 kilobytes; this is enforced by 1053jabber.el. 1054@item 1055The image height and width should be between 32 and 96 pixels; the 1056recommended size is 64 by 64 pixels. 1057@item 1058The image should be square. 1059@item 1060The image should be in either PNG, GIF, or JPEG format. (jabber.el will 1061behave incorrectly if the image is not in a format supported by Emacs.) 1062@end itemize 1063 1064Avatars are cached in the directory specified by 1065@code{jabber-avatar-cache-directory}, by default 1066@file{~/.jabber-avatars/}. The cache is never cleaned, so you might 1067want to do that yourself from time to time. 1068 1069@node Time queries, Useful features, Avatars, Top 1070@chapter Time queries 1071 1072@cindex time query 1073@findex jabber-get-time 1074With @kbd{M-x jabber-get-time}, you can ask what time an entity (client, 1075server or component) thinks it is, and what time zone it thinks it is 1076in. 1077 1078@cindex last online 1079@findex jabber-get-last-online 1080You can query a server about when a certain user was last seen online. 1081Use @kbd{M-x jabber-get-last-online} for that. 1082 1083@cindex uptime, query 1084@cindex idle time, query 1085@findex jabber-get-idle-time 1086You can also ask a client about how long a user has been idle with 1087@kbd{M-x jabber-get-idle-time}. Not all clients answer such queries, 1088e.g. jabber.el doesn't. This command can also tell the uptime of a 1089server or component. 1090 1091The first of these commands uses the old Entity Time protocol 1092(@pxref{XEP-0090}). It has been superseded by XEP-0202, but jabber.el 1093doesn't implement the newer protocol yet. The latter two commands use 1094the Last Activity protocol (@pxref{XEP-0012}). 1095 1096@node Useful features, Message history, Time queries, Top 1097@chapter Useful features 1098 1099jabber.el includes a number of features meant to improve the user 1100interface and do other useful things. 1101 1102@menu 1103* Autoaway:: 1104* Modeline status:: 1105* Keepalive:: 1106* Reconnecting:: 1107* Tracking activity:: 1108* Watch buddies:: 1109* Spell checking:: 1110* Gmail notifications:: 1111* Saving groups roll state:: 1112@end menu 1113 1114@node Autoaway, Modeline status, , Useful features 1115@section Autoaway 1116 1117@cindex autoaway 1118@cindex idle 1119@cindex xprintidle 1120@vindex jabber-autoaway-method 1121@vindex jabber-autoaway-methods 1122@findex jabber-current-idle-time 1123@findex jabber-xprintidle-program 1124@findex jabber-termatime-get-idle-time 1125@vindex jabber-autoaway-timeout 1126@vindex jabber-autoaway-xa-timeout 1127@vindex jabber-autoaway-status 1128@vindex jabber-autoaway-xa-status 1129@vindex jabber-autoaway-priority 1130@vindex jabber-autoaway-xa-priority 1131 1132It is possible to automatically set your status to ``away'' or ``xa'' 1133when you haven't used your computer for a while. This lets your 1134contacts know that you might not answer immediately. You can customize 1135timeouts (@code{jabber-autoaway-timeout}, 1136@code{jabber-autoaway-xa-timeout}), statuses 1137(@code{jabber-autoaway-status}, @code{jabber-autoaway-xa-status}) and 1138priorityes (@code{jabber-autoaway-priority}, 1139@code{jabber-autoaway-xa-priority}) to set. 1140 1141To activate this feature, add @code{jabber-autoaway-start} to 1142@code{jabber-post-connect-hooks}, e.g: 1143@example 1144(add-hook 'jabber-post-connect-hooks 'jabber-autoaway-start) 1145@end example 1146 1147There are different methods to find how long you have been ``idle''. 1148The method(s) to use is specified by @code{jabber-autoaway-methods} 1149(obsoleted @code{jabber-autoaway--method} will also work). The value 1150of this variable should be a list functions that returns the number of 1151seconds you have been idle (or nil on error). Minimum of values, 1152returned by these functions, is used as ``idle'' time, so default 1153should works well. Three functions are provided (all used by default). 1154 1155@itemize @bullet 1156@item 1157@code{jabber-current-idle-time} is used if your Emacs has the 1158@code{current-idle-time} function (which was introduced in Emacs 22). 1159Note that this method only measures the time since you last interacted 1160with Emacs, and thus disregards activity in other programs. 1161 1162@item 1163@code{jabber-xprintidle-get-idle-time} uses xprintidle 1164@footnote{@uref{http://www.dtek.chalmers.se/~henoch/text/xprintidle.html}} 1165program, if found. You can also manually set 1166@code{jabber-xprintidle-program} to the correct file path. This method 1167uses the same method as 1168@uref{http://www.jwz.org/xscreensaver,XScreensaver} to find your idle 1169time. 1170 1171@item 1172@code{jabber-termatime-get-idle-time} used on GNU/Linux terminals. It 1173uses the access time of the terminal device as a measure of idle time. 1174 1175@end itemize 1176 1177@node Modeline status, Keepalive, Autoaway, Useful features 1178@section Modeline status 1179 1180@cindex Modeline 1181@findex jabber-mode-line-mode 1182@vindex jabber-mode-line-mode 1183@vindex jabber-mode-line-compact 1184 1185By typing @kbd{M-x jabber-mode-line-mode} you toggle display of some 1186status in mode lines. The information is your own presence status, 1187and some numbers showing the status of your roster contacts. By 1188default, there are three numbers, for ``online'' (chatty and online), 1189``away'' (away, extended away and do not disturb) and offline 1190contacts. 1191 1192If you set @code{jabber-mode-line-compact} to nil, you get a complete 1193breakdown of presence status. That gives you six numbers indicating 1194the number of chatty, online, away, extended away, dnd, and offline 1195contacts, respectively. 1196 1197@node Keepalive, Reconnecting, Modeline status, Useful features 1198@section Keepalive 1199 1200@cindex Keepalive 1201@cindex Detecting lost connections 1202 1203Sometimes network connections are lost without you noticing. This is 1204especially true with Jabber, as it is quite reasonable to keep the 1205connection open for a long time without either sending or receiving 1206any data. 1207 1208On the other hand, the server may want to do the same kind of 1209detection, and may expect the client to send something at regular 1210intervals. 1211 1212If you want to detect a lost connection earlier, or make sure that the 1213server doesn't drop your connection, you can use the 1214keepalive functions. These come in two flavours: whitespace pings and 1215XMPP pings. 1216 1217@subsection Whitespace pings 1218@cindex Whitespace pings 1219 1220A @dfn{whitespace ping} is a single space character sent to the server. 1221This is often enough to make NAT devices consider the connection 1222``alive'', and likewise for certain Jabber servers, e.g. Openfire. It 1223may also make the OS detect a lost connection faster---a TCP connection 1224on which no data is sent or received is indistinguishable from a lost 1225connection. 1226 1227@findex jabber-whitespace-ping-start 1228@findex jabber-whitespace-ping-stop 1229Type @kbd{M-x jabber-whitespace-ping-start} to start it, and @kbd{M-x 1230jabber-whitespace-ping-stop} to stop it. The former is in 1231@code{jabber-post-connect-hooks} by default; @pxref{Hooks}. 1232 1233@vindex jabber-whitespace-ping-interval 1234The frequency of whitespace pings is controlled by the variable 1235@code{jabber-whitespace-ping-interval}. The default value is once every 123630 seconds. 1237 1238@subsection XMPP pings 1239 1240These functions work by sending a ping request to your server once in a 1241while (by default every ten minutes), and considering the connection 1242lost if the server doesn't answer within reasonable time (by default 124320 seconds). 1244 1245@findex jabber-keepalive-start 1246@findex jabber-keepalive-stop 1247Type @kbd{M-x jabber-keepalive-start} to start 1248it, and @kbd{M-x jabber-keepalive-stop} to stop it. You may want to add 1249@code{jabber-keepalive-start} to @code{jabber-post-connect-hooks}; 1250@pxref{Hooks}. 1251 1252@vindex jabber-keepalive-interval 1253@vindex jabber-keepalive-timeout 1254You can customize the interval and the timeout with the variables 1255@code{jabber-keepalive-interval} and @code{jabber-keepalive-timeout}, 1256respectively. 1257 1258@findex jabber-ping 1259You can also manually ping some client/server by using @kbd{M-x 1260jabber-ping}. Note that pong will be displayed according 1261@code{jabber-alerts-info-messages-hooks} (default is echo in 1262minibuffer). 1263 1264@node Reconnecting, Tracking activity, Keepalive, Useful features 1265@section Reconnecting 1266 1267@cindex Reconnect 1268@cindex Automatic reconnection 1269@vindex jabber-auto-reconnect 1270 1271jabber.el supports automatic reconnection to Jabber server(s) upon lost 1272connection. By default it is off. To turn on, customize 1273the @code{jabber-auto-reconnect} variable. 1274 1275This is of limited use if you have to type your password every time 1276jabber.el reconnects. There are two ways to save your password: you can 1277set it in @code{jabber-account-alist} (@pxref{Account settings}), and 1278you can use @file{password-cache.el}, which is available in 1279recent versions of Gnus and in Emacs 23. Note that you probably want to 1280customize @code{password-cache-expiry} if you use the latter. 1281 1282@node Tracking activity, Watch buddies, Reconnecting, Useful features 1283@section Tracking activity 1284 1285@cindex Activity 1286@findex jabber-activity-mode 1287@vindex jabber-activity-make-strings 1288@vindex jabber-activity-query-unread 1289@vindex jabber-activity-count-in-title 1290@vindex jabber-activity-count-in-title-format 1291 1292When you're working on something important you might want to delay 1293responding to incoming messages. However, when you're done working, 1294will you remember them? If you're anything like me, you'll have a lot 1295of buffers in your Emacs session, and a Jabber chat buffer can easily 1296get lost. 1297 1298When @code{jabber-activity-mode} is enabled (by default, it is), Emacs keeps 1299track of the buddies which have messaged you since last you visited 1300their buffer, and will display them in mode line. As soon as you 1301visit their buffer they disappear from the mode line, indicating that 1302you've read their message. 1303 1304If your mode line fills over because of these notifications, you can 1305customize @code{jabber-activity-make-strings} to shorten them to the 1306shortest possibly unambiguous form. 1307 1308If you try to exit Emacs while you still have unread messages, you 1309will be notified and asked about this. If you don't like that, set 1310@code{jabber-activity-query-unread} to nil. 1311 1312If you want to display the number of unread buffers in the frame title, 1313set @code{jabber-activity-count-in-title} to t. The format of the 1314number can be changed through 1315@code{jabber-activity-count-in-title-format}. 1316 1317To hide activity notifications for some contacts, use 1318@code{jabber-activity-banned} variable - just add boring JIDs (as 1319regexps) here. 1320 1321For complete customizability, write a hook function for 1322@code{jabber-activity-update-hook}. From that function, you can take 1323action based on @code{jabber-activity-jids}, 1324@code{jabber-activity-mode-string}, and 1325@code{jabber-activity-count-string}. 1326 1327@node Watch buddies, Spell checking, Tracking activity, Useful features 1328@section Watch buddies 1329 1330@cindex Watch 1331@cindex Online notifications 1332@findex jabber-watch-add 1333@findex jabber-watch-remove 1334 1335Sometimes you might be waiting for a certain person to come online, 1336and you don't want that occasion to get lost in the noise. To get an 1337obtrusive message when that happens, type @kbd{M-x jabber-watch-add} 1338and select the person in question. You can enter a comment, to 1339remember why you added the watch. 1340 1341You will get a message whenever that person goes from offline to 1342online. jabber.el will remember this for the rest of your Emacs 1343session (it's not saved to disk, though), but if you want to get rid 1344of it, type @kbd{M-x jabber-watch-remove}. 1345 1346@node Spell checking, Gmail notifications, Watch buddies, Useful features 1347@section Spell checking 1348 1349@cindex flyspell 1350@cindex Spell checking 1351 1352You can activate spell checking in a chat buffer with @kbd{M-x 1353flyspell-mode}. It will check only what you are currently writing, not 1354what you receive or what you have already sent. You may want to add 1355@code{flyspell-mode} to @code{jabber-chat-mode-hook}. 1356 1357For more information about Emacs spell checking, @pxref{Spelling, , 1358Checking and Correcting Spelling, emacs, GNU Emacs Manual}. 1359 1360@node Gmail notifications, Saving groups roll state, Spell checking, Useful features 1361@section Gmail notifications 1362 1363@cindex Gmail notifications 1364 1365If you are connected to a Google Talk account, you can receive 1366notifications when a new Gmail message arrives. Gmail notifications 1367are enabled by adding the following line to your @file{.emacs}: 1368 1369@example 1370(add-hook 'jabber-post-connect-hooks 'jabber-gmail-subscribe) 1371@end example 1372 1373Default behavior is to display a message that mentions the number of 1374received gmails. You can customize this behavior by providing your 1375own @code{jabber-gmail-dothreads} function. 1376 1377Example: 1378 1379@example 1380(eval-after-load "jabber-gmail" 1381 '(defun jabber-gmail-dothreads (threads) 1382 "Process <mail-thread-info/> elements. 1383THREADS is a list of XML sexps corresponding to <mail-thread-info/> 1384elements. 1385See http://code.google.com/apis/talk/jep_extensions/gmail.html#response" 1386 (osd "gmail: %d" (length threads)))) 1387 1388;;; It's usually a good idea to have a shortcut for querying GTalk server. 1389(global-set-key (kbd "<f9> g") 'jabber-gmail-query) 1390 1391;;; The definition of `osd' function used by `jabber-gmail-dothreads'. 1392;;; `osd_cat' is shipped with the X OSD library 1393;;; [http://www.ignavus.net/software.html]. 1394(if (and (display-graphic-p) (file-executable-p "/usr/bin/osd_cat")) 1395 (defun osd (fmt &rest args) 1396 "Display message on X screen." 1397 (let ((opts "-p bottom -A center -l 1 \ 1398-f '-adobe-helvetica-bold-r-*-*-24-*-*-*-*-*-iso10646-1'") 1399 (msg (apply 'format (concat fmt "\n") args))) 1400 (start-process "osd" nil shell-file-name shell-command-switch 1401 (format "echo %s | osd_cat %s" 1402 (shell-quote-argument msg) opts)))) 1403 (defalias 'osd 'message)) 1404@end example 1405 1406@node Saving groups roll state, , Gmail notifications, Useful features 1407@section Saving groups roll state 1408 1409@cindex Saving groups roll state 1410 1411You can save roster's groups rollup/rolldown state between sessions. 1412To do this you need to add @code{jabber-roster-save-groups} to 1413@code{jabber-pre-disconnect-hook} and 1414@code{jabber-roster-restore-groups} to 1415@code{jabber-post-connect-hooks}, respectively. 1416 1417State saved in private storage on server-side (for each account). Note 1418that state restoring working by rolling up groups, rolled up at state 1419saving (by default, all groups rolled down). Also note that at now, 1420@code{jabber-pre-disconnect-hook} run only with 1421@code{jabber-disconnect} (not with @code{jabber-disconnect-one}). 1422 1423 1424@node Message history, Typing notifications, Useful features, Top 1425@chapter Message history 1426 1427@cindex History 1428@cindex Backlog 1429@findex jabber-truncate-top 1430@findex jabber-truncate-muc 1431@findex jabber-truncate-chat 1432@vindex jabber-history-enabled 1433@vindex jabber-history-muc-enabled 1434@vindex jabber-global-history-filename 1435@vindex jabber-use-global-history 1436@vindex jabber-history-dir 1437@vindex jabber-history-enable-rotation 1438@vindex jabber-history-size-limit 1439@vindex jabber-backlog-number 1440@vindex jabber-backlog-days 1441@vindex jabber-log-lines-to-keep 1442 1443If you want a record of messages sent and received, set 1444@code{jabber-history-enabled} to t. If you also want record MUC groupchat 1445messages, set @code{jabber-history-muc-enabled} to t. By default all messages will 1446be saved to a global history file specified by 1447@code{jabber-global-history-filename} 1448(@file{~/.jabber_global_message_log} by default). If you prefer to 1449store your chats' history in per-contact files, you can set 1450@code{jabber-use-global-history} to @code{nil}. When using 1451per-contact history, files are named by the contact JID and saved 1452under the directory specified by the variable 1453@code{jabber-history-dir} (default is @file{~/.emacs-jabber}). 1454 1455When you open a new chat buffer and have entries in your history file, 1456the last few messages you recently exchanged with the contact in 1457question will be inserted. You can control how many messages with 1458@code{jabber-backlog-number} (by default 10), and how old messages 1459with @code{jabber-backlog-days} (by default 3 days). 1460 1461@findex jabber-chat-display-more-backlog 1462If you want to see more messages, use the function 1463@code{jabber-chat-display-more-backlog}, available in the Chat menu. 1464This is currently the only way to view the message history, apart from 1465opening the history files manually. 1466 1467@cindex Rotation of history files 1468@cindex History file rotation 1469If you worry about your history file(s) size, you can enable history 1470rotation feature by setting the variable 1471@code{jabber-history-enable-rotation} to @code{t} (default is 1472@code{nil}). This feature ``rotates'' your history files according to 1473the following rule: When @code{jabber-history-size-limit} (in 1474kilobytes) is reached, the @var{history-file} is renamed to 1475@file{@var{history-file}-@var{number}}, where @var{number} is 1 or the smallest number 1476after the last rotation. 1477 1478For example, suppose you set the 1479@code{jabber-history-size-limit} variable to 512 and you chat with 1480your buddy @samp{foo@@jabber.server} using the per-contact strategy to store 1481history files. So, when the history file (@file{foo@@jabber-server}) 1482reaches 512K bytes, it will be renamed to @file{foo@@jabber-server-1} 1483and @file{foo@@jabber-server} will be set empty. Next time 1484@file{foo@@jabber-server} grows to 512K bytes, it will be saved as 1485@file{foo@@jabber-server-2} and so on. Although the example was 1486presented with the per-contact history file strategy, history rotation 1487works for both per-contact and global history logging strategies. 1488 1489@cindex Truncate 1490@cindex Truncation 1491If you also want to keep chat and groupchat buffers from growing too 1492much, you can customize @code{jabber-alert-message-hooks} and 1493@code{jabber-alert-muc-hooks} by adding truncation upon receiving 1494message (@code{jabber-truncate-chat} and @code{jabber-truncate-muc}, respectively). 1495The truncation limit may be set by customizing the variable 1496@code{jabber-log-lines-to-keep}. 1497 1498@node Typing notifications, Roster import and export, Message history, Top 1499@chapter Typing notifications 1500 1501There are two protocols for ``contact is typing'' notifications in 1502Jabber. jabber.el supports both of them, displaying various information 1503in the header line of chat buffers. 1504 1505@section Message events 1506 1507@cindex Composing 1508@cindex Delivered 1509@cindex Displayed 1510@vindex jabber-events-request-these 1511@vindex jabber-events-confirm-delivered 1512@vindex jabber-events-confirm-displayed 1513@vindex jabber-events-confirm-composing 1514 1515The older protocol is called Message Events (@pxref{XEP-0022}). Besides 1516typing notification, it lets you know what happens to the messages you send. 1517These states are possible: 1518 1519@itemize @bullet 1520@item 1521@samp{In offline storage} (the user will receive it on next logon) 1522 1523@item 1524@samp{Delivered} to user's client (but not necessarily displayed) 1525 1526@item 1527@samp{Displayed} to user 1528 1529@item 1530User is @samp{typing a message} 1531 1532@end itemize 1533 1534The first state is only reported by servers; the other three are 1535reported by clients. jabber.el can report all three of them, and can 1536display all four; not all clients support all states, though. 1537 1538If you don't want jabber.el to send out this information about you, set 1539the variables @code{jabber-events-confirm-delivered}, 1540@code{jabber-events-confirm-displayed}, and/or 1541@code{jabber-events-confirm-composing} to nil. You can make jabber.el 1542not to request such information by customizing 1543@code{jabber-events-request-these}. 1544 1545@section Chat states 1546 1547@vindex jabber-chatstates-confirm 1548 1549The newer protocol is called Chat States (@pxref{XEP-0085}). Rather 1550than dealing with individual messages, it describes the state of the 1551chat session between two people. The following states are possible: 1552 1553@itemize @bullet 1554@item 1555Active (the default state, not displayed) 1556 1557@item 1558Inactive 1559 1560@item 1561Composing 1562 1563@item 1564Paused (i.e., taking a short pause in composing) 1565 1566@item 1567Gone 1568 1569@end itemize 1570 1571jabber.el can display all five states, but only ever sends ``active'' 1572and ``composing'' itself. 1573 1574To customize sending of chat states, customize the variable 1575@code{jabber-chatstates-confirm}. 1576 1577 1578@node Roster import and export, XMPP URIs, Typing notifications, Top 1579@chapter Roster import and export 1580 1581@findex jabber-export-roster 1582@findex jabber-import-roster 1583@cindex Export roster 1584@cindex Import roster 1585 1586Your roster is saved on the Jabber server, and usually not in the 1587client. However, you might want to save the roster to a file anyway. 1588The most common reason for this is probably to copy it to another 1589account. 1590 1591To export your roster to a file, type @kbd{M-x jabber-export-roster}. 1592A buffer will appear in which you can edit the data to be exported. 1593Changes done in that buffer will not affect your real roster. 1594 1595To import your roster from a file, type @kbd{M-x jabber-import-roster}. 1596You will be able to edit the data before importing it. Items not in the 1597roster will be added; items in the roster will be modified to match 1598imported data. Subscriptions will be updated. 1599 1600The format of the roster files is the XML used by roster pushes in the 1601XMPP protocol, in UTF-8 encoding. 1602 1603@node XMPP URIs, Customization, Roster import and export, Top 1604@chapter XMPP URIs 1605 1606@cindex URIs 1607@cindex URLs 1608@cindex links 1609@cindex xmpp: links 1610@cindex Mozilla integration 1611@cindex web browser integration 1612@cindex browser integration 1613@findex jabber-handle-uri 1614 1615Many web page authors use links starting with @samp{xmpp:} for JIDs. 1616Your web browser could be made to pass such links to jabber.el, so that 1617such links are actually useful and not just decoration. How to do that 1618depends on your operating system and web browser. 1619 1620For any of these methods, you need to make sure that you are running 1621the Emacs server. @xref{Emacs Server, , Using Emacs as a Server, 1622emacs, GNU Emacs Manual}, though the simplest way to start it is to 1623customize the variable @code{server-mode}. 1624 1625@section GNOME 1626 1627The jabber.el distribution contains a GConf schema which tries to set 1628up handling of @samp{xmpp:} URIs. It is installed by @samp{make 1629install}. This may or may not work, depending on your GConf 1630configuration and other installed applications. To check, try 1631running: 1632 1633@example 1634gconftool --get /desktop/gnome/url-handlers/xmpp/command 1635@end example 1636 1637This should print something like: 1638 1639@example 1640/usr/local/libexec/emacs-jabber-uri-handler "%s" 1641@end example 1642 1643This setting is picked up by most GNOME or GTK based web browsers, 1644including Firefox. 1645 1646@section Mozilla and Unix 1647 1648If you use a Mozilla-based web browser on a Unix-like operating 1649system, and the GConf method above doesn't work, you can set it up 1650manually by following these steps: 1651 1652@enumerate 1653 1654@item 1655Note the path of the @file{emacs-jabber-uri-handler} file in the jabber.el 1656distribution, and make sure it is executable. 1657 1658@item 1659Set the Mozilla preference @samp{network.protocol-handler.app.xmpp} to 1660the path of @file{emacs-jabber-uri-handler}. There are two ways to do this: 1661 1662@itemize 1663@item 1664Go to the URL @samp{about:config}, right-click in the list, choose ``New 1665string'', and enter @samp{network.protocol-handler.app.xmpp} and the 1666path in the following dialogs. 1667 1668@item 1669Open or create the file @file{user.js} in your Mozilla profile directory 1670(in the same directory as @file{prefs.js}), and add the following line: 1671 1672@example 1673user_pref("network.protocol-handler.app.xmpp", 1674 "@var{/path/to}/emacs-jabber-uri-handler"); 1675@end example 1676 1677Restart Mozilla for this change to take effect. 1678@end itemize 1679@end enumerate 1680 1681@section Other systems 1682 1683If you know how to pass an XMPP URI from your browser to the function 1684@code{jabber-handle-uri}, your contribution for this section would be 1685appreciated. 1686 1687@node Customization, Hacking and extending, XMPP URIs, Top 1688@chapter Customization 1689 1690@findex jabber-customize 1691@cindex Customization 1692 1693jabber.el is intended to be customizable for many tastes. After all, 1694this is Emacs. To open a customization buffer for jabber.el, type 1695@kbd{M-x jabber-customize}. 1696 1697@menu 1698* Account settings:: 1699* Menu:: 1700* Customizing the roster buffer:: 1701* Customizing the chat buffer:: 1702* Customizing alerts:: 1703* Hooks:: 1704* Debug options:: 1705@end menu 1706 1707@node Account settings, Menu, , Customization 1708@section Account settings 1709 1710@cindex Username 1711@cindex Resource 1712@cindex Password 1713@cindex JID 1714@cindex Network server 1715 1716@vindex jabber-account-list 1717All account settings reside in the variable @code{jabber-account-list}. 1718Usually you only need to set the JID, in the form 1719@samp{username@@server} (or @samp{username@@server/resource} to use a 1720specific resource name). These are the other account options: 1721 1722@table @asis 1723@item Disabled 1724If the account is disabled, @code{jabber-connect-all} will not attempt 1725to connect it. You can still connect it manually with 1726@code{jabber-connect}. 1727 1728@item Password 1729You can set the password of the account, so you don't have to enter it 1730when you connect. Note that it will be stored unencrypted in your 1731customization file. 1732 1733@item Network server 1734If the JID of the Jabber server is not also its DNS name, you may have 1735to enter the real DNS name or IP address of the server here. 1736 1737@item Connection type 1738This option specifies whether to use an encrypted connection to the 1739server. Usually you want ``STARTTLS'' (@code{starttls}), which means 1740that encryption is activated if the server supports it. The other 1741possibilities are ``unencrypted'' (@code{network}), which means just 1742that, and ``legacy SSL/TLS'' (@code{ssl}), which means that encryption 1743is activated on connection. 1744 1745@item Port 1746If the Jabber server uses a nonstandard port, specify it here. The 1747default is 5222 for STARTTLS and unencrypted connections, and 5223 for 1748legacy SSL connections. 1749@end table 1750 1751@subsection For Google Talk 1752 1753@cindex Google Talk 1754 1755If you have a very new version of @file{dns.el},@footnote{Specifically, 1756you need Emacs 23, or No Gnus 0.3.} you can connect to 1757Google Talk just by specifying your Gmail address as JID. Otherwise, 1758you also need to set 1759``network server'' to @kbd{talk.google.com} and ``connection type'' to 1760``legacy SSL''. 1761 1762See also @ref{Gmail notifications}. 1763 1764@subsection Upgrade note 1765 1766Previous versions of jabber.el had the variables @code{jabber-username}, 1767@code{jabber-server}, @code{jabber-resource} and 1768@code{jabber-password}. These are now obsolete and not used. 1769 1770@node Menu, Customizing the roster buffer, Account settings, Customization 1771@section Menu 1772 1773@vindex jabber-display-menu 1774@cindex Menus 1775There is a Jabber menu on the menu bar with some common commands. By 1776default, it is displayed only if you are connected, or if you have 1777configured any accounts. You can set the variable 1778@code{jabber-display-menu} to @code{t} or @code{nil}, to have the menu 1779displayed always or never, respectively. The default behaviour 1780corresponds to the setting @code{maybe}. 1781 1782@findex jabber-menu 1783Earlier, the way to have the menu appear was to call the function 1784@code{jabber-menu}. It still works, but is considered obsolete. 1785 1786@node Customizing the roster buffer, Customizing the chat buffer, Menu, Customization 1787@section Customizing the roster buffer 1788 1789@cindex Roster buffer, customizing 1790 1791@cindex Sorting the roster 1792@vindex jabber-roster-sort-functions 1793@code{jabber-roster-sort-functions} controls how roster items are 1794sorted. By default, contacts are sorted first by presence, and then 1795alphabetically by displayed name. 1796 1797@vindex jabber-sort-order 1798@code{jabber-sort-order} controls how roster items are sorted by 1799presence. It is a list containing strings corresponding to show 1800status (@pxref{Presence}) or @code{nil}, which represents offline. 1801 1802@vindex jabber-show-resources 1803@code{jabber-show-resources} controls when your contacts' resources 1804are shown in the roster buffer. The default is to show resources when 1805a contact has more than one connected resource. 1806 1807@vindex jabber-roster-line-format 1808@code{jabber-roster-line-format} specifies how the entry for each 1809contact looks. It is a string where some characters are special if 1810preceded by a percent sign: 1811 1812@table @code 1813@item %a 1814Avatar of contact, if any 1815@item %c 1816@samp{*} if the contact is connected, or @samp{ } if not 1817@item %u 1818Subscription state---see below 1819@item %n 1820Nickname of contact, or JID if no nickname 1821@item %j 1822Bare JID of contact (without resource) 1823@item %r 1824Highest-priority resource of contact 1825@item %s 1826Availability of contact as a string ("Online", "Away" etc) 1827@item %S 1828Status string specified by contact 1829@end table 1830 1831@code{jabber-roster-show-title} controls whether to show a "Jabber 1832roster" string at the top of the roster buffer. You need to run 1833@kbd{M-x jabber-display-roster} after changing this variable to update 1834the display. 1835 1836@code{%u} is replaced by one of the strings given by 1837`jabber-roster-subscription-display'. 1838 1839@vindex jabber-resource-line-format 1840@code{jabber-resource-line-format} is nearly identical, except that 1841the values correspond to the values of the resource in question, and 1842that the @code{%p} escape is available, which inserts the priority of 1843the resource. 1844 1845@vindex jabber-roster-buffer 1846@code{jabber-roster-buffer} specifies the name of the roster buffer. 1847If you change this, the new name will be used the next time the roster 1848is redisplayed. 1849 1850@vindex jabber-roster-show-bindings 1851@code{jabber-roster-show-bindings} controls whether to show a list of 1852keybindings at the top of the roster buffer. You need to run @kbd{M-x 1853jabber-display-roster} after changing this variable to update the display. 1854 1855@node Customizing the chat buffer, Customizing alerts, Customizing the roster buffer, Customization 1856@section Customizing the chat buffer 1857 1858@cindex Chat buffer 1859@cindex Timestamps 1860@cindex Faces, chat buffer 1861 1862You can customize the look of the prompts in the chat buffer. There 1863are separate settings for local text (i.e. what you write) and foreign text 1864(i.e. what other people write). 1865 1866@vindex jabber-chat-text-local 1867@vindex jabber-chat-text-foreign 1868@code{jabber-chat-text-local} and @code{jabber-chat-text-foreign} 1869determine the faces used for chat messages. 1870 1871@vindex jabber-chat-prompt-local 1872@vindex jabber-chat-prompt-foreign 1873@vindex jabber-muc-colorize-local 1874@vindex jabber-muc-colorize-foreign 1875@vindex jabber-muc-nick-saturation 1876@vindex jabber-muc-nick-value 1877@vindex jabber-muc-participant-colors 1878@cindex Nick coloring 1879@code{jabber-chat-prompt-local} and @code{jabber-chat-prompt-foreign} 1880determine the faces used for the prompts. You can also turn on 1881automatic colorization of local (@code{jabber-muc-colorize-local}) 1882and/or foreign (@code{jabber-muc-colorize-foreign}) prompts. By 1883default it is off. You can correct and save for future use auto-generated colors by 1884customizing @code{jabber-muc-participant-colors}, @code{jabber-muc-nick-saturation} and 1885@code{jabber-muc-nick-value}, if you wish. 1886 1887@vindex jabber-chat-local-prompt-format 1888@vindex jabber-chat-foreign-prompt-format 1889@code{jabber-chat-local-prompt-format} and 1890@code{jabber-chat-foreign-prompt-format} determine what text is 1891displayed in the prompts. They are format strings, with the following 1892special sequences defined: 1893 1894@table @code 1895@item %t 1896The time when the message was sent or received 1897@item %n 1898The nickname of the user. For the foreign prompt, this is the name of 1899the contact in the roster, or the JID if no name set. For the local 1900prompt, this is the username part of your JID. 1901@item %u 1902The username of the user (i.e. the first part of the JID). 1903@item %r 1904The resource. 1905@item %j 1906The bare JID of the user 1907@end table 1908 1909@cindex Timestamp format 1910@vindex jabber-chat-time-format 1911@code{jabber-chat-time-format} defines how @code{%t} shows time. Its 1912format is identical to that passed to @code{format-time-string}. 1913@xref{Time Conversion, , Time Conversion, elisp, GNU Emacs Lisp 1914Reference Manual}. 1915 1916@vindex jabber-chat-delayed-time-format 1917@code{jabber-chat-delayed-time-format} is used instead of 1918@code{jabber-chat-time-format} for delayed messages (messages sent while 1919you were offline, or fetched from history). This way you can have short 1920timestamps everywhere except where you need long ones. You can always 1921see the complete timestamp in a tooltip by hovering over the prompt with 1922the mouse. 1923 1924@cindex Rare timestamps 1925@vindex jabber-print-rare-time 1926@vindex jabber-rare-time-format 1927@vindex jabber-chat-text-local 1928By default, timestamps are printed in the chat buffer every hour (at 1929``rare'' times). This can be toggled with 1930@code{jabber-print-rare-time}. You can customize the displayed time by 1931setting @code{jabber-rare-time-format}. Rare timestamps will be printed 1932whenever time formatted by that format string would change. 1933 1934@cindex Header line of chat buffers 1935@vindex jabber-chat-header-line-format 1936@vindex jabber-muc-header-line-format 1937You can also customize the header line of chat buffers, by modifying 1938the variable @code{jabber-chat-header-line-format}. The format of 1939that variable is the same as that of @code{mode-line-format} and 1940@code{header-line-format}. @xref{Mode Line Format, , Mode-Line 1941Format, elisp, GNU Emacs Lisp Reference Manual}. For MUC buffers, 1942@code{jabber-muc-header-line-format} is used instead. 1943 1944@vindex jabber-chat-fill-long-lines 1945@cindex Filling long lines in chat buffer 1946The variable @code{jabber-chat-fill-long-lines} controls whether long 1947lines in the chat buffer are wrapped. 1948 1949@node Customizing alerts, Hooks, Customizing the chat buffer, Customization 1950@section Customizing alerts 1951 1952@cindex Alert hooks 1953@findex define-jabber-alert 1954 1955When an event happens (currently including presence changes, incoming 1956messages, and completed queries) you will usually want to be 1957notified. Since tastes in this area vary wildly, these alerts are 1958implemented as hooks, so you can choose which ones you want, or write 1959your own if none fit. 1960 1961Actually, if you don't want to write your own, stop reading this 1962section and just read @ref{Standard alerts}. 1963 1964Many kinds of alerts consist in displaying a text message through a 1965certain mechanism. This text message is provided by a function which 1966you can rewrite or replace. If this function returns @code{nil}, no 1967message is displayed, and non-textual alerts refrain from action. 1968 1969If you want to write alert hooks that do nothing except displaying the 1970supplied message in some way, use the macro 1971@code{define-jabber-alert}. For example, if @var{foo} is a function 1972that takes a string as an argument, write 1973@example 1974(define-jabber-alert foo 1975 "Display a message in a fooish way" 1976 'foo) 1977@end example 1978@noindent 1979and all details will be taken care of for you. 1980 1981The hooks take different arguments depending on category. However, 1982they all have in common that the last argument is the result of the 1983message function. The message function for each category takes the 1984same arguments as the corresponding hooks, except for that last 1985argument. 1986 1987Alert hook contributions are very welcome. You can send them to the 1988mailing list, or to the Sourceforge patch tracker. @xref{Contacts}. 1989 1990Alert hooks are meant for optional UI things, that are subject to 1991varying user tastes, and that can be toggled by simply adding or 1992removing the function to and from the hook. For other purposes, there 1993are corresponding general hooks, that are defvars instead of 1994defcustoms, and that are meant to be managed by Lisp code. They have the 1995same name as the alert hooks minus the @code{-alert} part, 1996e.g. @code{jabber-message-hooks} vs @code{jabber-alert-message-hooks}, 1997etc. 1998 1999@menu 2000* Standard alerts:: 2001* Presence alerts:: 2002* Message alerts:: 2003* MUC alerts:: 2004* Info alerts:: 2005@end menu 2006 2007@node Standard alerts, Presence alerts, , Customizing alerts 2008@subsection Standard alerts 2009 2010@cindex Alerts 2011@cindex Scroll 2012 2013Thirteen alerts are already written for all four alert categories. These 2014all obey the result from the corresponding message function. 2015 2016The @code{beep} alerts simply sound the terminal bell by calling 2017@code{ding}. They are disabled by default. 2018 2019The @code{echo} alerts display a message in the echo area by calling 2020@code{message}. They are enabled by default. 2021 2022The @code{switch} alerts switch to the buffer where the event occurred 2023(chat buffer for incoming messages, roster buffer for presence 2024changes, browse buffer for completed queries). They are disabled by 2025default. Take care when using them, as they may interrupt your 2026editing. 2027 2028The @code{display} alerts display but do not select the buffer in 2029question, using the function @code{display-buffer}. @xref{Choosing 2030Window, , Choosing a Window for Display, elisp, GNU Emacs Lisp 2031Reference Manual}, for information about customizing its behaviour. 2032This is enabled by default for info requests. 2033 2034@cindex Sound effects 2035The @code{wave} alerts play a sound file by calling 2036@code{play-sound-file}. No sound files are provided. To use this, 2037enter the names of the sound files in 2038@code{jabber-alert-message-wave}, @code{jabber-alert-presence-wave} 2039and @code{jabber-alert-info-wave}, respectively. You can specify 2040specific sound files for contacts matching a regexp in the variables 2041@code{jabber-alert-message-wave-alist} and 2042@code{jabber-alert-presence-wave-alist}. 2043 2044@cindex Screen terminal manager 2045The @code{screen} alerts send a message through the Screen terminal 2046manager@footnote{See @uref{http://www.gnu.org/software/screen/}.}. They do no 2047harm if called when you don't use Screen. 2048 2049@cindex Tmux terminal manager 2050The @code{tmux} alerts send a message through the tmux terminal 2051manager@footnote{See @uref{http://tmux.sourceforge.net/}.}. 2052 2053@cindex Ratpoison window manager 2054@cindex Window manager, Ratpoison 2055The @code{ratpoison} alerts send a message through the Ratpoison 2056window manager@footnote{See @uref{http://ratpoison.sourceforge.net/}.}. They 2057do no harm if used when you're not running X, but if you are running X 2058with another window manager, the ratpoison processes will never exit. 2059Emacs doesn't hold on to them, though. 2060 2061@cindex Sawfish window manager 2062@cindex Window manager, Sawfish 2063The @code{sawfish} alerts send a message through the Sawfish window 2064manager. 2065 2066@cindex wmii window manager 2067@cindex Window manager, wmii 2068The @code{wmii} alerts display a message through the wmii window 2069manager. 2070 2071@cindex awesome window manager 2072@cindex Window manager, awesome 2073The @code{awesome} alerts display a message through the awesome window 2074manager. However, to work it needs naughty (i.e. 2075@code{require("naughty")} in rc.lua). 2076 2077@cindex xmessage 2078@vindex jabber-xmessage-timeout 2079The @code{xmessage} alerts send a message through the standard 2080@code{xmessage} tool. The variable @code{jabber-xmessage-timeout} 2081controls how long the alert appears. 2082 2083@cindex OSD 2084The @code{osd} alerts send a message onto your screen using 2085XOSD.@footnote{XOSD can be found at 2086@uref{http://www.ignavus.net/software.html}. You also need 2087@file{osd.el} from @uref{http://www.brockman.se/software/osd.el}.} 2088 2089@cindex libnotify 2090@cindex notification-daemon 2091The @code{libnotify} alerts send a message onto your screen using 2092@code{notification-daemon}. 2093 2094@cindex Festival speech synthesis 2095@cindex Speech synthesis, Festival 2096The @code{festival} alerts speak the message using the Emacs interface 2097of the Festival speech synthesis system@footnote{See 2098@uref{http://www.cstr.ed.ac.uk/projects/festival/}.}. 2099 2100@cindex Autoanswerer 2101The @code{autoanswer} alert is kind of special: it will not show you 2102message/muc alert, but instead will automaticaly answer to sender. See 2103variable `jabber-autoanswer-alist' description for details. 2104 2105@cindex Scroll chat buffers 2106Additionally, for one-to-one and MUC messages, there are @code{scroll} 2107alerts (enabled by default), that aim to do the right thing with chat 2108buffers that are visible but not active. Sometimes you want point to 2109scroll down, and sometimes not. These functions should do what you 2110mean; if they don't, it's a bug. 2111 2112Also, in MUC you can use a family of so-called ``personal'' alerts. 2113They are like other MUC alerts, but fire only on incoming messages 2114addresed directly to you (also known as ``private messages''). One 2115example of such an alert is @code{jabber-muc-echo-personal}, which shows 2116a note for an MUC message only if it was addressed to you. 2117 2118Some of these functions are in the @file{jabber-alert.el} file, and the 2119others are in their own files. You can use them as templates or 2120inspiration for your own alerts. 2121 2122@node Presence alerts, Message alerts, Standard alerts, Customizing alerts 2123@subsection Presence alerts 2124 2125@vindex jabber-alert-presence-message-function 2126@findex jabber-presence-default-message 2127 2128Set @code{jabber-alert-presence-message-function} to your desired 2129function. This function should look like: 2130 2131@example 2132(defun @var{function} (@var{who} @var{oldstatus} @var{newstatus} @var{statustext}) 2133 ... 2134 ) 2135@end example 2136 2137@var{who} is the JID symbol (@pxref{JID symbols}), 2138@var{oldstatus} and @var{newstatus} are the previous and current 2139stati, respectively, and @var{statustext} is the status message if 2140provided, otherwise nil. 2141 2142@var{oldstatus} and @var{newstatus} can be one of @code{""} 2143(i.e. online), @code{"away"}, @code{"xa"}, @code{"dnd"}, @code{"chat"}, 2144@code{"error"} and @code{nil} (i.e. offline). 2145 2146@var{newstatus} can also be one of @code{"subscribe"}, 2147@code{"subscribed"}, @code{"unsubscribe"} and @code{"unsubscribed"}. 2148 2149The default function, @code{jabber-presence-default-message}, returns 2150@code{nil} if @var{oldstatus} and @var{newstatus} are the same, and in 2151other cases constructs a message from the given data. 2152 2153Another function, @code{jabber-presence-only-chat-open-message}, 2154behave just like @code{jabber-presence-default-message}, but only if 2155conversation buffer for according JID is already open. Use it to show 2156presence notifications only for ``interesting'' contacts. 2157 2158All presence alert hooks take the same arguments plus the additional 2159@var{proposed-alert}, which is the result of the specified message 2160function. This last argument is usually the only one they use. 2161 2162@node Message alerts, MUC alerts, Presence alerts, Customizing alerts 2163@subsection Message alerts 2164 2165@vindex jabber-alert-message-function 2166@findex jabber-message-default-message 2167 2168Set @code{jabber-alert-message-function} to your desired 2169function.@footnote{Logically it should be 2170@code{jabber-alert-message-message-function}, but that would be 2171really ugly.} This function should look like: 2172 2173@example 2174(defun @var{function} (@var{from} @var{buffer} @var{text}) 2175 ... 2176 ) 2177@end example 2178 2179@var{from} is the JID symbol (@pxref{JID symbols}), @var{buffer} 2180is the buffer where the message is displayed, and @var{text} is the 2181text of the message. 2182 2183The default function, @code{jabber-message-default-message}, returns 2184``Message from @var{person}'', where @var{person} is the name of the 2185person if specified in the roster, otherwise the JID. 2186 2187All message alert hooks take the same arguments plus the additional 2188@var{proposed-alert}, which is the result of the specified message 2189function. 2190 2191@vindex jabber-message-alert-same-buffer 2192If you don't want message alerts when the chat buffer in question is 2193already the current buffer, set @code{jabber-message-alert-same-buffer} 2194to nil. This affects the behaviour of the default message function, so 2195you'll have to reimplement this functionality if you write your own 2196message function. 2197 2198@node MUC alerts, Info alerts, Message alerts, Customizing alerts 2199@subsection MUC alerts 2200 2201@vindex jabber-alert-muc-function 2202@vindex jabber-muc-alert-self 2203@findex jabber-muc-default-message 2204 2205Set @code{jabber-alert-muc-function} to your desired 2206function. This function should look like: 2207 2208@example 2209(defun @var{function} (@var{nick} @var{group} @var{buffer} @var{text}) 2210 ... 2211 ) 2212@end example 2213 2214@var{nick} is the nickname, @var{group} is the JID of the group, 2215@var{buffer} is the buffer where the message is displayed, and 2216@var{text} is the text of the message. 2217 2218The default function, @code{jabber-muc-default-message}, returns 2219``Message from @var{nick} in @var{group}'' or ``Message in 2220@var{group}'', the latter for messages from the room itself. 2221 2222All MUC alert hooks take the same arguments plus the additional 2223@var{proposed-alert}, which is the result of the specified message 2224function. 2225 2226By default, no alert is made for messages from yourself. To change 2227that, customize the variable @code{jabber-muc-alert-self}. 2228 2229@node Info alerts, , MUC alerts, Customizing alerts 2230@subsection Info alerts 2231 2232@vindex jabber-alert-info-message-function 2233@findex jabber-info-default-message 2234 2235Info alerts are sadly underdeveloped. The message function, 2236@code{jabber-alert-info-message-function}, takes two arguments, 2237@var{infotype} and @var{buffer}. @var{buffer} is the buffer where 2238something happened, and @var{infotype} is either @code{'roster} for 2239roster updates, or @code{'browse} for anything that uses the browse 2240buffer (basically anything except chatting). 2241 2242The info alert hooks take an extra argument, as could be expected. 2243 2244@node Hooks, Debug options, Customizing alerts, Customization 2245@section Hooks 2246 2247jabber.el provides various hooks that you can use for whatever 2248purpose. 2249 2250@table @code 2251@vindex jabber-post-connect-hooks 2252@item jabber-post-connect-hooks 2253This hook is called after successful connection and authentication. 2254By default it contains @code{jabber-send-current-presence} 2255(@pxref{Presence}). The hook functions get the connection object as 2256argument. 2257 2258@vindex jabber-lost-connection-hooks 2259@item jabber-lost-connection-hooks 2260This hook is called when you have been disconnected for unknown 2261reasons. Usually this isn't noticed for quite a long time. 2262 2263The hook is called with one argument: the connection object. 2264 2265@vindex jabber-pre-disconnect-hook 2266@item jabber-pre-disconnect-hook 2267This hook is called just before voluntary disconnection, i.e. in 2268@code{jabber-disconnect}, the command to disconnect all accounts. There 2269is currently no hook for disconnection of a single account. 2270 2271@vindex jabber-post-disconnect-hook 2272@item jabber-post-disconnect-hook 2273This hook is called after disconnection of any kind, possibly just 2274after @code{jabber-lost-connection-hook}. 2275 2276@vindex jabber-chat-mode-hook 2277@item jabber-chat-mode-hook 2278This hook is called when a new chat buffer is created. 2279 2280@vindex jabber-browse-mode-hook 2281@item jabber-browse-mode-hook 2282This hook is called when a new browse buffer is created. 2283 2284@vindex jabber-roster-mode-hook 2285@item jabber-roster-mode-hook 2286This hook is called when the roster buffer is created. 2287 2288@end table 2289 2290@node Debug options, , Hooks, Customization 2291@section Debug options 2292 2293These settings provide a lot of information which is usually not very 2294interesting, but can be useful for debugging various things. 2295 2296@vindex jabber-debug-log-xml 2297@cindex XML console 2298@code{jabber-debug-log-xml} activates XML console. All XML stanzas 2299sent and received are logged in the buffer @code{*-jabber-console-@var{jid}-*} 2300(and to specified file if value is string). 2301Also this buffer can be used to send XML stanzas manually. 2302 2303@vindex jabber-console-name-format 2304Format for console buffer name. %s mean connection jid. Default value is 2305@code{*-jabber-console-%s-*}. 2306 2307@vindex jabber-console-truncate-lines 2308Maximum number of lines in console buffer. Use this option to prevent 2309over bloating size of buffer. 2310Set value to 0 if you want to keep all stanzas in buffer, but 2311it's not recommended and may be unsafe. 2312 2313@vindex jabber-debug-keep-process-buffers 2314Usually, the process buffers for Jabber connections are killed when the 2315connection is closed, as they would otherwise just fill up memory. 2316However, they might contain information about why the connection was 2317lost. To keep process buffers, set 2318@code{jabber-debug-keep-process-buffers} to @code{t}. 2319 2320@node Hacking and extending, Protocol support, Customization, Top 2321@chapter Hacking and extending 2322 2323This part of the manual is an attempt to explain parts of the source 2324code. It is not meant to discourage you from reading the code 2325yourself and trying to figure it out, but as a guide on where to 2326look. Knowledge of Jabber protocols is assumed. 2327 2328@menu 2329* Connection object:: 2330* XML representation:: 2331* JID symbols:: 2332* Listening for new requests:: 2333* Sending new requests:: 2334* Extending service discovery:: 2335* Chat printers:: 2336* Stanza chains:: 2337@end menu 2338 2339@node Connection object, XML representation, , Hacking and extending 2340@section Connection object 2341@cindex connection object 2342@cindex account object 2343@cindex FSM 2344 2345Each Jabber connection is represented by a ``connection object''. This 2346object has the form of a finite state machine, and is realized by the 2347library @code{fsm}.@footnote{So far, this library is only distributed 2348with jabber.el. The author hopes that it could be useful for other 2349projects, too.} 2350 2351The various states of this object are defined in @file{jabber-core.el}. 2352They describe the way of the connection through the establishing of a 2353network connection and authentication, and finally comes to the 2354@code{:session-established} state where ordinary traffic takes place. 2355 2356These details are normally opaque to an extension author. As will be 2357noted, many functions expect to receive a connection object, and 2358functions at extension points generally receive such an object in order 2359to pass it on. The following functions simply query the internal state 2360of the connection: 2361 2362@defun jabber-connection-jid connection 2363The @code{jabber-connection-jid} function returns the full JID of 2364@var{connection}, i.e. a string of the form 2365@code{"username@@server/resource"}. 2366@end defun 2367 2368@defun jabber-connection-bare-jid connection 2369The @code{jabber-connection-bare-jid} function returns the bare JID of 2370@var{connection}, i.e. a string of the form @code{"username@@server"}. 2371@end defun 2372 2373@node XML representation, JID symbols, Connection object, Hacking and extending 2374@section XML representation 2375 2376@cindex XML representation 2377 2378The XML representation is the one generated by @file{xml.el} in Emacs, 2379namely the following. Each tag is a list. The first element of the 2380list is a symbol, the name of which is the name of the tag. The 2381second element is an alist of attributes, where the keys are the 2382attribute names in symbol form, and the values are strings. The 2383remaining elements are the tags and data contained within the tag. 2384 2385For example, 2386@example 2387<foo bar='baz'> 2388<frobozz/>Fnord 2389</foo> 2390@end example 2391is represented as 2392@example 2393(foo ((bar . "baz")) (frobozz nil "") "Fnord 2394") 2395@end example 2396 2397Note the empty string as the third element of the @code{frobozz} 2398list. It is not present in newer (post-21.3) versions of 2399@file{xml.el}, but it's probably best to assume it might be there. 2400 2401@defun jabber-sexp2xml xml-sexp 2402This function takes a tag in list representation, and returns its XML 2403representation as a string. You will normally not need to use this 2404function directly, but it can be useful to see how your sexps will look 2405when sent to the outer, non-Lisp, world. 2406@end defun 2407 2408@defun jabber-send-sexp connection sexp 2409This function sends @var{sexp}, an XMPP stanza in list representation, 2410and sends it over @var{connection}. 2411 2412You will normally use the functions @code{jabber-send-presence}, 2413@code{jabber-send-message} and @code{jabber-send-iq} instead of this 2414function. 2415@end defun 2416 2417@node JID symbols, Listening for new requests, XML representation, Hacking and extending 2418@section JID symbols 2419 2420@vindex jabber-jid-obarray 2421JIDs are sometimes represented as symbols. Its name is the JID, and it is interned 2422in @code{jabber-jid-obarray}. A roster entry can have the following 2423properties: 2424 2425@table @code 2426@item xml 2427The XML tag received from the server on roster update 2428 2429@item name 2430The name of the roster item (just like the XML attribute) 2431 2432@item subscription 2433The subscription state; a string, one of @code{"none"}, @code{"from"}, 2434@code{"to"} and @code{"both"} 2435 2436@item ask 2437The ask state; either @code{nil} or @code{"subscribe"} 2438 2439@item groups 2440A list of strings (possibly empty) containing all the groups the 2441contact is in 2442 2443@item connected 2444Boolean, true if any resource is connected 2445 2446@item show 2447Presence show value for highest-priority connected resource; a string, 2448one of @code{""} (i.e. online), @code{"away"}, @code{"xa"}, 2449@code{"dnd"}, @code{"chat"}, @code{"error"} and @code{nil} 2450(i.e. offline) 2451 2452@item status 2453Presence status message for highest-priority connected resource 2454 2455@item resources 2456Alist. Keys are strings (resource names), values are plists with 2457properties @code{connected}, @code{show}, @code{status} and 2458@code{priority}. 2459 2460@end table 2461 2462Incoming presence information is inserted in @code{resources}, and the 2463information from the resource with the highest priority is inserted in 2464@code{show} and @code{status} by the function 2465@code{jabber-prioritize-resources}. 2466 2467@node Listening for new requests, Sending new requests, JID symbols, Hacking and extending 2468@section Listening for new requests 2469 2470@findex jabber-send-iq 2471@findex jabber-process-iq 2472@findex jabber-signal-error 2473@vindex jabber-iq-get-xmlns-alist 2474@vindex jabber-iq-set-xmlns-alist 2475 2476To listen for new IQ requests, add the appropriate entry in 2477@code{jabber-iq-get-xmlns-alist} or @code{jabber-iq-set-xmlns-alist}. 2478The key is the namespace of the request, and the value is a function 2479that takes two arguments, the connection object, and 2480the entire IQ stanza in list format. 2481@code{jabber-process-iq} reads these alists to determine which 2482function to call on incoming packets. 2483 2484For example, the Ad-Hoc Commands module contains the following: 2485 2486@example 2487(add-to-list 'jabber-iq-set-xmlns-alist 2488 (cons "http://jabber.org/protocol/commands" 2489 'jabber-ahc-process)) 2490@end example 2491 2492To send a response to an IQ request, use @samp{(jabber-send-iq 2493@var{connection} @var{sender} "result" @var{query} nil nil nil nil 2494@var{id})}, where @var{query} is the query in list format. 2495@code{jabber-send-iq} will encapsulate the query in an IQ packet with 2496the specified id. 2497 2498To return an error to the Jabber entity that sent the query, use 2499@code{jabber-signal-error}. The signal is caught by 2500@code{jabber-process-iq}, which takes care of sending the error. 2501You can also use @code{jabber-send-iq-error}. 2502 2503@node Sending new requests, Extending service discovery, Listening for new requests, Hacking and extending 2504@section Sending new requests 2505 2506@findex jabber-send-iq 2507@findex jabber-process-iq 2508 2509To send an IQ request, use @code{jabber-send-iq}. It will generate an 2510id, and create a mapping for it for use when the response comes. The 2511syntax is: 2512 2513@example 2514(jabber-send-iq @var{connection} @var{to} @var{type} @var{query} 2515 @var{success-callback} @var{success-closure} 2516 @var{failure-callback} @var{failure-closure}) 2517@end example 2518 2519@var{success-callback} will be called if the response is of type 2520@samp{result}, and @var{failure-callback} will be called if the response 2521is of type @samp{error}. Both callbacks take three arguments, the 2522connection object, the IQ stanza of the response, and the corresponding 2523closure item earlier passed to @code{jabber-send-iq}. 2524 2525@findex jabber-report-success 2526@findex jabber-process-data 2527Two standard callbacks are provided. @code{jabber-report-success} takes 2528a string as closure item, and reports success or failure in the echo 2529area by appending either @samp{succeeded} or @samp{failed} to the 2530string. @code{jabber-process-data} prepares a browse buffer. If its 2531closure argument is a function, it calls that function with point in 2532this browse buffer. If it's a string, it prints that string along with 2533the error message in the IQ response. If it's anything else 2534(e.g. @code{nil}), it just dumps the XML in the browse buffer. 2535 2536Examples follow. This is the hypothetical Jabber protocol ``frob'', 2537for which only success report is needed: 2538@example 2539(jabber-send-iq connection 2540 "someone@@somewhere.org" "set" 2541 '(query ((xmlns . "frob"))) 2542 'jabber-report-success "Frobbing" 2543 'jabber-report-success "Frobbing") 2544@end example 2545This will print ``Frobbing succeeded'' or ``Frobbing failed: @var{reason}'', 2546respectively, in the echo area. 2547 2548The protocol ``investigate'' needs to parse results and show them in a 2549browse buffer: 2550@example 2551(jabber-send-iq connection 2552 "someone@@somewhere.org" "get" 2553 '(query ((xmlns . "investigate"))) 2554 'jabber-process-data 'jabber-process-investigate 2555 'jabber-process-data "Investigation failed") 2556@end example 2557Of course, the previous example could have used 2558@code{jabber-report-success} for the error message. It's a matter of 2559UI taste. 2560 2561@node Extending service discovery, Chat printers, Sending new requests, Hacking and extending 2562@section Service discovery 2563 2564Service discovery (XEP-0030) is a Jabber protocol for communicating 2565features supported by a certain entity, and items affiliated with an 2566entity. jabber.el has APIs for both providing and requesting such 2567information. 2568 2569 2570@menu 2571* Providing info:: 2572* Requesting info:: 2573@end menu 2574 2575@node Providing info, Requesting info, , Extending service discovery 2576@subsection Providing info 2577 2578Your new IQ request handlers will likely want to advertise their 2579existence through service discovery. 2580 2581@vindex jabber-advertised-features 2582To have an additional feature reported in response to disco info 2583requests, add a string to @code{jabber-advertised-features}. 2584 2585@vindex jabber-disco-items-nodes 2586@vindex jabber-disco-info-nodes 2587By default, the service discovery functions reject all requests 2588containing a node identifier with an ``Item not found'' error. To 2589make them respond, add the appropriate entries to 2590@code{jabber-disco-items-nodes} and @code{jabber-disco-info-nodes}. 2591Both variables work in the same way. They are alists, where the keys 2592are the node names, and the values are lists of two items. 2593 2594The first item is the data to return --- either a list, or a function 2595taking the connection object and the entire IQ stanza and returning a 2596list; in either case this list contains the XML nodes to include in the 2597@code{<query/>} node in the response. 2598 2599@findex jabber-my-jid-p 2600The second item is the access control function. An access control 2601function receives the connection object and a JID as arguments, and 2602returns non-nil if access is to be granted. If nil is specified 2603instead of a function, access is always granted. One such function is 2604provided, @code{jabber-my-jid-p}, which grants access for JIDs where 2605the username and server (not necessarily resource) are equal to those 2606of the user, or one of the user's configured accounts. 2607 2608@node Requesting info, , Providing info, Extending service discovery 2609@subsection Requesting info 2610 2611jabber.el has a facility for requesting disco items and info. All 2612positive responses are cached. 2613 2614To request disco items or info from an entity, user one of these 2615functions: 2616 2617@defun jabber-disco-get-info jc jid node callback closure-data &optional force 2618Get disco information for @var{jid} and @var{node}. A request is sent 2619asynchronously on the connection @var{jc}. When the response arrives, 2620@var{callback} is called with three arguments: @var{jc}, 2621@var{closure-data}, and the result. The result may be retrieved from 2622the cache, unless @var{force} is non-nil. 2623 2624If the request was successful, or retrieved from cache, it looks like 2625@code{(@var{identities} @var{features})}, where @var{identities} and 2626@var{features} are lists. Each identity is @code{["@var{name}" 2627"@var{category}" "@var{type}"]}, and each feature is a string denoting 2628the namespace of the feature. 2629 2630If the request failed, the result is an @code{<error/>} node. 2631@end defun 2632 2633@defun jabber-disco-get-items jc jid node callback closure-data &optional force 2634Get disco information for @var{jid} and @var{node}. A request is sent 2635asynchronously on the connection @var{jc}. When the response arrives, 2636@var{callback} is called with three arguments: @var{jc}, 2637@var{closure-data}, and the result. The result may be retrieved from 2638the cache, unless @var{force} is non-nil. 2639 2640If the request was successful, or retrieved from cache, the result is 2641a list of items, where each item is @code{["@var{name}" "@var{jid}" 2642"@var{node}"]}. The values are either strings or nil. 2643 2644If the request failed, the result is an @code{<error/>} node. 2645@end defun 2646 2647If you only want to see what is in the cache, use one of the following 2648functions. They don't use a callback, but return the result directly. 2649 2650@defun jabber-disco-get-info-immediately jid node 2651Return cached disco information for @var{jid} and @var{node}, or nil 2652if the cache doesn't contain this information. The result is the same 2653as for @code{jabber-disco-get-info}. 2654@end defun 2655 2656@defun jabber-disco-get-items-immediately jid node 2657Return cached disco items for @var{jid} and @var{node}, or nil 2658if the cache doesn't contain this information. The result is the same 2659as for @code{jabber-disco-get-items}. 2660@end defun 2661 2662In the future, this facility will be expanded to provide information 2663acquired through XEP-0115, Entity capabilities, which is a protocol 2664for sending disco information in @code{<presence/>} stanzas. 2665 2666@node Chat printers, Stanza chains, Extending service discovery, Hacking and extending 2667@section Chat printers 2668 2669@vindex jabber-chat-printers 2670@vindex jabber-muc-printers 2671@vindex jabber-body-printers 2672@cindex Chat printers 2673@cindex Body printers 2674 2675Chat printers are functions that print a certain aspect of an incoming 2676message in a chat buffer. Included are functions for printing subjects 2677(@code{jabber-chat-print-subject}), bodies 2678(@code{jabber-chat-print-body}, and @code{jabber:x:oob}-style URLs 2679(@code{jabber-chat-print-url}). The functions in 2680@code{jabber-chat-printers} are called in order, with the entire 2681@code{<message/>} stanza as argument. As described in the docstring 2682of @code{jabber-chat-printers}, these functions are run in one of two 2683modes: @code{printp}, in which they are supposed to return true if 2684they would print anything, and @code{insert}, in which they are 2685supposed to actually print something, if appropriate, using the 2686function @code{insert}. 2687 2688For MUC, the functions in @code{jabber-muc-printers} are prepended to 2689those in @code{jabber-chat-printers}. 2690 2691Body printers are a subgroup of chat printers. They are exclusive; only 2692one of them applies to any given message. The idea is that 2693``higher-quality'' parts of the message override pieces included for 2694backwards compatibility. Included are @code{jabber-muc-print-invite} 2695and @code{jabber-chat-normal-body}; functions for XHTML-IM and PGP 2696encrypted messages may be written in the future. The functions in 2697@code{jabber-body-printers} are called in order until one of them 2698returns non-nil. 2699 2700@node Stanza chains, , Chat printers, Hacking and extending 2701@section Stanza chains 2702 2703@vindex jabber-message-chain 2704@vindex jabber-iq-chain 2705@vindex jabber-presence-chain 2706 2707If you really need to get under the skin of jabber.el, you can add 2708functions to the lists @code{jabber-message-chain}, 2709@code{jabber-iq-chain} and @code{jabber-presence-chain}. The 2710functions in these lists will be called in order when an XML stanza of 2711the corresponding type arrives, with the connection object and the 2712entire XML stanza passed as arguments. Earlier functions can modify 2713the stanza to change the behaviour of downstream functions, but 2714remember: with great power comes great responsibility. 2715 2716@node Protocol support, Concept index, Hacking and extending, Top 2717@appendix Protocol support 2718 2719@cindex Supported protocols 2720 2721These are the protocols currently supported (in full or partially) by 2722jabber.el. 2723 2724@menu 2725* RFC 3920:: XMPP-CORE 2726* RFC 3921:: XMPP-IM 2727* XEP-0004:: Data Forms 2728* XEP-0012:: Last Activity 2729* XEP-0020:: Feature Negotiation 2730* XEP-0022:: Message Events 2731* XEP-0030:: Service Discovery 2732* XEP-0045:: Multi-User Chat 2733* XEP-0049:: Private XML Storage 2734* XEP-0050:: Ad-Hoc Commands 2735* XEP-0054:: vcard-temp 2736* XEP-0055:: Jabber Search 2737* XEP-0065:: SOCKS5 Bytestreams 2738* XEP-0066:: Out of Band Data 2739* XEP-0068:: Field Standardization for Data Forms 2740* XEP-0077:: In-Band Registration 2741* XEP-0078:: Non-SASL Authentication 2742* XEP-0082:: Jabber Date and Time Profiles 2743* XEP-0085:: Chat State Notifications 2744* XEP-0086:: Error Condition Mappings 2745* XEP-0090:: Entity Time 2746* XEP-0091:: Delayed Delivery 2747* XEP-0092:: Software Version 2748* XEP-0095:: Stream Initiation 2749* XEP-0096:: File Transfer 2750* XEP-0146:: Remote Controlling Clients 2751* XEP-0153:: vCard-Based Avatars 2752* XEP-0199:: XMPP Ping 2753* XEP-0245:: The /me Command 2754@end menu 2755 2756@node RFC 3920, RFC 3921, , Protocol support 2757@section RFC 3920 (XMPP-CORE) 2758 2759Most of RFC 3920 is supported, with the following exceptions. 2760 2761SASL is supported only when an external SASL library from FLIM or Gnus 2762is present. As SASL is an essential part to XMPP, jabber.el will send 2763pre-XMPP stream headers if it is not available. 2764 2765None of the stringprep profiles are implemented. jabber.el changes 2766JIDs to lowercase internally; that's all. 2767 2768jabber.el doesn't interpret namespace prefixes. 2769 2770The @code{xml:lang} attribute is neither interpreted nor generated. 2771 2772SRV records are used if a modern version of @code{dns.el} is installed. 2773 2774@node RFC 3921, XEP-0004, RFC 3920, Protocol support 2775@section RFC 3921 (XMPP-IM) 2776 2777Most of RFC 3921 is supported, with the following exceptions. 2778 2779Messages of type ``headline'' are not treated in any special way. 2780 2781The @code{<thread/>} element is not used or generated. 2782 2783Sending ``directed presence'' is supported; however, presence stanzas 2784received from contacts not in roster are ignored. 2785 2786Privacy lists are not supported at all. 2787 2788jabber.el doesn't support XMPP-E2E or ``im:'' CPIM URIs. 2789 2790@node XEP-0004, XEP-0012, RFC 3921, Protocol support 2791@section XEP-0004 (Data Forms) 2792 2793XEP-0004 support is good enough for many purposes. Limitations are 2794the following. 2795 2796Forms in incoming messages are not interpreted. See each specific 2797protocol for whether forms are accepted in that context. 2798 2799``Cancel'' messages are probably not consistently generated when they 2800should be. This is partly a paradigm clash, as jabber.el doesn't use 2801modal dialog boxes but buffers which can easily be buried. 2802 2803@code{<required/>} elements are not enforced. 2804 2805The field types ``jid-single'', ``jid-multi'' and ``list-multi'' are 2806not implemented, due to programmer laziness. Let us know if you need 2807them. 2808 2809@node XEP-0012, XEP-0020, XEP-0004, Protocol support 2810@section XEP-0012 (Last Activity) 2811 2812jabber.el can generate all three query types described in the protocol. 2813However, it does not answer to such requests. 2814 2815@node XEP-0020, XEP-0022, XEP-0012, Protocol support 2816@section XEP-0020 (Feature Negotiation) 2817 2818There are no known limitations or bugs in XEP-0020 support. 2819 2820@node XEP-0022, XEP-0030, XEP-0020, Protocol support 2821@section XEP-0022 (Message Events) 2822 2823jabber.el understands all four specified kinds of message events 2824(offline, delivered, displayed, and composing) and by default requests 2825all of them. It also reports those three events that make sense for 2826clients. 2827 2828@node XEP-0030, XEP-0045, XEP-0022, Protocol support 2829@section XEP-0030 (Service Discovery) 2830 2831Service discovery is supported, both as client and server. When used in 2832the code, service discovery results are cached indefinitely. 2833 2834@node XEP-0045, XEP-0049, XEP-0030, Protocol support 2835@section XEP-0045 (Multi-User Chat) 2836 2837jabber.el supports parts of XEP-0045. Entering, leaving and chatting 2838work. So do invitations and private messages. Room configuration is 2839supported. Changing roles of participants (basic moderation) is 2840implemented, as is changing affiliations, but requesting affiliation 2841lists is not yet supported. 2842 2843@node XEP-0049, XEP-0050, XEP-0045, Protocol support 2844@section XEP-0049 (Private XML Storage) 2845 2846jabber.el contains an implementation of XEP-0049; It is used 2847for bookmarks and roster's groups roll state saving. 2848 2849@node XEP-0050, XEP-0054, XEP-0049, Protocol support 2850@section XEP-0050 (Ad-Hoc Commands) 2851 2852jabber.el is probably the first implementation of XEP-0050 (see 2853@uref{http://article.gmane.org/gmane.network.jabber.devel/21413, post 2854on jdev from 2004-03-10}). Both the client and server parts are 2855supported. 2856 2857@node XEP-0054, XEP-0055, XEP-0050, Protocol support 2858@section XEP-0054 (vcard-temp) 2859 2860Both displaying other users' vCards and editing your own vCard are 2861supported. The implementation tries to follow the schema in the XEP 2862accurately. 2863 2864@node XEP-0055, XEP-0065, XEP-0054, Protocol support 2865@section XEP-0055 (Jabber Search) 2866 2867XEP-0055 is supported, both with traditional fields and with Data Forms 2868(@pxref{XEP-0004}). As the traditional fields specified by the XEP is a 2869subset of those allowed in XEP-0077, handling of those two form types 2870are merged. @xref{XEP-0077}. 2871 2872@node XEP-0065, XEP-0066, XEP-0055, Protocol support 2873@section XEP-0065 (SOCKS5 Bytestreams) 2874 2875XEP-0065 is supported. Currently jabber.el cannot act as a server, not 2876even on on Emacsen that support server sockets (GNU Emacs 22 and up). 2877Therefore it relies on proxies. Proxies have to be entered and queried 2878manually. 2879 2880Psi's ``fast mode'' 2881(@uref{http://delta.affinix.com/specs/stream.html}), which gives 2882greater flexibility with regards to NAT, is not implemented. 2883 2884@node XEP-0066, XEP-0068, XEP-0065, Protocol support 2885@section XEP-0066 (Out of Band Data) 2886 2887jabber.el will display URLs sent in message stanzas qualified by 2888the @code{jabber:x:oob} namespace, as described in this XEP. Sending 2889such URLs or doing anything with iq stanzas (using the 2890@code{jabber:iq:oob} namespace) is not supported. 2891 2892@node XEP-0068, XEP-0077, XEP-0066, Protocol support 2893@section XEP-0068 (Field Standardization for Data Forms) 2894 2895XEP-0068 is only used in the context of creating a new Jabber account, 2896to prefill the username field of the registration form. 2897 2898@node XEP-0077, XEP-0078, XEP-0068, Protocol support 2899@section XEP-0077 (In-Band Registration) 2900 2901In-band registration is supported for all purposes. That means 2902registering a new Jabber account, changing Jabber password, removing a 2903Jabber account, registering with a service, and cancelling 2904registration to a service. Data forms are supported as well. URL 2905redirections are not. 2906 2907jabber.el will not prevent or alert a user trying to change a password 2908over an unencrypted connection. 2909 2910@node XEP-0078, XEP-0082, XEP-0077, Protocol support 2911@section XEP-0078 (Non-SASL Authentication) 2912 2913Non-SASL authentication is supported, both plaintext and digest. 2914Digest is preferred, and a warning is displayed to the user if only 2915plaintext is available. 2916 2917@node XEP-0082, XEP-0085, XEP-0078, Protocol support 2918@section XEP-0082 (Jabber Date and Time Profiles) 2919 2920The DateTime profile of XEP-0082 is supported. Currently this is only 2921used for file transfer. 2922 2923@node XEP-0085, XEP-0086, XEP-0082, Protocol support 2924@section XEP-0085 (Chat State Notifications) 2925 2926XEP-0085 is partially supported. Currently only active/composing 2927notifications are @emph{sent} though all five notifications are handled on 2928receipt. 2929 2930@node XEP-0086, XEP-0090, XEP-0085, Protocol support 2931@section XEP-0086 (Error Condition Mappings) 2932 2933Legacy errors are interpreted, but never generated. XMPP style error 2934messages take precedence when errors are reported to the user. 2935 2936@node XEP-0090, XEP-0091, XEP-0086, Protocol support 2937@section XEP-0090 (Entity Time) 2938 2939jabber.el can query other entities for their time, and return the 2940current time to those who ask. 2941 2942@node XEP-0091, XEP-0092, XEP-0090, Protocol support 2943@section XEP-0091 (Delayed Delivery) 2944 2945The time specified on delayed incoming messages is interpreted, and 2946displayed in chat buffers instead of the current time. 2947 2948@node XEP-0092, XEP-0095, XEP-0091, Protocol support 2949@section XEP-0092 (Software Version) 2950 2951The user can request the version of any entity. jabber.el answers 2952version requests to anyone, giving ``jabber.el'' as name, and the 2953Emacs version as OS. 2954 2955@node XEP-0095, XEP-0096, XEP-0092, Protocol support 2956@section XEP-0095 (Stream Initiation) 2957 2958XEP-0095 is supported, both incoming and outgoing, except that jabber.el 2959doesn't check service discovery results before sending a stream 2960initiation request. 2961 2962@node XEP-0096, XEP-0146, XEP-0095, Protocol support 2963@section XEP-0096 (File Transfer) 2964 2965Both sending and receiving files is supported. If a suitable program is 2966found, MD5 hashes of outgoing files are calculated and sent. However, 2967hashes of received files are not checked. Ranged transfers are not 2968supported. In-band bytestreams are not yet supported, even though 2969XEP-0096 requires them. 2970 2971@node XEP-0146, XEP-0153, XEP-0096, Protocol support 2972@section XEP-0146 (Remote Controlling Clients) 2973 2974The ``set-status'' command in XEP-0146 is supported. 2975 2976@node XEP-0153, XEP-0199, XEP-0146, Protocol support 2977@section XEP-0153 (vCard-Based Avatars) 2978 2979vCard-based avatars are supported, both publishing and displaying. The 2980pixel size limits on avatars are not enforced. 2981 2982@node XEP-0199, XEP-0245, XEP-0153, Protocol support 2983@section XEP-0199 (XMPP Ping) 2984 2985XEP-0199 is fully supported. 2986 2987@node XEP-0245, ,XEP-0199, Protocol support 2988@section XEP-0245 (/me Command) 2989 2990XEP-0245 is partially supported (except XHTML-IM). 2991 2992@node Concept index, Function index, Protocol support, Top 2993@unnumbered Concept index 2994 2995@printindex cp 2996 2997@node Function index, Variable index, Concept index, Top 2998@unnumbered Function index 2999 3000@printindex fn 3001 3002@node Variable index, , Function index, Top 3003@unnumbered Variable index 3004 3005@printindex vr 3006 3007@bye 3008 3009@ignore 3010 arch-tag: 995bf3da-0e87-4b15-895a-1e85fac139a2 3011@end ignore 3012