191 lines
4.2 KiB
Plaintext
191 lines
4.2 KiB
Plaintext
|
|
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 <who> has come online.
|
|
|
|
IMCOMM_IM_SIGNOFF
|
|
(void *handle, char *who)
|
|
|
|
Buddy <who> has gone offline.
|
|
|
|
IMCOMM_IM_BUDDYAWAY
|
|
(void *handle, char *who)
|
|
|
|
Buddy <who> is away.
|
|
|
|
IMCOMM_IM_BUDDYUNAWAY
|
|
(void *handle, char *who)
|
|
|
|
Buddy <who> 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)
|
|
|
|
<who> 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 <errortype>. 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 <whom>. If automsg is 1, then it is sent as
|
|
an auto response.
|
|
|
|
imcomm_request_profile(void *handle, char *sn);
|
|
|
|
Requests profile for user <sn>.
|
|
|
|
imcomm_request_awaymsg(void *handle, char *sn);
|
|
|
|
Requests away message for user <sn>.
|
|
|
|
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.
|