1.1.1 action methods

These are the ``do things'' methods. Many of them return a ``sequence number'' which will then match up to calls to RequestNotify.

SetProxy (phost, pport, [pname, ppass])
Use host:port as your proxy, with supplied authentication information as necessary.

Returns None.

UnsetProxy ()
Do not use a proxy for this connection.

Returns None.

Connect ([hostname, port])
Connect to the server. Defaults to Connect("icq.mirabilis.com",4000).

Returns the fd of the UDP socket connecting us to the server.

Disconnect ()
Disconnected from the server.

Returns None.

GetSok ()
Returns the fd of the UDP socket connecting us to the server.

GetProxySok ()
Returns the fd of the TCP socket connecting us to the proxy.

HandleServerResponse ()
This function is the main magic for UDP (client/server) communication. So if there is something on UDP socket (GetSok), call HandleServerResponse. Use this method if you'd like to handle all sockets yourself instead of Main function. Be aware that TCP isn't yet working this way and you'll need to call TCPMain constantly to be able to use TCP part of the protocol (client-client or peer-to-peer)

Returns None, though an exception raised in a callback will be propogated.

HandleProxyResponse ()
Like for HandleServerResponse, but should be called when there's something on the proxy socket (GetProxySok).

Returns None, though an exception raised in a callback will be propogated.

HandleTimeout ()
The SetTimeout callback asks the client app to install a timeout timer and call HandleTimeout function back when the timeout has elapsed.

Returns None.

Main ()
The core of icqlib. Respond to a packet from the server, if there is one in the queue. Call this frequently - i.e. every 10 milliseconds or so.

Returns None, though an exception raised in a callback will be propogated.

KeepAlive ()
Tell the server we're still here - must be called every 2 minutes or so.

Returns a sequence number - which is a bit pointless. Ignore it.

Login ([status])
Attempt to login to the server connected to with a call to Connect, and set your status to status (which defaults to STATUS_ONLINE).

Returns None.

Logout ()
Log out from the server.

Returns None.

SendContactList ()
Syncronise the server's idea of the contact list with the client's. You will get UserOnline/UserStatusUpdate/UserOffline callbacks for users on your contact list, which can be manipulated with ContactAdd and ContactRemove.

Returns None.

SendVisibleList ()
Syncronise the server's idea of the visible list with the client's. Users on your visible list can see you when you are invisble. You can manipulate the visible list with ContactSetVis.

Returns None.

SendInvisibleList ()
Syncronise the server's idea of the invisible list with the client's. Users on your invisible list can see you, even when you are visble. You can manipulate the invisible list with ContactSetVis.

Returns None.

SendNewUser (cuin)
Add a new contact to the server's idea of your contact list; you should have called ContactAdd(cuin) first.

Returns None.

SendMessage (uin, text, [thruSrv])
Send message text to user uin. thruSrv can be one of ICQ_SEND_THRUSERVER, ICQ_SEND_DIRECT or ICQ_SEND_BESTWAY (the default).

Returns a sequence number.

SendURL (uin, url, descr, [thruSrv])
Send url url with description descr to user uin. thruSrv can be one of ICQ_SEND_THRUSERVER, ICQ_SEND_DIRECT or ICQ_SEND_BESTWAY (the default).

Returns a sequence number.

ChangeStatus (status)
Change your status to, well, status. I don't really understand how the values in ICQLIB match up with what you want to pass in here, but I'm sure you can work it out ;-).

Returns None.

SendInfoReq (uin)
Request info about user uin; InfoReply will be called in due course.

Not sure what the return value (some kind of sequence number) is for...

SendExtInfoReq (uin)
Request extra info about user uin; ExtInfoReply will be called in due course.

Not sure what the return value (some kind of sequence number) is for...

SendAuthMsg (uin)
Allow user uin to add you to their contact list. (This is one of the more amusing ``security'' features of icq - the official Mirabilis client is generally the only one to actually ask...).

Returns a sequence number.

SendSearchReq (email, nick, first, last)
Search for a user with specified details (which may be None). UserFound will be called for each matching user, then SearchDone.

Returns None.

