icq(n) 0.8.6 "icq protocol handling command"

NAME

icq - icq protocol handling command

SYNOPSIS

package require icq 0.8.6

icq::icq UIN password ?options?
icq::icq new password ?options?
cmd configure option ?options?
cmd cget key
cmd status ?status?
cmd send type recipient message
cmd password password ?ref?
cmd info uin ?ref?
cmd personal ?info?
cmd search filter
cmd roster ?action? ?item? ?...?
cmd contacts list ?action? ?uins?
cmd encoding ?encoding? ?uins?
cmd delete

DESCRIPTION

icq command creates icq connection command assotiated with given UIN. This command returns new connection command, which is used for work in ICQ network. Connection command has number of methods, described below. uin can be either existing ICQ numerical UIN or word new. In latter case new ICQ uin will be registered and returned in Registered event.

OPTIONS

-server
Specify ICQ server to connect to. If not specified, the default icq server login.icq.com is used.

-port
Specifies port to connect to. If not specified, the default port 5190 is used.

-proxy
Specifies tcl command which provides proxy connection interface. If no command specified, icq command will connect directly to server. See proxy (n).

-events
Specifies script to handle ICQ events (see EVENTS section). Event name and arguments are added to the end of this script or command and eval is invoked on result.

-keepalive
Specifies interval (in seconds) for sending keepalive packets. If it is zero, keepalive packets are not being sent.

-ping
Specifies interval (in seconds) for sending ping packets. If it is zero, ping packets are not being sent. The difference between ping and keepalive is that ping packets imply pong responces from server. This means it consumes more bandwidth, but allows detect link death.

-reconnect
Boolean option which enables or disables automatical reconnect after disconnect due to network problems.

-capabilities
List of additional capabilities sent to icq server (see CAPABILITIES section for details). Capabilities of wrong format are ignored. Default value is ICQ RELAY UTF8.

-glue-timeout
Specifies timeout (in milliseconds) after which incomplete long message is pushed to event script (see LONG MESSAGE SPLITTING secrion below). Default value is 600000 (10 minutes).

-roster
Enable operations with server-side roster. This option is either boolean value (enable or disable operations with server-side roster), or list of two integers: time of last update and number of items in local contact list. If roster is only enabled, all roster items will be retirieved from server after getting online and passed via event Roster:Items. If list of time and count is given, roster will be retrieved from server only if these values do not match with server roster ones, otherwise

-auto-away
Specify text which will be used as automatical responce when status is "away"

-auto-occ
Specify text which will be used as automatical responce when status is "occupied"

-auto-dnd
Specify text which will be used as automatical responce when status is "do not disturb".

-auto-na
Specify text which will be used as automatical responce when status is "not available".

-auto-ffc
Specify text which will be used as automatical responce when status is "free for chat".

CONNECTION METHODS

cmd configure option ?options?
Change one or more icq options (see OPTIONS).

cmd cget key
Get value of one of icq options (see OPTIONS).

cmd status ?status?
Set new status or retreive current status, if status parameter is omitted. status can be one of: offline, online, away, na, dnd, occ, ffc, invisible (see ICQ STATUS section). The default status (if no status was previously set) is offline. This commands always returns current status, which can differ from new status, because it requries certain time to icq server set and confirm new status.

cmd send type recipient message
?message-id? Send message of given type to recipient. message and recipient parameters depend on message type (see MESSAGE TYPES section). Optional argument message-id is used to explicitly specify message identifier. It's format is two hexadecimal numbers delimited with colon. It's only purpose is to provide ability to re-send message with same identifier for proper acknowledgements.

cmd password password ?ref?
Change own login password to password. Additional parameter ref can be used for identification of acknowledge event OK:Password. ref can be any integer number in the range 0-255. This subcommand returns event reference.

cmd info uin ?ref?
Query contact information in ICQ whitepages by ICQ UIN. Additional parameter ref can be used for acknowledgement identification (see password method). Returns event reference.

cmd personal ?info?
Query or change personal information in ICQ whitepages. Returns event reference.

cmd search filter
Search for ICQ contacts in ICQ whitepages by provided filter. Filter is a list of key-value pairs, where key identifies field name and value - value of the field in whitepages.

cmd roster ?action? ?item? ?...?
Add, delete or modify items in server-side roster. action should be one of add, delete or update. Each item is a list and consists of following elements: type, id, name, additional information. Type should be contact or group. Id is numerical identifier in the range 0-32767. Name is ICQ UIN for contact or group name for group. Additional information is a key-value list of additional properties.

