gtmess(1)

NAME
gtmess - MSN messenger client

SYNOPSIS
gtmess [options]

DESCRIPTION

gtmess is an MSN messenger client, which allows you to use the MSN messenger service. It is a console application that uses the curses library to present a friendly user interface. This manpage corresponds to version 0.91.

OPTIONS

-h, --help
    Short help.

-Ovariable=value
    Assigns the value to the configuration variable.

--version
    Print the program version and CVR string to stdout and exit.

CONFIGURATION VARIABLES
The following list shows all configuration variables in alphabetic order. The value of a variable is either an integer or a (line-terminated) string of characters. In the following descriptions, N represents an integer value, S represents a character string value and B represents a boolean value, a special case of an integer value with only two possible values, 0 and 1. 1 stands for True and 0 for False.

aliases=N
    When N is 2, the user-defined contact aliases are displayed instead of nick names. A value of 1 displays aliases only when nicknames are too long (see max_nick_len variable) or when nicknames contain the email address (which is very irritating). A value of 0 disables the use of aliases completely and nick names are always displayed. User-defined contact aliases are stored into ~/.gtmess/aliases (see the FILES section). This variable affects the use of aliases everywhere but the notification window. See also the notif_aliases variable. The default value is 1.

auto_login=B
    When enabled, the login procedure starts as soon as the client is invoked, provided that login and password variables are nonempty. The default value is 1.

cert_prompt=B
    If enabled and a certificate cannot be verified against the list of trusted certificate authorities (see the FILES section), the user is asked if the login process should continue. Three options are given, Yes, No and Always. The meaning of each option is obvious. The login procedure requires more than one SSL connection, so option Always means that successive SSL connections will also continue upon unverified certificates. If this option is disabled, then the procedure always continues without asking the user, even if certificates cannot be verified. The default value is 1.

colors=N
    Sets initial color mode. Possible values are 0, 1 or 2. With 0, color is selected automatically (according to curses). 1 forces color mode, while 2 forces black and white. The default value is 0 (automatic).

common_name_prompt=B
    Like cert_prompt, the user is asked if the login process should continue, when the common name does not match the host name upon the initialization of an SSL connection. The default value is 1.

console_encoding=S
    Sets the character encoding to be used for displaying the text on the console. S is the name of the encoding. To see all valid encoding names, look at the output of the iconv -l command (on systems that provide it). If S is *locale* then the console encoding is that of the LC_CTYPE property of the current locale. The default value is *locale*.

cvr=S
    Sets the consumer versioning (CVR) string that is sent to the server during the login process. This string provides information about the client. For more information you should look at the protocol specification. The protocol requires (from version MSNP8 and above) your login account to be the last part of the CVR string. Since gtmess uses MSNP9, your login account is appended automatically at the end. The default value is computed at configure-time and is of the following form:
    0x0409 <system> <os-version> <architecture> GTMESS <clientversion> MSMSGS
    For example: 0x0409 Linux 2.6.8-1-686 i686 GTMESS 0.9 MSMSGS.

gtmesscontrol_ignore=S
    Ignore gtmess-specific messages that are substrings of S. To accept all such messages, leave S empty. To ignore all such messages, use the special value *all*, which is also the default value.

idle_sec=N
    If greater than zero, specifies how many seconds should pass without the user pressing any key before his/her status is automatically set to Idle. If N is zero, this feature is disabled. Note that the status is automatically set to Idle only if the previous status is Online. The default value is 180.

initial_status=N
    Sets the initial status after login. For the MSN Messenger protocol N can be a number from 0 to 8 representing the following statuses: 0 = Offline, 1 = Appear Offline, 2 = Online, 3 = Idle, 4 = Away, 5 = Busy, 6 = Be Right Back, 7 = On the Phone, 8 = Out to Lunch.
    The default value is 2 (Online).

invitable=B
    If disabled, others cannot invite you to conversation windows because the client does not respond to the invitations they send. So, if you want to chat, you have to invite others to the conversation windows yourself. If enabled, then gtmess automatically accepts invitations to switchboard sessions. Note that this option overrides the BLP setting which is stored at the server and is about users not on your forward list. This option is enabled by default.

