climm 0.4.10.2, released 2003-03-07.

climm is (c) Matt Smith, Rüdiger Kuhlmann, and released under version 2 of the GPL.

Note: This package requires libiconv. Get it from <URL:http://www.bebits.com/app/2971/>.

Note 2: This package requires a properly set locale. If you don't understand this, enter
"export LC_ALL=en_US.UTF-8" before you start climm, or edit your climmrc to contain
a line "encoding local UTF-8".

Note 3: I do develop climm, but I am not a BeOS developer. If you have BeOS-specific
questions, ask someone else. If you're a BeOS developer, you might want to help porting.

Note 4: There is a mailing list for climm, go to <URL:http://www.climm.org/> and subscribe.

Note 5: Don't ask me to make a version for SKELETONs. Access to this software is illegal
for me. If you do have access, then you're able to compile from source. Consider note 4.

Note 6: Don't ask me to make a GUI for this program, or whine that it's not a native BeOS
application. It is command-line only, and it comes from Linux. If you don't understand this,
come up with a commonly-used GUI toolkit that works under BeOS, AmigaOS, Linux, *BSD,
commercial Unices and Windows. Then make one yourself.

If you don't accept any of these notes, then please do not install this software.

HPUX:
  Please use GNU libiconv. Otherwise, if even ISO-8859-1 won't work,
  try --disable-iconv.

Windows (MingW):
  The binary was created by cross-compiling with the
  mingw-cross compiler packaged by Debian:

  ii  mingw32                 3.4.2.20040916.1-2      Minimalist GNU win32 (cross) compiler
  ii  mingw32-binutils        2.15.94-20050118.1-1    Minimalist GNU win32 (cross) binutils
  ii  mingw32-runtime         3.7-1                   Minimalist GNU win32 (cross) runtime

  Additionally, libiconv was installed from a W32 Gimp Gtk installer,
  packaged as follows:

  ii  mingw32-libiconv        0.0-1                   iconv for cross-compiling with mingw32 (runtime)
  ii  mingw32-libiconv-dev    0.0-1                   iconv for cross-compiling with mingw32 (developer)

  It was configured as follows:

  ./configure --host=i586-mingw32msvc --build=i686-pc-linux-gnu CFLAGS=-O4 --disable-ssl --disable-tcl

  The binary was stripped afterwards.

  NOTE since 0.5.0.3+ for previous users:
  * the climmrc file is now taken from %USERPROFILE% (if defined), %HOME% (if defined),
    {HKEY_CURRENT_USER\Software\climm\InstallationDirectory}\etc (if key is set),
    {HKEY_LOCAL_MACHINE\Software\climm\InstallationDirectory}\etc (if key is set),
    the directory etc under the directory where climm.exe is located (if w32 gives this info),
    or C:\climm\etc\.

  NOTE:
  * This binary is still HIGHLY EXPERIMENTAL.
  * It does, unfortunately, not run under WINE.
  * Use %LC_ALL% or -i option to set locale to e.g. de.CP437
  * load ANSI.SYS; see
      http://mysite.verizon.net/jialpert/Computrs/ANSI_COM.htm
      http://www.nthelp.com/40/ansiNT.htm
      http://www.robvanderwoude.com/ansi.html
      http://www.xs4all.nl/~robw/files/ansi.zip

  The following features do not work:
  * no remote-control via a FIFO (no FIFOs on this platform)
  * the socket is not(!) non-blocking - help is needed here

Windows (Cygwin):
  You need a Cygwin installation with libiconv and openssl.

  NOTE for previous users:
  * see Windows (MingW)

  The following features do not work:
  * no remote-control via a FIFO (no FIFOs on this platform)

Playstation 2 / Linux:
  The binary was contributed by J. Grant. Here's a note he wants to have displayed:
  -
  Sony PS2 GNU/Linux default locale is broken, please make file in your
  home dir called .i18n with the following locale variables.  If you do
  not correct his error you will only see "????" instead of Japanese.
  LANG=ja
  LC_CTYPE=ja
  -

AmigaOS:
  The following features do not work in AmigaOS:
  * only buildin iconv() support (no system iconv() available)
  * no remote-control via a FIFO (no FIFOs on this platform)
    - if you want to code an AREXX port instead, let me know

BeOS:
  The last climm build is quite outdated. If you want to create a newer,
  feel free to contribute.

MacOS X:
  You need a Fink environment; see http://fink.sourceforge.net/ for details.

