gtmess

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

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_cl=B

When enabled, the contact list is selected automatically when the last chat window closes. 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*.

0x0409 <system> <os−version> <architecture> GTMESS <clientversion> MSMSGS
For example: 0x0409 Linux 2.6.8−1−686 i686 GTMESS 0.9 MSMSGS.

err_connreset=B

Ignore ‘Connection reset by peer’ error messages in chat windows. These messages may occur very often as the server closes inactive connections. Therefore, they are not displayed by default.

force_nick=S

The nickname chosen by the user is not stored permantently on the server any more, due to protocol changes concerning MSNP12. When this option is set, gtmess sets the nickname to S just after login. By default, this option is not set (empty string) which means that gtmess will not force a nickname change upon login. In this case the server will provide the stored nickname which could be either a proper nickname (which was stored by some msn client supporting a newer protocol version) or a nickname consisting of the email address of the account.

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*. By default, all such messages are accepted.

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.

keep_alive=N

If greater than zero, the client sends a ping request in every N seconds. This will help to keep the connection alive on some networks. The default value is 60. Note that due to changes in the protocol, the server is more willing to close inactive connections. You are not advised to set this option too low.

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.

max_retries=N

Due to a strange bug of gtmess (or maybe feature of the openssl library), you frequently get ‘socket read error’ upon initial login attempts. The error seems to go away just by retrying. Gtmess will retry N more times, before giving up. The default value is 4.

msg_debug=N

Defines the client behavior on unrecognized messages. If N is 0, then those messages are silently ignored. 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 that 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.

nonotif_mystatus=N

Specifies a set of statuses that the user may be in without receiving any sound or popup notifications. For example, if a user is Busy, having notification windows pop up all the time might be annoying. Each status corresponds to a bit of N in the order presented in the paragraph describing initial_status. The default value is 368 which stands for the set of statuses {Away, Busy, Be-Right-Back, Out-To-Lunch}, as its binary representation is 101110000.

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. The password should be given in obfuscated form. See Options/Password for more information.

passp_server=S

This option caches the default passport login server, which by default is login.live.com/login2.srf, in order to speed-up the login process. When this option is set to the empty string, a server will be requested from nexus.passport.com.

popup=B

Enables/disables the popup notification window, each time launching the script defined by the pop_exec variable. The default value is 1.

pop_exec=S

Sets the script to be used for notification windows. For Linux systems, the default value is which notify-send >/dev/null 2>&1 && notify-send gtmess ’%s’ > /dev/null 2>&1 which corresponds to the freedesktop.org notification scheme. For Darwin/MacOS the default value is which -s growlnotify && growlnotify -a gtmess -t ’%s’ -m gtmess which makes use of the Growl notification system. The provided gtmess−notify script (see also the corresponding manpage) can be launched by specifying the following string: test -n "$DISPLAY" && which notify-send > /dev/null 2>&1 && notify-send gtmess ’%s’ > /dev/null 2>&1. In this case, make sure that gtmess-notify is already running (that is notify.pip is opened for reading), otherwise an attempt to write to notify.pip will block!

Note that this string will be passed to system() and only a single ‘%s’ is allowed which will be substituted with the message string. Single quotes in the message string will be replaced by spaces. Leaving this variable empty is another way to disable popups.

safe_history=B

Enables/disables safe history browsing for the editboxes. When enabled and the editbox contains text that does not exist in the history buffer, the history browsing (up/down arrows) is disabled. This is to prevent the user from inadvertently pressing the arrow keys and losing some recently typed text. The default value is 1.

safe_msg=N

Prevents the user from inadvertently closing a chat window containing very recent messages. It does so by not allowing the user to close a window when there are messages that have appeared during the last N+1 seconds. A value of -1 disables this option. The default value is 0.

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 R hostname [ :port ]. If port is not specified, 1863 is assumed. The default value is messenger.hotmail.com.

skip_says=N

