The ICQLINK struct

The ICQLINK type is a type definition of struct icq_link. This long structure is defined in lines 69-207 of the code. Its one purpose is to hold information on a single ICQ session.

Let's take a close look at the struct:

General (lines 71-78):

In this sections you will find variables that hold general information about the connection such as the UIN of the user, its nickname and password, the local IP and port and the ICQ status of the user.

You should refer to this information as ``read only''. If you need your current UIN or need to know your status, you can use them but unless you really know what you're doing, don't try to change them by yourselves. This is why you have icqlib, to manage this information correctly without you having to worry about parsing network response and things like that.

UDP (lines 81-86) and TCP (lines 89-96):

As you know, the ICQ network is composed of all sorts of UDP and TCP links. These two sections hold information that is required for the icqlib in order to maintain these connections. This includes mainly socket file descriptors and related structures.

Again, do not touch unless you know what you're doing. I don't see a reason why you would even want to read this information for most basic purposes.

Proxy (lines 99-109):

Well, naturally you'll find the proxy settings here. Since we did not use the proxy feature in the csicq project, we prefer not to review it in this document.

Callbacks (lines 112-206):

This is a set of pointers to functions⁶ to which you assign the callbacks.

Unlike the previous sections, you would usually refer to these as ``write only''. After initializing your connection, you will assign your callbacks to where they belong and just forget about it for the rest of the session.

The callbacks determine how your connection reacts to events. In the previous section we described the icq_RecvMessage callback. Now let's take a different example: icq_UserOnline (line 150). Naturally when programming a client, you would like to notify the user when a member of the contact list comes online. Say you have some graphic front-end and you'd like to paint the name of that user in blue (just an example).

The prototype of icq_UserOnline is:

void (*icq_UserOnline)(struct icq_link *link, unsigned long uin, unsigned long status, unsigned long ip, unsigned short port, unsigned long real_ip, unsigned char tcp_flag );

Now what we do is first write a function that does what we want to do (paint the name of the user in blue):

void my_UserOnline(struct icq_link *link, unsigned long uin, unsigned long status, unsigned long ip, unsigned short port, unsigned long real_ip, unsigned char tcp_flag )
{
paint_it_in_blue(uin);
/* Or just do whatever you want to do when a user goes online. */
return;
}

And then all you have to do is ``plug it in'' after the initialization of the connection (we will elaborate on the initialization process later):

link.icq_UserOnline = &my_UserOnline;

And from that moment, whenever icqlib identifies a message from the ICQ network saying some user from your contact list went online, your callback function (my_UserOnline in our example) will be called.