login=S
    Sets the default login account. If S does not contain an `@' character, then the string `@hotmail.com' is appended.

log_traffic=B
    If enabled, network traffic between the client and the notification server is recorded into file ~/.gtmess/msn.log. The default value is 0.

log_console=N
    Sets console logging level. 0 disables logging, 1 enables switchboard window logging, 2 enables notification window logging, and 3 enables both. Log files are stored into ~/.gtmess/account/log/ in a per-contact scheme. The notification window messages are stored in the special file _nserver.log. This option is disabled by default.

max_nick_len=N
    Specifies the maximum allowed nickname length before displaying the alias. If N is 0, then aliases are displayed only if the nickname does not fit on a single line of the contact list window. The default value is 0.

msg_debug=N
    Defines the client behaviour on unrecognised messages. If N is 0, then those messages are ignored silently. If N is 1, then the type of the message is displayed, and if N is 2, the whole message is displayed. This option is useful for development purposes. The default value is 0.

msg_notify=N
    If N is greater than 0, gtmess notifies you when a new message is received even when the corresponding chat window is in the foreground. This feature is useful in graphical environments where the gtmess (console) window may not be visible all the time. However, you will not be notified if less than N seconds have passed since the previous message. This is to avoid too many notifications thay might be annoying. In fact, if N is 1, then the extra notification will occur only when the user is in Idle mode. The default value is 1.

msnftpd=N
    Specifies the port number the MSNFTP server is listening to. The MSNFTP server is a thread that runs in the background and enables outgoing file transfers by allowing incoming connections. A value of 0 disables the server. The default value is 6891.

notif_aliases=N
    This variable has exactly the same meaning as the aliases variable. It affects the use of aliases in the notification window. The default value is 0.

online_only=B
    If enabled, only contacts with online status are shown on the screen. The default value is 0.

password=S
    Sets the default password.

popup=B
    Enables/disables the popup notification window at the lower right corner of the screen. This is an external Tcl/Tk script. The default value is 1.

server=S
    Sets the initial server to connect to. For the MSN Messenger protocol, this can be a dispatch or a notification server. S is of the form hostname[:port]. If port is not specified, 1863 is assumed. The default value is messenger.hotmail.com.

snd_dir=S
    Sets the location of the sound effect (.wav) files. The default value is *data* which corresponds to the snd/ directory in the data prefix, usually /usr/local/share/gtmess.

snd_exec=S
    Sets the playback program for the sound effects. The default value is /usr/bin/aplay -Nq % which corresponds to the playback utility of the ALSA system. Note that this string is parsed in a naive way. Therefore, each argument should be separated by exactly one space character and there is no form of escape sequence for space characters. The percent character substitutes to the full path of the audio file in the sound effects directory.

snd_redirect=N
    Redirects standard output and standard error streams of the sound player into /dev/null. A value of 0 performs no redirection, 1 redirects stdout, 2 redirects stderr and 3 redirects both. The default value is 3.

sound=N
    Sets sound mode. N can be 0, 1 or 2. 0 disables all sound, 1 produces always a (console) beep, while 2 plays sound effects (through a sound device using an external utility). The default value is 1 (beep). There are 6 sound effects that correspond to various events (guess from the name): online.wav, offline.wav, newemail.wav, type.wav, ring.wav, meout.wav.

syn_cache=B
    If enabled, the contact/group lists are cached for future use. This option seems to have no meaning nowadays, as the msn server always rejects the cached version of the list. It has been disabled in this version of the client and will be removed completely in the future. The default value is 0.

time_user_types=N
    Sets how often typing notifications are sent. It is the time interval in seconds. The default value is 5.

update_nicks=N
    Sets how the nicknames are updated on the msn server. When a contact is initially online or changes his/her nickname while online, the server lets you know about his/her nickname. Gtmess uses the new nickname when provided, otherwise it uses the last nickname stored on the server (on your forward list). A value of 0 never updates nicknames, and a value of 2 always updates modified nicknames upon logout. A value of 1 updates nicknames only if they do not contain the email address. Note that you can always update the nickname of a specific contact manually (rename function). The default value is 0.