Skips subsequent ‘..... says:’ prefixes in a chat window from the same user, when the user messages are less than N seconds apart. The purpose of this option is to allow for more text in the chat window suppressing redundant prompts. The default value is 20.

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 on Linux systems is /usr/bin/aplay -Nq %s > /dev/null 2>&1 & which corresponds to the playback utility of the ALSA system. On Darwin/MacOS systems, the default value is /usr/bin/afplay %s > /dev/null 2>&1 & which corresponds to the system’s audio playback utility. Note that this string will be passed to system() and only a single ‘%s’ is allowed which will be substituted with the full path of the audio file. An empty string disables this option (which is equivalent to setting sound to 0).

sound=N

Sets sound mode. N can be 0, 1, 2, 3 or 4. 0 disables all sound, 1 produces always a (console) beep, while 2 plays sound effects (using the external command defined by snd_exec). Value 3 produces pcspeaker sounds using the external program beep, and value 4 produces pcspeaker sounds by directly accessing the speaker on linux systems. However, this last option requires special privileges and might not work at all, or work only as root. It works in linux VTs, however (i.e., ctrl-alt-F1). 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 may 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.

url_exec=S

Sets the command line for the url browser. This typically launches a web browser to open urls that a users sends to you. Those urls are automatically parsed and displayed in the transfers window. The default value is opera --remote ’openURL(%s,new-page)’ >/dev/null 2>&1 & for Linux, which corresponds to opening the url using the Opera web browser. Under Darwin/MacOS, the default value is /usr/bin/open ’%s’ > /dev/null 2>&1 which will open the url with the default web browser. As in snd_exec, only one occurrence of ‘%s’ is allowed that will be replaced by the url. An empty string disables this option.

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

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 accessed by pressing ESC or F9 first, or by holding down the default modifier key (ALT) and then pressing one of the following keys (case insensitive):

The shortcut key for the menu is shown underlined. Some menu entries may display a nested menu. Only selected menu entries are explained in this document:

Lists/Forward/Block

add contact to BL and remove from AL

Lists/Forward/Unblock

add contact to AL and remove from BL

Lists/Forward/Rename

change the name of the contact (see also the update_nicks variable)

Lists/Forward/Ungroup

remove contact from all groups (a contact may belong to no particular group)

Lists/Forward/Copy

the contact to another group

Lists/Forward/Move

the contact to a different group

Lists/Forward/Invite

the contact to the current switchboard session

Lists/Forward/Per-contact settings

Manage contact-specific settings. Currently there are two settings for each contact. Notifications (enabled by default) toggles the popup windows and sound effects for the selected contact (i.e., when somebody keeps logging in and out, it can be quite irritating). Ignored option (disabled by default) causes gtmess to ignore the contact’s requests to start a chat with you. It might appear to the other party that there is no response from the network. In this mode, conversations can be initiated only by yourself.

Lists/Reverse/Add

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

Lists/Reverse/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)

Lists/Pending

In this list you manage pending add requests.

Lists/Group/Empty

remove all contacts in a group (use with care!)

Lists/Add

a new contact or create a new group

Lists/Export aliases

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

Lists/Clean up

helps you remove obsolete entries from your contact lists. Shows which contacts have removed you from their contact list, so that there is no point in having them in your FL, AL and BL. Note that this is 100% accurate anymore, due to protocol changes. Consequently, you can having some contact in your FL while not in RL. Having a contact in your AL while not in RL may be pointless unless you have disabled the "All others" (BLP) flag. Similarly, having a contact in your BL while not in RL might have no meaning, unless you have the BLP flag enabled and that contact is disturbing you. Ideally, there should hold AL + BL = RL, that is each contact in the reverse list is either blocked or allowed. Occasionally, you will have same PL (Pending List) requests that you must decide whether to add or block.

Server/Nickname

set the nickname

Server/Personal msg

set the Personal Message, usually displayed after the nickname

