File: README

package info (click to toggle)
centericq 4.20.0-1sarge5
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 8,712 kB
  • ctags: 11,687
  • sloc: cpp: 45,557; ansic: 39,745; sh: 17,325; makefile: 677; yacc: 316; perl: 235; sed: 16
file content (1821 lines) | stat: -rw-r--r-- 65,693 bytes parent folder | download | duplicates (3)
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
Centericq documentation by
Konstantin Klyagin <konst@konst.org.ua>
2001-2005

Contents
--------

1. Introduction
    1.1. Creation history
    1.2. Features overview
    1.3. Requirements
    1.4. First time start
2. IM accounts registration
    2.1. ICQ accounts
    2.2. Yahoo! accounts
    2.3. AIM accounts
    2.4. IRC accounts
	2.4.1. IRC channels
    2.5. Jabber accounts
	2.5.1. Jabber groupchat conferences
    2.6. LiveJournal
    2.7. Gadu-gadu
    2.8. MSN
    2.9. Updating details
3. User interface
    3.1. The ESC key
    3.2. The main screen
    3.3. Menus
    3.4. Dialogs
    3.5. Hotkeys in dialogs
    3.6. Some UI tips
4. Configuration
    4.1. Migrating from other ICQ software
    4.2. Event sounds
    4.3. Color schemes
    4.4. Key bindings
    4.5. URL open action (web browser support)
    4.6. Hostnames and port numbers (for crazy firewall admins)
	4.6.1. ICQ
	4.6.2. Yahoo!
	4.6.3. AIM TOC
	4.6.4. IRC
	4.6.5. Jabber
	4.6.6. LiveJournal
	4.6.7. Gadu-gadu
	4.6.8. MSN
    4.7. Binding to various IP addresses
5. Online status
    5.1. "Auto Away" and "Auto N/A"
6. Contact list
    6.1. Finding and adding users
	6.1.1. Some useful hints
	6.1.2. ICQ search specific modes
    6.2. Removing users
    6.3. Users' details
    6.4. Groups of contacts
7. Sending and receiving events
    7.1. Messages
    7.2. URLs
    7.3. SMSes
    7.4. Contacts
    7.5. Files
    7.6. E-mail express messages
    7.7. WebPager messages
    7.8. Away messages
    7.9. Events history
8. Ignore, visible and invisible lists
    8.1. Ignore list
    8.2. Visible list
    8.3. Invisible list
9. Advanced features
    9.1. Arabic and Hebrew languages support
    9.2. Command line facilities
	9.2.1. Sending events
	9.2.2. Changing current IM status
    9.3. External actions and auto-responses
	9.3.1. IM answering machine
	9.3.2. Elizatalk: making fun with your friends
	9.3.3. Remote control with external actions
	9.3.4. Forwarding events
	9.3.5. Hiding from scary ones
	9.3.6. "Manual" external actions
    9.4. Internal RSS reader
    9.5. Protocol debug mode
    9.6. "Friendly" logging
    9.7. Custom base directories
    9.8. Latest CVS snapshots
10. Lynx
    10.1. The program homepage
	10.1.1. Centericq mailing list
	10.1.2. German fan-club of the program :-)
    10.2. thekonst.net
    10.3. Other programs I write
    10.4. IM protocols
11. Help to the project I would appreciate
    11.1. Feedback
    11.2. Patches
    11.3. Promoting the little program
    11.4. Donations
	11.4.1. Money
	11.4.2. Hardware
	11.4.3. Other stuff


1. Introduction
---------------

  Centericq is a text mode menu- and window-driven IM interface. ICQ,
Yahoo!, AIM TOC, IRC, MSN, Gadu-Gadu and Jabber protocols are currently
supported. It allows you to send, receive, and forward messages, URLs,
SMSes and, contacts, mass message send, search for users (including extended
"whitepages search"), view users' details, maintain your contact list
directly from the program (including non-icq contacts), view the
messages history, register a new UIN and update your details, be
informed on receiving email messages, automatically set away after the
defined period of inactivity (on any console), and have your own ignore,
visible and invisible lists. It can also associate events with sounds,
has support for Hebrew and Arabic languages and allows to arrange
contacts into groups. There is also an internal RSS reader and even a
LiveJournal client!

  Centericq is known to build and work well under Linux, FreeBSD,
OpenBSD, NetBSD, Sun Solaris, MacOS X/Darwin and Microsoft
Windows (built with cygwin).


1.1. Creation history
---------------------

  This program was written because of a very simple cause. I just
couldn't find any console based ICQ clients with really useful user
interface. When I started it I had quite a slow computer at home. Having
X window running on it took incredibly a lot of resources making whole
the system really slow. I didn't like an idea of launching it just to be
on ICQ, but there were several good programs only for X. For console
they had only mICQ and zicq. The former was ok, but its interface made
me cry. I know, it's of quite a UNIX style, and I don't have anything
against command line, but typing nicks and uins all the time was
terrible. The second thingie, zicq, was an attempt to implement menus
and windows for ICQ in text-mode, but its author couldn't go further
than just splitting the screen into two windows, one with contact list
and another with usual mICQ output :) Actually it was all based on mICQ
code. I don't wanna say mICQ was bad, for it was the first ICQ client
for Linux, and its author made a great job exploring and sniffing the
protocol.

  After looking at freshmeat and some "icq for linux" pages the hope to
find something worth was finally lost. I decided to put some effort into
making a program which would be really useful for me. It took me about
two weeks to write and then 1 week to test before releasing the first
version.

  Since that time the software suffered a lot of changes, including
rewrite resulted into the version 3.0.0, and then adding more IM protocols
since 4.1.0. Now I'm continuing to develop it, going the standard way of
adding new features and fixing bugs. And feedback from users helps me a
lot in it.


1.2. Features overview
----------------------

  Centericq's ICQ module has almost all the functionality including
extended issues that Mirabilis client has. Speaking of other protocols,
it has quite full support for features of Yahoo!, AIM, IRC and
Jabber.

  Beside simple things like sending and receiving messages, changing
online status and basic user information, centericq advanced features
such as "White pages" and keyword search, an ability to update almost
all the fields in user's details, send URLs and SMSes, etc. I hope you
enjoy it a lot :)


1.3. Requirements
-----------------

In order to build the software the following libraries are required:

ncurses (at least 4.2 version)
    A CRT screen handling and optimization package.
	http://dickey.his.com/ncurses/ncurses.html

openssl
    The secure communications library. Optional, but you will require
    if you want SSL support for Jabber. Previous versions of the library
    called SSLeay will work with centericq too.
	http://www.openssl.org/

gnutls
    The secure communications library. Optional. An alternative to
    OpenSSL distributed under the GNU Public License.
	http://www.gnutls.org/

gpgme
    This is for PGP support in Jabber. Optional also.
	http://www.gnupg.org/(en)/download/index.html#gpgme

Please note that in order to compile centericq from source on Redhat
based systems you should have *-devel RPM packages of the above
mentioned libraries installed.

It's possible to disable support of various protocols during the build
phase. Just take a look at the --disable-xxx parameters for configure.
You can invoke the scripts command line help with the following command:

$ ./configure --help


1.4. First time start
---------------------

  Upon the first execution, the program shows its configuration screen
and then gets to the next stage, the account manager dialog. All the
configuration dialog items are self-descriptive, so there must be no
problems to customize your centericq. As soon as you're finished with
it, using the right allow key, move cursor to the "Done" button and
press Enter.

  Russian speaking users should pay attention to the "Russian
translation" item of the registration dialog. It's vital to set its
value to "yes" to be able to use cyrillic. In most cases. Unless you use
win1251 as a default charset, about what I doubt a lot :) Unfortunatelly
we have two different encodings for our language, koi8-r is default for
UNIX like systems and win1251 is used in Windows. Since ICQ comes from
Windows we need to recode every sent and received message in order for
it to be readable.


2. IM accounts registration
---------------------------

  This section says a bit about registering new and entering existing
accounts' details into configuration of your centericq. Everything that
centericq can do about it is available through the "Accounts" dialog
displayed at the start and then residing under the f4->Accounts.. menu
item.


2.1. ICQ accounts
-----------------

  To be able to use the ICQ IM service you should have a UIN (I think it
stands for something like "user identification number"). You can either
use an already existing UIN or register a new one selecting appropriate
items in the "Account manager" dialog. Some attention should only be
paid to the "server address" field. The default value will be
substituted unless something is set there, i.e. empty "server" field is
quite ok. In the majority of cases you do not need to change it. The
only exception is if you have your own ICQ server on LAN.


2.2. Yahoo! accounts
--------------------

  Centericq doesn't support registring new Yahoo! ID's, so if you don't
have one yet, just visit the homepage Yahoo! messenger at
http://messenger.yahoo.com/ and select the "Acct info" link in the top
right corner.


2.3. AIM accounts
-----------------

  AIM accounts can be created with the AOL's web interface at
http://my.screenname.aol.com/ by clicking on the "Get a Screen Name"
link. Don't also forget to set your profile information with "Update
your details" item in the Account manager dialog.


2.4. IRC accounts
-----------------

  This service is completely different from others supported by
centericq. You don't need to register to connect to irc. All you need is
just choose a nick which is not used by anyone else. Otherwise it'll be
reported as soon as you try to login. So set any nick and a host name of
the server you want to chat on, and go ahead!

  For the advanced IRC users there can be a need for so-called NickServ
authentification using a password to identify himself. Sometimes it's
used to protect your nickname from overtaking on a specific IRC network.
Centericq does support this too, providing a non-obligatory password
field.


2.4.1. IRC channels
-------------------

  IRC channels behave theirselves like usual contacts, though the set of
actions possible to perform upon them is different. Using the F2-menu
and hotkeys it's possible to join or leave a channel, view the list of
users, etc. Please note, in order to stay on a channel you should have
it on your contact list. As soon as a channel is deleted, you leave it
automatically.


2.5. Jabber accounts
--------------------

  Jabber is the most advanced open source and free instant messaging
solution. Since the version 4.8.8 it's been supported by centericq. Due
to its being open and developed by the wide community, centericq can
register new nicknames in it very easily.


2.5.1. Jabber groupchat conferences
-----------------------------------

   Like IRC channels, they're controlled like usual contacts, too.


2.6. LiveJournal
----------------

  Though LiveJournal is not actually an IM service, but I hope you
forgive me for that. LiveJournal is a weblogs community. Its URL is
http://www.livejournal.com/. Centericq makes use of their open source
and well-documented client-server protocol, and makes it possible to
post items and read friends' RSS feeds directly from its interface. So
if you want an account, go to http://www.livejournal.com/ and see how to
get it. If you don't like the rules, you can always download their
server software and install it on your own. Long live open source!


2.7. Gadu-gadu
--------------

  If you have libjpeg installed in your system and the configure script
does find it, centericq can register a UIN on this network for you.
Otherwise you can only register one with the official client that can be
downloaded from the official site at http://www.gadu-gadu.pl/


2.8. MSN
--------

  An account for MSN can also be registered through a web interface at
http://chat.msn.com/ though it seems that they block access from Linux
based web browsers.


2.9. Updating details
---------------------

  If you have just registered on the ICQ network only basic fields of
your details were set. Now, if you want to provide the world with more
information about yourself, you should invoke the "Update ICQ details"
dialog. First go to the "Accounts" dialog which can be accessed through
the global menu, and there in the ICQ node select "Update user details".
You can fill in information that will be visible to other ICQ users.
They also will be able to find you with specifying what you filled in
their "find users" requests.

  It's possible to update your ICQ and AIM details any time you're
online with the dialog. Details within other networks are possible to be
updated with respective web interfaces, I believe.


3. User interface
-----------------

  The text UI centericq has, as well as UI of other programs for console
I have written, is very simple. There are menus, windows, menus and
input lines. In the bottom line of the screen there is a status bar. It
usually contains hints about what to press to invoke various menus,
dialogs, and perform various actions.


3.1. The ESC key
----------------

  This key is used for termination of input, if you wanna cancel the
operation you wanted to perform. Say, if "send message" operation is
chosen (invoked just with a press of "Enter" on a contact), an editor
window appears. As status bar says, you can use "Ctrl-X" to send it, and
ESC to cancel. The only hint is that you have to press the ESC key
twice. It's a common practice for console based UNIX programs (Midnight
commander is a good example), because checking for only one ESC would
spoil arrow key processing. The point is that they have correspond
sequences that start with an ASCII#27 character which is actually ESC.

  If you still want to press a simple key combination to close a dialog
or cancel something, try Alt-ESC. Though it's not guaranteed to work on
all terminals.

  The ESC key can also help you to issue shortcuts and key combinations
such as Alt-? or F<x>. The former, if Alt-Shift-/ doesn't work can be
produced by first pressing ESC and then Shift-/ (i.e. "?"). And instead
of any F-key the ESC and then a number can be used.


3.2. The main screen
--------------------

  The main screen of centericq consists of three parts. First is contact
list which is situated to the left. Next is information window which is
used to show received events, users' details, and also to edit events
that are going to be sent. And the smallest one is a log window in which
you can see messages about what centericq is doing right now.


3.3. Menus
----------

  No need to say, menus are a common way to provide a user with an
ability to select one (or several) items from a certain list. To make a
difference between single and multiple choice menu you gotta just have a
look at the items. If square brackets stand next to items text in every
line, a multiple selection is requested. Otherwise you can only select
one item. To do it, just press "Enter" on it. To make a mutiple
selection, press "Space" on items and use "Enter" to finish the
selection. ESC does also work in all menus to cancel the selection.

  I will mention two menus below. They are global menu and contact