USER INTERFACE

The screen is divided in 7 parts. Four lines and three windows. The first line of the screen displays your nickname, your account and your status. The right-hand corner shows the system's clock (local time). The bottom line displays the copyright string and the menus or the input boxes. On the right is the contact list window. On the left of the contact list window is the switchboard (chat) window. Right below the switchboard window is the messages or notification window. This window displays various messages and errors from the operating system, as well as the notification server. The switchboard window is separated from the messages window by two lines. The first line is the edibox where you type your text when you chat. The second line is a kind of window-bar that displays a character for each open switchboard window. The window bar is displayed in three different modes, depending on the number of open switchboard windows:

Text
    In this mode, each window is represented by the name of the first contact that joined it. The name of the selected sb window (which is displayed on top) is enclosed in square brackets. Braces instead of square brackets denote that the window has unread messages (something got typed in the window while it was in the background and the user has not seen it yet).

Icons
    The selected switchboard window is represented with an `O'. A `-' represents a switchboard window that is open but not on the foreground, while a `+' means additionally that the designated window has unread messages .

Stats
    If there are too many open windows, then the window bar displays the only the number of the current window. It also displays how many windows exist on the left and right of the current one and how many of them have unread messages. The 5 numbers displayed correspond to these quantities respectively: left_unread, left, current, right_unread, right.

In the following description of the keyboard controls, `^' denotes holding CTRL, while `$' denotes holding SHIFT. `@' denotes holding ALT (or mod1 or pressing ESC first).

  MENUS

The functions of the main menu can be accesed by pressing ESC first, or by holding down the default modifier key (ALT) and then pressing one of the following keys (case insensitive):

C   Connect to server

D   Logout from notification server

S   Change status

L   Manage contact/group lists

N   Change nickname

O   Options

M   Display mailbox status

P   Ping the server and calculate RTT

I   Invite a contact from your Forward List to the active switchboard window. This is actually a shortcut for Alt-L-F-contact-I, although only online contacts are shown.

T   Write a note to the notification window.

/   Enter special client command (none available yet)

The shortcut key for the menu is shown in parentheses. Some menu entries may display a nested menu. The menu tree of the application is the following (for readability purposes the parentheses have been omitted and the shortcut key is shown alone on the left; also full names have been used instead of abbreviations):

A   Add

C   Contact

F   Forward - add a contact in your forward list

B   Block - add a contact in your block list

G   Group - add a new group

C   Connect

D   Disconnect

S   Status

N   On-line

I   Idle

A   Away

S   Busy

B   Be Right Back

P   On the Phone

L   Out to Lunch

H   Appear Offline (Hidden)

L   List

F   Forward - you are presented with a contact selection menu where you can pick up up a contact from your list and do the following

B   Block the selected contact (by adding him/her to the block list)

R   Remove the contact from the list

U   Unblock the selected contact (by adding him/her to the allow list)

N   Rename - change the name of the contact (see also the update_nicks variable)

C   Copy the contact to another group

M   Move the contact to a different group

I   Invite the contact to the active switchboard window

R   Reverse