Server/RL Prompt

prompt when others add you to their forward list. This option is stored on the server.

Server/All others

allow others (not on your forward list) to start conversations with you. This is also referred to as the BLP flag. This option is stored on the server.

Options/Variables

set the value of a configuration variable; takes effect immediately

Options/Query

all configuration variables

Options/Write

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

Options/Password

Obfuscates the given password, so that you can store it in the configuration file. While this cannot be considered SAFE, it would prevent someone from stealing your password just by looking in your configuration file for a few seconds.

Options/(1)-(6) Sound test

By pressing the number keys ‘1’ to ‘6’, you can test the different sound effects.

MENU NAVIGATION (F9)
[] or arrow left/right

previous/next entry

{} or home/end

first/last entry

<> or PgUp/PgDn

page up/down (skip many entries)

ENTER/SPACE

select

-/ESC/BACKSPACE

cancel or return to parent menu

underlined letter

shortcut for selection

SWITCHBOARD (chat window) CONTROLS

PgUp/F7

scroll down switchboard window

PgDn/F8

scroll up switchboard window

CONTACT LIST MENU MODE
] or arrow DOWN

next contact

[ or arrow UP

previous contact

ENTER/SPACE

new chat session & invite contact & leave menu

PgUp/F7

contact list scroll down

PgDn/F8

contact 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 shortcut /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

/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

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

BACKSPACE or ^H

delete character on the left

arrow UP/DOWN

recall previous/next line from history

EDITBOX ESCAPE MODE CONTROLS
Escape mode is valid for exactly one keystroke and is automatically exited after it. Typical operations in this mode are clipboard operations. 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 escape mode:

CONTACT/GROUP SELECTION MODE
When you are presented with a list of contacts or groups, you can use the following keys (note that this contact/group selection is required by some functions and appears in the bottom line; do not confuse it with the contact list on the right that can also be used as a menu):
] or arrow RIGHT/DOWN

next entry

[ or arrow LEFT/UP

previous entry

{ or HOME

first entry

} or END

last entry

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

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:

NOTE: If you log in as Appear Offline, other users will still receive some offline events, at least under protocol version MSNP12. Therefore, if you were offline in the first place, they can suspect that you have just logged in. Gtmess will detect this ‘fact’ and warn for a user possibly appearing offline (aka Invisible) ;)

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. It is not used directly in this version of gtmess, you can safely remove it. ATTENTION: If the named pipe is not already open, an attempt to write to this file by a script through gtmess will block (unless the process that writes to the file runs in background)!

~/.gtmess/account/log/

The directory where console logs are stored.

~/.gtmess/account/per_contact

The file where per-contact settings are stored. Each line contains the contact email and its specific settings. The file is updated upon logout. Per-contact settings can be modified from the menu and only those contacts whose settings have been modified 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.

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 may occur conflicts in the authorization cookies of file transfers (though rare).

Messages are always assumed to be UTF−8 encoded.

When running ‘gtmess -h’, the default values shown for the scripts (*_exec) are overriden by the user configuration file.

You might get ‘socket read error’ when trying to log in. Retrying usually solves this problem.

SEE ALSO

gtmess−notify(1), gtmess_w(1), README file that comes along with the program; contains more up-to-date information, especially on the keyboard shortcuts

MAKING OF

Operating System

Debian Linux, Mac OS X

Desktop Environment

WindowMaker, KDE 4, Quartz

Code Editor

NEdit, Qt Creator

Sound Effects

ZynAddSubFX

Audio Editor

Audacity

Graphics Editor

The GIMP

File Manager

Midnight Commander

ACKNOWLEDGMENTS

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: R 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.

The aMSN team for some useful ideas I got from their client.

CONTRIBUTORS

Tibor Billes has corrected quite a few bugs and is also actively contributing code to the project.

AUTHORS

gtmess − MSN Messenger client
Copyright (C) 2002−2010 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