CenterIM4 Documentation

From CenterIM
Jump to: navigation, search


CenterIM4 documentation.

This document was originally written by Konstantin Klyagin <k@thekonst.net>. 2001-2005

Currently modified by the CenterIM community. 2007, version 1.0

Contents

Introduction

CenterIM 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!

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


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 thing, 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.


Features overview

CenterIM'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, CenterIM 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 :)


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 CenterIM 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 CenterIM from source on Redhat based systems you should have *-devel RPM packages of the above mentioned libraries installed.

For more information on the software requirements, take a look at: http://www.centerim.org/index.php/Requirements

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


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 CenterIM. 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 :) Unfortunately 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.


IM accounts registration

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


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.


Yahoo! accounts

CenterIM doesn't support registering new Yahoo! IDs, 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.


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.


IRC accounts

This service is completely different from others supported by CenterIM. 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 log in. 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 authentication using a password to identify himself. Sometimes it's used to protect your nickname from overtaking on a specific IRC network. CenterIM does support this too, providing a non-obligatory password field.

It is not possible (with centerim4) to connect to multiple irc servers at one time.

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.

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 CenterIM. Due to its being open and developed by the wide community, CenterIM can register new nicknames in it very easily.


Jabber groupchat conferences

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


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/. CenterIM 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!


Gadu-gadu

If you have libjpeg installed in your system and the configure script does find it, CenterIM 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/


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.


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.


User interface

The text UI CenterIM 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.


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.


The main screen

The main screen of CenterIM 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 CenterIM is doing right now.


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 multiple 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.


Dialogs

Every dialog in CenterIM 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 :)


Hotkeys in dialogs

Dialogs of CenterIM 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.


Some UI tips

There at some quite standard key combinations supported by CenterIM 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 CenterIM 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.


Configuration

The majority of CenterIM 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.


Migrating from other ICQ software

If you decided to migrate to CenterIM 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.


Event sounds

As it was said before, CenterIM can play sounds on various events. It's done the following way. Upon, say, receiving a message, CenterIM 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 CenterIM 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 .centerim/ 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 ~/.centerim/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".


Color schemes

It's possible to customize colors in the CenterIM's user interface. It's done with the ~/.centerim/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, CenterIM 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 CenterIM.de: http://centericq.de/misc/colorscheme_helper.png


Key bindings

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


URL open action (web browser support)

CenterIM 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 ~/.centerim/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 CenterIM, so please only pass your URLs to scripts or to X based browsers, but to nothing interactive.

Though, if you're using CenterIM 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.


Hostnames and port numbers (for crazy firewall admins)

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


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 :)


Yahoo!

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


AIM TOC

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


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, CenterIM sets the following parameters:

 Hostname: irc.freenode.net
 Port: 6667


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


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


Gadu-gadu

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


MSN

 Hostname: messenger.hotmail.com
 Port: 1863


Binding to various IP addresses

If the box you're running CenterIM 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>.


Online status

With CenterIM 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, CenterIM 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.


"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 CenterIM 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.


Contact list

The list of your contacts is displayed to the left on the CenterIM 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.


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. CenterIM 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 criteria. 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 CenterIM 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 CenterIM 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 "#CenterIM #linux" query will show a list of users that are currently talking on both channels.


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 ~/.centerim/<UIN of a user to add>
 This one is for ICQ
 $ mkdir ~/.centerim/y<nickname>
 For Yahoo!
 $ mkdir ~/.centerim/a<nickname>
 For AIM
 $ mkdir ~/.centerim/i<nickname>
 For IRC
 $ mkdir ~/.centerim/j<nickname>
 For Jabber
 
 $ mkdir ~/.centerim/i<msn-mailaddress>
 For MSN

Don't forget to restart CenterIM 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 curiosity, sometimes names of people get me interested 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 curiosity 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 :)


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.


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.


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 hesitate to do it before asking people who they are. It takes time to explain, though it can be looked up so easily.


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. CenterIM 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".


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.


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 CenterIM 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).


URLs

Though you can send URLs with regular messages the Mirabilis guys decided to make a separate event for it. No problem, CenterIM 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 :)


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 chosen. Then if a user does not have any cellular number on his details, CenterIM will ask you to provide one. This number can be changed any time with the "Edit details" item of the same menu.

CenterIM 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 CenterIM does so too.


Contacts

Sharing parts of your contact list with other users on the instant messaging network is a feature supported only by ICQ so far. CenterIM 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.


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 invoked 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.


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.


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.


Away messages

Another feature of IM networks supported by CenterIM 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 CenterIM 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.