A   Add the contact to your forward list, too (usually you 'll do this just after somebody has added you to his/her forward list)

B   Block the contact (you don't have to add the contact to your forward list if you don't want to, you can block him/her instead)

A   Allow

R   Remove the contact from your allow list

B   Block - remove the contact from your allow list and add to your block list

B   Block

R   Remove the contact from your block list

A   Allow - remove the contact from your block list and add to your allow list

G   Group

R   Remove the selected group

N   Rename the selected group

X   Export aliases - export the forward list into ~/.gtmess/aliases so that you can edit it

N   Name

O   Options

R   RL Prompt - prompt when others add you to their forward list

A   All others - allow others (not on your forward list) to start conversations with you

V   Var - set the value of a configuration variable; takes effect immediately

Q   Query all configuration variables

W   Write configuration variables into ~/.gtmess/config; in fact, only those variables with values other than the default are written

1-6 Playback respective sound effect (for testing)

M   Mail

P   Ping

I   Invite

N   Note

  SWITCHBOARD (chat window) CONTROLS

^N  new switchboard session

^W  leave current switchboard session and close the window

^X  leave current swithboard session, but leave the window open

F1  previous switchboard session

F2  next switchboard session

F3  next switchboard session that has unread messages

PgUp
    scroll down switchboard window

PgDn
    scroll up switchboard window

@F7 participant list scroll down

@F8 participant list scroll up

  SWITCHBOARD TEXT INPUT

Type any string and press enter to send it to server (talk). While you are typing, typing notifications are being sent in time_user_types sec intervals. If the string you type begins with `/', then it forms a special command (and typing notifications are not being sent while you are typing it).
Type `//' if you want to send a message with one `/' in the beginning.

  SWITCHBOARD COMMANDS

/ string
    This command sends string to the server without a typing notification. This actually happens because the string gets typed in command-entry mode (`/'). Note that there is a space after the first slash.

/send string
    Send a raw command string to server.

/invite useraccount
    Invite the user with account useraccount to join the switchboard session. You can also use the shorcut /i for this command. Example:
    /i myfriend@hotmail.com

/spoof fake
    Send a fake typing notification from user fake.

/file filename
    Send a request to send the file filename.

  GTMESS SPECIFIC SWITCHBOARD COMMANDS

/beep
    Send a beep to others so that everybody pay attention.

/gtmess
    Tell everybody you are using gtmess.

/msg text
    Send a message to other gtmess users. The message appears on their notification window.

/dlg text
    Send a message to other gtmess users. The message appears on their switchboard window.

  MISCELLANEOUS CONTROLS

^L  redraw screen from scratch

^G  produce a console beep

F4  display / hide the transfers window

F5  messages window scroll down

F6  messages window scroll up

F7  contact list scroll down

F8  contact list scroll up

F10 exit the client

NOTE: You can emulate the function keys F1 to F10 by pressing ESC first and then a digit from `1' to `0'. For instance, ESC-1 is equivalent to F1, ESC-2 is F2, ESC-0 is F10. ALT-<digit> might also work. To emulate Alt+F7 or Alt+F8 you can press ESC-& or ESC-* (or ALT-&, ALT-*).

  EDITBOX CONTROLS

When you are presented with an edit box to type a string, you can use the following keys:

arrow LEFT/RIGHT
    move cursor left/right

HOME/END
    move cursor to home/end

INSERT
    toggle insert mode

DELETE
    delete character at cursor and move the rest to the left

^T  delete word

^A  move one word left

^D  move one word right

BACKSPACE or ^H
    delete character on the left

ESC cancel editing (leaves string unmodified)

ENTER
    exit edit mode and save string

arrow UP/DOWN
    recall previous/next line from history

^K  enter clipboard mode

  EDITBOX CLIPBOARD MODE CONTROLS

Clipboard mode is valid for exactly one keystroke and is automatically exited after it. Invalid keystrokes exit the mode. You cannot cut or copy a masked field (i.e. password), though you can paste on it. The following are valid keystrokes in clipboard mode:

C   copy whole line to clipboard buffer

B   set block begin

K   copy from block begin to current position

V   paste buffer contents

X   cut line to buffer

Z   clear line (without affecting the buffer)

  CONTACT/GROUP SELECTION MODE

When you are presented with a list of contacts or groups, you can use the following keys:

] or arrow RIGHT/DOWN
    next entry

[  or  arrow LEFT/UP
    previous entry

{ or HOME
    first entry

} or END
    last entry

q   show contact/group information

SPACE or ENTER
    select

ESC or BACKSPACE or ^H
    cancel selection

  TRANSFERS WINDOW CONTROLS

When the transfers window is visible, you can use the following keys:

] or arrow DOWN
    next entry

[ or arrow UP
    previous entry

} or arrow RIGHT
    scroll left

{ or arrow LEFT
    scroll right

a   accept incoming invitation

r   reject incoming invitation

c   cancel (abort) incoming/outgoing transfer or outgoing invitation

q   quick printout

DELETE
    delete entry

?   mini help

  TYPING NOTIFICATIONS

When a user is typing a message, a typing notification is usually sent by the user's client. Not all clients are able to send or receive typing notifications. However, gtmess both sends and receives typing notifications. It is also able to do some kind of spoofing (see next section). When a typing notification is received, an exclamation mark (`!') is displayed on the left of the user's name on the contact list. This means that the user is typing a message in some switchboard window. Although it is possible to know the specific s/b window, the current version does not distinguish between s/b windows. Hopefully this will be fixed in the future.

ADVANCED FEATURES

There are some features of the protocol that gtmess takes advantage of, while the original client for windows does not use them. These features are:

*   Get notified when somebody has opened a chat window to you (but has not sent a message yet).

*   Allow you to log in with a different initial status. NOTE: In the past, you if logged in as Appear Offline other users would still receive some offline events and if you originally were offline, they could suspect that you had just logged in. Nowadays this server bug has been fixed.

*   Allow you to send a fake typing notification. This does not affect all clients. However, you can have fun with the original client!

*   Allow you to know if somebody is online, but has blocked you. To find out if a user is blocking you do the following: Open a switchboard window and invite the user you think has blocked you (whom you see offline) to the session. If you receive an error 216, then the user has blocked you. Otherwise, if you receive an error 217 then we cannot tell. When you receive error 217 there are two cases: 1) The user is really offline and you can't find out if he or she has blocked you. 2) The user appears offline and hasn't blocked you.
    To sum up, if a user is logged in and has blocked you, you will receive error 216. NOTE: This feature was actually available due to a bug at the original messenger server. Nowadays the bug has been fixed, so block detection does not work any more. It is mentioned here for historic purposes.

