General structure of the icqlib code

The functionality of the icqlib could be roughly divided into two major parts:

Passive functions (handlers, callbacks).

Handlers are invoked by the network⁵ in response to certain events.

Lets say someone sent you an ICQ message. How can you tell that this has happened? Well, the ICQ network will send you packets describing the message (the beauty of using icqlib is that you do not need to know how these packets are composed nor how they are interpreted). The icqlib code will listen on the network (we will explain how to we make it listen later on) and upon receiving and interpreting those packets, it will invoke the correct handler. In this example this would be the icq_RecvMessage handler (line 114).

But what is the functionality of the handler itself? Now that is up to you. It is up to the programmer to program the handlers and assign them to the correct place in the ICQLINK struct (we will elaborate on that a great deal later).

Active functions.

Okay, so we know (in general terms) what happens when the network informs you of something. But what if you want to notify the ICQ network of some event? Say you want to send a message to a friend?

Well, what you do is just call the icq_SendMessage (line 234) function with the appropriate arguments and icqlib will wrap your message and send them to the ICQ network in the correct format.

Other than things you might want to do, there are also things you have to do in order to be connected to the ICQ network. This includes connecting to the server and logging in to the network (of course) and letting the network know you are still connected (namely keepalive). There are functions for all of these (and more) which will be discussed further along this document.

In the next section we will see exactly how these two types of functions are implemented in the code.