FILE FORMAT

The *.i18n files follow a simple file format. All empty lines or lines
starting with a hash sign (#) are comments and thus ignored. All other lines
should be translation entries, that consist of a four digit number, a colon
or dot, and the translated string. The order of the strings does not matter
for climm, but it does matter for the scripts updating these files. The first
10 entries contain meta data:

  1000: character encoding used for this file.
  1001: the ISO 3166 country code, e.g. de for German.
  1002: the current locale, e.g. de_DE for German/Germany.
  1003: climm version this file was last updated for, e.g. 0-4-9-4.
  1004: maintainers and contributors to this translation
  1005: maintainer who last updated this file
  1006: date of last update
  1007: reserved (was character encoding)
  1008: reserved
  1009: reserved

CREATING A NEW TRANSLATION WITHOUT CVS

If you want to make a new translation, lets assume for Danish (language
code: da), you start by copying the C.i18n file from the latest climm source
package to a new file, da.i18n. Add a hash sign in front of every line of
this file. Then translate each line, and for each line done, remove the
leading hash sign. This way, all untranslated lines are commented out, while
all translated lines are not. When you've done a significant part of the
file, simply mail it to me (i18n@ruediger-kuhlmann.de, ICQ # 82274703). You
may want to contact me when you start working on a translation as well. From
this on, follow the directions for translation updates.

UPDATING A TRANSLATION WITHOUT CVS

Download the current translation file from the climm web page, namely from
<URL:http://www.climm.org/documentation.shtml>, which is for the example
given the file <URL:http://www.climm.org/doc/da.i18n>. DO THIS EVEN IF YOU
HAVE A PREVIOUS VERSION OF THIS FILE. If I have made changes since you sent
me the file the last time that you don't agree with, undo them now, but for
heavens sake work on the file you downloaded from climm.org. Then update
whatever needs updating. Often, same strings have changed. Then, instead of
your translation, the file will now contain three lines: a line preceded by
"#-#" containing your previous translation, a line preceded by "+"
containing the previous English string, and a line preceded by "# #"
containing the current English string. Thus, you can see what exactly has
changed in the English string and whether any change and which is necessary
for your translation. If, e.g., a typo in the English string is fixed, your
translation doesn't need to be changed, but it needs to be checked anyway.
When finished, mail the file to me as usual.

CREATING A NEW TRANSLATION WITH CVS

Get the newest CVS check-out from climm. Type "./i18n-template <cc>.i18n",
where <cc> is the language code of the language you're going to translate
to.

UPDATING A TRANSLATION WITH CVS

Update your CVS checkout to the current version. Watch for conflicts in the
file you're maintaining, as you're the one who needs to fix them. Type
"./i18n-template <cc>.i18n" to update the translation file; any <cc>.i18n~
file needs to be removed first. See the section for updating without CVS
about changed English strings. When finished updating, type "./i18n-format
<cc>.i18n" to check for format string errors; any differences will be
printed. You may want to remove all .*.fmt files if the output seems bogus.
If there are still differences, you need to fix them. Remember: the order of
format string interpolates cannot be changed! When you're done, check the
file in (if you have CVS write access), send me a diff (cvs diff -u
<cc>.i18n, DO NOT SEND ME ANY OTHER DIFF NOT GENERATED THIS WAY) or
otherwise the complete file.

PROGRAMMERS INFORMATION

The scripts i18n-extract and i18n-number extract the current set of strings
into C.i18n resp. number new strings without a number. They're usually
called by typing "make lang" in the src/ subdirectory after new strings have
been added. These script create backups.

To add a new string to be translated, add
    i18n (###, "new string")

in your new code. Please never use tabs ("\t") and color codes (COLNONE,
COL<whatever>), and use trailing white space only if you *absolutely* need
them. Newlines ("\n") are fine. Never add an untranslated string. It is okay
for patches to contain unnumbered new strings. It is not okay to have
numbers that do not have the same english string.

marker ::= "#" stamp [ "/" [ "-" ] offset ] SPACE spec
	[ SPACE range ] [ SPACE "(" type ")" ]
range ::= "+" count | "-" delim | "/" indent
ident ::= [ nick ] "[" origin "]" [ "!" addr ]
	| [ [ nick ] "[" origin "]" "!"] addr
origin ::= ( "tcp" | "icq" ) [ version ] ":" uin [ "+" stat ]
addr ::= user "@" host

spec ::= ident SPACE event SPACE ident

version: [0-9]+
indent: [0-9]+
count: [0-9]*
delim: [-*=@;,+~0-9a-zA-Z]+
stamp: [0-9]{14}
offset: [0-9]+
host: [a-zA-Z0-9]([-.]?[a-zA-Z0-9])*
user: [a-zA-Z][-_.a-zA-Z0-9]*
nick: [a-zA-Z][a-zA-Z0-9]*
type: [0-9]+

event              description
----------         ------------
->                 sent message
<-                 received message
::                 status change
:!                 status report
:?                 status guess
:-                 went offline
:+                 went online
<#                 ACK to message
<*                 added to contact list by someone
*>                 added someone to contact list
=>                 automatic message

# time/delay NICK[icq:UIN]!USER@HOST <- NICK[icq:UIN+STAT] +9
# time/delay ... -delim

This document describes the behaviour and implementation details of climm's SSL
support. A small FAQ can be found at the end.


***   COMPILATION   ***

To enable SSL support in climm, gnutls from www.gnutls.org needs to be installed
on your system.

Specify the command line option --enable-ssl when running configure.


***   BEHAVIOUR / USING SSL   ***

Whenever climm opens a direct connection to another peer, it tries to start
SSL encryption if the peer is considered to be SSL capable. climm detects SSL
capability of licq peers by the licq specific timestamp flag, and of SIM
(*yuck*) peers by it's CAP_NEWSIM. climm peers are expected to support SSL
anyway. Why this does not raise problems with older climm peers that indeed
do not support SSL will be explained below.

In contrary if the direct connection is incoming from another peer, climm does
not try to start SSL for two reasons. First we want to avoid mutual SSL
start trials among climm and other "auto-start-ssl" clients. Second this gives a
behaviour as usual for the licq user.

The climm user can force the starting of SSL encryption anyway by issuing the
"peer ssl <contact>" command, if not done so by the peer.


***   IMPLEMENTATION   ***

SSL encryption is started after establishing a direct connection by sending
a special ICQ packet to the peer. This packet is designed like a common simple
text message as depicted in
http://www.stud.uni-karlsruhe.de/~uck4/ICQ/Packets/Peer/Msg/2

The message type field is set to 0x00EF and its content is empty. The response
must be a similar message with content set to "1". These details are taken from
licq.

If the peer does not answer at all (there are bad guys out there) or responds
with a "NACK" (Not acknowledged), SSL handshake will not be started.

Licq also supports stopping SSL encryption on a direct connection. But climm
never sends a SSL stop request and closes the direct connection upon receiving
one.


***   FAQ   ***

Q: I'm connected to a licq peer, but SSL is established upon explicit command
only (peer ssl <contact>). Why is SSL not activated upon connection immediately?

A: climm only establishes SSL encryption on its own if the direct connection is
going from climm to the peer, not vice versa. This inhibits mutual SSL handshake
attempts between ICQ clients starting SSL on their own.


Q: Why did you not use OpenSSL instead of gnutls? My software distribution
provides OpenSSL but no gnutls. This leads to inconvenience!

A: OpenSSL's licence is no strict GPL.

1. Preface.

Tcl is easy yet powerful scripting language. climm provides Tcl support
both for evaluating Tcl constructions from climm command line and
writing Tcl "hooks" to handle different events (incoming messages,
status changes, etc). This short HOWTO provides an introduction to
writing Tcl scripts for climm. I assume the reader has basic knowledge
of Tcl itself - just like I have. ;)

Why this HOWTO? When trying to implement a simple hook I discovered
that the documentation for this climm functionality is rather sparse
and then I had to study climm sources to get my task done. As not
everybody can read C source code freely (well, at least I cannot) I
decided to try to cover the theme. Hope my efforts will help somebody.

Ah, and of course comments and additions are welcome. Reach me at
jeff < at > macloue.com.

2. Prerequisites - compiling climm with Tcl support.

If your system contains a usable Tcl 8.4 installation climm build
system will detect it and use automatically. However you can disable
Tcl support with --disable-tcl switch - this may give your build a
small performance boost.

3. Basics.

When climm is compiled with Tcl support it creates an internal Tcl
interpreter upon startup. The user can use this interpreter to execute
tcl code by using one of the following commands at climm promt:

	tcl <command>

Executes inline Tcl <command> in climm Tcl interpreter.

Arbitrary Tcl commands can be used, for example:

climm> tcl puts [expr 1+2]
3
climm>

Unlike tclsh climm doesn't automatically echo the result of evaluation
so the following command prints nothing:

climm> tcl expr 1+2
climm>

So remember to "puts" the result of your calculations!

	tclscript <file>

Executes <file> as a Tcl script in scope of climm Tcl interpreter.

Supposing that the following script is stored in $HOME/.climm/hello.tcl:

puts "Hello, world"

the following command will provide:

climm> tclscript .climm/hello.tcl
Hello, world
climm>

You can also execute Tcl script upon climm startup by adding option
"tclscript" to "[General]" section of your climmrc file. In this case
script path can be given relative to climm base directory (usually
$HOME/.climm).

4. Tcl extensions provided by climm.

As most application do, climm provides some extensions to common Tcl
syntax. The extension command is "climm" and you can get a short usage
description by "climm help" ("tcl climm help" or even "tcl help" from
the climm prompt). I will describe "climm" subcommands in slightly more
depth below, following Tcl man pages syntax.

	climm exec <cmd>

Executes <cmd> as if it is given at climm command prompt. So, the
following code:

climm exec "msg Commander Good day, commander!"

will send message "Good day, commander!" to Commander contact.

	climm nick <uin>

Finds contact name for <uin>. For example, this code:

climm nick 48130434

will return my nickname in your contact list (or empty string if I'm
not there).

The following commands deal with hooks that can be installed into
climm. I will describe them later.

	climm receive <script> ?<contact>?

Installs message hook <script>, invoked on every incoming message or if
<contact> is given - on incoming messages from <contact>.

	climm unreceive ?<contact>?

Removes global message hook or message hook for <contact>.

[NB: Actually you need to provide exactly the same arguments as to
"climm receive" command to successfully remove the hook.]

	climm event <script>

Installs an event hook.

	climm unevent

Removes event hook.

[NB: Actually you need to provide exactly the same arguments as to
"climm event" command to successfully remove the hook.]

	climm hooks

Returns list (in Tcl meaning, see list(n)) of hooks installed. The list
consists of two-element lists with first element being a hook type
(either "event hook" for event hook or contact name for receive hooks)
and second showing the script which is executed.

5. Hooks - basic ideas and examples.

When compiled with Tcl support climm can execute different Tcl commands
upon certain events. As said above, "climm receive" command can be used
to make given <script> to be executed upon incoming message arrival.
Actually as far as I can guess from climm source code climm just
executes the following construct:

	<script> <uin> <message>

when message <message> is received from UIN <uin>. This requires
<script> to be no more than a name of procedure accepting two
parameters - or a construction like that:

puts "some string"; return;

This will make the code executed as follows:

puts "some string"; return; 48130434 {Hello!}

and hook arguments are ignored - simple but ugly, isn't it? And not as
flexible as a procedure too - isn't it useful to know whom we received
a message from?

But enough chit-chat, let's try to write some hooks already!

5.1. Message hooks

Message hooks are simple. Unlike event hooks there are always two
arguments to the script. Let's write a simple procedure and attach it
as a message hook.

proc msghook {uin message} {puts "Oh, message from $uin!"}
climm receive msghook

In climm prompt this will look as follows:

climm> tcl proc msghook {uin message} {puts "Oh, message from $uin!"}
climm> tcl climm receive msghook

Let's try to test it:

climm> msg 48130434 test
14:39:13              48130434 {<< test
Oh, message from 48130434!
14:39:14              48130434 >>} test

It works, doesn't it? Then let's try to remove the hook:

climm> tcl climm unreceive msghook

The hook is now removed.

This hook was global, let's make it filter UINs.

climm> tcl climm receive msghook Larry_Laffer
climm> msg 48130434 test
14:42:35              48130434 {<< test
14:42:35              48130434 >>} test

The hook is not executed. To remove it we need to give the following
command:

climm> tcl climm unreceive msghook Larry_Laffer

5.2. Event hooks

Event hooks are complex. At the moment of writing climm doesn't
distinguish different event types - there is only one global event hook
and it is called with variable number of parameters. The first is
always an event type - so it's up to hook procedure to decide whether
to continue processing or return. Second is always UIN of the contact
who triggered the event. Other parameters can vary so precautions need
to be made not to receive many error messages.

5.2.1. Event: status change.

Let's try to implement simple "status change" event handler. Status
change event happens every time a contact changes its status
(naturally) and executes the following Tcl code:

	<event handler script> status <uin> <status>

So, let's write something like this:

proc evhandler {type uin args} {
	if { $type != "status" } then return
	set status [lindex $args 0]
	set nick [climm nick $uin]
	puts "$nick changes status to $status"
}

This procedure analyzes event type and if it is a status change event
extracts status value and prints a message. Let's attach it as an event
handler:

climm event evhandler

If the procedure is stored in file $HOME/.climm/evhandler.tcl the
following commands will do the trick:

climm> tclscript .climm/evhandler.tcl
climm> tcl climm event evhandler

Then, when a contact changes his/her status, we will get the following:

15:17:46               Contact1 changed status to occupied.
Contact1 changes status to occupied

Or even:

15:19:39              Contact2 logged off.
Contact2 changes status to logged_off

Going offline is also a status change.

6. Hooks reference.

6.1. Message hook.

Install syntax:

	climm receive <script> ?<contact>?

Remove syntax:

	climm unreceive <script> ?<contact>?

Tcl code executed upon message arrival (from <contact> if specified):

	<script> <uin> <message>

6.2. Event hooks.

Install syntax:

	climm event <script>

Remove syntax:

	climm unevent <script>

Tcl code executed upon event:

	<script> <type> <uin> ?<arg1>? ...

List of optional arguments depends on event <type>.

6.2.1. Event: status change.

When a contact <uin> changes his status to <status> the following Tcl
code is executed:

	<script> status <uin> <status>

6.2.2. Event: message received.

This event is triggered when incoming message arrives. Although it's
better to use message hooks to handle events of this type you can
handle messages through the event hook as well - it may useful in some
cases because message and event hooks are invoked independently.

When a message <message> is received from user <uin> the following Tcl
code executed is as follows:

	<script> message <uin> <message>

6.2.3. Event: incoming file request.

This event is triggered when file transfer request arrives. The
following Tcl code is executed:

	<script> file_request <uin> <file name> <bytes> <ref>

FIXME: I don't know much about ICQ file transfers, so can somebody tell
me what the <ref> is?

6.2.4. Event: added to contact list.

This event is triggered when you are added to somebody's contact list.
When user <uin> adds you to his contact list the following Tcl code is
executed:

	<script> contactlistadded <uin>

6.2.5. Event: authorization.

Events of this group are triggered when authorization messages arrive.
When auth message arrives from user <uin> the following Tcl code is
executed:

	<script> authorization <uin> <authtype>

<authtype> can be:

 - request - when incoming auth request is received from user <uin>;
 - refused - if your auth request is refused by user <uin>;
 - granted - if your auth request is granted by user <uin>.

6.2.6. Event: Web message arrived.

This event is triggered when you receive a message from ICQ web site
("web message"). The following Tcl code is executed:

	<script> web <uin> <t0> <t3> <t4> <t5>

FIXME: add t0-t5 parameters description; not sure what <uin> is in this
case.

6.2.7. Event: Mail message arrived.

This event is triggered when you receive a ICQ Mail message. The
following Tcl code is executed:

	<script> mail <uin> <t0> <t3> <t4> <t5>

FIXME: add t0-t5 parameters description; not sure what <uin> is in this case

6.2.8. Event: SSL.

Events of this group are triggered at various stage of SSL connection setup.

When it is detected that the user <uin>'s client doesn't support SSL
channel the following Tcl code is executed:

	<script> ssl <uin> no_candidate

When it is detected that the user <uin>'s client supports SSL channel
the following Tcl code is executed:

	<script> ssl <uin> candidate

When SSL connection is tried to user <uin>, the following Tcl code is
executed if remote hasn't SSL connetion enabled:

	<script> ssl <uin> failed precondition

When SSL connection is tried to user <uin>, the following Tcl code is
executed if SSL connection initialization fails:

	<script> ssl <uin> failed init

When SSL connection is tried to user <uin>, the following Tcl code is
executed if SSL key exchange fails:

	<script> ssl <uin> failed key

When SSL connection is tried to user <uin>, the following Tcl code is
executed if SSL handshake fails:

	<script> ssl <uin> failed handshake

And, finally, when SSL connection to user <uin> is successfully
established the following Tcl code is executed:

	<script> ssl <uin> ok

If the SSL connection to <uin> fails at some stage finally the
following Tcl code is executed:

	<script> ssl <uin> incapable