context menu, invoked with F4 and F2 correspondingly. The former allows
to execute various actions of global kind, such as find and add users,
manage ignore, visible and invisible lists, change settings, etc. With
the context menu you can do various current contact specific things.


3.4. Dialogs
------------

  Every dialog in centericq has a tree-like view. When I was about to
write classes for form-based input, I remembered that there was a
"treeview" class written by me before. So, I decided to use it for
dialogs and was right. There was no need to re-design the whole form in
case I need to add some controls, or so. I just add it as a node or a
leaf it scrolls, and nothing gets spoiled. Everything really nice is
always simple :)


3.5. Hotkeys in dialogs
-----------------------

  Dialogs of centericq usually have a bar with buttons. To access a
button without moving the highlighted bar over it with the arrow keys
you can use shortcuts. It's enough to press the first capital letter of
a button name to access the function behind it.


3.6. Some UI tips
-----------------

  There at some quite standard key combinations supported by centericq I
wanna tell you about. Here they go.

    Ctrl-L
      Redraws the screen in any place of program execution. If output of    
    some kind of background programs or system messages spoil your screen
    just press it so centericq display is refreshed.

    Ctrl-Y
      In a message writing mode removes entire current line.

    Ctrl-K
      Single line edit mode.
      Kills entire content.

    Ctrl-U
      Single line edit mode.
      Kills a part of line to the left from cursor.

    Alt-H
      Single line edit mode.
      Invokes history of recently entered lines.


4. Configuration
----------------

  The majority of centericq settings can be found in the "Configuration"
dialog which can be invoked by selecting an appropriate items in the
global menu (the one you see on pressing F4). There are only three
things you should setup from outside the program with modifying the
program's configuration files. They are event sounds, actions (see
below) and color schemes.

  With the "Configuration" dialog you can turn on and off various
features, as well as change the ICQ server address and adjust network
settings. All the items there are self-explanatory and their meaning is
quite obvious. I suppose the program users are usually not dumb :) so I
won't cover all of the items here in the documentation.


4.1. Migrating from other ICQ software
--------------------------------------

  If you decided to migrate to centericq from another ICQ software or
have a need to you something else in parallel, there is a way to convert
the contact list. This means you can migrate without loosing your
contacts and history.

  How to do it? There is a perl script named cicqconv. It's usually
installed on "make install" under @prefix@/bin (/usr/local/bin in the
majority of cases). Its usage is very simple. You should only pass one
parameter to it, telling from what kind of ICQ software it's to convert
your data. To see the list of supported software, run the script without
parameters.


4.2. Event sounds
-----------------

  As it was said before, centericq can play sounds on various events.
It's done the following way. Upon, say, receiving a message, centericq
executes an external command. Actually it can be whatever you want, but
original idea is to execute a command line WAV player.

  There are three WAV sound files which centericq has by default. They
are sounds taken from Mirabilis ICQ. When you set "Change sound device
to" item to "sound card", the program generates a file named sounds in
the .centericq/ directory in your home folder. The default file has
commands to execute a "play" utility (from sox package) with a name of a
file to play, one of the default ones. If you wanna change the player or
a sound simply edit ~/.centericq/sounds.

  If you use ESD (Enlightenment Sound Daemon) to have some extra sound
facilities such as mixing streams, or playing on another computer, you
might wish to change the "play" command to "esdplay".


4.3. Color schemes
------------------

  It's possible to customise colors in the centericq's user interface.
It's done with the ~/.centericq/colorscheme configuration file. Its
contents are self-descriptive, and parameter names mean exactly that
they're named after. Please note, that among the standard color names
it's possible to specify "transparent" which is useful when the program
is used in terminals with background images set.

  Started for the first time, centericq creates the default colorscheme
file filled in with settings of one of default schemes that the
Configuration dialog proposes. Also its contents are re-written every
time you change color scheme from the dialog.

  To define your own color scheme, feel free to modify the default
colors configuration file or choose one of contributed ones that can be
found under the contrib/ directory of the source tarball.

  More "visual" explanation can be found here at the centericq.de:
http://centericq.de/misc/colorscheme_helper.png


4.4. Key bindings
-----------------

  Key bindings are also configurable in centericq. On the first start it
creates a file called keybindings in your ~/.centericq/ directory. You can
use its initial contents for reference. If you want to change something,
well, it's all there.


4.5. URL open action (web browser support)
------------------------------------------

  Centericq can extract URLs from messages and user information records
for you. And it also can launch your preferred web browser to view them.
No need to have a big attention to notice "F2 to URLs" text in the
status bar when you view either a message or user's details. The "open
URL" action starts right after you make a selection in the menu invoked.
The ~/.centericq/actions file is responsible for this. By default it has
a command to execute netscape, but you can change to whatever you want.
Please only note that you cannot put lynx or any other text mode based
browser starting in the same console there. The commands from "actions"
run in parallel with centericq, so please only pass your URLs to scripts
or to X based browsers, but to nothing interactive.

  Though, if you're using centericq under screen(1) there is a solution.
Jochen Sprickerhof <jochen.sprickerhof@web.de> advised it having read
the statement in the previous paragraph. He proposes to define open url
action the following way: "openurl screen lynx $url$", in order to open
lynx in a new screen window as soon as an URL to browse it chosen.


4.6. Hostnames and port numbers (for crazy firewall admins)
-----------------------------------------------------------

  I'm frequently asked what ports and hostnames centericq uses to
connect to various IM services. To avoid further buzz, I just include
them here.


4.6.1. ICQ
----------

  Hostname: login.icq.com
  Port: 5190

  Here a small note is needed. To a great displeasure of network admins,
the ICQ main server listens on all the TCP ports, from 1 to 65535. So
if in your network the 5190 is blocked, don't be upset, set it to 80 or
to 21 or whatever is not restricted by firewall and it will work :)


4.6.2. Yahoo!
-------------

  Hostname: scs.msg.yahoo.com
  Port: 5050


4.6.3. AIM TOC
--------------

  Hostname: toc.oscar.aol.com
  Port: 9898


4.6.4. IRC
----------

  For this network you gotta choose a server yourself, because the
auditory of people you chat with and other things depend exactly on this
choice. However, by default, centericq sets the following parameters:

  Hostname: irc.freenode.net
  Port: 6667


4.6.5. Jabber
-------------

  There are many Jabber servers in the world, also the solution is
widely used for in-house communications inside various companies, so you
can choose the server yourself. At the other hand, the default server
open to the public is the following:

  Hostname: jabber.com
  Port: 5222


4.6.6. LiveJournal
------------------

  Since LiveJournal, despite of its being not an IM network, is also a
completely open source and free (in the "free speech" sense) solution,
you can find LiveJournal servers installed anywhere. You can even
install one on your own. Just in case, here I'm giving you parameters of
their main server:

  Hostname: livejournal.com
  Port: 80