cmd contacts list ?action? ?uins?
Get or change one of ICQ contact lists. List is specified with list parameter and can be one of: all visible invisible. If uins is omitted current content of specified list returned, otherwise contents of the list modified according to action parameter with uins list values. action is one of add, delete. Default action is add.

cmd encoding ?encoding? ?uins?
Query or set encoding for non-unicode messages. If uins parameter is omitted, the default encoding queried or set. Default encoding is used if no encoding specified for contact. If uins parameter is specified, it should be UIN or list of UINs, and given encoding associates with these UINs only. This method returns current assotiated encoding.

cmd delete
Close connection and delete command cmd.

EVENTS

Events is the main way of getting information from ICQ server. To process events callback script should be defined in icq command or configure method. When one of events occurs, callback script invoked using eval command, with event name and event parameters (if any) added to script.

Log tags string
Error code ?description?
Error:Protocol handler reason packet
Status uin status ?ip?
Reports new ICQ status of contact \fIuin\fR when it is changed. Note, that icq package does not keep statuses of contacts in contacts list, thus you should handle this event if you want know status of contact in any time.

MyStatus uin
Birthday uin
ShowIp uin
LanDetails uin addr port type
SignupDate uin date
SignonDate uin date
Client uin version client unicode-flag
Additional information about client program of contact. version is version of ICQ protocol, usually it is one of 7, 8, 9. client is the name of ICQ client contact uses. It is determined by indirect properties and not always correct. unicode-flag is boolean value which is set to true if client supports unicode text and false otherwise.

Roster roster time
Roster:OK timestamp size
ACK type uin id
Acknowledgement on message sent. Type can be one of client, server or sent. client acknowledgement is sent when client receives your message, server - when ICQ server receives your message while recipient is offline. sent acknowledgement is sent when outgoing message is actually sent.

Info ref info
SearchResults ref info
PasswordChanged ref
Incoming type sender time message
Incoming message message of type type (see MESSAGE TYPES) from sender sent at time. Time is given in seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Outgoing type recipient time message msgid
Outgoing message message of type type (see MESSAGE TYPES) to recipient sent at time. Time is given in seconds since the Epoch (00:00:00 UTC, January 1, 1970). msgid is message identifier used in acknowledgements to identify the message.

Capabilities uin capabilities
List of capabilities (see CAPABILITIES) of ICQ client used by contact uin.

Registered uin
RegistrationRefused

ICQ STATUS

The following statuses are supported in ICQ network:

offline
No connection to ICQ server, not registered in ICQ network.

online
Connected to ICQ server and successfully logged in ICQ network. This is primary status.

away
Indicates that contact is online, but away from computer for short period of time.

na
Not awailable. Indicates that contact is online, but away from computer for a long period of time.

dnd
Do not disturb. Indicates that contact is online but does not want to receive messages from anyone now.

occ
Occupied. Indicates that contact is occupied and will answer only on important messages.

ffc
Free for chat. Indicates that contact is not occupied and can chat with anyone who wants it.

invisible
Indicates that contact is in invisible mode.

Note, that offline status differs from other ones - when status is offline no network connection required. This means that switching from offline to another status implies connecting to ICQ server, and switching to offline implies closing connection to ICQ server.

MESSAGE TYPES

ICQ protocol allows different kinds of intormation be sent or received. icq library supports following types of messages in send method and Incoming and Outgoing events. In most message types sender or recepient is ICQ UIN, unless other specified in type description.

text
Most common type of message. It represents just text strings which ICQ clients send to each other when chatting. Additionaly text can contain information about background and foreground colors.

web
Represents message sent from web client on icq.com. The difference with text type is that sender is not ICQ contact, but list of three elements: name, e-mail and IP address of sender. This type can appear only in Incoming events

URL
URL message is a list of two elements: URL and URL description.

SMS
SMS type can be used to send message to contact's cell phone. This type is can only be sent and never appears in Incoming event.

contacts
Contatacts message is used to send a list of contacts to recepient. Message of this type is a list with even number of elements representing url-alias pairs of form {uin alias uin alias ...}.

authorization
Accept or reqject authorization request from contact. Authorization message can be one of the words grant or deny to grant or deny authorization respectively.

authrequest
Autorization request. This message is sent to ICQ contact when you desire to be included in recipient's contact list. When sending this message via send method, message conent is just a text string representing short message for recepient. However, in Incoming event message it is a list, having following elements: nick, first name, last name, email, auxilliary info, autorization request message.

