This is rather roughly written at the moment. Please forgive any grammar mistakes I made when I rushed this together. -Claudio ----- IMCOMM REFERENCE GUIDE 1. Data structures IMComm operates on "handles," which are simply structures filled with the information IMComm needs for one single IM session. In order to allow multiple connections per program, IMComm leaves the pointers to those structures up to the user. Users should use a void * pointer to set up the structure. Example: void *handle; handle = imcomm_create_handle(); 2. Callbacks All IMComm events operate on callbacks. The list of events can be found in imcomm.h. Developers should register the callbacks after creating a handle and before signing on. Example: imcomm_register_callback(handle, IMCOMM_IM_INCOMING, incoming_im); This will make the library call the function incoming_im when an incoming message is received on the conncection pointed by handle. The first parameter a for any called back function is the handle. Following that, the parameter varies based on the event type. 3. Signing on Signing on is rather simple. imcomm_im_signon(handle, username, password); 4. Errors and status All errors are handled using callbacks. To register the error callback, use the IMCOMM_ERROR callback ID with imcomm_register_callback(); The error types are in an enumerated list in imcomm.h for example: void error_cb(void *handle, int event) { switch(event) { case IMCOMM_STATUS_CONNECTED: printf("Connected.\n"); break; } } EVENTS CURRENTLY IMPLEMENTED: IMCOMM_IM_SIGNON (void *handle, char *who) Buddy has come online. IMCOMM_IM_SIGNOFF (void *handle, char *who) Buddy has gone offline. IMCOMM_IM_BUDDYAWAY (void *handle, char *who) Buddy is away. IMCOMM_IM_BUDDYUNAWAY (void *handle, char *who) Buddy is no longer away. IMCOMM_IM_IDLEINFO (void *handle, char *who, long idletime) Buddy's idletime, reported in minutes. IMCOMM_IM_INCOMING (void *handle, char *who, int automessage, char *message) has sent you a message. If automessage is 1, then the message is an auto response. IMCOMM_IM_PROFILE (void *handle, char *who, char *profile) Buddy's profile after a profile request. IMCOMM_IM_AWAYMSG (void *handle, char *who, char *msg) Buddy's away message after a away message request. IMCOMM_ERROR (void *handle, int errortype, void *ptr1, void *ptr2, void *ptr3) Error of error . ptr1-3 are currently unused. FUNCTIONS FOR PROGRAMMERS imcomm_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout) This is where the main work is done. It behaves just like a standard select() call, meaning it can be used to multiplex keyboard input and AIM input. It cycles through every handle known to IMComm (a list is kept internally), checking for input and processing if necessary. Example: fd_set readfs; struct timeval tm; while(1) { FD_ZERO(&readfs); FD_SET(fileno(stdin), &readfs); tm.tv_sec = 1; tm.tv_usec = 15; /* * this will check fileno(stdin) AND all of the * sessions currently established. */ imcomm_select(fileno(stdin), &readfs, NULL, NULL &tm); if(FD_ISSET(fileno(stdin))) { /* keyboard input handler */ } } imcomm_set_profile(void *handle, char *profile); Sets the user profile. imcomm_set_away(void *handle, char *msg); Sets away message. imcomm_set_unaway(void *handle); Unsets away message. imcomm_im_send_message(void *handle, const char *whom, const char *msg, int automsg); Sends message to user . If automsg is 1, then it is sent as an auto response. imcomm_request_profile(void *handle, char *sn); Requests profile for user . imcomm_request_awaymsg(void *handle, char *sn); Requests away message for user . imcomm_im_add_buddy(void *handle, char *sn); Adds buddy to session buddy list. imcomm_im_remove_buddy(void *handle, char *sn); Removes buddy from session buddy list. imcomm_compare_nicks(void *handle, char *sn1, char *sn2) Compares two screen names, ignoring spaces and case. char *imcomm_simplify_sn(char *sn) Returns a simplified version of a screen name, all lowercase with no spaces. Note that you must free this string later, since it is malloc'ed by imcomm.