4.6.7. Gadu-gadu
----------------

  Hostname: appmsg.gadu-gadu.pl
  Port: 80


4.6.8. MSN
----------

  Hostname: messenger.hotmail.com
  Port: 1863


4.7. Binding to various IP addresses
------------------------------------

  If the box you're running centericq on has several IPs and you would
like to use a certain one of them for IM connections, there is a command
line parameter made especially for you, --bind <IP address> or shortly,
-B <IP address>.


5. Online status
----------------

  With centericq you can be either on or off the ICQ network. The status
can be changed with the "Status" menu invoked either with F3 or "S" key
or from the global menu. It provides you with a choice to switch between
online statuses along with an ability to go offline. If one of online
statuses if selected when you're offline, centericq will connect and
switch the status to what was chosen.

  With an online status you can indicate to those who are in touch with
you your being away, occupied, free for chat, not available, etc.


5.1. "Auto Away" and "Auto N/A"
-------------------------------

  Also there is a way to switch status to Away and N/A (not available)
after a certain period of inactivity, to show your friends or colleagues
you're somewhere away from computer.

  The very useful thing about is that centericq detects inactivity for
all the consoles if you use it locally. So it won't change your status
if you're just working in another console and only don't tweak it.

  The auto periods can be changed with the "Configuration" dialog. Zero
value means the feature is off.


6. Contact list
---------------

  The list of your contacts is displayed to the left on the centericq
main screen, and has a tree-like structure. There are "Online" and,
unless the "Hide offline users" options is on, "Offline" nodes, groups
(if switched on). If a user has a birthday today, a smiley face ":)" is
shown next to his or her nickname.

  If a contact is online, a status letter in square brackets is shown
for him. Though, the brackets kind can vary. Besides the square ones,
there can be {x} and <x> items. The former means a contact is on your
invisible list, and the latter represents your "always visible" status
for a contact.

  Finally, if there is an unfinished (postponed) message for a certain
contact, the ">" character will appear between status and nickname.


6.1. Finding and adding users
-----------------------------

  The most common way to add an IM contact to your list is to use the
"find/add user(s)" dialog invoked from the global menu. First you have
to find the contact you wanna add. Centericq allows you to search for
users with various parameters in various networks.

  In ICQ, you can add a user knowing his UIN, or see a list of people
matching your criterias. In fact, ICQ server sends only first 40 matching
UINs, but usually it's quite enough.

  Note that in ICQ search requests you can use simple wildcards in the
text input fields. It's possible to put "*" there. For example, you don't
remember my last name exactly, but know only several first letters. Then
just type in a first name ("Konstantin") and fill in the "last name" field
with "Klyag*". The same trick can be done with other fields: "city",
"nickname", "company", etc..

  The Yahoo!, AIM, IRC and Jabber networks support in centericq
does only allow to add users by nicknames.

  With IRC it's possible to get users from channels. For more info on
channels and other IRC related stuff, please refer to http://www.irc.org/.
So, with centericq you can either fetch a list of users for a specified
channel, or (sic!) find users that stay on several channels simultaneously.
To perform the latter, just put several channel names separated with spaces.
For example, the "#centericq #linux" query will show a list of users that
are currently talking on both channels.


6.1.1. Some useful hints
------------------------

  You can skip the finding step by issuing one of the following shell
commands to add a user (depends on an IM type):

    $ mkdir ~/.centericq/<UIN of a user to add>
	This one is for ICQ

    $ mkdir ~/.centericq/y<nickname>
	For Yahoo!

    $ mkdir ~/.centericq/a<nickname>
	For AIM

    $ mkdir ~/.centericq/i<nickname>
	For IRC

    $ mkdir ~/.centericq/j<nickname>
	For Jabber

Don't forget to restart centericq so that it re-reads the contact list.
Though, it's better anyway to follow the usual find/add procedure.

  Another intresting ICQ related trick I wanna share with you. Because of
a natural couriousity, sometimes names of people get me intrested in finding
out about their ethnical origin. Once I saw a last name, Aslam, which seemed
like a muslim one, but I had no idea which country the guy originated
from. I decided to use ICQ to find out. Opened the "find/add" dialog and
typed that in. After looking at several matched contacts I noticed the
majority of people were from Pakistan, so I realized where the guy was
from and my couriosity was satisfied.

  I go the same way to find out in which country a certain city is
located, and so on. This makes ICQ extremely useful for me. Just use
your imagination to find other ways to use such a great statistics
database :)


6.1.2. ICQ search specific modes
--------------------------------

  The "find/add users" dialog for ICQ besides the obvious parameters
does also contain two interesting items such as "Random chat group" and
"Keywords". With the help of the former you can easily look for chat
partners from standard 10 groups, if you're bored or just feel like
chatting with someone. You never know who can be there. Also, you can
make yourself available for others so that they can find you in random
chat groups. Just set the corresponding parameter in the "Update your
details" dialog for ICQ.

  The keyword search feature allows to search for contacts by specified
keywords that are taken from interests, geographical location and other
places, and indexed somehow by the Mirabilis guys. Quite an interesting
feature too.


6.2. Removing users
-------------------

  Removing users is a very simple procedure. You can either hit DEL on a
certain contact or select an appropriate item in the context menu. After
confirmation the contact is removed.


6.3. Users' details
-------------------

  On the ICQ network, every user has a set of details that can be
browsed and used in search queries by others. To browse details of a
specific user on the contact list it's enough just to press '?' on a
corresponding to a contact item.

  Please don't hesistate to do it before asking people who they are. It
takes time to explain, though it can be looked up so easily.


6.4. Groups of contacts
-----------------------

  In case you have a lot of people on contact list, you might wish to be
able to visually arrange them into groups. Choose any criteria.
Geography, companies, activities, interests.. Anything. Centericq
supports it.

  To turn the feature on invoke the configuration dialog and switch the
"arrange contacts into groups" option value to "yes". By default, all of
your contacts will appear on standard "Global" group from which you can
move them to other groups creating them "on fly". There is an item in
the context menu named "Move to group.." which allows you to do it.

  It's also possible to collapse and expand groups by pressing the Enter
key on them.

  Remove, add and rename operations on groups can be done with the group
manager dialog invoked from the global menu item named "Organize contact
groups".


7. Sending and receiving events
-------------------------------

  Sending and receiving events is what ICQ and all the instant messaging
are all about. The concept itself means an ability to stay in touch by
delivering messages of various kind immediately.


7.1. Messages
-------------

  The most common type of events. It takes the ICQ network about one
second to deliver one. Messages can be sent either through server or
directly through a TCP link. Size of a message sent through server
cannot exceed 450 characters, while size of direct messages is
unlimited. In case centericq cannot establish a direct link or you have
the "sent all events through server" option enabled, a message is
automatically split into several parts.

  To send a message just press "Enter" on a contact. Then type and press
"Ctrl-X" to send it. To cancel the message press ESC (twice).


