Centericq. Documentation. Contents -------- 1. Introduction 1.1. Creation history 1.2. Features overview 1.3. Requirements 2. UIN registration 2.1. Updating details 3. User interface 3.1. The ESC key 3.2. The main screen 3.3. Menus 3.4. Dialogs 3.5. Some UI tips 4. Configuration 4.1. Migrating from other ICQ software 4.2. Event sounds 4.3. URL open action (web browser support) 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.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. Files 7.5. E-mail express messages 7.6. Away messages 7.7. 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. Protocol debug mode 9.3. 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. Konst.org.ua 10.3. Other programs I write 10.4. IM protocols 1. Introduction --------------- Centericq is a text mode menu- and window-driven IM interface. ICQ, Yahoo! and MSN protocols are now 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. Centericq is known to build and work well under Linux, FreeBSD, OpenBSD and NetBSD. 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 enough support for Yahoo! and MSN. Beside simple things like sending and receiving messages, changing online status and basic user information, centericq advanced features such as "White pages" search, an ability to update almost all the fields in user's details, send URL, files, contacts, 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 libsigc++ (at least 1.0.0) The Typesafe Signal Framework for C++. http://libsigc.sourceforge.net/ 2. UIN registration ------------------- To be able to use ICQ you should have a UIN (I think it stands for something like "user identification number"). When you start centericq for the first time the registration dialog appears. You can either use an already existing UIN or register a new one. Actually, all the fields the dialog has are self-descriptive. Some attention should only be paid to the "server address" field. The default value it has 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. If you want to use Yahoo! and MSN you should have already registered logins for these networks. 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.1. 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 details any time you're online with the dialog. 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. 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 is 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. 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. 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. 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. Also it always has an item named "ICQ" which is used to receive various system messages, such as authorization requests, "you were added" messages, and so on. 6.1. Finding and adding users ----------------------------- The most common way to add a 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. 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 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.. 6.1.1. Some useful hints ------------------------ You can skip the finding step by issuing the following shell command to add a user: $ mkdir ~/.centericq/<UIN of a user to add> 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 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.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, interestests.. 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. 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 (and only ICQ so far) 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. 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 link - http://www.icq.com/sms/smsnetworks.html 7.4. Files ---------- [ currently disabled ] To send or receive files over the ICQ network, centericq must have an ability to establish a direct TCP connection from side of a sender to receiver. Unfortunatelly there is no way to use the server for this ;) Sending files with centericq is also simple. Just activate the appropriate menu item and select files to send. Voila. If something goes wrong, the program will tell you by displaying a message in the log window. 7.5. E-mail express messages ---------------------------- This kind of events is ICQ specific. There is no way to receive them with Yahoo! or MSN 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. 7.6. Away messages ------------------ Another feature of ICQ network 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.7. 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 :) 9.2. 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, ./configure the program the following way CXXFLAGS="-DDEBUG" ./configure and after this perform the standard "make" and "make install" steps. The protocol messages will be visible in the log window, and also they'll be written into the ~/.centericq/log file. 9.3. 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://konst.org.ua/centericq/ To go directly to the "download" section use http://konst.org.ua/centericq/download/ 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@linuxpl.org with "subscribe" in the subject field. 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 openprojects network, irc.freshmeat.net. The channel name is #centericq. The majority of centericq fans can be met there. 10.2. Konst.org.ua ------------------ 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://konst.org.ua/ It's currently available in English and Russian. Use icons in the right bottom corner to switch the language. 10.3. Other programs I write ---------------------------- To find out more about my software developments use the following URL: http://konst.org.ua/software/ There is also an "articles" section at http://konst.org.ua/articles/ 10.4. IM protocols ------------------ Here I want to say thanks to authors of libraries I used for the supported 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/ Shane P. Brady <shane@jxie.com>, for his MSN library. Douglas Winslow <douglas@min.net>, for the Yahoo! protocol implmentation. Since centericq only 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.