SendSearchUINReq (uin)
Search for a user by uin. I imagine this also results in calls to UserFound and SearchDone.

Returns None.

RegNewUser (pass)
XXX I don't understand new user voodoo.

Returns None.

UpdateUserInfo (nick, first, last, email)
Update your information in the server's user database.

Returns a sequence number.

UpdateAuthInfo (auth)
Update your authorization status (i.e. do you want users to require your permission to add you to their contact lists?). Note that this only concerns the Mirabilis client, as most clones allow their users to override this setting.

Returns a sequence number.

UpdateMetaInfoSet (nick, first, last, email, email2, email3, city, state, phone, fax, street, cellular, zip, cnt_code, cnt_stat, emailhide)
Lose your privacy!

Returns a sequence number.

UpdateMetaInfoHomepage (age, homepage, year, month, day, lang1, lang2, lang3)
Lose your privacy!

Returns a sequence number.

UpdateMetaInfoAbout (about)
Lose your privacy!

Returns a sequence number.

UpdateMetaInfoSecurity (reqauth, webpresence, pubip)
Retain your privacy! But only with users of official clients!

Returns a sequence number.

UpdateNewUserInfo (nick, first, last, email)
XXX I don't understand new user voodoo.

Returns a sequence number.

SendMetaInfoReq (uin)
Arrange for callbacks to MetaUser*.

Returns a sequnce number.

ContactAdd (cuin)
Add user cuin to your contact list; this does not affect the server's idea of your contact list until you call SendContactList.

Returns None.

ContactRemove (cuin)
Remove user cuin from your contact list; this does not affect the server's idea of your contact list until you call SendContactList.

Returns None.

ContactClear ()
Remove all users from your contact list; this does not affect the server's idea of your contact list until you call SendContactList.

Returns None.

ContactSetVis (cuin, vu)
Add or remove user cuin from your visible list (a user on your visible list can see you when you are invisible) as determined by vis; this does not affect the server's idea of your visible list until you call SendVisibleList. Has no effect at all if cuin is not on your contact list.

Returns None.

TCPMain ()
This is called by Main. I don't know why it has a separate existence.

Returns None, though an exception raised in a callback will be propogated.

TCPSendMessage (uin, message)
Send a message via TCP (as opposed to, presumably, UDP). Don't know why you'd want to do this, but isn't it nice that you can?

Returns a sequence number.

TCPSendURL (uin, message, url)
Send a URL via TCP (as opposed to, presumably, UDP). Don't know why you'd want to do this, but isn't it nice that you can?

Returns a sequence number.

SendChatRequest (uin, message)
Send a chat request to uin.

Returns a sequence number.

AcceptChatRequest (uin, seq)
Accept a chat request. Get seq from a call to RecvChatRequest.

Returns None.

TCPSendChatData (uin, data)
Send chat data to uin. Don't know how this works in detail.

Returns None.

TCPSendChatData_n (uin, data)
Send chat data to uin. Don't know how this works in detail. You can send NULLs using this method; otherwise I fail to see how this differs from TCPSendChatData.

Returns None.

TCPCloseChat (uin)
End a chat session.

Returns None.

CancelChatRequest (uin, sequence)
Give up waiting for user uin to respond to a chat request.

Returns None.

RefuseChatRequest (uin, sequence, reason)
Refuse the chat request from uin; get sequence from a call to RecvChatReq and say why in reason.

Returns None.

AcceptFileRequest (uin, sequence)
OK: dodgy terminology - in accepting a file request, you are agreeing to receive some files! I'm not going to document file transfers yet as I haven't even tried to use them.

Returns a ICQFileSession object.

SendFileRequest (uin, message, files)
OK: dodgy terminology - a file request is a request to *send* some files! So this function asks cuin if they would like to receive files - which must be a list of filenames. I'm not going to document file transfers yet as I haven't even tried to use them.

Returns a sequence number.

CancelFileRequest (uin, sequence)
Give up waiting for user uin to respond to your file request.

Returns None.

RefuseFileRequest (uin, sequence, reason)
Refuse the file request from uin; get sequence from a call to RecvFileReq and say why in reason.

Returns None.