7.2. URLs
---------

  Though you can send URLs with regular messages the Mirabilis guys
decided to make a separate event for it. No problem, centericq supports
URL events. An URL message consists of two parts, they're an URL itself
and a description. Well, nothing else to say about it. Except maybe a
wish for future version of the protocol to support e-mail addresses and
host names as separate events :)


7.3. SMSes
----------

  ICQ has a server-side mechanism which allows its users to send and
receive short text messages to cellular phones. There is an item visible
in the context menu for ICQ contacts, named "Send an SMS" which is be
choosen. Then if a user does not have any cellular number on his
details, centericq will ask you to provide one. This number can be
changed any time with the "Edit details" item of the same menu.

  Centericq allows sending SMS messages to contacts of any kind on your
list with the only restriction that they will only be sent as soon as
you log in with your ICQ account. When you type in a phone number don't
forget to include all the international and regional prefixes.

  If an SMS you sent is rejected, the appropriate message is displayed
in the log window. This usually happens because ICQ does not support some
cellular networks. To see the list of supported ones use the following
links:

    http://www.icq.com/sms/smsnetworks.html
    http://www.icq.com/sms/eg_networks.html

  Both ways of sending SMSes are supported by libicq2000, and this means
centericq does so too.


7.4. Contacts
-------------

  Sharing parts of your contact list with other users on the instant
messaging network is a feature supported only by ICQ so far. Centericq
does support it, thus you can easily send contacts from your contact
list or receive contacts from someone else using the program's
interface. Much easier than typing or cut'n'pasting UINs.


7.5. Files
----------

  It's only possible to send files to your remote buddies within the IRC
network so far. In order to do it, it's enough to choose the "Send
file(s)" item from the context menu (the one ivoked with F2), and point
out the files you want to send. In order to receive files you should
press the "Accept" button in the dialog you'll see as soon as someone
sends a file to you.


7.6. E-mail express messages
----------------------------

  This kind of events is ICQ specific. There is no way to receive them
with Yahoo! or other protocols. E-mail express is a service
provided by Mirabilis to make it possible to send messages through
e-mail to logged in ICQ users. A gate, indeed.

  The principle is simple. To send such a message you use an e-mail
client application, and you receive one with an ICQ client. The
destination e-mail address looks like this <UIN>@pager.icq.com, where
UIN is the receiver's ICQ number. If a person is not online, they'll get
the message as soon as connect to the ICQ network.

  Please also note that with some SMTPs it won't work, since the pager
server has a protection which tries to make a connection to the sender
SMTP. If it's behind a firewall you have no chance to get your message
delivered.


7.7. WebPager messages
----------------------

  ICQ network does also allow sending messages to icq clients from their
web sites. The so-called "Web panel" makes it possible. You can access
your own by the URL of the following look: http://web.icq.com/wwp?Uin=<UIN>

  Messages are delivered to the contact list immediately. And if a user
is not online he's supposed to received them as soon as he logs in.


7.8. Away messages
------------------

  Another feature of IM networks supported by centericq is away
messages. It's quite a useful way to explain to everybody why you're
away from your box right now. To read your reason for being away they
just have to use the feature to fetch an away message in their ICQ
client application.

  It's possible to set such a message from the account manager dialog
invoked from the global menu. There is a "Set away message" item for IM
engines that support such a feature.

  With centericq you can also read away messages of others. To fetch
someone's away message (it's possible even when a person has the
"available/online" status) just select the respective item in the
"current user" context menu (invoked with F2 or "m"). It's impossible to
fetch away messages of users that are offline.


7.9. Events history
-------------------

  All of events sent and received with centericq are held in its
database. It's very simple to access history of events you exchanged
with a particular user. You should only select the "Events history" item
of the context menu. Then, if at least one event is there, you'll be
shown a list every item of which can be read, replied or forwarded to
someone.


8. Ignore, visible and invisible lists
--------------------------------------

  ICQ provides an easy way to have lists of users you want to be visible
or invisible to, if you're online. Also there is a place to move all the
annoying ones so that they don't disturb you with their stupid messages.

  Modification operation with the lists can be performed with
appropriate dialogs invoked from the global menu.


8.1. Ignore list
----------------

  List for worst ones. If you find someone on (or outside) your contact
list too annoying, you can just add him or her to the ignore list. After
this simple operation you will never receive events from this user,
until the contact is removed from this list of yours.


8.2. Visible list
-----------------

  ICQ has the "invisible" option among its online status modes. When you
switch to it, noone is able to see your online presence. But there can
be a handful of people you would like to keep in touch, and you also
feel like remaining visible for them. That's what this feature is all
about.


8.3. Invisible list
-------------------

  Invisible list has an opposite aim to the previous one. People who you
have on this list are unable to see your presence all the time. Either
you're online or offline, or occupied.. whatever, they see your status
as "offline".


9. Advanced features
--------------------

  Centericq has some advanced features that you may need, though they're
not so easy to turn on for novice users. In this chapter I explain how
to do it.


9.1. Arabic and Hebrew languages support
----------------------------------------

  There is a basic support for bidirectional languages in centericq. It
allows not to type, but only read messages in Hebrew and Arabic. It's
possible to enable only on the ./configure stage, because the program
needs to be linked against FriBiDi library. This means first you need to
have the latter installed. The library homepage is located at
    http://fribidi.sourceforge.net/

  Once you have successfully installed FriBiDi, you need to execute
centericq's ./configure script with "--with-fribidi" parameter. If it
fails to find the library (you'll be reported), try
"--with-fribidi=<prefix the library was installed with>".

  Common "make" and "make install" steps should follow, and finally
"shalom" or "selam" can be seen well on your monitor :) So don't fight
there, guys.


9.2. Command line facilities
----------------------------

  Centericq has a bunch of command line options that make it possible to
queue IM events and change your status in various IM networks.


9.2.1. Sending events
---------------------

  In fact, it's not really sending. Centericq just allows you to put an
event to the outgoing queue from another process with command line
options. To have the event sent immediately centericq must be running,
otherwise all of your queued events will be sent as soon as the program
is launched and connected to the corresponding IM network.

  The following command line options are used to put an event to the
outgoing queue:

-s or --send <event type>

    This parameter specifies the type of event you want to send.
    Currently only "msg", "url" and "sms" are supported.

-p or --proto <protocol type>

    This one specifies to which IM network the destination contact
    belongs to. Can be either "icq", "yahoo", "aim", "irc", "jab"
    or "lj".

-t or --to

    With this one you specify nickname or UIN of the destination
    contact. For icq it's possible to specify 0 to send events to
    yourself. Only SMSes are known to be possible to be sent to oneself
    though.

-n or --number

    Using this parameter you can send SMSes to any mobile numbers
    through the ICQ network.

The message text is read from the standard input, so use pipes in shell
to pass it. For example, you can say "hi" to me through the ICQ network
with the following command:

    $ echo "hi" | centericq -s msg -p icq -t 17502151

