Project: jabber.el
Code Location: git://emacs-jabber.git.sourceforge.net/gitroot/emacs-jabber/emacs-jabbermaster
Browse
/
Download File
jabber.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
\input texinfo          @c -*-texinfo-*-
@c %**start of header
@setfilename jabber.info
@settitle jabber.el manual 0.8.0
@c %**end of header

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

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

Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 Magnus Henoch, Tom Berger.

@quotation
Permission is granted to make and distribute verbatim copies or
modified versions of this manual, provided the copyright notice and
this permission notice are preserved on all copies.
@end quotation
@end copying

@titlepage
@title jabber.el
@subtitle instant messaging for Jabber
@author by Magnus Henoch and Tom Berger

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top jabber.el manual

@insertcopying

@end ifnottex

@menu
* Introduction::
* Basic operation::
* Groupchat::
* Composing messages::
* File transfer::
* Services::
* Personal information::
* Avatars::
* Time queries::
* Useful features::
* Message history::
* Typing notifications::
* Roster import and export::
* XMPP URIs::
* Customization::
* Hacking and extending::
* Protocol support::
* Concept index::
* Function index::
* Variable index::
@end menu


@node Introduction, Basic operation, Top, Top
@chapter Introduction

jabber.el is a Jabber client running under Emacs.  For more
information on the open-protocol instant messaging network Jabber,
please visit @uref{http://www.jabber.org}.

As a Jabber client, jabber.el is mostly just a face in the crowd,
except that it uses buffers where GUI clients have windows.  There is
a roster buffer, and to chat with someone you open a chat buffer, and
there are buffers for
interaction with servers and services.  Then again, jabber.el delivers
excellent console performance and customizable hooks (if you have
speech synthesizer software, hook it up to your presence alerts).

jabber.el does not yet support PGP encryption, sending and receiving
roster items, and various other things.

@menu
* Contacts::
@end menu

@node Contacts,  , , Introduction
@section Contacts

@itemize @bullet
@item
There is a web page at
@uref{http://emacs-jabber.sf.net/}.

@item
There is a Sourceforge
project page at @uref{http://sourceforge.net/projects/emacs-jabber},
with bug and patch trackers.

@item
There is a mailing list:
@email{emacs-jabber-general@@lists.sourceforge.net},
@uref{https://lists.sourceforge.net/lists/listinfo/emacs-jabber-general},
@uref{http://dir.gmane.org/gmane.emacs.jabber.general}

@item
There is a chat room, @code{jabber.el@@conference.jabber.se}.  If you
have successfully connected, you can join it by typing @kbd{M-x
jabber-muc-join} and entering the address.

@end itemize

@node Basic operation, Groupchat, Introduction, Top
@chapter Basic operation

This chapter is intended as an introduction to basic usage of
jabber.el.  If you have used Jabber before and are familiar with the
terminology, you might find it a bit too basic---in that case, just
skim it, making sure to pick up the commands mentioned.

I'll assume that you have already successfully installed jabber.el; if
not, consult the @file{README} file.  Also, make sure you have
@code{(require 'jabber)} or @code{(load "jabber-autoloads")} in your
@file{.emacs}.

There are a handful of global keybindings for common commands.  They
start with @kbd{C-x C-j}, and you can get a list of them by typing
@kbd{C-x C-j C-h}.

@menu
* Do you have a Jabber account?::
* Registering an account::
* Connecting::
* Chatting::
* Presence::
* Presence subscription::
* Roster buffer::
@end menu

@node Do you have a Jabber account?, Registering an account, , Basic operation
@section Do you have a Jabber account?

Jabber has become rather popular as an instant messaging technology.
Several sites use it, but often not under the names ``Jabber'' or
``XMPP''.  Examples:

@itemize @bullet
@item
Google Talk uses Jabber.  If you have a Gmail address, you can use it as
a Jabber ID.  @xref{Account settings}, for Google-specific configuration.

@item
LJ Talk (of Livejournal) uses Jabber.  Your Jabber ID is
@samp{@var{ljusername}@@livejournal.com}.
@end itemize

@node Registering an account, Connecting, Do you have a Jabber account?, Basic operation
@section Registering an account

@cindex Registering an account

If you do not yet have a Jabber account, you can register one.  The
registration processes for various servers differ, but many servers
support so-called ``in-band registration'', which is described in this
section.

To register an account, type @kbd{C-u M-x jabber-connect} and enter your
desired JID in the form @samp{@var{username}@@@var{server}}.  You will
be presented with a registration form to fill out and send.  There the
username you chose will be prefilled.  After registration, you can
connect to the server as usual.

@node Connecting, Chatting, Registering an account, Basic operation
@section Connecting

@findex jabber-connect-all
@findex jabber-connect
@findex jabber-disconnect-one
@findex jabber-disconnect

@cindex Connecting

Now, type @kbd{C-x C-j C-c} and enter your JID and password.  If you
successfully connect, jabber.el will download your roster and display it
in a buffer called @code{*-jabber-roster-*}.

By default, you will appear as ``online'' to your contacts.  To change
this to e.g. ``away'', type @kbd{M-x jabber-send-presence} or @kbd{C-x
C-j C-p}.  @xref{Presence}, for more information.

To disconnect, type @kbd{M-x jabber-disconnect} or @kbd{C-x C-j C-d}.
Use @kbd{M-x jabber-disconnect-one} to disconnect just one account (or just type @kbd{C-u C-x C-j C-d}).

If you don't want to type your JID every time you connect, you can save
it in the variable @code{jabber-account-list}.  @xref{Account
settings}.  If you configure more than one account, all of them will be
connected when you type @kbd{C-x C-j C-c}, as that key is bound to
@code{jabber-connect-all}.  To connect only one account, possibly one
that's not in your list, type @kbd{M-x jabber-connect} or @kbd{C-u C-x
C-j C-c}.

@node Chatting, Presence, Connecting, Basic operation
@section Chatting

@cindex Chatting
@findex jabber-chat-with

There are several ways to open a chat buffer.  The shortest way is to
put point over the person you want to chat with in the roster display
and hit RET.

You can also use the function @code{jabber-chat-with}.  This function is
bound to @kbd{C-x C-j C-j} in the global keymap.  You will be asked to
enter a JID in the minibuffer.  You can also enter the roster name of
one of your contacts.  All JIDs and names in your roster can be
tab-completed.

You can also use menus to access commands.  In the roster display, you
can access several menus through keystrokes or mouse clicks.  You can
bring one big menu up by pressing the second mouse button, or you can
bring up the ``chat menu'' by typing @kbd{C-c C-c}.  If you do the
latter while point is on a roster entry, that entry will be the
default value when you are asked for whom to chat with.

Now, try opening a chat with someone.  A buffer named
@code{*-jabber-chat-:-@var{person}-*} will be created and selected.
Type your message at the end of the buffer, and hit @kbd{RET} to send
it.  To include a newline in your message, use @kbd{C-j}.

When you receive a message from someone, you will see a red indicator in
the mode line.  You can click this indicator with the mouse, or type
@kbd{C-x C-j C-l} to switch to the relevant buffer.  @xref{Tracking
activity}.

@node Presence, Presence subscription, Chatting, Basic operation
@section Presence

@cindex Presence
@cindex Sending presence
@findex jabber-send-presence
@findex jabber-send-default-presence
@vindex jabber-default-show
@vindex jabber-default-status
@vindex jabber-default-priority

@dfn{Presence} is the Jabber term for letting other people know that you
are online, and additionally how ``available'' you are.  There are
three elements to presence: availability state (called ``show''),
status message, and priority.

Your show state may either be empty (meaning simply ``online''), or
one of @code{away}, @code{xa}, @code{dnd} and @code{chat}, meaning
``away'', ``extended away'' (i.e. away for an extended period), ``do
not disturb'', and ``free for chat'', respectively.  This information
is available to everyone subscribing to your presence, but technically
it does not restrict anyone's actions.  You can chat with people even
if you claim to be away.

The status message is a short text complementing your show status,
such as ``at home'', ``working'', ``phone'', ``playing games'' or
whatever you want.  It is sent to everyone subscribing to your
presence, but not all clients prominently display it to the user.

The priority is only interesting if you are running more than one Jabber
client at a time accessing the same account.  @xref{Resources and
priority}.

To set your presence, use the function @code{jabber-send-presence}
(bound to @kbd{C-x C-j C-p}).
It can be called both interactively and in Lisp code.  For the latter
case, use something like @code{(jabber-send-presence "away" "idle for
10 minutes" 10)}.  There are a few shortcuts:
@table @kbd
@item C-x C-j C-a
Send ``away'' presence (with prefix argument, specify status text)
@item C-x C-j C-x
Send ``extended away'' presence (with prefix argument, specify status
text)
@item C-x C-j C-o
Send default presence (see below)
@end table

By default, jabber.el sets your presence when you connect.  If you
want it not to do that, remove @code{jabber-send-current-presence}
from @code{jabber-post-connect-hooks}.  If you want to change the
presence that is sent, change the variables
@code{jabber-default-show}, @code{jabber-default-status} and
@code{jabber-default-priority}.

With jabber.el, you can set your presence remotely.  @xref{Ad-Hoc Commands}.

@menu
* Resources and priority::
* Directed presence::
@end menu

@node Resources and priority, Directed presence, , Presence
@subsection Resources and priority

@cindex Resource
@cindex Priority

Every connection to an account has a specific name, a @dfn{resource}.
The account itself has a JID of the form
@samp{@var{username}@@@var{server}} (a @dfn{bare JID}), but the
connections have JIDs of the form
@samp{@var{username}@@@var{server}/@var{resource}} (a @dfn{full JID}).
You can choose the resource name yourself by entering a JID of the
latter form at the connection prompt (@pxref{Connecting}), or by
configuring it in @code{jabber-account-list} (@pxref{Account settings})

Each session has a @dfn{priority}.  The priority determines what happens
when a message is sent to the bare JID (i.e. without specifying what
connection should receive message).  Such messages are delivered to the
connection with the highest non-negative priority value.  If there are
no connections, or if all connections have negative priority, the
message is either stored on the server for later delivery or bounced to
the sender, depending on the server configuration.

If there are several connections with the same priority, the behaviour
depends on the server.  Some server implementations deliver the message
to all such connections, while others choose one connection depending on
certain rules.

Note that these rules do not apply when a message is sent to a full
JID.  Such messages are sent to the specified resource, if it is still
connected, and otherwise treated as messages to the bare JID.  In the
chat buffers of jabber.el, messages are sent to whatever JID the last
message came from (usually a full JID), or to the bare JID if no message
has been received yet.  Other clients may have different behaviour.

@node Directed presence,  , Resources and priority, Presence
@subsection Directed presence

@cindex directed presence
@cindex send directed presence
@findex jabber-send-directed-presence
You can send ``directed presence'' with @kbd{M-x
jabber-send-directed-presence}.  This is mostly useful to manage
transports---sending directed presence is a way to turn them on and
off.  You can also send directed presence to an annoying contact to
appear as away or offline to that contact.  Note, however, that in both
of these cases, all subscribed entities will get your next global
presence update.

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

@cindex Presence subscription
@cindex Subscribing to someone's presence
@findex jabber-send-subscription-request

Having permission to view the presence status of a person is called
@dfn{subscribing to his presence}.  Presence subscription between two
persons can be asymmetric.  Subscription state is shown in the roster
display by arrows (@pxref{Customizing the roster buffer}).  A
left-pointing arrow means that the contact can see your presence
(``from'').  A right-pointing arrow means that you can see the contact's
presence (``to'').  The most common case is mutual subscription, a
double-ended arrow (``both'').

When jabber.el receives a presence subscription request, it will present
it to you in a chat buffer, and offer you to choose subscription mode
and send a subscription request back to that person.  The ``Mutual''
button accepts the request and sends a reciprocal request.@footnote{If this
request is superfluous, the server will drop it without bothering the
contact.}  The ``One-way'' button accepts the request, but doesn't ask
for a subscription in return.  The ``Decline'' button declines the
request.

To request subscription to someone, type @kbd{M-x
jabber-send-subscription-request}.  You will be prompted for the JID
to send it to.  This command can also be accessed through the Roster
menu, by typing @kbd{C-c C-r} in the roster buffer.  After that, you
will probably want to give the contact a more readable name.  The
command for that is @code{jabber-roster-change}, which is also
available in the Roster menu or by typing @kbd{e} on a person in the
roster buffer.

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

@cindex Roster buffer, basics
@cindex Menus
@cindex Key bindings

The roster buffer is called @code{*-jabber-roster-*}.  It simply
contains a list of the contacts on your roster.  If you have several
accounts connected, contacts will be grouped by account.

In the roster buffer, any command which requires a JID will default to
the JID under point when called.  These commands can be called through
either keyboard menus or mouse menus.  To open a menu with the mouse,
simply press the second mouse button over the JID in
question.@footnote{For some reason, mouse menus don't work in XEmacs.
Patches are welcome.}  This will bring up a menu with all available
actions.  The keyboard menus are split into categories: Chat, Roster,
Information, MUC (Multi-User Chat, or groupchat) and Services, opened
by @kbd{C-c C-c}, @kbd{C-c C-r}, @kbd{C-c C-i}, @kbd{C-c C-m} and
@kbd{C-c C-s}, respectively.

@vindex jabber-roster-show-bindings
A list of keybindings is displayed at the top of the roster buffer.
You can turn it off by setting @code{jabber-roster-show-bindings} to
nil.

@findex jabber-display-roster
You can call @code{jabber-display-roster} (bound to @kbd{g}) to
redisplay your roster according to changed preferences
(@pxref{Customizing the roster buffer}).  This will not refetch your
roster from the server.  Refetching the roster is usually not needed,
since updates are pushed to clients automatically.

You can choose not to have the roster updated automatically on
presence changes (@pxref{Presence alerts}).  In that case, you need to
call @code{jabber-display-roster} manually.

@vindex jabber-show-offline-contacts
@cindex Hiding offline contacts
@cindex Offline contacts, hiding
Please note, that by default offline contacts showed in roster as any
others. To hide them, you can use @kbd{o} in roster buffer. To
permanently hide them, customize @code{jabber-show-offline-contacts}
variable.

@node Groupchat, Composing messages, Basic operation, Top
@chapter Groupchat

@cindex Groupchat
@cindex MUC
@cindex Chatrooms

The groupchat menu can be accessed by typing @kbd{C-c C-m} in the
roster buffer.  You can also type the commands directly, as will be
shown here.

@findex jabber-muc-join
@cindex Joining a groupchat
@cindex Changing nickname
@cindex Nickname, changing
To join a groupchat, type @kbd{M-x jabber-muc-join}.  You will
be prompted for the groupchat to join, and your nickname in the
groupchat.  This nickname doesn't need to have any correlation to your
JID; in fact, groupchats are usually (but not always) configured such
that only moderators can see your JID.  You can change your nickname
with @kbd{M-x jabber-muc-nick}.  @xref{Configuration}, for setting default
nicknames.

@cindex Query groupchat
@vindex jabber-muc-disable-disco-check
When trying to join a room, jabber.el first sends a service discovery
info request to the room, to find out whether it exists and what
features are enabled (in particular whether the room is
password-protected).  However, this can cause problems with some buggy
MUC services (or services that respond in a way that jabber.el doesn't
expect).  A workaround for that is to set
@code{jabber-muc-disable-disco-check} to @code{t}; however, the bug should be
unearthed and fixed.

Groupchat messages will be displayed in a buffer called
@code{*-jabber-groupchat-:-@var{groupchat}-*}.  By default, the buffer
name is based on the JID of the chat room.  If you want a shorter name,
you can add the chat room to your roster and give it a name, using the
command @kbd{M-x jabber-roster-change}.  The groupchat buffer works much
like the chat buffer.  It has its own class of alerts
(@pxref{Customizing alerts}), and uses activity tracking
(@pxref{Tracking activity}).

@vindex jabber-muc-completion-delimiter
@vindex jabber-muc-looks-personaling-symbols
@cindex Groupchat completion
@cindex Nick completion in groupchat
Also, to save from repeating unnesesary typing you can press @kbd{Tab}
key to complete nick of a groupchat member that you are talking with.
You can customize your form of personal talking in MUC
(@code{jabber-muc-completion-delimiter}) and form of personal talking to
you (@code{jabber-muc-looks-personaling-symbols})---see ``jabber-chat''
customization group. Defaults are sane, so it is unlikely that you would
want to change this, but... it is Emacs!

@cindex Topic, MUC
@findex jabber-muc-set-topic
To change the topic of a groupchat, type @kbd{M-x jabber-muc-set-topic}.
The current topic is shown in the header line.

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

@findex jabber-muc-get-config
If you are the owner of a groupchat, you can change its configuration
by typing @kbd{M-x jabber-muc-get-config}.  A configuration form
will be rendered in new buffer.

@findex jabber-muc-names
@vindex jabber-muc-print-names-format
To see which people are in a groupchat, type @kbd{M-x
jabber-muc-names}.  This gives a list of nicknames,
``affiliations'', and possibly JIDs according @code{jabber-muc-print-names-format}, sorted by ``roles''.
@xref{MUC Administration}, for the meaning of roles and affiliations.


@menu
* Configuration::
* Invitations::
* Private messages::
* MUC Administration::
@end menu

@node Configuration, Invitations, , Groupchat
@section Configuration

@vindex jabber-muc-default-nicknames
@vindex jabber-muc-autojoin
@findex jabber-muc-autojoin
@cindex Default MUC nickname
@cindex Autojoin chat rooms
@cindex Bookmarks, MUC
@findex jabber-edit-bookmarks

You can configure jabber.el to use a certain nickname for a certain
room, or to automatically join a certain room when you connect.  You can
do this either by storing bookmarks on the server or by setting Emacs
variables.

Type @kbd{M-x jabber-edit-bookmarks} to add bookmarks.  You can specify
the JID of the conference, the name of the conference (not used by
jabber.el), whether to automatically join the room, your desired
nickname (or leave empty), and the room password (or leave empty).

The default nickname for groupchats is the username part of your JID.
If you don't use bookmarks, you can set different nicknames for
different groups by customizing @code{jabber-muc-default-nicknames}.
There you specify the JID of the group, and your preferred nickname.

Automatically joining certain rooms when connecting can be accomplished
by setting @code{jabber-muc-autojoin} to a list containing the JIDs of
the rooms you want to enter.  To disable this feature, remove
@code{jabber-muc-autojoin} from @code{jabber-post-connect-hooks}.

Please note, that @code{jabber-muc-default-nicknames} and
@code{jabber-muc-autojoin} are machine-local, but apply to @emph{all}
accounts---if you connect several accounts, both will try to connect to
the same chat rooms, or use the same nickname.  This will lead to
confusion.

@node Invitations, Private messages, Configuration, Groupchat
@section Invitations

@cindex Invitations
@findex jabber-muc-invite

You can invite someone to a groupchat with @kbd{M-x jabber-muc-invite}
(also available in the MUC menu).  Pay attention to the order of the
arguments---as both users and rooms are just JIDs, it is technically
possible to invite a room to a user, but that's probably not what you
want.

When you receive an invitation, it appears in the chat buffer along
with two buttons, ``Accept'' and ``Decline''.  Pressing ``Accept''
enters the room, as you would expect.  Pressing ``Decline'' gives you
an opportunity to state the reason why you're not joining.

@node Private messages, MUC Administration, Invitations, Groupchat
@section Private messages

@cindex Private MUC messages
@findex jabber-muc-private

You can open a private chat with a participant in a chat room with
@kbd{M-x jabber-muc-private} (or by using the MUC menu).  This creates
a buffer with the name
@code{*-jabber-muc-priv-@var{group}-@var{nickname}-*} (customizable by
@code{jabber-muc-private-buffer-format}), which behaves mostly like an
ordinary chat buffer.  This buffer will also be created if someone
sends a private message to you.

Private MUC messages use the same alerts as normal chat messages.
@xref{Message alerts}.

@node MUC Administration,  , Private messages, Groupchat
@section Administration

Administration of a MUC room mostly consists of managing roles and
affiliations.  Roles are temporary, and apply until the user leaves the
room.  Affiliations are permanent, and based on JIDs.

@subsection Roles

@findex jabber-muc-set-role
@cindex Kicking, MUC
@cindex Voice, MUC
@cindex Moderator, MUC
@cindex Roles, MUC
If you have moderator privileges, you can change the role of a
participant with @kbd{M-x jabber-muc-set-role}.  Kicking means setting
the role to ``none''.  Granting and revoking voice are ``participant''
and ``visitor'', respectively.  ``moderator'' gives moderator
privileges, obviously.

The possible roles are:

@table @samp
@item moderator
Has voice, can change other people's roles.

@item participant
Has voice.

@item visitor
Doesn't have voice (can't send messages to everyone, but can send
private messages)

@item none
Not in room.
@end table

@subsection Affiliations

@findex jabber-muc-set-affiliation
@cindex Affiliations, MUC
@cindex Banning, MUC
If you have admin or owner privileges, you can change the affiliation of
a user with @kbd{M-x jabber-muc-set-affiliation}.  Affiliation is
persistent, and based on JIDs.  Depending of your affiliation and the
MUC implementation, you might not be allowed to perform all kinds of
changes, and maybe not in one step.

Affiliations are:

@table @samp
@item owner
Can destroy room, appoint admins, make people members, ban people.

@item admin
Can make people members or ban people.

@item member
Can enter the room, and has voice by default.

@item none
Rights depend on room configuration.  The room might be members-only, or
grant voice only to members.

@item outcast
Banned from the room.
@end table


@node Composing messages, File transfer, Groupchat, Top
@chapter Composing messages

@findex jabber-compose
@cindex composing messages
@cindex message composition

The chat buffer interface can be inconvenient for some purposes.  As you
can't use @kbd{RET} to insert a newline (use @kbd{C-j} for that),
writing a longer message can be painful.  Also, it is not possible to
include a subject in the message, or send the message to multiple
recipients.

These features are implemented by the message composing tool.  Type
@kbd{M-x jabber-compose} to start it.  In the buffer that comes up, you
can specify recipients, enter a subject, and type your message.

@node File transfer, Services, Composing messages, Top
@chapter File transfer

@cindex File transfer
@cindex Sending files

jabber.el has limited support for file transfer.  The most important
limit is that files sent and received are kept in buffers, so Emacs must
be able to allocate enough memory for the entire file, and the file size
must be smaller than the maximum buffer size.@footnote{The maximum
buffer size depends on in the variable @code{most-positive-fixnum}.  On
32-bit systems, this is 128 or 256 megabytes, depending on your
Emacs version.}

jabber.el is able to exchange files with most Jabber clients (and also
some MSN transports), but notably not with the official Google Talk
client.  The Google Talk client uses a different file transfer protocol
which, at the time of this release, has not been published.

@menu
* Receiving files::
* Sending files::
@end menu

@node Receiving files, Sending files, , File transfer
@section Receiving files

Receiving files requires no configuration.  When someone wants to send a
file to you, you are asked (through @code{yes-or-no-p}) whether you want
to accept the file.  If you answer yes, you get to choose where to save
the file.

If the sender's client is correctly configured (this is often not the
case; see below), the file transfer will start.  Currently, the only way
to watch the progress is to inspect the buffer of the file being
transfered; @kbd{C-x C-b} is one way of doing that.  @xref{List Buffers,
, Listing Existing Buffers, emacs, GNU Emacs Manual}.  When the transfer
is done, the message ``@var{file} downloaded'' appears in the echo area,
and the buffer is killed.

@c This truly sucks...
If this doesn't happen, it is most likely the sender's fault.  The
sender needs to have a public IP address, either directly, through port
forwarding (in which case the client needs to be configured with the
real public IP address), or through an XEP-0065 proxy.  If you have
activated XML logging (@pxref{Debug options}), you can see the IP
address that the other client is asking you to connect to there.  Often
you will find that this is an internal IP address (often starts with
@code{192.168}).  See the documentation of the sender's client for
setting this up.

@node Sending files,  , Receiving files, File transfer
@section Sending files

@cindex proxy, file transfer
@cindex file transfer proxy
@cindex XEP-0065 proxy

To send a file to someone, you need an XEP-0065 proxy.@footnote{This
requirement is not inherent in the protocol, only in the current file
transfer implementation of jabber.el, and in Emacs versions earlier than
22.}  If your Jabber server hosts such a proxy, it will be found
automatically, otherwise it needs to be manually configured.

You can check whether your Jabber server has a proxy with @kbd{M-x
jabber-get-disco-items}; see @ref{Service discovery}.

@vindex jabber-socks5-proxies
@findex jabber-socks5-query-all-proxies
To configure a proxy manually, customize the variable
@code{jabber-socks5-proxies}.  Putting @code{proxy.jabber.se} there
should work.  Type @kbd{M-x jabber-socks5-query-all-proxies} to see if
the proxies answer.

@findex jabber-ft-send
Now, you can type @kbd{M-x jabber-ft-send} to send a file to someone.
You need to enter the correct full JID, including resource, to get this
right.  If the contact is logged in with only one client, and you can
see it online, just typing the JID or roster name is enough.  If you run
the command from a chat buffer, the JID of the contact is given as
the default value.

If the contact has several clients online, you probably want to send the
file to a particular one.  If you run this command from within a chat
buffer, the default target will be the one that last sent a message to
you.  If you just type a bare JID or a roster name, the client with the
highest priority will get the file.

If the contact accepts the file, and the contact's client succeeds in
connecting to the proxy, jabber.el will send the file through the
proxy.  During this time, your Emacs will be blocked, so you might want
to avoid sending large files over slow connections.

@node Services, Personal information, File transfer, Top
@chapter Services

@cindex Browse buffers

Not every Jabber entity is a physical person.  There are many
automatic entities, called servers, services, components, agents,
transports and other names.  The use of these is described here.

The functions described in this chapter use @dfn{browse buffers}.
Browse buffers are named @code{*-jabber-browse-:-@var{service}-*},
sometimes with a numerical suffix.  The different menus have the same
keybindings as in the roster buffer, and if you call a function
operating on a JID while point is over a JID, that JID will be the
default value, so you don't have to type it or copy it yourself.

You can change the buffer name template by customizing
the variable @code{jabber-browse-buffer-format}.

@menu
* Commands::
* Your home server::
* Transports::
* User directories::
* MUC services::
@end menu

@node Commands, Your home server, , Services
@section Commands

A small number of commands is used for almost all interaction with
Jabber services.  Essentially, they are all the same: you request a form
from the server, fill it in, and send it back.

Most of these commands are available under the Service menu, which is
opened by typing @kbd{C-c C-s}.  Service discovery is under the Info
menu instead, which is available under @kbd{C-c C-i}.

@menu
* Registration::
* Search::
* Ad-Hoc Commands::
* Service discovery::
* Browsing::
@end menu

@node Registration, Search, , Commands
@subsection Registration

@cindex Registration
@findex jabber-get-register

You can get a registration form for a service by typing @kbd{M-x
jabber-get-register} and entering the JID of the service.  On success,
you get a single-stage form to fill in.

There are two buttons at the bottom of the form, ``Submit'' and ``Cancel
registration''.  ``Submit'' does what you would expect it to, but
``Cancel registration'' cancels any existing registration with the
service.  Whichever of them you choose, you get a message in the echo
area informing whether the operation succeeded.

@node Search, Ad-Hoc Commands, Registration, Commands
@subsection Search

@cindex Search
@findex jabber-get-search

You can get a search form for a service by typing @kbd{M-x
jabber-get-search}.  This gives you a single-stage form to fill in.
After you press the ``Submit'' button at the bottom, the search results
will be displayed in the same buffer.

@node Ad-Hoc Commands, Service discovery, Search, Commands
@subsection Ad-Hoc Commands

@cindex Ad-Hoc Commands
@findex jabber-ahc-get-list
@findex jabber-ahc-execute-command

jabber.el supports a subset of XEP-0050, the standard for Ad-Hoc
Commands.  As the name implies, this can be used for just about
anything.  In particular, it is used not only by services, but also by
clients (e.g. Psi, and jabber.el itself).

To find which commands are available, run ``Request command list''
(@code{jabber-ahc-get-list}).@footnote{This is the same thing as a
disco items request to the node
@code{http://jabber.org/protocol/commands}.}

To run a command from the list, put point over it and run ``Execute
command'' (@code{jabber-ahc-execute-command}), accepting the defaults
for JID and node.  (If you already know those, you could of course
enter them yourself.)

What happens next depends on the command and the service.  In some
cases, the service just responds that the command has been run.  You may
also get a form to fill out.  This form may have multiple stages, in
which case there are ``Next'' and ``Previous'' buttons for navigating
between stages.  You may also see ``Complete'', which runs the command
skipping any remaining stages of the form, and ``Cancel'', which cancels
the command.

Currently, jabber.el uses ad-hoc commands for setting presence remotely.
If you realize that you forgot to set your client to ``away'' with a low
priority, you can do it remotely from any JID from
@code{jabber-account-list}. So, you can add disabled JIDs in
@code{jabber-account-list} to allow them control your
presence.@footnote{Most Jabber servers also support kicking a client off
the net by logging in with another client with exactly the same
resource.}

@node Service discovery, Browsing, Ad-Hoc Commands, Commands
@subsection Service discovery

@cindex Service discovery
@findex jabber-get-disco-items
@findex jabber-get-disco-info

Service discovery is used to find information about servers, services
and clients.  There are two kinds of requests: find @dfn{info} about a
Jabber entity---i.e. its identity and supported features---and find
@dfn{items} related to an entity, where the definition of ``related'' is
left to the entity itself.

The commands to execute such requests are @code{jabber-get-disco-info}
and @code{jabber-get-disco-items}, respectively.  These commands can be
accessed from the Info menu, which is opened by typing @kbd{C-c C-i}.
The commands accept a JID and optionally a ``node''.

The result of such a command is displayed in a browse buffer.  For an
info request, the result just lists the identities and features of the
entity.  For an item request, the related items are listed.  The items
may be JIDs, or JIDs with a node.  If you put point on one of the items,
its JID and node will be the default value for any Jabber command.

If you think that the interface to service discovery is awkward and
should be replaced with something better, you are completely right.

@node Browsing,  , Service discovery, Commands
@subsection Browsing

@cindex Browsing
@findex jabber-get-browse

Before service discovery, browsing was the way to find information about
Jabber entities.  Nowadays it is all but superseded, but jabber.el still
supports it.  You can use it by typing @kbd{M-x jabber-get-browse}.  It
works much like service discovery.

@node Your home server, Transports, Commands, Services
@section Your home server

@cindex Password change
@cindex Changing password
@cindex Account removal
@cindex Removing an account

You can interact with your Jabber server to change your password or
remove your account.  Both of these can be accomplished by typing
@kbd{M-x jabber-get-register} and typing the JID of your server;
@pxref{Registration}.


@node Transports, User directories, Your home server, Services
@section Transports to other IM networks

@cindex Gateways
@cindex Transports
@cindex MSN transport
@cindex ICQ transport
@cindex AIM transport

Some Jabber services make it possible to communicate with users on other
instant messaging networks (e.g. MSN, ICQ, AIM), in effect turning your
Jabber client into a multi-protocol client.  These are called
@dfn{gateways} or @dfn{transports}.  They work by impersonating you on
the legacy network; therefore you need to provide your username and
password through registration.

@subsection Finding a transport

To use such a transport, you first need to find one, obviously.
Sometimes your home server provides the transports you need, but you are
not limited to those; in principle you can use any transport on the
Jabber network.  Some transports only accept local users, though.

Transports are generally mentioned on the web page of the Jabber server
in question.  You can also find transports from within the client;
@pxref{Service discovery}.

@subsection Registering with a transport

To register with a transport, type @kbd{M-x jabber-get-register} and
enter the JID of the transport.  This will open a registration form
where you get to fill in your login information; @pxref{Registration}.
You can later use this same form to change the information or cancel
your registration.

After you have registered, the transport will request presence
subscription.  It needs that to know when you are online, and
synchronize your presence on the legacy network.

@subsection Contact list

Once you are registered, the transport will transfer the contact list
from the legacy service.  From the Jabber side, it appears as if lots of
people suddenly request presence subscription to you.  This is somewhat
inconvenient, but it is currently the only way that the transport can
influence your Jabber contact list, as it is an entity external to your
server.@footnote{Of course, jabber.el could do more to alleviate this
inconvenience.}

When you have accepted these presence subscriptions, the contacts from
legacy networks appear as if they were Jabber contacts.

@subsection Finding users

Some legacy networks have a global database of users, and some
transports support searching that database.  In that case, you can
search for other users with @kbd{M-x jabber-get-search};
@pxref{Search}.

@node User directories, MUC services, Transports, Services
@section User directories

There are some Jabber user directories, usually abbreviated JUDs.  The
most well-known one is @samp{users.jabber.org}.  You can register with
such a directory to let other people find you (@pxref{Registration}),
and you can search the directory (@pxref{Search}).

@node MUC services,  , User directories, Services
@section MUC services

MUC services (Multi-User Chat, chat rooms) are usually not operated by
these commands, but by commands specific to the MUC protocol;
@pxref{Groupchat}.  However, some MUC services offer nickname
registration through the registration protocol (@pxref{Registration}),
and other commands; @pxref{Ad-Hoc Commands}.

@node Personal information, Avatars, Services, Top
@chapter Personal information

@cindex vCard
@cindex Personal information
@findex jabber-vcard-get
@findex jabber-vcard-edit

The Jabber way of handling personal information (name, addresses, phone
numbers, etc) is ``vCards'' encoded in XML.@footnote{@xref{XEP-0054}.}
You can get information about a user by running @kbd{M-x
jabber-vcard-get}, @kbd{M-x jabber-muc-vcard-get} if you in MUC (also
available in the MUC menu), and you can edit your own information by
running @kbd{M-x jabber-vcard-edit}.

The form for editing your information can be slightly confusing---you
are allowed to enter any number of addresses, phone numbers and e-mail
addresses, each of which has a set of orthogonal properties.  You can
add and remove items with the @samp{[INS]} and @samp{[DEL]} buttons,
respectively.

This is also where you set your avatar (@pxref{Avatars}).  The size of
your avatar file is limited to 8 kilobytes.

@node Avatars, Time queries, Personal information, Top
@chapter Avatars

@cindex avatars
@vindex jabber-vcard-avatars-retrieve
@vindex jabber-vcard-avatars-publish
@vindex jabber-avatar-cache-directory
@vindex jabber-chat-buffer-show-avatar

jabber.el supports viewing and publishing avatars according to XEP-0153,
vCard-Based Avatars.  By default, if you have an avatar in your vCard
(@pxref{Personal information}), it will be published for others to see,
and if other people publish their avatars, they will be displayed in the
roster buffer and in the header line of chat buffers, if your Emacs can
display images.  Otherwise, jabber.el will not fetch avatars at all.

To disable retrieval of other people's avatars, set
@code{jabber-vcard-avatars-retrieve} to nil.  To disable publishing of
your own avatar, set @code{jabber-vcard-avatars-publish} to nil.  To
disable avatars in chat buffer header lines, set
@code{jabber-chat-buffer-show-avatar} to nil.

There are a number of restrictions on avatar images in the
specification.  Most of them are not enforced by jabber.el.
@itemize @bullet
@item
The image should be smaller than 8 kilobytes; this is enforced by
jabber.el.
@item
The image height and width should be between 32 and 96 pixels; the
recommended size is 64 by 64 pixels.
@item
The image should be square.
@item
The image should be in either PNG, GIF, or JPEG format.  (jabber.el will
behave incorrectly if the image is not in a format supported by Emacs.)
@end itemize

Avatars are cached in the directory specified by
@code{jabber-avatar-cache-directory}, by default
@file{~/.emacs.d/jabber-avatar-cache/}.@footnote{The default directory
used to be @file{~/.jabber-avatars}.  If this directory already
exists, it will be used.}  The cache is never cleaned, so you might
want to do that yourself from time to time.

@node Time queries, Useful features, Avatars, Top
@chapter Time queries

@cindex time query
@findex jabber-get-time
With @kbd{M-x jabber-get-time}, you can ask what time an entity (client,
server or component) thinks it is, and what time zone it thinks it is
in.

@cindex last online
@findex jabber-get-last-online
You can query a server about when a certain user was last seen online.
Use @kbd{M-x jabber-get-last-online} for that.

@cindex uptime, query
@cindex idle time, query
@findex jabber-get-idle-time
You can also ask a client about how long a user has been idle with
@kbd{M-x jabber-get-idle-time}.  Not all clients answer such queries,
e.g. jabber.el doesn't.  This command can also tell the uptime of a
server or component.

The first of these commands uses the old Entity Time protocol
(@pxref{XEP-0090}).  It has been superseded by XEP-0202, but jabber.el
doesn't implement the newer protocol yet.  The latter two commands use
the Last Activity protocol (@pxref{XEP-0012}).

@node Useful features, Message history, Time queries, Top
@chapter Useful features

jabber.el includes a number of features meant to improve the user
interface and do other useful things.

@menu
* Autoaway::
* Modeline status::
* Keepalive::
* Reconnecting::
* Tracking activity::
* Watch buddies::
* Spell checking::
* Gmail notifications::
* Saving groups roll state::
@end menu

@node Autoaway, Modeline status, , Useful features
@section Autoaway

@cindex autoaway
@cindex idle
@cindex xprintidle
@vindex jabber-autoaway-method
@vindex jabber-autoaway-methods
@findex jabber-current-idle-time
@findex jabber-xprintidle-program
@findex jabber-termatime-get-idle-time
@vindex jabber-autoaway-timeout
@vindex jabber-autoaway-xa-timeout
@vindex jabber-autoaway-status
@vindex jabber-autoaway-xa-status
@vindex jabber-autoaway-priority
@vindex jabber-autoaway-xa-priority

It is possible to automatically set your status to ``away'' or ``xa''
when you haven't used your computer for a while. This lets your
contacts know that you might not answer immediately. You can customize
timeouts (@code{jabber-autoaway-timeout},
@code{jabber-autoaway-xa-timeout}), statuses
(@code{jabber-autoaway-status}, @code{jabber-autoaway-xa-status}) and
priorityes (@code{jabber-autoaway-priority},
@code{jabber-autoaway-xa-priority}) to set.

To activate this feature, add @code{jabber-autoaway-start} to
@code{jabber-post-connect-hooks}, e.g:
@example
(add-hook 'jabber-post-connect-hooks 'jabber-autoaway-start)
@end example

There are different methods to find how long you have been ``idle''.
The method(s) to use is specified by @code{jabber-autoaway-methods}
(obsoleted @code{jabber-autoaway--method} will also work). The value
of this variable should be a list functions that returns the number of
seconds you have been idle (or nil on error). Minimum of values,
returned by these functions, is used as ``idle'' time, so default
should works well. Three functions are provided (all used by default).

@itemize @bullet
@item
@code{jabber-current-idle-time} is used if your Emacs has the
@code{current-idle-time} function (which was introduced in Emacs 22).
Note that this method only measures the time since you last interacted
with Emacs, and thus disregards activity in other programs.

@item
@code{jabber-xprintidle-get-idle-time} uses xprintidle
@footnote{@uref{http://www.dtek.chalmers.se/~henoch/text/xprintidle.html}}
program, if found. You can also manually set
@code{jabber-xprintidle-program} to the correct file path. This method
uses the same method as
@uref{http://www.jwz.org/xscreensaver,XScreensaver} to find your idle
time.

@item
@code{jabber-termatime-get-idle-time} used on GNU/Linux terminals. It
uses the access time of the terminal device as a measure of idle time.

@end itemize

@node Modeline status, Keepalive, Autoaway, Useful features
@section Modeline status

@cindex Modeline
@findex jabber-mode-line-mode
@vindex jabber-mode-line-mode
@vindex jabber-mode-line-compact

By typing @kbd{M-x jabber-mode-line-mode} you toggle display of some
status in mode lines.  The information is your own presence status,
and some numbers showing the status of your roster contacts.  By
default, there are three numbers, for ``online'' (chatty and online),
``away'' (away, extended away and do not disturb) and offline
contacts.

If you set @code{jabber-mode-line-compact} to nil, you get a complete
breakdown of presence status.  That gives you six numbers indicating
the number of chatty, online, away, extended away, dnd, and offline
contacts, respectively.

@node Keepalive, Reconnecting, Modeline status, Useful features
@section Keepalive

@cindex Keepalive
@cindex Detecting lost connections

Sometimes network connections are lost without you noticing.  This is
especially true with Jabber, as it is quite reasonable to keep the
connection open for a long time without either sending or receiving
any data.

On the other hand, the server may want to do the same kind of
detection, and may expect the client to send something at regular
intervals.

If you want to detect a lost connection earlier, or make sure that the
server doesn't drop your connection, you can use the
keepalive functions.  These come in two flavours: whitespace pings and
XMPP pings.

@subsection Whitespace pings
@cindex Whitespace pings

A @dfn{whitespace ping} is a single space character sent to the server.
This is often enough to make NAT devices consider the connection
``alive'', and likewise for certain Jabber servers, e.g. Openfire.  It
may also make the OS detect a lost connection faster---a TCP connection
on which no data is sent or received is indistinguishable from a lost
connection.

@findex jabber-whitespace-ping-start
@findex jabber-whitespace-ping-stop
Type @kbd{M-x jabber-whitespace-ping-start} to start it, and @kbd{M-x
jabber-whitespace-ping-stop} to stop it.  The former is in
@code{jabber-post-connect-hooks} by default; @pxref{Hooks}.

@vindex jabber-whitespace-ping-interval
The frequency of whitespace pings is controlled by the variable
@code{jabber-whitespace-ping-interval}.  The default value is once every
30 seconds.

@subsection XMPP pings

These functions work by sending a ping request to your server once in a
while (by default every ten minutes), and considering the connection
lost if the server doesn't answer within reasonable time (by default
20 seconds).

@findex jabber-keepalive-start
@findex jabber-keepalive-stop
Type @kbd{M-x jabber-keepalive-start} to start
it, and @kbd{M-x jabber-keepalive-stop} to stop it.  You may want to add
@code{jabber-keepalive-start} to @code{jabber-post-connect-hooks};
@pxref{Hooks}.

@vindex jabber-keepalive-interval
@vindex jabber-keepalive-timeout
You can customize the interval and the timeout with the variables
@code{jabber-keepalive-interval} and @code{jabber-keepalive-timeout},
respectively.

@findex jabber-ping
You can also manually ping some client/server by using @kbd{M-x
jabber-ping}. Note that pong will be displayed according
@code{jabber-alerts-info-messages-hooks} (default is echo in
minibuffer).

@node Reconnecting, Tracking activity, Keepalive, Useful features
@section Reconnecting

@cindex Reconnect
@cindex Automatic reconnection
@vindex jabber-auto-reconnect

jabber.el supports automatic reconnection to Jabber server(s) upon lost
connection.  By default it is off.  To turn on, customize
the @code{jabber-auto-reconnect} variable.

This is of limited use if you have to type your password every time
jabber.el reconnects.  There are two ways to save your password: you can
set it in @code{jabber-account-alist} (@pxref{Account settings}), and
you can use @file{password-cache.el}, which is available in
recent versions of Gnus and in Emacs 23.  Note that you probably want to
customize @code{password-cache-expiry} if you use the latter.

@node Tracking activity, Watch buddies, Reconnecting, Useful features
@section Tracking activity

@cindex Activity
@findex jabber-activity-mode
@vindex jabber-activity-make-strings
@vindex jabber-activity-query-unread
@vindex jabber-activity-count-in-title
@vindex jabber-activity-count-in-title-format

When you're working on something important you might want to delay
responding to incoming messages.  However, when you're done working,
will you remember them?  If you're anything like me, you'll have a lot
of buffers in your Emacs session, and a Jabber chat buffer can easily
get lost.

When @code{jabber-activity-mode} is enabled (by default, it is), Emacs keeps
track of the buddies which have messaged you since last you visited
their buffer, and will display them in mode line.  As soon as you
visit their buffer they disappear from the mode line, indicating that
you've read their message.

If your mode line fills over because of these notifications, you can
customize @code{jabber-activity-make-strings} to shorten them to the
shortest possibly unambiguous form.

If you try to exit Emacs while you still have unread messages, you
will be notified and asked about this.  If you don't like that, set
@code{jabber-activity-query-unread} to nil.

If you want to display the number of unread buffers in the frame title,
set @code{jabber-activity-count-in-title} to t.  The format of the
number can be changed through
@code{jabber-activity-count-in-title-format}.

To hide activity notifications for some contacts, use
@code{jabber-activity-banned} variable - just add boring JIDs (as
regexps) here.

For complete customizability, write a hook function for
@code{jabber-activity-update-hook}.  From that function, you can take
action based on @code{jabber-activity-jids},
@code{jabber-activity-mode-string}, and
@code{jabber-activity-count-string}.

@node Watch buddies, Spell checking, Tracking activity, Useful features
@section Watch buddies

@cindex Watch
@cindex Online notifications
@findex jabber-watch-add
@findex jabber-watch-remove

Sometimes you might be waiting for a certain person to come online,
and you don't want that occasion to get lost in the noise.  To get an
obtrusive message when that happens, type @kbd{M-x jabber-watch-add}
and select the person in question.  You can enter a comment, to
remember why you added the watch.

You will get a message whenever that person goes from offline to
online.  jabber.el will remember this for the rest of your Emacs
session (it's not saved to disk, though), but if you want to get rid
of it, type @kbd{M-x jabber-watch-remove}.

@node Spell checking, Gmail notifications, Watch buddies, Useful features
@section Spell checking

@cindex flyspell
@cindex Spell checking

You can activate spell checking in a chat buffer with @kbd{M-x
flyspell-mode}.  It will check only what you are currently writing, not
what you receive or what you have already sent.  You may want to add
@code{flyspell-mode} to @code{jabber-chat-mode-hook}.

For more information about Emacs spell checking, @pxref{Spelling, ,
Checking and Correcting Spelling, emacs, GNU Emacs Manual}.

@node Gmail notifications, Saving groups roll state, Spell checking, Useful features
@section Gmail notifications

@cindex Gmail notifications

If you are connected to a Google Talk account, you can receive
notifications when a new Gmail message arrives. Gmail notifications
are enabled by adding the following line to your @file{.emacs}:

@example
(add-hook 'jabber-post-connect-hooks 'jabber-gmail-subscribe)
@end example

Default behavior is to display a message that mentions the number of
received gmails.  You can customize this behavior by providing your
own @code{jabber-gmail-dothreads} function.

Example:

@example
(eval-after-load "jabber-gmail"
  '(defun jabber-gmail-dothreads (threads)
     "Process <mail-thread-info/> elements.
THREADS is a list of XML sexps corresponding to <mail-thread-info/>
elements.
See http://code.google.com/apis/talk/jep_extensions/gmail.html#response"
     (osd "gmail: %d" (length threads))))

;;; It's usually a good idea to have a shortcut for querying GTalk server.
(global-set-key (kbd "<f9> g") 'jabber-gmail-query)

;;; The definition of `osd' function used by `jabber-gmail-dothreads'.
;;; `osd_cat' is shipped with the X OSD library
;;; [http://www.ignavus.net/software.html].
(if (and (display-graphic-p) (file-executable-p "/usr/bin/osd_cat"))
    (defun osd (fmt &rest args)
      "Display message on X screen."
      (let ((opts "-p bottom -A center -l 1 \
-f '-adobe-helvetica-bold-r-*-*-24-*-*-*-*-*-iso10646-1'")
	    (msg (apply 'format (concat fmt "\n") args)))
	(start-process "osd" nil shell-file-name shell-command-switch
		       (format "echo %s | osd_cat %s"
			       (shell-quote-argument msg) opts))))
  (defalias 'osd 'message))
@end example

@node Saving groups roll state, , Gmail notifications, Useful features
@section Saving groups roll state

@cindex Saving groups roll state

You can save roster's groups rollup/rolldown state between sessions.
To do this you need to add @code{jabber-roster-save-groups} to
@code{jabber-pre-disconnect-hook} and
@code{jabber-roster-restore-groups} to
@code{jabber-post-connect-hooks}, respectively.

State saved in private storage on server-side (for each account). Note
that state restoring working by rolling up groups, rolled up at state
saving (by default, all groups rolled down). Also note that at now,
@code{jabber-pre-disconnect-hook} run only with
@code{jabber-disconnect} (not with @code{jabber-disconnect-one}).


@node Message history, Typing notifications, Useful features, Top
@chapter Message history

@cindex History
@cindex Backlog
@findex jabber-truncate-top
@findex jabber-truncate-muc
@findex jabber-truncate-chat
@vindex jabber-history-enabled
@vindex jabber-history-muc-enabled
@vindex jabber-global-history-filename
@vindex jabber-use-global-history
@vindex jabber-history-dir
@vindex jabber-history-enable-rotation
@vindex jabber-history-size-limit
@vindex jabber-backlog-number
@vindex jabber-backlog-days
@vindex jabber-log-lines-to-keep

If you want a record of messages sent and received, set
@code{jabber-history-enabled} to t.  If you also want record MUC
groupchat messages, set @code{jabber-history-muc-enabled} to t.
Messages will be saved in one file per contact in the directory
specified by the variable @code{jabber-history-dir} (the default is
@file{~/.emacs.d/jabber-history}).  If you prefer to store messages
for all contacts in a single file, set
@code{jabber-use-global-history} to @code{t} and set
@code{jabber-global-history-filename} as required.@footnote{Using a
global history file used to be the default.  If the file specified by
@code{jabber-global-history-filename} exists,
@code{jabber-use-global-history} will default to @code{t} to support
existing installations.}

When you open a new chat buffer and have entries in your history file,
the last few messages you recently exchanged with the contact in
question will be inserted.  You can control how many messages with
@code{jabber-backlog-number} (by default 10), and how old messages
with @code{jabber-backlog-days} (by default 3 days).

@findex jabber-chat-display-more-backlog
If you want to see more messages, use the function
@code{jabber-chat-display-more-backlog}, available in the Chat menu.
This is currently the only way to view the message history, apart from
opening the history files manually.

@cindex Rotation of history files
@cindex History file rotation
If you worry about your history file(s) size, you can enable history
rotation feature by setting the variable
@code{jabber-history-enable-rotation} to @code{t} (default is
@code{nil}).  This feature ``rotates'' your history files according to
the following rule: When @code{jabber-history-size-limit} (in
kilobytes) is reached, the @var{history-file} is renamed to
@file{@var{history-file}-@var{number}}, where @var{number} is 1 or the smallest number
after the last rotation.

For example, suppose you set the
@code{jabber-history-size-limit} variable to 512 and you chat with
your buddy @samp{foo@@jabber.server} using the per-contact strategy to store
history files.  So, when the history file (@file{foo@@jabber-server})
reaches 512K bytes, it will be renamed to @file{foo@@jabber-server-1}
and @file{foo@@jabber-server} will be set empty. Next time
@file{foo@@jabber-server} grows to 512K bytes, it will be saved as
@file{foo@@jabber-server-2} and so on.  Although the example was
presented with the per-contact history file strategy, history rotation
works for both per-contact and global history logging strategies.

@cindex Truncate
@cindex Truncation
If you also want to keep chat and groupchat buffers from growing too
much, you can customize @code{jabber-alert-message-hooks} and
@code{jabber-alert-muc-hooks} by adding truncation upon receiving
message (@code{jabber-truncate-chat} and @code{jabber-truncate-muc}, respectively).
The truncation limit may be set by customizing the variable
@code{jabber-log-lines-to-keep}.

@node Typing notifications, Roster import and export, Message history, Top
@chapter Typing notifications

There are two protocols for ``contact is typing'' notifications in
Jabber.  jabber.el supports both of them, displaying various information
in the header line of chat buffers.

@section Message events

@cindex Composing
@cindex Delivered
@cindex Displayed
@vindex jabber-events-request-these
@vindex jabber-events-confirm-delivered
@vindex jabber-events-confirm-displayed
@vindex jabber-events-confirm-composing

The older protocol is called Message Events (@pxref{XEP-0022}).  Besides
typing notification, it lets you know what happens to the messages you send.
These states are possible:

@itemize @bullet
@item
@samp{In offline storage} (the user will receive it on next logon)

@item
@samp{Delivered} to user's client (but not necessarily displayed)

@item
@samp{Displayed} to user

@item
User is @samp{typing a message}

@end itemize

The first state is only reported by servers; the other three are
reported by clients.  jabber.el can report all three of them, and can
display all four; not all clients support all states, though.

If you don't want jabber.el to send out this information about you, set
the variables @code{jabber-events-confirm-delivered},
@code{jabber-events-confirm-displayed}, and/or
@code{jabber-events-confirm-composing} to nil.  You can make jabber.el
not to request such information by customizing
@code{jabber-events-request-these}.

@section Chat states

@vindex jabber-chatstates-confirm

The newer protocol is called Chat States (@pxref{XEP-0085}).  Rather
than dealing with individual messages, it describes the state of the
chat session between two people.  The following states are possible:

@itemize @bullet
@item
Active (the default state, not displayed)

@item
Inactive

@item
Composing

@item
Paused (i.e., taking a short pause in composing)

@item
Gone

@end itemize

jabber.el can display all five states, but only ever sends ``active''
and ``composing'' itself.

To customize sending of chat states, customize the variable
@code{jabber-chatstates-confirm}.


@node Roster import and export, XMPP URIs, Typing notifications, Top
@chapter Roster import and export

@findex jabber-export-roster
@findex jabber-import-roster
@cindex Export roster
@cindex Import roster

Your roster is saved on the Jabber server, and usually not in the
client.  However, you might want to save the roster to a file anyway.
The most common reason for this is probably to copy it to another
account.

To export your roster to a file, type @kbd{M-x jabber-export-roster}.
A buffer will appear in which you can edit the data to be exported.
Changes done in that buffer will not affect your real roster.

To import your roster from a file, type @kbd{M-x jabber-import-roster}.
You will be able to edit the data before importing it.  Items not in the
roster will be added; items in the roster will be modified to match
imported data.  Subscriptions will be updated.

The format of the roster files is the XML used by roster pushes in the
XMPP protocol, in UTF-8 encoding.

@node XMPP URIs, Customization, Roster import and export, Top
@chapter XMPP URIs

@cindex URIs
@cindex URLs
@cindex links
@cindex xmpp: links
@cindex Mozilla integration
@cindex web browser integration
@cindex browser integration
@findex jabber-handle-uri

Many web page authors use links starting with @samp{xmpp:} for JIDs.
Your web browser could be made to pass such links to jabber.el, so that
such links are actually useful and not just decoration.  How to do that
depends on your operating system and web browser.

For any of these methods, you need to make sure that you are running
the Emacs server.  @xref{Emacs Server, , Using Emacs as a Server,
emacs, GNU Emacs Manual}, though the simplest way to start it is to
customize the variable @code{server-mode}.

@section GNOME

The jabber.el distribution contains a GConf schema which tries to set
up handling of @samp{xmpp:} URIs.  It is installed by @samp{make
install}.  This may or may not work, depending on your GConf
configuration and other installed applications.  To check, try
running:

@example
gconftool --get /desktop/gnome/url-handlers/xmpp/command
@end example

This should print something like:

@example
/usr/local/libexec/emacs-jabber-uri-handler "%s"
@end example

This setting is picked up by most GNOME or GTK based web browsers,
including Firefox.

@section Mozilla and Unix

If you use a Mozilla-based web browser on a Unix-like operating
system, and the GConf method above doesn't work, you can set it up
manually by following these steps:

@enumerate

@item
Note the path of the @file{emacs-jabber-uri-handler} file in the jabber.el
distribution, and make sure it is executable.

@item
Set the Mozilla preference @samp{network.protocol-handler.app.xmpp} to
the path of @file{emacs-jabber-uri-handler}.  There are two ways to do this:

@itemize
@item
Go to the URL @samp{about:config}, right-click in the list, choose ``New
string'', and enter @samp{network.protocol-handler.app.xmpp} and the
path in the following dialogs.

@item
Open or create the file @file{user.js} in your Mozilla profile directory
(in the same directory as @file{prefs.js}), and add the following line:

@example
user_pref("network.protocol-handler.app.xmpp",
  "@var{/path/to}/emacs-jabber-uri-handler");
@end example

Restart Mozilla for this change to take effect.
@end itemize
@end enumerate

@section Other systems

If you know how to pass an XMPP URI from your browser to the function
@code{jabber-handle-uri}, your contribution for this section would be
appreciated.

@node Customization, Hacking and extending, XMPP URIs, Top
@chapter Customization

@findex jabber-customize
@cindex Customization

jabber.el is intended to be customizable for many tastes.  After all,
this is Emacs.  To open a customization buffer for jabber.el, type
@kbd{M-x jabber-customize}.

@menu
* Account settings::
* Menu::
* Customizing the roster buffer::
* Customizing the chat buffer::
* Customizing alerts::
* Hooks::
* Debug options::
@end menu

@node Account settings, Menu, , Customization
@section Account settings

@cindex Username
@cindex Resource
@cindex Password
@cindex JID
@cindex Network server

@vindex jabber-account-list
All account settings reside in the variable @code{jabber-account-list}.
Usually you only need to set the JID, in the form
@samp{username@@server} (or @samp{username@@server/resource} to use a
specific resource name).  These are the other account options:

@table @asis
@item Disabled
If the account is disabled, @code{jabber-connect-all} will not attempt
to connect it.  You can still connect it manually with
@code{jabber-connect}.

@item Password
You can set the password of the account, so you don't have to enter it
when you connect.  Note that it will be stored unencrypted in your
customization file.

@item Network server
If the JID of the Jabber server is not also its DNS name, you may have
to enter the real DNS name or IP address of the server here.

@item Connection type
This option specifies whether to use an encrypted connection to the
server.  Usually you want ``STARTTLS'' (@code{starttls}), which means
that encryption is activated if the server supports it.  The other
possibilities are ``unencrypted'' (@code{network}), which means just
that, and ``legacy SSL/TLS'' (@code{ssl}), which means that encryption
is activated on connection.

@item Port
If the Jabber server uses a nonstandard port, specify it here.  The
default is 5222 for STARTTLS and unencrypted connections, and 5223 for
legacy SSL connections.
@end table

@subsection For Google Talk

@cindex Google Talk

If you have a very new version of @file{dns.el},@footnote{Specifically,
you need Emacs 23, or No Gnus 0.3.} you can connect to
Google Talk just by specifying your Gmail address as JID.  Otherwise,
you also need to set
``network server'' to @kbd{talk.google.com} and ``connection type'' to
``legacy SSL''.

See also @ref{Gmail notifications}.

@subsection Upgrade note

Previous versions of jabber.el had the variables @code{jabber-username},
@code{jabber-server}, @code{jabber-resource} and
@code{jabber-password}.  These are now obsolete and not used.

@node Menu, Customizing the roster buffer, Account settings, Customization
@section Menu

@vindex jabber-display-menu
@cindex Menus
There is a Jabber menu on the menu bar with some common commands.  By
default, it is displayed only if you are connected, or if you have
configured any accounts.  You can set the variable
@code{jabber-display-menu} to @code{t} or @code{nil}, to have the menu
displayed always or never, respectively.  The default behaviour
corresponds to the setting @code{maybe}.

@findex jabber-menu
Earlier, the way to have the menu appear was to call the function
@code{jabber-menu}.  It still works, but is considered obsolete.

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

@cindex Roster buffer, customizing

@cindex Sorting the roster
@vindex jabber-roster-sort-functions
@code{jabber-roster-sort-functions} controls how roster items are
sorted.  By default, contacts are sorted first by presence, and then
alphabetically by displayed name.

@vindex jabber-sort-order
@code{jabber-sort-order} controls how roster items are sorted by
presence.  It is a list containing strings corresponding to show
status (@pxref{Presence}) or @code{nil}, which represents offline.

@vindex jabber-show-resources
@code{jabber-show-resources} controls when your contacts' resources
are shown in the roster buffer.  The default is to show resources when
a contact has more than one connected resource.

@vindex jabber-roster-line-format
@code{jabber-roster-line-format} specifies how the entry for each
contact looks.  It is a string where some characters are special if
preceded by a percent sign:

@table @code
@item %a
Avatar of contact, if any
@item %c
@samp{*} if the contact is connected, or @samp{ } if not
@item %u
Subscription state---see below
@item %n
Nickname of contact, or JID if no nickname
@item %j
Bare JID of contact (without resource)
@item %r
Highest-priority resource of contact
@item %s
Availability of contact as a string ("Online", "Away" etc)
@item %S
Status string specified by contact
@end table

@code{jabber-roster-show-title} controls whether to show a "Jabber
roster" string at the top of the roster buffer.  You need to run
@kbd{M-x jabber-display-roster} after changing this variable to update
the display.

@code{%u} is replaced by one of the strings given by
`jabber-roster-subscription-display'.

@vindex jabber-resource-line-format
@code{jabber-resource-line-format} is nearly identical, except that
the values correspond to the values of the resource in question, and
that the @code{%p} escape is available, which inserts the priority of
the resource.

@vindex jabber-roster-buffer
@code{jabber-roster-buffer} specifies the name of the roster buffer.
If you change this, the new name will be used the next time the roster
is redisplayed.

@vindex jabber-roster-show-bindings
@code{jabber-roster-show-bindings} controls whether to show a list of
keybindings at the top of the roster buffer.  You need to run @kbd{M-x
jabber-display-roster} after changing this variable to update the display.

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

@cindex Chat buffer
@cindex Timestamps
@cindex Faces, chat buffer

You can customize the look of the prompts in the chat buffer.  There
are separate settings for local text (i.e. what you write) and foreign text
(i.e. what other people write).

@vindex jabber-chat-text-local
@vindex jabber-chat-text-foreign
@code{jabber-chat-text-local} and @code{jabber-chat-text-foreign}
determine the faces used for chat messages.

@vindex jabber-chat-prompt-local
@vindex jabber-chat-prompt-foreign
@vindex jabber-muc-colorize-local
@vindex jabber-muc-colorize-foreign
@vindex jabber-muc-nick-saturation
@vindex jabber-muc-nick-value
@vindex jabber-muc-participant-colors
@cindex Nick coloring
@code{jabber-chat-prompt-local} and @code{jabber-chat-prompt-foreign}
determine the faces used for the prompts. You can also turn on
automatic colorization of local (@code{jabber-muc-colorize-local})
and/or foreign (@code{jabber-muc-colorize-foreign}) prompts. By
default it is off. You can correct and save for future use auto-generated colors by
customizing @code{jabber-muc-participant-colors}, @code{jabber-muc-nick-saturation} and
@code{jabber-muc-nick-value}, if you wish.

@vindex jabber-chat-local-prompt-format
@vindex jabber-chat-foreign-prompt-format
@code{jabber-chat-local-prompt-format} and
@code{jabber-chat-foreign-prompt-format} determine what text is
displayed in the prompts.  They are format strings, with the following
special sequences defined:

@table @code
@item %t
The time when the message was sent or received
@item %n
The nickname of the user.  For the foreign prompt, this is the name of
the contact in the roster, or the JID if no name set.  For the local
prompt, this is the username part of your JID.
@item %u
The username of the user (i.e. the first part of the JID).
@item %r
The resource.
@item %j
The bare JID of the user
@end table

@cindex Timestamp format
@vindex jabber-chat-time-format
@code{jabber-chat-time-format} defines how @code{%t} shows time.  Its
format is identical to that passed to @code{format-time-string}.
@xref{Time Conversion, , Time Conversion, elisp, GNU Emacs Lisp
Reference Manual}.

@vindex jabber-chat-delayed-time-format
@code{jabber-chat-delayed-time-format} is used instead of
@code{jabber-chat-time-format} for delayed messages (messages sent while
you were offline, or fetched from history).  This way you can have short
timestamps everywhere except where you need long ones.  You can always
see the complete timestamp in a tooltip by hovering over the prompt with
the mouse.

@cindex Rare timestamps
@vindex jabber-print-rare-time
@vindex jabber-rare-time-format
@vindex jabber-chat-text-local
By default, timestamps are printed in the chat buffer every hour (at
``rare'' times).  This can be toggled with
@code{jabber-print-rare-time}.  You can customize the displayed time by
setting @code{jabber-rare-time-format}.  Rare timestamps will be printed
whenever time formatted by that format string would change.

@cindex Header line of chat buffers
@vindex jabber-chat-header-line-format
@vindex jabber-muc-header-line-format
You can also customize the header line of chat buffers, by modifying
the variable @code{jabber-chat-header-line-format}.  The format of
that variable is the same as that of @code{mode-line-format} and
@code{header-line-format}.  @xref{Mode Line Format, , Mode-Line
Format, elisp, GNU Emacs Lisp Reference Manual}.  For MUC buffers,
@code{jabber-muc-header-line-format} is used instead.

@vindex jabber-chat-fill-long-lines
@cindex Filling long lines in chat buffer
The variable @code{jabber-chat-fill-long-lines} controls whether long
lines in the chat buffer are wrapped.

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

@cindex Alert hooks
@findex define-jabber-alert

When an event happens (currently including presence changes, incoming
messages, and completed queries) you will usually want to be
notified.  Since tastes in this area vary wildly, these alerts are
implemented as hooks, so you can choose which ones you want, or write
your own if none fit.

Actually, if you don't want to write your own, stop reading this
section and just read @ref{Standard alerts}.

Many kinds of alerts consist in displaying a text message through a
certain mechanism.  This text message is provided by a function which
you can rewrite or replace.  If this function returns @code{nil}, no
message is displayed, and non-textual alerts refrain from action.

If you want to write alert hooks that do nothing except displaying the
supplied message in some way, use the macro
@code{define-jabber-alert}.  For example, if @var{foo} is a function
that takes a string as an argument, write
@example
(define-jabber-alert foo
  "Display a message in a fooish way"
  'foo)
@end example
@noindent
and all details will be taken care of for you.

The hooks take different arguments depending on category.  However,
they all have in common that the last argument is the result of the
message function.  The message function for each category takes the
same arguments as the corresponding hooks, except for that last
argument.

Alert hook contributions are very welcome.  You can send them to the
mailing list, or to the Sourceforge patch tracker. @xref{Contacts}.

Alert hooks are meant for optional UI things, that are subject to
varying user tastes, and that can be toggled by simply adding or
removing the function to and from the hook.  For other purposes, there
are corresponding general hooks, that are defvars instead of
defcustoms, and that are meant to be managed by Lisp code.  They have the
same name as the alert hooks minus the @code{-alert} part,
e.g. @code{jabber-message-hooks} vs @code{jabber-alert-message-hooks},
etc.

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

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

@cindex Alerts
@cindex Scroll

Thirteen alerts are already written for all four alert categories.  These
all obey the result from the corresponding message function.

The @code{beep} alerts simply sound the terminal bell by calling
@code{ding}.  They are disabled by default.

The @code{echo} alerts display a message in the echo area by calling
@code{message}.  They are enabled by default.

The @code{switch} alerts switch to the buffer where the event occurred
(chat buffer for incoming messages, roster buffer for presence
changes, browse buffer for completed queries).  They are disabled by
default.  Take care when using them, as they may interrupt your
editing.

The @code{display} alerts display but do not select the buffer in
question, using the function @code{display-buffer}.  @xref{Choosing
Window, , Choosing a Window for Display, elisp, GNU Emacs Lisp
Reference Manual}, for information about customizing its behaviour.
This is enabled by default for info requests.

@cindex Sound effects
The @code{wave} alerts play a sound file by calling
@code{play-sound-file}.  No sound files are provided.  To use this,
enter the names of the sound files in
@code{jabber-alert-message-wave}, @code{jabber-alert-presence-wave}
and @code{jabber-alert-info-wave}, respectively.  You can specify
specific sound files for contacts matching a regexp in the variables
@code{jabber-alert-message-wave-alist} and
@code{jabber-alert-presence-wave-alist}.

@cindex Screen terminal manager
The @code{screen} alerts send a message through the Screen terminal
manager@footnote{See @uref{http://www.gnu.org/software/screen/}.}.  They do no
harm if called when you don't use Screen.

@cindex Tmux terminal manager
The @code{tmux} alerts send a message through the tmux terminal
manager@footnote{See @uref{http://tmux.sourceforge.net/}.}.

@cindex Ratpoison window manager
@cindex Window manager, Ratpoison
The @code{ratpoison} alerts send a message through the Ratpoison
window manager@footnote{See @uref{http://ratpoison.sourceforge.net/}.}.  They
do no harm if used when you're not running X, but if you are running X
with another window manager, the ratpoison processes will never exit.
Emacs doesn't hold on to them, though.

@cindex Sawfish window manager
@cindex Window manager, Sawfish
The @code{sawfish} alerts send a message through the Sawfish window
manager.

@cindex wmii window manager
@cindex Window manager, wmii
The @code{wmii} alerts display a message through the wmii window
manager.

@cindex awesome window manager
@cindex Window manager, awesome
The @code{awesome} alerts display a message through the awesome window
manager. However, to work it needs naughty (i.e.
@code{require("naughty")} in rc.lua).

@cindex xmessage
@vindex jabber-xmessage-timeout
The @code{xmessage} alerts send a message through the standard
@code{xmessage} tool.  The variable @code{jabber-xmessage-timeout}
controls how long the alert appears.

@cindex OSD
The @code{osd} alerts send a message onto your screen using
XOSD.@footnote{XOSD can be found at
@uref{http://www.ignavus.net/software.html}.  You also need
@file{osd.el} from @uref{http://www.brockman.se/software/osd.el}.}

@cindex libnotify
@cindex notification-daemon
The @code{libnotify} alerts send a message onto your screen using
@code{notification-daemon}.

@cindex Festival speech synthesis
@cindex Speech synthesis, Festival
The @code{festival} alerts speak the message using the Emacs interface
of the Festival speech synthesis system@footnote{See
@uref{http://www.cstr.ed.ac.uk/projects/festival/}.}.

@cindex Autoanswerer
The @code{autoanswer} alert is kind of special: it will not show you
message/muc alert, but instead will automaticaly answer to sender. See
variable `jabber-autoanswer-alist' description for details.

@cindex Scroll chat buffers
Additionally, for one-to-one and MUC messages, there are @code{scroll}
alerts (enabled by default), that aim to do the right thing with chat
buffers that are visible but not active.  Sometimes you want point to
scroll down, and sometimes not.  These functions should do what you
mean; if they don't, it's a bug.

Also, in MUC you can use a family of so-called ``personal'' alerts.
They are like other MUC alerts, but fire only on incoming messages
addresed directly to you (also known as ``private messages'').  One
example of such an alert is @code{jabber-muc-echo-personal}, which shows
a note for an MUC message only if it was addressed to you.

Some of these functions are in the @file{jabber-alert.el} file, and the
others are in their own files.  You can use them as templates or
inspiration for your own alerts.

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

@vindex jabber-alert-presence-message-function
@findex jabber-presence-default-message

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

@example
(defun @var{function} (@var{who} @var{oldstatus} @var{newstatus} @var{statustext})
   ...
   )
@end example

@var{who} is the JID symbol (@pxref{JID symbols}),
@var{oldstatus} and @var{newstatus} are the previous and current
stati, respectively, and @var{statustext} is the status message if
provided, otherwise nil.

@var{oldstatus} and @var{newstatus} can be one of @code{""}
(i.e. online), @code{"away"}, @code{"xa"}, @code{"dnd"}, @code{"chat"},
@code{"error"} and @code{nil} (i.e. offline).

@var{newstatus} can also be one of @code{"subscribe"},
@code{"subscribed"}, @code{"unsubscribe"} and @code{"unsubscribed"}.

The default function, @code{jabber-presence-default-message}, returns
@code{nil} if @var{oldstatus} and @var{newstatus} are the same, and in
other cases constructs a message from the given data.

Another function, @code{jabber-presence-only-chat-open-message},
behave just like @code{jabber-presence-default-message}, but only if
conversation buffer for according JID is already open. Use it to show
presence notifications only for ``interesting'' contacts.

All presence alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.  This last argument is usually the only one they use.

@node Message alerts, MUC alerts, Presence alerts, Customizing alerts
@subsection Message alerts

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

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

@example
(defun @var{function} (@var{from} @var{buffer} @var{text})
   ...
   )
@end example

@var{from} is the JID symbol (@pxref{JID symbols}), @var{buffer}
is the buffer where the message is displayed, and @var{text} is the
text of the message.

The default function, @code{jabber-message-default-message}, returns
``Message from @var{person}'', where @var{person} is the name of the
person if specified in the roster, otherwise the JID.

All message alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.

@vindex jabber-message-alert-same-buffer
If you don't want message alerts when the chat buffer in question is
already the current buffer, set @code{jabber-message-alert-same-buffer}
to nil.  This affects the behaviour of the default message function, so
you'll have to reimplement this functionality if you write your own
message function.

@node MUC alerts, Info alerts, Message alerts, Customizing alerts
@subsection MUC alerts

@vindex jabber-alert-muc-function
@vindex jabber-muc-alert-self
@findex jabber-muc-default-message

Set @code{jabber-alert-muc-function} to your desired
function.  This function should look like:

@example
(defun @var{function} (@var{nick} @var{group} @var{buffer} @var{text})
   ...
   )
@end example

@var{nick} is the nickname, @var{group} is the JID of the group,
@var{buffer} is the buffer where the message is displayed, and
@var{text} is the text of the message.

The default function, @code{jabber-muc-default-message}, returns
``Message from @var{nick} in @var{group}'' or ``Message in
@var{group}'', the latter for messages from the room itself.

All MUC alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.

By default, no alert is made for messages from yourself.  To change
that, customize the variable @code{jabber-muc-alert-self}.

@node Info alerts,  , MUC alerts, Customizing alerts
@subsection Info alerts

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

Info alerts are sadly underdeveloped.  The message function,
@code{jabber-alert-info-message-function}, takes two arguments,
@var{infotype} and @var{buffer}.  @var{buffer} is the buffer where
something happened, and @var{infotype} is either @code{'roster} for
roster updates, or @code{'browse} for anything that uses the browse
buffer (basically anything except chatting).

The info alert hooks take an extra argument, as could be expected.

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

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

@table @code
@vindex jabber-post-connect-hooks
@item jabber-post-connect-hooks
This hook is called after successful connection and authentication.
By default it contains @code{jabber-send-current-presence}
(@pxref{Presence}).  The hook functions get the connection object as
argument.

@vindex jabber-lost-connection-hooks
@item jabber-lost-connection-hooks
This hook is called when you have been disconnected for unknown
reasons.  Usually this isn't noticed for quite a long time.

The hook is called with one argument: the connection object.

@vindex jabber-pre-disconnect-hook
@item jabber-pre-disconnect-hook
This hook is called just before voluntary disconnection, i.e. in
@code{jabber-disconnect}, the command to disconnect all accounts.  There
is currently no hook for disconnection of a single account.

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

@vindex jabber-chat-mode-hook
@item jabber-chat-mode-hook
This hook is called when a new chat buffer is created.

@vindex jabber-browse-mode-hook
@item jabber-browse-mode-hook
This hook is called when a new browse buffer is created.

@vindex jabber-roster-mode-hook
@item jabber-roster-mode-hook
This hook is called when the roster buffer is created.

@end table

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

These settings provide a lot of information which is usually not very
interesting, but can be useful for debugging various things.

@vindex jabber-debug-log-xml
@cindex XML console
@code{jabber-debug-log-xml} activates XML console.  All XML stanzas
sent and received are logged in the buffer @code{*-jabber-console-@var{jid}-*}
(and to specified file if value is string).
Also this buffer can be used to send XML stanzas manually.

@vindex jabber-console-name-format
Format for console buffer name. %s mean connection jid. Default value is
@code{*-jabber-console-%s-*}.

@vindex jabber-console-truncate-lines
Maximum number of lines in console buffer. Use this option to prevent
over bloating size of buffer.
Set value to 0 if you want to keep all stanzas in buffer, but
it's not recommended and may be unsafe.

@vindex jabber-debug-keep-process-buffers
Usually, the process buffers for Jabber connections are killed when the
connection is closed, as they would otherwise just fill up memory.
However, they might contain information about why the connection was
lost.  To keep process buffers, set
@code{jabber-debug-keep-process-buffers} to @code{t}.

@node Hacking and extending, Protocol support, Customization, Top
@chapter Hacking and extending

This part of the manual is an attempt to explain parts of the source
code.  It is not meant to discourage you from reading the code
yourself and trying to figure it out, but as a guide on where to
look.  Knowledge of Jabber protocols is assumed.

@menu
* Connection object::
* XML representation::
* JID symbols::
* Listening for new requests::
* Sending new requests::
* Extending service discovery::
* Chat printers::
* Stanza chains::
@end menu

@node Connection object, XML representation, , Hacking and extending
@section Connection object
@cindex connection object
@cindex account object
@cindex FSM

Each Jabber connection is represented by a ``connection object''.  This
object has the form of a finite state machine, and is realized by the
library @code{fsm}.@footnote{So far, this library is only distributed
with jabber.el.  The author hopes that it could be useful for other
projects, too.}

The various states of this object are defined in @file{jabber-core.el}.
They describe the way of the connection through the establishing of a
network connection and authentication, and finally comes to the
@code{:session-established} state where ordinary traffic takes place.

These details are normally opaque to an extension author.  As will be
noted, many functions expect to receive a connection object, and
functions at extension points generally receive such an object in order
to pass it on.  The following functions simply query the internal state
of the connection:

@defun jabber-connection-jid connection
The @code{jabber-connection-jid} function returns the full JID of
@var{connection}, i.e. a string of the form
@code{"username@@server/resource"}.
@end defun

@defun jabber-connection-bare-jid connection
The @code{jabber-connection-bare-jid} function returns the bare JID of
@var{connection}, i.e. a string of the form @code{"username@@server"}.
@end defun

@node XML representation, JID symbols, Connection object, Hacking and extending
@section XML representation

@cindex XML representation

The XML representation is the one generated by @file{xml.el} in Emacs,
namely the following.  Each tag is a list.  The first element of the
list is a symbol, the name of which is the name of the tag.  The
second element is an alist of attributes, where the keys are the
attribute names in symbol form, and the values are strings.  The
remaining elements are the tags and data contained within the tag.

For example,
@example
<foo bar='baz'>
<frobozz/>Fnord
</foo>
@end example
is represented as
@example
(foo ((bar . "baz")) (frobozz nil "") "Fnord
")
@end example

Note the empty string as the third element of the @code{frobozz}
list.  It is not present in newer (post-21.3) versions of
@file{xml.el}, but it's probably best to assume it might be there.

@defun jabber-sexp2xml xml-sexp
This function takes a tag in list representation, and returns its XML
representation as a string.  You will normally not need to use this
function directly, but it can be useful to see how your sexps will look
when sent to the outer, non-Lisp, world.
@end defun

@defun jabber-send-sexp connection sexp
This function sends @var{sexp}, an XMPP stanza in list representation,
and sends it over @var{connection}.

You will normally use the functions @code{jabber-send-presence},
@code{jabber-send-message} and @code{jabber-send-iq} instead of this
function.
@end defun

@node JID symbols, Listening for new requests, XML representation, Hacking and extending
@section JID symbols

@vindex jabber-jid-obarray
JIDs are sometimes represented as symbols.  Its name is the JID, and it is interned
in @code{jabber-jid-obarray}.  A roster entry can have the following
properties:

@table @code
@item xml
The XML tag received from the server on roster update

@item name
The name of the roster item (just like the XML attribute)

@item subscription
The subscription state; a string, one of @code{"none"}, @code{"from"},
@code{"to"} and @code{"both"}

@item ask
The ask state; either @code{nil} or @code{"subscribe"}

@item groups
A list of strings (possibly empty) containing all the groups the
contact is in

@item connected
Boolean, true if any resource is connected

@item show
Presence show value for highest-priority connected resource; a string,
one of @code{""} (i.e. online), @code{"away"}, @code{"xa"},
@code{"dnd"}, @code{"chat"}, @code{"error"} and @code{nil}
(i.e. offline)

@item status
Presence status message for highest-priority connected resource

@item resources
Alist.  Keys are strings (resource names), values are plists with
properties @code{connected}, @code{show}, @code{status} and
@code{priority}.

@end table

Incoming presence information is inserted in @code{resources}, and the
information from the resource with the highest priority is inserted in
@code{show} and @code{status} by the function
@code{jabber-prioritize-resources}.

@node Listening for new requests, Sending new requests, JID symbols, Hacking and extending
@section Listening for new requests

@findex jabber-send-iq
@findex jabber-process-iq
@findex jabber-signal-error
@vindex jabber-iq-get-xmlns-alist
@vindex jabber-iq-set-xmlns-alist

To listen for new IQ requests, add the appropriate entry in
@code{jabber-iq-get-xmlns-alist} or @code{jabber-iq-set-xmlns-alist}.
The key is the namespace of the request, and the value is a function
that takes two arguments, the connection object, and
the entire IQ stanza in list format.
@code{jabber-process-iq} reads these alists to determine which
function to call on incoming packets.

For example, the Ad-Hoc Commands module contains the following:

@example
(add-to-list 'jabber-iq-set-xmlns-alist
	     (cons "http://jabber.org/protocol/commands"
                   'jabber-ahc-process))
@end example

To send a response to an IQ request, use @samp{(jabber-send-iq
@var{connection} @var{sender} "result" @var{query} nil nil nil nil
@var{id})}, where @var{query} is the query in list format.
@code{jabber-send-iq} will encapsulate the query in an IQ packet with
the specified id.

To return an error to the Jabber entity that sent the query, use
@code{jabber-signal-error}.  The signal is caught by
@code{jabber-process-iq}, which takes care of sending the error.
You can also use @code{jabber-send-iq-error}.

@node Sending new requests, Extending service discovery, Listening for new requests, Hacking and extending
@section Sending new requests

@findex jabber-send-iq
@findex jabber-process-iq

To send an IQ request, use @code{jabber-send-iq}.  It will generate an
id, and create a mapping for it for use when the response comes.  The
syntax is:

@example
(jabber-send-iq @var{connection} @var{to} @var{type} @var{query}
                @var{success-callback} @var{success-closure}
                @var{failure-callback} @var{failure-closure})
@end example

@var{success-callback} will be called if the response is of type
@samp{result}, and @var{failure-callback} will be called if the response
is of type @samp{error}.  Both callbacks take three arguments, the
connection object, the IQ stanza of the response, and the corresponding
closure item earlier passed to @code{jabber-send-iq}.

@findex jabber-report-success
@findex jabber-process-data
Two standard callbacks are provided.  @code{jabber-report-success} takes
a string as closure item, and reports success or failure in the echo
area by appending either @samp{succeeded} or @samp{failed} to the
string.  @code{jabber-process-data} prepares a browse buffer.  If its
closure argument is a function, it calls that function with point in
this browse buffer.  If it's a string, it prints that string along with
the error message in the IQ response.  If it's anything else
(e.g. @code{nil}), it just dumps the XML in the browse buffer.

Examples follow.  This is the hypothetical Jabber protocol ``frob'',
for which only success report is needed:
@example
(jabber-send-iq connection
                "someone@@somewhere.org" "set"
                '(query ((xmlns . "frob")))
                'jabber-report-success "Frobbing"
                'jabber-report-success "Frobbing")
@end example
This will print ``Frobbing succeeded'' or ``Frobbing failed: @var{reason}'',
respectively, in the echo area.

The protocol ``investigate'' needs to parse results and show them in a
browse buffer:
@example
(jabber-send-iq connection
                "someone@@somewhere.org" "get"
                '(query ((xmlns . "investigate")))
                'jabber-process-data 'jabber-process-investigate
                'jabber-process-data "Investigation failed")
@end example
Of course, the previous example could have used
@code{jabber-report-success} for the error message.  It's a matter of
UI taste.

@node Extending service discovery, Chat printers, Sending new requests, Hacking and extending
@section Service discovery

Service discovery (XEP-0030) is a Jabber protocol for communicating
features supported by a certain entity, and items affiliated with an
entity.  jabber.el has APIs for both providing and requesting such
information.


@menu
* Providing info::
* Requesting info::
@end menu

@node Providing info, Requesting info, , Extending service discovery
@subsection Providing info

Your new IQ request handlers will likely want to advertise their
existence through service discovery.

@vindex jabber-advertised-features
To have an additional feature reported in response to disco info
requests, add a string to @code{jabber-advertised-features}.

@vindex jabber-disco-items-nodes
@vindex jabber-disco-info-nodes
By default, the service discovery functions reject all requests
containing a node identifier with an ``Item not found'' error.  To
make them respond, add the appropriate entries to
@code{jabber-disco-items-nodes} and @code{jabber-disco-info-nodes}.
Both variables work in the same way.  They are alists, where the keys
are the node names, and the values are lists of two items.

The first item is the data to return --- either a list, or a function
taking the connection object and the entire IQ stanza and returning a
list; in either case this list contains the XML nodes to include in the
@code{<query/>} node in the response.

@findex jabber-my-jid-p
The second item is the access control function.  An access control
function receives the connection object and a JID as arguments, and
returns non-nil if access is to be granted.  If nil is specified
instead of a function, access is always granted.  One such function is
provided, @code{jabber-my-jid-p}, which grants access for JIDs where
the username and server (not necessarily resource) are equal to those
of the user, or one of the user's configured accounts.

@node Requesting info,  , Providing info, Extending service discovery
@subsection Requesting info

jabber.el has a facility for requesting disco items and info.  All
positive responses are cached.

To request disco items or info from an entity, user one of these
functions:

@defun jabber-disco-get-info jc jid node callback closure-data &optional force
Get disco information for @var{jid} and @var{node}.  A request is sent
asynchronously on the connection @var{jc}.  When the response arrives,
@var{callback} is called with three arguments: @var{jc},
@var{closure-data}, and the result.  The result may be retrieved from
the cache, unless @var{force} is non-nil.

If the request was successful, or retrieved from cache, it looks like
@code{(@var{identities} @var{features})}, where @var{identities} and
@var{features} are lists.  Each identity is @code{["@var{name}"
"@var{category}" "@var{type}"]}, and each feature is a string denoting
the namespace of the feature.

If the request failed, the result is an @code{<error/>} node.
@end defun

@defun jabber-disco-get-items jc jid node callback closure-data &optional force
Get disco information for @var{jid} and @var{node}.  A request is sent
asynchronously on the connection @var{jc}.  When the response arrives,
@var{callback} is called with three arguments: @var{jc},
@var{closure-data}, and the result.  The result may be retrieved from
the cache, unless @var{force} is non-nil.

If the request was successful, or retrieved from cache, the result is
a list of items, where each item is @code{["@var{name}" "@var{jid}"
"@var{node}"]}.  The values are either strings or nil.

If the request failed, the result is an @code{<error/>} node.
@end defun

If you only want to see what is in the cache, use one of the following
functions.  They don't use a callback, but return the result directly.

@defun jabber-disco-get-info-immediately jid node
Return cached disco information for @var{jid} and @var{node}, or nil
if the cache doesn't contain this information.  The result is the same
as for @code{jabber-disco-get-info}.
@end defun

@defun jabber-disco-get-items-immediately jid node
Return cached disco items for @var{jid} and @var{node}, or nil
if the cache doesn't contain this information.  The result is the same
as for @code{jabber-disco-get-items}.
@end defun

In the future, this facility will be expanded to provide information
acquired through XEP-0115, Entity capabilities, which is a protocol
for sending disco information in @code{<presence/>} stanzas.

@node Chat printers, Stanza chains, Extending service discovery, Hacking and extending
@section Chat printers

@vindex jabber-chat-printers
@vindex jabber-muc-printers
@vindex jabber-body-printers
@cindex Chat printers
@cindex Body printers

Chat printers are functions that print a certain aspect of an incoming
message in a chat buffer.  Included are functions for printing subjects
(@code{jabber-chat-print-subject}), bodies
(@code{jabber-chat-print-body}, and @code{jabber:x:oob}-style URLs
(@code{jabber-chat-print-url}).  The functions in
@code{jabber-chat-printers} are called in order, with the entire
@code{<message/>} stanza as argument.  As described in the docstring
of @code{jabber-chat-printers}, these functions are run in one of two
modes: @code{printp}, in which they are supposed to return true if
they would print anything, and @code{insert}, in which they are
supposed to actually print something, if appropriate, using the
function @code{insert}.

For MUC, the functions in @code{jabber-muc-printers} are prepended to
those in @code{jabber-chat-printers}.

Body printers are a subgroup of chat printers.  They are exclusive; only
one of them applies to any given message.  The idea is that
``higher-quality'' parts of the message override pieces included for
backwards compatibility.  Included are @code{jabber-muc-print-invite}
and @code{jabber-chat-normal-body}; functions for XHTML-IM and PGP
encrypted messages may be written in the future.  The functions in
@code{jabber-body-printers} are called in order until one of them
returns non-nil.

@node Stanza chains,  , Chat printers, Hacking and extending
@section Stanza chains

@vindex jabber-message-chain
@vindex jabber-iq-chain
@vindex jabber-presence-chain

If you really need to get under the skin of jabber.el, you can add
functions to the lists @code{jabber-message-chain},
@code{jabber-iq-chain} and @code{jabber-presence-chain}.  The
functions in these lists will be called in order when an XML stanza of
the corresponding type arrives, with the connection object and the
entire XML stanza passed as arguments.  Earlier functions can modify
the stanza to change the behaviour of downstream functions, but
remember: with great power comes great responsibility.

@node Protocol support, Concept index, Hacking and extending, Top
@appendix Protocol support

@cindex Supported protocols

These are the protocols currently supported (in full or partially) by
jabber.el.

@menu
* RFC 3920::                    XMPP-CORE
* RFC 3921::                    XMPP-IM
* XEP-0004::                    Data Forms
* XEP-0012::                    Last Activity
* XEP-0020::                    Feature Negotiation
* XEP-0022::                    Message Events
* XEP-0030::                    Service Discovery
* XEP-0045::                    Multi-User Chat
* XEP-0049::                    Private XML Storage
* XEP-0050::                    Ad-Hoc Commands
* XEP-0054::                    vcard-temp
* XEP-0055::                    Jabber Search
* XEP-0065::                    SOCKS5 Bytestreams
* XEP-0066::                    Out of Band Data
* XEP-0068::                    Field Standardization for Data Forms
* XEP-0077::                    In-Band Registration
* XEP-0078::                    Non-SASL Authentication
* XEP-0082::                    Jabber Date and Time Profiles
* XEP-0085::                    Chat State Notifications
* XEP-0086::                    Error Condition Mappings
* XEP-0090::                    Entity Time
* XEP-0091::                    Delayed Delivery
* XEP-0092::                    Software Version
* XEP-0095::                    Stream Initiation
* XEP-0096::                    File Transfer
* XEP-0146::                    Remote Controlling Clients
* XEP-0153::                    vCard-Based Avatars
* XEP-0199::                    XMPP Ping
* XEP-0245::                    The /me Command
@end menu

@node RFC 3920, RFC 3921, , Protocol support
@section RFC 3920 (XMPP-CORE)

Most of RFC 3920 is supported, with the following exceptions.

SASL is supported only when an external SASL library from FLIM or Gnus
is present.  As SASL is an essential part to XMPP, jabber.el will send
pre-XMPP stream headers if it is not available.

None of the stringprep profiles are implemented.  jabber.el changes
JIDs to lowercase internally; that's all.

jabber.el doesn't interpret namespace prefixes.

The @code{xml:lang} attribute is neither interpreted nor generated.

SRV records are used if a modern version of @code{dns.el} is installed.

@node RFC 3921, XEP-0004, RFC 3920, Protocol support
@section RFC 3921 (XMPP-IM)

Most of RFC 3921 is supported, with the following exceptions.

Messages of type ``headline'' are not treated in any special way.

The @code{<thread/>} element is not used or generated.

Sending ``directed presence'' is supported; however, presence stanzas
received from contacts not in roster are ignored.

Privacy lists are not supported at all.

jabber.el doesn't support XMPP-E2E or ``im:'' CPIM URIs.

@node XEP-0004, XEP-0012, RFC 3921, Protocol support
@section XEP-0004 (Data Forms)

XEP-0004 support is good enough for many purposes.  Limitations are
the following.

Forms in incoming messages are not interpreted.  See each specific
protocol for whether forms are accepted in that context.

``Cancel'' messages are probably not consistently generated when they
should be.  This is partly a paradigm clash, as jabber.el doesn't use
modal dialog boxes but buffers which can easily be buried.

@code{<required/>} elements are not enforced.

The field types ``jid-single'', ``jid-multi'' and ``list-multi'' are
not implemented, due to programmer laziness.  Let us know if you need
them.

@node XEP-0012, XEP-0020, XEP-0004, Protocol support
@section XEP-0012 (Last Activity)

jabber.el can generate all three query types described in the protocol.
However, it does not answer to such requests.

@node XEP-0020, XEP-0022, XEP-0012, Protocol support
@section XEP-0020 (Feature Negotiation)

There are no known limitations or bugs in XEP-0020 support.

@node XEP-0022, XEP-0030, XEP-0020, Protocol support
@section XEP-0022 (Message Events)

jabber.el understands all four specified kinds of message events
(offline, delivered, displayed, and composing) and by default requests
all of them.  It also reports those three events that make sense for
clients.

@node XEP-0030, XEP-0045, XEP-0022, Protocol support
@section XEP-0030 (Service Discovery)

Service discovery is supported, both as client and server.  When used in
the code, service discovery results are cached indefinitely.

@node XEP-0045, XEP-0049, XEP-0030, Protocol support
@section XEP-0045 (Multi-User Chat)

jabber.el supports parts of XEP-0045.  Entering, leaving and chatting
work.  So do invitations and private messages.  Room configuration is
supported.  Changing roles of participants (basic moderation) is
implemented, as is changing affiliations, but requesting affiliation
lists is not yet supported.

@node XEP-0049, XEP-0050, XEP-0045, Protocol support
@section XEP-0049 (Private XML Storage)

jabber.el contains an implementation of XEP-0049; It is used
for bookmarks and roster's groups roll state saving.

@node XEP-0050, XEP-0054, XEP-0049, Protocol support
@section XEP-0050 (Ad-Hoc Commands)

jabber.el is probably the first implementation of XEP-0050 (see
@uref{http://article.gmane.org/gmane.network.jabber.devel/21413, post
on jdev from 2004-03-10}).  Both the client and server parts are
supported.

@node XEP-0054, XEP-0055, XEP-0050, Protocol support
@section XEP-0054 (vcard-temp)

Both displaying other users' vCards and editing your own vCard are
supported.  The implementation tries to follow the schema in the XEP
accurately.

@node XEP-0055, XEP-0065, XEP-0054, Protocol support
@section XEP-0055 (Jabber Search)

XEP-0055 is supported, both with traditional fields and with Data Forms
(@pxref{XEP-0004}).  As the traditional fields specified by the XEP is a
subset of those allowed in XEP-0077, handling of those two form types
are merged.  @xref{XEP-0077}.

@node XEP-0065, XEP-0066, XEP-0055, Protocol support
@section XEP-0065 (SOCKS5 Bytestreams)

XEP-0065 is supported.  Currently jabber.el cannot act as a server, not
even on on Emacsen that support server sockets (GNU Emacs 22 and up).
Therefore it relies on proxies.  Proxies have to be entered and queried
manually.

Psi's ``fast mode''
(@uref{http://delta.affinix.com/specs/stream.html}), which gives
greater flexibility with regards to NAT, is not implemented.

@node XEP-0066, XEP-0068, XEP-0065, Protocol support
@section XEP-0066 (Out of Band Data)

jabber.el will display URLs sent in message stanzas qualified by
the @code{jabber:x:oob} namespace, as described in this XEP.  Sending
such URLs or doing anything with iq stanzas (using the
@code{jabber:iq:oob} namespace) is not supported.

@node XEP-0068, XEP-0077, XEP-0066, Protocol support
@section XEP-0068 (Field Standardization for Data Forms)

XEP-0068 is only used in the context of creating a new Jabber account,
to prefill the username field of the registration form.

@node XEP-0077, XEP-0078, XEP-0068, Protocol support
@section XEP-0077 (In-Band Registration)

In-band registration is supported for all purposes.  That means
registering a new Jabber account, changing Jabber password, removing a
Jabber account, registering with a service, and cancelling
registration to a service.  Data forms are supported as well.  URL
redirections are not.

jabber.el will not prevent or alert a user trying to change a password
over an unencrypted connection.

@node XEP-0078, XEP-0082, XEP-0077, Protocol support
@section XEP-0078 (Non-SASL Authentication)

Non-SASL authentication is supported, both plaintext and digest.
Digest is preferred, and a warning is displayed to the user if only
plaintext is available.

@node XEP-0082, XEP-0085, XEP-0078, Protocol support
@section XEP-0082 (Jabber Date and Time Profiles)

The DateTime profile of XEP-0082 is supported.  Currently this is only
used for file transfer.

@node XEP-0085, XEP-0086, XEP-0082, Protocol support
@section XEP-0085 (Chat State Notifications)

XEP-0085 is partially supported. Currently only active/composing
notifications are @emph{sent} though all five notifications are handled on
receipt.

@node XEP-0086, XEP-0090, XEP-0085, Protocol support
@section XEP-0086 (Error Condition Mappings)

Legacy errors are interpreted, but never generated.  XMPP style error
messages take precedence when errors are reported to the user.

@node XEP-0090, XEP-0091, XEP-0086, Protocol support
@section XEP-0090 (Entity Time)

jabber.el can query other entities for their time, and return the
current time to those who ask.

@node XEP-0091, XEP-0092, XEP-0090, Protocol support
@section XEP-0091 (Delayed Delivery)

The time specified on delayed incoming messages is interpreted, and
displayed in chat buffers instead of the current time.

@node XEP-0092, XEP-0095, XEP-0091, Protocol support
@section XEP-0092 (Software Version)

The user can request the version of any entity.  jabber.el answers
version requests to anyone, giving ``jabber.el'' as name, and the
Emacs version as OS.

@node XEP-0095, XEP-0096, XEP-0092, Protocol support
@section XEP-0095 (Stream Initiation)

XEP-0095 is supported, both incoming and outgoing, except that jabber.el
doesn't check service discovery results before sending a stream
initiation request.

@node XEP-0096, XEP-0146, XEP-0095, Protocol support
@section XEP-0096 (File Transfer)

Both sending and receiving files is supported.  If a suitable program is
found, MD5 hashes of outgoing files are calculated and sent.  However,
hashes of received files are not checked.  Ranged transfers are not
supported.  In-band bytestreams are not yet supported, even though
XEP-0096 requires them.

@node XEP-0146, XEP-0153, XEP-0096, Protocol support
@section XEP-0146 (Remote Controlling Clients)

The ``set-status'' command in XEP-0146 is supported.

@node XEP-0153, XEP-0199, XEP-0146, Protocol support
@section XEP-0153 (vCard-Based Avatars)

vCard-based avatars are supported, both publishing and displaying.  The
pixel size limits on avatars are not enforced.

@node XEP-0199, XEP-0245, XEP-0153, Protocol support
@section XEP-0199 (XMPP Ping)

XEP-0199 is fully supported.

@node XEP-0245, ,XEP-0199, Protocol support
@section XEP-0245 (/me Command)

XEP-0245 is partially supported (except XHTML-IM).

@node Concept index, Function index, Protocol support, Top
@unnumbered Concept index

@printindex cp

@node Function index, Variable index, Concept index, Top
@unnumbered Function index

@printindex fn

@node Variable index,  , Function index, Top
@unnumbered Variable index

@printindex vr

@bye

@ignore
   arch-tag: 995bf3da-0e87-4b15-895a-1e85fac139a2
@end ignore