Events history

All of events sent and received with CenterIM 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.


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.


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.


Visible list

ICQ has the "invisible" option among its online status modes. When you switch to it, no one 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.


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".


Advanced features

CenterIM 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.


Arabic and Hebrew languages support

There is a basic support for bidirectional languages in CenterIM. 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 CenterIM'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.


Command line facilities

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


Sending events

In fact, it's not really sending. CenterIM just allows you to put an event to the outgoing queue from another process with command line options. To have the event sent immediately CenterIM 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" | centerim -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." | CenterIM -s url -p icq -t 17502151

Finally, a small example of sending SMSes:

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

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


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:

   $ centerim -S _ -p icq

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

   $ centerim -S a -p yahoo

And this command will switch your yahoo status to away.


External actions and auto-responses

It is possible to make CenterIM 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 .centerim/ directory in your home. Here is an example which demonstrates its options. It's recommended just cut'n'paste the following text.


$HOME/.centerim/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 mustn'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 CenterIM'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 synonym 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 CenterIM 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 CenterIM:

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
   ~/.centerim/ 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 :)


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 (CenterIM 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!

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

--
me
EOF


Elizatalk: making fun with your friends

One of the most intresting and funny uses for external actions in CenterIM is auto-responding chat robots. So far I know only one which is called Eliza. Unfortunately its doc covers only setup for licq, so it'll describe how to make it work with CenterIM 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.


%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 :)


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 ~/.centerim/external file, and leave CenterIM 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, up time and files listing under your ~/.centerim/ directory. The commands are "df", "uptime" and "ls" respectively. As soon as CenterIM receives them it answers with external commands' answers. It won't reply any other messages.

cut (CenterIM 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 ~/.centerim/;;
    df) df -h;;
    uptime) uptime;;
esac


Forwarding events

The same way it's possible to setup forwarding of events to other contacts, or with SMSes when you are away from CenterIM. The forwarding is to be performed with the CenterIM 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 (CenterIM 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 | CenterIM -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.


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 (CenterIM 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
    centerim -S _ -p $EVENT_NETWORK
fi

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


"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 ~/.centerim/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.


Internal RSS reader

There is another useful technology whose power can be utilized with CenterIM. 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 CenterIM 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 CenterIM. 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 CenterIM you can stay tuned about updates on the program author's site. You'll be announced about new releases of CenterIM 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).


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 CenterIM with --debug parameter. Protocol debug messages will be in the log window, and also they'll be written into the ~/.centerim/debug file.


"Friendly" logging

Another (better) way to log what is going on in your CenterIM, is possible to be enabled with the "Detailed IM events log" item in the Configuration dialog. When enabled, CenterIM produces a log file named .centerim/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.


Custom base directories

By default, CenterIM uses the .centerim/ 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>"


Latest snapshots

If you wanna always have the recent version of the program, there is an anonymous GIT repository available to get the code.

You can find documentation at our website to get the latest (development) source code, using the GIT at: http://repo.or.cz/w/centerim.git

At our website is a description how to get it.

* http://www.centerim.org/index.php/Contribute_Code

You can also get complete packages from:

* http://www.centerim.org/download/
* ftp://ftp.centerim.org/


Lynx

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


The program homepage

The CenterIM homepage can be found at http://www.centerim.org/


CenterIM mailing list

There are two mailing lists for CenterIM, one is used by program users and the other is used by developers to discuss their ideas, bug reports, fixes, and other stuff.

To subscribe go to the CenterIM home page and fill out the appropriate form. For CenterIM users http://centerim.org/mailman/listinfo/centerim-users

For CenterIM developers http://centerim.org/mailman/listinfo/centerim-devel


IM protocols

Here we want to say thanks to authors of libraries CenterIM uses to support various IM protocols.

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 CenterIM to provide the AIM and IRC services.

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

Since CenterIM 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.


Help to the project is appreciated

What if you think that CenterIM is the best text console based instant messaging program around? What if CenterIM is the application you'd been waiting whole of your life, and want to express your appreciation somehow? Helping the authors, you help the project itself to keep rolling. It's not something vital we require to keep on writing and improving CenterIM, neither you have to do it.


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 put a detailed bug-report on http://bugzilla.centerim.org/ or drop a detailed email on our developers mailing list if you think you've found a bug.

If you have questions about how CenterIM works, you can also say hallo on our irc channel #centerim on freenode.


Patches

Don't wait for us to implement a feature you'd like to have in CenterIM. 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 us.

At our website is written how to get the code and how you can contribute patches.

We'd like you to follow our 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.