In case you want to send an URL, the URL itself and its description are
separated with a newline character the following way:

    $ echo -e "http://thekonst.net/\nMy modest homepage." \
    | centericq -s url -p icq -t 17502151

Finally, a small example of sending SMSes:

    $ echo "sms test" | centericq -s sms -n 1234567890

Please note, that all three parameters are required in order to queue an
event.


9.2.2. Changing current IM status
---------------------------------

  Changing status is done with a pair of parameters. They're -S and -p.
The former is used to specify the status itself, and -p points which IM
engine is to be affected.

-S or --status <status letter>

    The argument parameter is a letter which indicates which status is
    to be set:

	o (Online)              _ (Offline)
	a (Away)                d (Don't disturb)
	n (N/A)                 c (Occupied)
	f (Free for chat)       i (Invisible)

-p or --protocol <protocol name>

    This one specifies to which IM network the destination contact
    belongs to. Can be either "icq", "yahoo", "aim", "msn", "irc",
    "jab" or "lj".

Examples:

    $ centericq -S _ -p icq

This will set the icq status to offline. In other words, it'll be
disconnected immediately.

    $ centericq -S a -p yahoo

And this command will switch your yahoo status to away.


9.3. External actions and auto-responses
----------------------------------------

  It is possible to make centericq run external programs, scripts and
whatever to answer and/or process incoming events. Though, some extra
setup is needed. Let me introduce you with another configuration file,
named "external" which should reside under the .centericq/ directory in
your home. Here is an example which demonstrates its options. It's
recommended just cut'n'paste the following text.


[ - $HOME/.centericq/external ---------------------------------------------- ]

#
# External actions
# ----------------
#
# Every section starts with a line containing the "%action <name>",
# "%pre-send <name>", "%pre-receive <name>" or "%manual <name>" text.
# Please note that the <name> of any kind is necessary. It musn't be
# empty. Inside it the following parameters can be used:
#
# event
# -----
# Can be "msg", "sms", "url", "online", "offline", "auth",
#	"contacts" or "notification".
#
# The latter means centericq's own notifications, such as birthday reminders,
# away messages, and other stuff. Specifying several event types is
# also allowed. "all" stands for all the event types.
#
# proto
# -----
# Can be "icq", "yahoo", "aim", "irc", "msn", "lj", "rss" or "jab". Or
# combination of these words. "all" can be used as a synonim for all of
# them.
#
# status
# ------
# Can be "online", "away", "dnd", "na", "occupied", "ffc" or "invisible".
# Specifying several ones is possible. "all" stands for all of possible
# status modes.
#
# options
# -------
# Possible options for an action are:
#
#       stdin           The incoming message text is to be passed to
#                       stdin of the script to be executed.
#
#       stdout          The script output is to be sent as a reply
#                       message (if not empty).
#
#       nowait          Don't wait for the script to finish. Obviously, the
#                       stdout option won't make sense if this one is used.
#
# Then, the section named "%exec" should follow. It contains a piece of
# script to be executed being copied to a file first.
#

%action         Simple auto-responder

event           msg
# Reacts only on events of message type ..

proto           icq yahoo
# .. only for icq and yahoo protocols

status          away na
# .. when we are in away or n/a status

options         stdin stdout
# .. the external commands text (below) reads the message from
# stdin, then its stdout output is sent as a response to a
# remote user.

%exec

msg=`cat`
echo "hello. this is auto-responder. your message was: $msg"


[ -------------------------------------------------------------------------- ]

With this simple external actions configuration file centericq will
perform a simple auto-respond action. You can have as many sections as
you need. You can call any kind of external scripts and programs. Please
note that the message text (when "stdin" option is specified for an
action) can be read with cat command or something similar.

Please also note it's possible to define actions that get invoked before
the event is written to the history (and delivered to the contact list)
as well as before it gets sent. Such kind of actions are defined with
the %pre-send and %pre-receive directives. Using them, an event can be
modified or even prevented from further processing, i.e. from showing on
the contact list or actual sending. The latter is done with returning a
non-zero return code in the %exec section.

Every time something is to be executed the "%exec" section's contents
are copied to a temporary file, and the latter is processed with the
default shell. But it doesn't mean those code parts are default shell
dependent. You can easily specify your favourite one with the first line
like this:

#!/usr/bin/perl

for example. Though, anyway this code piece's aim is just to perpare
arguments, perform initial checks, and then execute something for
further processing.

Another point to be explained is multiple actions with the same or
similar parameters (event, proto, and status). If an event matches
several actions, all of them are executed. If there is a need only in
one, you can always perform necessary checks in "%exec" so that only one
sends a reply.

Also, the script from the %exec section when executed has the following
environment variables imported by centericq:

EVENT_TYPE

    The type of the received event. Can be "msg", "sms", "url",
    "online", "offline", "auth", "contacts" or "notification".

EVENT_NETWORK

    The IM network name through which the event was received. Can be
    "icq", "yahoo", "aim", "irc", "msn", "lj" or "jab".

CONTACT_UIN

    If an event is received through ICQ equals to the other party's UIN.
    Otherwise empty.

CONTACT_NICK

    Set to other party's real nickname. Real means that even if you
    renamed the user in your contact list, this parameter will be equal
    to the original one, and not to what you set.

CONTACT_INFODIR

    The most intresting parameter. Using it, you can access further
    information about the user. Every time an external action is
    executed it is set to the user's information directory under your
    ~/.centericq/ directory. It makes it easier to access "about" and
    "info" files under it. Fetching lines from certain positions of the
    latter allows to get details. It's enough to take a look at an
    "info" file of any user to find out what lines mean. Here I'll
    describe the most useful ones:

    - the 2nd and 3rd lines contain user's first and last names 
	respectively;
    - the 4th one contains user's e-mail address;
    - the 7th has the home city;
    - the 8th is used for the home state name;
    - the 9th is used for the home phone number;
    - the user's home country resides in the 14th line;
    - etc;

To read a certain line from the info file I recommend to use the
following shell command: "head -n <N> $CONTACT_INFODIR/info | tail -n 1",
where N is the line number. Below the real examples go.

    fname=`head -n 2 $CONTACT_INFODIR/info | tail -n 1`
    # to fetch contact's first name

    lname=`head -n 3 $CONTACT_INFODIR/info | tail -n 1`
    # to fetch contact's last name

The example from the next section demonstrates usage of the environment
variables on an example of a simple answering machine :)


9.3.1. IM answering machine
---------------------------

  This simple setup will answer on incoming messages automatically when
you're away from your computer and your IM mode is set to Away or N/A.

[ - cut (centericq external actions setup for an IM answering machine) ----- ]

%action         Answering machine
event           msg
proto           all
status          away na
options         stdout

%exec
#!/bin/sh

fname=`head -n 2 $CONTACT_INFODIR/info | tail -n 1`
lname=`head -n 3 $CONTACT_INFODIR/info | tail -n 1`

