icq(n) 0.8.6 "icq protocol handling command"
icq - icq protocol handling command
package require icq 0.8.6
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.
- -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".
- 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 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
-
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.
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 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.
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.
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
|
icq package and this man page was written by
Ihar Viarheichyk <iverg@mail.ru>
alicq(1), alicqrc(5), proxy(n)
icq, messenger, protocol