included
Message of this type appears only in Incoming event and indicates that you was included in sender's contact list. Content of the message is empty string.

auto
Same as text, but it is sent automatically by program as a responce to common message or to away, occ, dnd, na, ffc messages. Message of this type is never sent explicitly.

away
Request "away" autoresponce. Contact sends message of type auto as a responce.

occ
Request "occupied" autoresponce. Contact sends message of type auto as a responce.

dnd
Request "do not disturb" autoresponce. Contact sends message of type auto as a responce.

na
Request "not available" autoresponce. Contact sends message of type auto as a responce.

ffc
Request "free for chat" autoresponce. Contact sends message of type auto as a responce.

CAPABILITIES

Capabilities can be used for icq client identification or other client-specific purposes. Each capability is a string of 32 hexadecimal didits, representing 16 byte sequence or one of pre-defined aliases. If specified capabililty is longer than 32 characters it is truncated, and filled with zeroes to 32 characters if shorter. There is a set of pre-defined capabilities aliases. They are:

ICQ
Client is ICQ client, not AIM client.

RELAY
Client understands type-2 messages with acknowledgements.

UTF8
Client understands unicode messages in UTF-8 encoding.

RTF
Client understands messages in Rich Text Format.

STR_2001
This capability is sent by ICQ2001.

STR_2002
This capability is sent by ICQ2002.

IS_2001
This capability is sent by ICQ2001.

LICQ
This capability is sent by Licq.

WEB
This capability is sent by ICQ Lite and icq2go (java applet).

TRILL_UNK
Unknonw capability sent by Trillian.

TRILL_CRYPT
This capability is sent by Trillian and indicates support of encripted messages.

AIM_SENDFILE
AIM client send it if supports sending files.

AIM_GETFILE
AIM client send it if supports receiving files.

AIM_CHAT
AIM client send it if supports chat.

AIM_VOICE
AIM specific capability.

AIM_ICON
AIM specific capability.

AIM_IMAGE
AIM specific capability.

AIM_STOCKS
AIM specific capability.

AIM_GAMES
AIM specific capability.

AIM_BUD
AIM specific capability.

AIM_INTEROPERATE
This capability allows ICQ clients send messages to AIM contacts and AIM clients to ICQ contacts.

Sim
Indicates that client is Sim.

mICQ
Indicates that client is mICQ.

LONG MESSAGES SPLITTING

icq package can automatically split long text messages when sending them through the server. If recipient of such messages is icq-based clilent too, it can combine message from chunks transparently. Special glue sequence (<...>) is used to mark first, last and inner chunks. First chunk only ends with glue sequence, last chunks only beginning with glue sequence, inner chunks begin and end with glue sequences. Such approach allows determine end of long message, detect previous incomplete long messages, and compatible with other ICQ clients which do not support message splitting. Moreover, it allows custom creation of pseudo-long messages, i.e. send messages with glue which will be interpreted as one long message by recipient. The possible problem with combining long messages is that receiver does not know when last chunk arrive, thus incomplete message can be stored in chunk cache forever, if last chunk is lost. To prevent such situation, incomplete message ``pushed'' to event script if no messages from same UIN received during timeout. Default timeout is 10 minutes, and can be specified when creating icq command or via configure method.

EXAMPLES

Generic template for ICQ events handling

 
proc Event {event args} {
	if {[llength [info commands ICQ::$event]]} {
		eval ICQ::$event $args
	} else {
		puts "No handler for ICQ event $event"
	}
}
set icq [icq::icq 47298730 xxx -port 1024\\
	-reconnect yes -events Event]
$icq status online
vwait fin

Simple ICQ robot to report Unix machine status

 
proc Event {event args} {
	if {[llength [info commands ICQ::$event]]} {
		eval ICQ::$event $args
	} 
}
namespace eval ICQ {
	global icqcmd
	proc Incoming {type sender time msg} {
		if {$type!="text"} return
		set f [open "|uptime", r]
		$icqcmd send text $sender [read $f]
		close $f
	}
}

set icqcmd [icq::icq 47298730 xxx -port 1024\\
	-reconnect yes -events Event]
$icqcmd status online
vwait fin

AUTHOR

icq package and this man page was written by Ihar Viarheichyk <iverg@mail.ru>

SEE ALSO

alicq(1), alicqrc(5), proxy(n)

KEYWORDS

icq, messenger, protocol