cat <<EOF
Hello, $fname $lname!

Unfortunatelly, I'm not near my box now, but I'll certainly contact you
as soon as I get here.

--
me
EOF

[ -------------------------------------------------------------------------- ]


9.3.2. Elizatalk: making fun with your friends
----------------------------------------------

  One of the most intresting and funny uses for external actions in
centericq is auto-responding chat robots. So far I know only one which
is called Eliza. Unfortunatelly its doc covers only setup for licq, so
it'll describe how to make it work with centericq here. Actually, it's
not difficult thing to do at all.

  First, you'll have to download the elizatalk plugin itself. It's
homepage can be found at the following URL:

    http://elizatalk.sourceforge.net/

  Let's assume we want it to work with all the IM engines, answer on
messages only, and it's to be activated as soon as we're switched to
away mode. All we need is to add one more section.

[ - cut (centericq external actions setup for elizatalk) ------------------- ]

%action         Eliza
event           msg
proto           all
status          away
options         stdin stdout

%exec
msg=`cat`
echo $msg | elizatalk

[ -------------------------------------------------------------------------- ]

Voila! You might also want to read the elizatalk documentation. Though,
with my great explanations it's not necessary anymore :)


9.3.3. Remote control with external actions
-------------------------------------------

  Another useful thing you can make with external actions is remote
control for your servers or workstations. You can write an action which
will report you various diagnostic messages or perform administrative
tasks reacting on special pre-defined commands that only you may know.
So you just add a section to your ~/.centericq/external file, and leave
centericq running. Of course, the commands can be requested through any
of supported IM networks, though it's also configurable.

  The following example can report free disk space, uptime and files
listing under your ~/.centericq/ directory. The commands are "df",
"uptime" and "ls" respectively. As soon as centericq receives them it
answers with external commands' answers. It won't reply any other
messages.

[ - cut (centericq external actions setup for simple remote control) ------- ]

%action         Remote control
event           msg
proto           all
status          all
options         stdin stdout

%exec
#!/bin/sh

case `cat` in
    ls) ls -l ~/.centericq/;;
    df) df -h;;
    uptime) uptime;;
esac

[ -------------------------------------------------------------------------- ]


9.3.4. Forwarding events
------------------------

  The same way it's possible to setup forwarding of events to other
contacts, or with SMSes when you are away from centericq. The forwarding
is to be performed with the centericq command line options described
below, which allow to send events from out the program.

  The following example shows a simple setup for forwarding incoming icq
messages when you're away to a cellular phone with SMS.

[ - cut (centericq external actions setup for simple events forwarding) ---- ]

%action         ICQ messages forwarding
event           msg
proto           icq
status          away na
options         stdin

%exec
#!/bin/sh

msg=`cat`
echo $msg | centericq -s sms -p icq -t 0

[ -------------------------------------------------------------------------- ]

Please note UIN 0 is specified to send SMS to your own contact. Also,
you can easily forward your incoming events to any other IM contacts,
emails with the mail(1) command. In fact, everything you can access from
the command line is possible to be used here.


9.3.5. Hiding from scary ones
-----------------------------

  This example will use the -S command line parameter which allows to
control current status on IM networks from the command line.

[ - cut (centericq external actions setup for hiding from scary ones) ------ ]

%action         Hide from freddy_krueger
event           online
proto           all
status          all
options         stdin

%exec
#!/bin/sh

if test "$CONTACT_NICK" = "freddy_krueger"; then
    centericq -S _ -p $EVENT_NETWORK
fi

[ -------------------------------------------------------------------------- ]

Such a setup will make your centericq go offline as soon as the
freddy_krueger user appears online on any of the IM networks you're
currently logged in.


9.3.6. "Manual" external actions
--------------------------------

  There were only automatically executed actions so far. "But where are
manual ones?" - you will probably ask. Let me introduce to you the type
of actions that can be executed either from the contact list or from the
"users details" screen by pressing the F6 key. Such actions are executed
depending on a menu selection, then the corresponding code is ran
passing the data of a current contact, and if there was some output, it
will be shown in a dialog. One of the applications of the feature is to
invoke the host(1) command for a users' IP in order to find out his
Internet domain name. If you're a cool hacker, you can bind invoking nmap
this way or anything else you want :)

[ - cut (external actions setup for invoking of host(1) manually) ---------- ]

%manual         host
proto           icq
#
# Only ICQ shows up IP addresses
#

%exec
#!/bin/sh

ip=`head -n 45 $CONTACT_INFODIR/info | tail -n 1`
for i in $ip; do ip=$i; break; done
host $ip

[ -------------------------------------------------------------------------- ]

The strange "for" cycle is there because we want only the first IP
number, while quite frequently there are two separated with a space,
where the second one represents a local IP address which we don't need
to resolve.

Add this section to your ~/.centericq/external and enjoy the comfort of
not having to copy'n'paste the IP address in case you want to look up a
domain name.


9.4. Internal RSS reader
------------------------

  There is another useful technology whose power can be utilized with
centericq. It's called RSS or just "Really Simple Syndication". It's
about a uniform XML format which is used to describe recent changes at
various web sites and not only web sites. Theoretically you can describe
updates of any kind of information resources with it. See
http://backend.userland.com/rss for more info about the format.

  Now, what centericq can do about it. Since version 4.9.5 it allows you
to add RSS feeds to contact list just like they were usual contacts. You
can also specify the check period. As soon as there are any updates, the
contact pops up and you can read the news without a need to leave your
favourite sweet IM proggy.

  In order to find out if there is an RSS feed for a web site you're
looking to receiving updates from, navigate to it and look for a button
saying something like "RSS" or "XML". Then take a link and add it to
centericq. If there are no such a button, ask web master to setup the
feature.

  Also, there is a feed URL for you to try: http://thekonst.net/rss_en.xml
Having added it to your centericq you can stay tuned about updates on
the program author's site. You'll be announced about new releases of
centericq and other cool pieces of free software, as well as on
publication of various articles and photos which I take sometimes with
my digital camera.

  LiveJournal syndications will also work. In order to subscribe to
someone's updates, use the following URL:
    http://www.livejournal.com/users/USERNAME/rss/.
As an example, you can try
    http://www.livejournal.com/users/thekonst/rss/
(it's mainly in Russian though).


9.5. Protocol debug mode
------------------------

  Actually I have this feature for myself, to track protocol messages
generated by icqlib. But I also don't mind your looking at them :) The
only thing I wanna warn you is that no questions about their meaning are
answered. If you feel like seeing and understanding them, please refer
to the unofficial ICQ protocol specification, icqlib sources, whatever..

  To enable this feature, just run centericq with --debug parameter.
Protocol debug messages will be in the log window, and also they'll be
written into the ~/.centericq/debug file.


9.6. "Friendly" logging
-----------------------

  Another (better) way to log what is going on in your centericq, is
possible to be enabled with the "Detailed IM events log" item in the
Configuration dialog. When enabled, centericq produces a log file named
.centericq/log under your home directory. It contains messages about users'
logging in and out, receiving and sending messages, changed your own IM
status, and other blah. The file's format is quite clear, so any kind of
automatic parsing tool can be written without a problem. Though in this
case you should keep in mind the messages are locale dependent.


9.7. Custom base directories
----------------------------

  By default, centericq uses the .centericq/ directory under your home
to hold all of its information, such as configuration and contact list.
There can be situations, when you want to have several IM identities in
the same networks under the same UNIX account. To make it possible, the
-b or (--basedir) command line parameter was implemented. It's syntax is
simple "-b <directory name>"


9.8. Latest CVS snapshots
-------------------------

  If you wanna always have the recent version of the program, there is
an annonymous CVS access and a script which allows you to download
recent hot source with new features as soon as they appear.

  Ok, now how to do it. There is a script in the centericq package under
the misc/ directory. If you use an RPM package, it's installed to your
$prefix/bin/. Its name is cicqsync. Using it you can checkout or update
your source snapshot any time.

  Command line usage is simple. Cicqsync takes two parameters, the first
one is an action to perform (checkout - fresh copy from scratch, or
update - to update an already checked out source), and the second is a
path name to put the result to. Note that the directory must exist and
centericq/ will be created under it.

  Once you checked out or updated the fresh source, a usual build
procedure must be followed. Change current dir to {whatever}/centericq/,
execute configure, make and make install. Voila!


10. Lynx
--------

  This section contains links and references that may be of interest for
you.


10.1. The program homepage
--------------------------

The centericq homepage can be found at
    http://thekonst.net/centericq/


10.1.1. Centericq mailing list
------------------------------

  There is a mailing list for centericq which is used by the program
users to discuss their ideas, bug reports, fixes, and other stuff. You
would rather want to use it instead of direct mailing to me.

  To subscribe go to the centericq home page (URL is above) or send a
message to cicq-request@mailman.linuxpl.org with "subscribe" in the subject
field. To post a message to the list, send it to cicq@mailman.linuxpl.org
after you subscribe. The archive can be found at
    http://news.gmane.org/gmane.network.centericq/


10.1.2. German fan-club of the program :-)
------------------------------------------

  There are also some guys that decided to make their own resource on
the web where they share advises, tips and tricks on using the program.
I find it very nice. The site itself can be found at
http://www.centericq.de/

  Also they made an irc channel at the freenode network, irc.freenode.net.
The channel name is #centericq. The majority of centericq fans can be met
there.


10.2. thekonst.net
------------------

  If you want to find out more about my recent activities, news,
software developments and other things I'm involved in, visit my web
site at http://thekonst.net/


10.3. Other programs I write
----------------------------

To find out more about my software developments use the following URL:
    http://thekonst.net/konstware/

There is also an "writings" section with my publications at
    http://thekonst.net/writings/


10.4. IM protocols
------------------

  Here I want to say thanks to authors of libraries I used for various
IM protocols support in centericq.

  Barnaby Gray <barnaby@beedesign.co.uk>, who wrote a great library
  for icq2000 protocol and a GTK+ based ICQ client for UNIX.
  http://ickle.sourceforge.net/

  The whole team of
    Mark Spencer <markster@marko.net>,
    Adam Fritzler <afritz@marko.net>,
    Rob Flynn <rob@marko.net>,
    Eric Warmenhoven <eric@warmenhoven.org>,
    Brian Macke <macke@strangelove.net>,
    Anand Biligiri S <abiligiri@users.sf.net>,
    Valdis Kletnieks,
    Sean Egan <bj91704@binghamton.edu>,
    Toby Gray <toby.gray@ntlworld.com>
  for the library implementing the Yahoo! protocol.

  Ian Gulliver <ian@penguinhosting.net> for the nice Firetalk library
  used by centericq to provide the AIM and IRC services.

  The Jabber Team http://jabber.org/ for their GNU Jabber library.

  Since centericq contains support for the ICQ protocol taken from the
original software made by Israeli company named "Mirabilis", you might
wish to know more about it. So, visit the ICQ website at

    http://www.icq.com/

  It provides information about the company itself along with a lot of
community services including SMS messaging, web directory, and so on.


11. Help to the project I would appreciate
------------------------------------------

  What if you think that centericq is the best text console based
instant messaging program around? What if centericq is the application
you'd been waiting whole of your life, and want to express your
appreciation somehow? Helping the author you help the project itself to
keep rolling. It's not something vital I require to keep on writing and
improving centericq, neither you have to do it. I quite enjoy making it
in my spare time, and happy of the fact there are no deadlines and
obligations from my side. It's just my hobby.

  So how you can express appreciation to the way I waste my spare time,
so that to make me a bit more happy and satisfied by my activities?
There are several possibilites that bubbled out from my head while I was
sitting here in the office sweating of July's heat.


11.1. Feedback
--------------

  You can write some feedback saying what you liked and what is missing
in the program. Also, don't be silent if you notice bugs. Just check
everything attentively and send a detailed bug-report to the mailing
list. Please don't drop into my icq messages like "I found the icq
related bug, please fix it". The first reason is that usually during the
day I'm in the office working, and I'm not involved into centericq
development here too much. Also, such reports don't make sense because
of the lack of details. Please be more precise.


11.2. Patches
-------------

  Don't wait for me to implement a feature you'd like to have in
centericq. Please have in mind that whole the source code is available
and you can modify it yourself, then make a patch and send it to me.
Though I'd like you to follow my style of formatting the code. Please
don't make any changes not related to the feature you implement, it
makes your patch difficult to commit.


11.3. Promoting the little program
----------------------------------

  I bet you read some computers related magazines and visit various
Linux related sites. Please don't keep silence instead of screaming out
your adoration for the little nice program. Submit it to a software site
or catalogue or/and encourage the authors of your favourite magazine to
take a look at it and possibly write about centericq. Interviews,
speeches, presedential elections ;) and stuff are also possible, just
contact me for more details.


11.4. Donations
---------------

  If you're a materialist guy like me, you might want to present me
something what I can touch, put on a sandwich or into my pocket. Here it
goes.


11.4.1. Money
-------------

  The most universal way. Depending on a sum I will be able to drink one
more beer or tequila for the health of centericq users or buy a piece of
hardware, electronic gagdet or the newest model of "Porsche" ;)

  The on-line donations page is located at
    http://centericq.de/donation/


11.4.2. Hardware
----------------

  Since usually I write centericq at home, it's always nice to upgrade
the computer it's being developed with. It can increase the speed and
pleasure I get during the process.


11.4.3. Other stuff
-------------------

  Other stuff like t-shirts, souvenirs, albums or postcards with nice
views of the nature in places where you live, baseball tickets ;) are
also welcome.

$Id: README,v 1.104 2005/01/31 15:21:16 konst Exp $