FILES

~/.gtmess/
    Main configuration directory. This directory relies in the user's home directory and stores the following gtmess-specific files:

~/.gtmess/aliases
    The aliases file. It contains lines of the form email alias. Lines beginning with `#' are considered to be comments, and therefore ignored. The alias export feature provides a convenient way to create an initial version of this file and then edit it manually.

~/.gtmess/config
    The configuration file. It contains lines of the form variable=value. Lines beginning with `#' are considered to be comments, and therefore ignored.

~/.gtmess/received/
    Received files from other users are stored in this directory.

~/.gtmess/msn.log
    The traffic log (see the log_traffic variable).

~/.gtmess/notify.pip
    This file is a named pipe that is used by the gtmess-notify script to pop up notification windows. The client writes data in this file.

~/.gtmess/account/log/
    The directory where console logs are stored.

./root.pem
    Trusted root certificates, verified upon the initialization of an SSL connection. Gtmess first looks into the current directory for this file, then into ~/.gtmess/ and then into the default data prefix, usually /usr/local/share/gtmess.

/usr/local/share/gtmess/snd/
    This is the location of the sound effect files. Note that the prefix /usr/local/share/gtmess might be different in your system.

BUGS
This is a list of known bugs and limitations. They will be removed as soon as possible. Notification or Passport login servers are not cached. If you send a file, you cannot see the IP of the receiver. When you receive a file, you cannot be server. When you send a file, you cannot be client. There is no option to keep an idle connection alive. There may occur conflicts in the authorization cookies of file transfers (though rare). Messages are always assumed to be UTF-8 encoded.

SEE ALSO
gtmess-gw(1), gtmess-notify(1)

ACKNOWLEDGEMENTS
Credits go to the following people: Mike Mintz for his excellent site on the MSN Messenger Protocol.
http://www.hypothetic.org/docs/msn/index.php L. Peter Deutsch for his MD5 module. Eric Rescorla for his article on SSL programming: An introduction to OpenSSL Programming. Qi Wenmin, kuuldor, David Lefevre for some useful patches they sent me. Kosta Fliangos for kindly providing his FreeBSD box for testing.

MAKING OF

Operating System
    Debian Linux Sarge (2.6.10)

Desktop Environment
    WindowMaker 0.91.0

Code Editor
    NEdit 5.5

Sound Effects
    ZynAddSubFX 1.4.3

Audio Editor
    Audacity 1.2.1

Graphics Editor
    The GIMP 1.2.3

File Manager
    Midnight Commander 4.6.1-pre1

AUTHORS
gtmess - MSN Messenger client
Copyright (C) 2002-2005 George M. Tzoumas

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA