Quote:
ICQ's API Reference Guide
Version 0x00010001
20/2/98
Document Conventions
API functions descriptions will follow this general format (for calls and notifications):
Call Name
In (Arguments): The list of arguments and their explanation.
Out (Returns): The list of arguments and their explanation found in the data returned.
Description: A more verbose description of the purpose of the call, and how ICQ will handle it in general.
Notification Name
Code: The notification code (ICQAPINOTIFY_xxx)
In (Arguments): The list of arguments passed to the notification function and their explanation.
Description: A more verbose description of the purpose of the notification, and how ICQ will handle it in general.
Using the ICQ API
ICQ API is a set of functions implemented in a DLL. The API enables the query of data from the ICQ Client,
initiating operations in the client and getting notifications from the client asynchronously.
In order to use the API, the application must call first the ICQAPICall_SetLicenseKey function once. Only then, may other functions be called.
The current revision of ICQ's API can be retrieved using the ICQAPICall_GetVersion query. It is suggested that you make use of this query in order to maintain compliance with ICQ's API.
The ICQ API is composed of calls and notifications.
All calls are synchronous with a timeout of 1 second, thus if the ICQ Client did not reply in 1 second, the call is regarded as failed. Every call returns a boolean value, TRUE means success, while FALSE mean failure.
Notifications are sent back from ICQ Client using a 1 second timeout, thus if the application did not reply in 1 second, the notification is regarded as a failure and the application will not get anymore notifications.
If your application registered to get notifications from ICQ (using the ICQAPICall_RegisterNotify), it should unregister from ICQ once it doesn’t need these notifications anymore (using the ICQAPICall_UnRegisterNotfiy).
To register notifications 2 simple steps should be done:
1. A function must be supplied to handle the notification. This is done through the utility function ICQAPIUtil_SetUserNotificationFunc. The function is supplied with the required notification code and the developer’s notification function. The given function should be defined with the WINAPI (i.e. __stdcall) modifier.
2. After setting all the notification functions, an ICQAPICall_RegisterNotify call should be made for notifications to start arriving from the ICQ Client.
The description of these functions can be found in the reference ahead.
ICQ API FILES
ICQMsgAPI.lib - The ICQAPI library file.
ICQMsgAPI.dll - The ICQAPI dll itself.
ICQAPINotifications.h - the ICQAPI main header file. This file includes the following headers :
ICQAPICalls.h
ICQAPIData.h
ICQAPIInterface.h
API Reference
Calls
1. ICQAPICall_GetDockingState
2. ICQAPICall_GetFirewallSettings
3. ICQAPICall_GetFullOwnerData
4. ICQAPICall_GetFullUserData
5. ICQAPICall_GetOnlineListDetails
6. ICQAPICall_GetOnlineListPlacement
7. ICQAPICall_RegisterNotify
8. ICQAPICall_SetLicenseKey
9. ICQAPICall_SendFile
10. ICQAPICall_UnRegisterNotify
11. ICQAPICall_GetVersion
12. ICQAPICall_GetWindowHandle
// Version 1.0001
13. ICQAPICall_GetOnlineListType
14. ICQAPICall_GetGroupOnlineListDetails
15. ICQAPICall_SetOwnerState
16. ICQAPICall_SetOwnerPhoneState
17. ICQAPICall_SendMessage
18. ICQAPICall_SendURL
19. ICQAPICall_SendExternal
Notifications
1. ICQAPINotify_OnlineListChange
2. ICQAPINotify_FullUserDataChange
3. ICQAPINotify_AppBarStateChange
4. ICQAPINotify_OnlinePlacementChange
5. ICQAPINotify_OwnerChange
6. ICQAPINotify_OwnerFullUserDataChange
7. ICQAPINotify_OnlineListHandleChange
8. ICQAPINotify_FileReceived
Utility Functions
1. ICQAPIUtil_FreeUser
2. ICQAPIUtil_FreeUsers
3. ICQAPIUtil_SetUserNotificationFunc
Data Structures
1. BSICQAPI_FireWallData
2. BSICQAPI_User
CALLS
ICQAPICall_GetDockingState
BOOL WINAPI ICQAPICall_GetDockingState(int &iDockingState);
In (Arguments): None
Out (Returns): iDockingState
iDockingState is the current docking state of the ICQ main window
0 - floating
1 - docked right
2 - docked left
3 - docked top
4 - docked bottom
Description: The function returns the current docking state of the ICQ main window.
ICQAPICall_GetFirewallSettings
BOOL WINAPI ICQAPICall_GetFirewallSettings(BSICQAPI_FireWallData &oFireWallData);
In (Arguments): None
Out (Returns): oFireWallData
oFireWallData - the stuct is filled with the current firewall data configured in the client.
Description: the function fills the given firewall structure with the current firewall details.
ICQAPICall_GetFullOwnerData
BOOL WINAPI ICQAPICall_GetFullOwnerData(BSICQAPI_User **ppUser, int iVersion);
In (Arguments): ppUser , iVersion
ppUser - a pointer to a pointer to a user struct (BSICQAPI_USER).
iVersion - the ICQ API version the caller application expect to work with.
Out (Returns): pUser
ppUser - a pointer to a struct filled with the current owner data
Description: the function allocates a user structure and fills it with the current owner details. The caller should free the structure using the ICQAPIUtil_FreeUser.
ICQAPICall_GetFullUserData
BOOL WINAPI ICQAPICall_GetFullUserData(BSICQAPI_User *pUser, int iVersion);
In (Arguments): pUser , iVersion
pUser - a pointer to a user struct (BSICQAPI_USER) with the m_iUIN field set to the user ICQ#.
iVersion - the ICQ API version the caller application expect to work with.
Out (Returns): pUser
pUser - the struct is filled with the user’s data
Description: the function fills the given user structure with the user’s details.
ICQAPICall_GetOnlineListDetails
BOOL WINAPI ICQAPICall_GetOnlineListDetails(int &iCount, BPSICQAPI_User **ppUsers);
In (Arguments): None
Out (Returns): iCount, ppUsers
iCount - the number of Users to follow
ppUsers - a pointer to the users’ array.
Description: The data returned is in the order of the online list, top to bottom. The users array is initialized with the user’s ICQ# (m_iUIN field) and the Window Handle (m_hFloatWindow) if the user is “floating”. The users array should be freed by calling ICQAPIUtil_FreeUsers to free each user structure and the array itself.
ICQAPICall_GetOnlinePlacement
BOOL WINAPI ICQAPICall_GetOnlineListPlacement(int &iIsShowOnlineList);
In (Arguments): None
Out (Returns): iIsShowOnlineList
Description: iIsShowOnlineList - nonzero value indicates that the Online tab appears above the contact list.
ICQAPICall_RegisterNotify
BOOL WINAPI ICQAPICall_RegisterNotify(int iVersion, int iCount, BYTE *piEvents);
In (Arguments): iVersion, iCount, piEvents
iVersion - the ICQ API version the caller application expect to work with.
iCount - the size of the piEvents byte array.
piEvents - byte array of notification events codes the application wants to be notified about.
Out (Returns): None
Description: This call registers the given application in the ICQ notification list. The application will receive notifications for the events it requires. The byte array represents event codes to be notified on.
Multiple applications can be registered with this call, none will be denied. Note that if the application is already registered, the specified notification events will override the current ones.
ICQAPICall_SetLicenseKey
BOOL WINAPI ICQAPICall_SetLicenseKey(char *pszName, char *pszPassword, char *pszLicense);
In (Arguments): pszName, pszPassword, pszLicense
pszName - the application developer name.
pszPassword - the application developer chosen password
pszLicense - the license key the application developer got while applying for the API.
Out (Returns): None
Description: The function enables the use of the ICQ API. It needs to be called only once per session.
ICQAPICall_SendFile
BOOL WINAPI ICQAPICall_SendFile(int iUIN, char *pszFileNames);
In (Arguments): iUIN, pszFileNames
iUIN - the user ICQ# to which the files should be sent.
pszFileNames - a list of file names separated by commas.
Data (Returns): None
Description: The fucntion opens ICQ’s send file dialog, with the selected user and files.
ICQAPICall_UnRegisterNotify
BOOL WINAPI ICQAPICall_UnRegisterNotify();
In (Arguments): None
Out (Returns): None
Description: Use this to call to disconnect from the ICQ notification mechanism established by the ICQAPICall_RegisterNotify calls.
ICQAPICall_GetVersion
BOOL WINAPI ICQAPICall_GetVersion(int &iVersion);
In (Arguments): None
Out (Returns): iVersion
iVersion - the version of the API which the ICQ Client is using. The high word is the major version, the low word the minor.
Description: All applications which plan to check for compatibility with the ICQ API implementation should use this call.
ICQAPICall_GetWindowHandle
BOOL WINAPI ICQAPICall_GetWindowHandle(HWND &hWindow);
In (Arguments): None
Out (Returns): hWindow
hWindow - the handle of the main ICQ window.
Description: Gets the window handle of the ICQ Client main window.
ICQAPICall_GetOnlineListType
BOOL WINAPI ICQAPICall_GetOnlineListType(int &iListType);
In (Arguments): None
Out (Returns): iListType
iListType - the current contact list – 0 – regular mode, 1 – group mode.
Description: Returns the code of the list currently shown in the ICQ Client main window.
ICQAPICall_GetGroupOnlineListDetails (version 1.0001)
BOOL WINAPI ICQAPICall_GetGroupOnlineListDetails(int &iGroupCount, BPSICQAPI_Group **ppGroups);
In (Arguments): None
Out (Returns): iGroupCount, ppGroups
iGroupCount - count of the groups returned in the ppGroups array.
ppGroups - array of pointers to groups of users
Description: The data returned is in the order of the online list, top to bottom. The ppGroups groups array is initialized with the group name and an array of user which is initialized with the ICQ# (m_iUIN field). The groups should be freed one by one by calling ICQAPIUtil_FreeGroup to free each group structure and the array itself.
ICQAPICall_SetOwnerState (version 1.0001)
BOOL WINAPI ICQAPICall_SetOwnerState (int iState);
In (Arguments): iState
iState – the owner requsted state.
BICQAPI_USER_STATE_ONLINE 0
BICQAPI_USER_STATE_CHAT 1
BICQAPI_USER_STATE_AWAY 2
BICQAPI_USER_STATE_NA 3
BICQAPI_USER_STATE_OCCUPIED 4
BICQAPI_USER_STATE_DND 5
BICQAPI_USER_STATE_INVISIBLE 6
BICQAPI_USER_STATE_OFFLINE 7
Out (Returns): None
Description: The function sets the current owner state to that was specified by iState.
ICQAPICall_SetOwnerPhoneState (version 1.0001)
BOOL WINAPI ICQAPICall_SetOwnerPhoneState(int iPhoneState);
In (Arguments): iPhoneState
iPhoneState - the owner requested phone state: 0 - Unavailable, 1 - Available
Out (Returns): None
Description: The function sets the current phone owner state to that was specified by iPhoneState
(same as changing it through the services menu on the client).
ICQAPICall_SendMessage (version 1.0001)
BOOL WINAPI ICQAPICall_SendMessage(int iUIN, char *pszMessage);
In (Arguments): iUIN, pszMessage
iUIN - the ICQ# to whom the message will be sent
pszMessage - the message text
Out (Returns): None
Description: The function opens the message request dialog of the given user with the text field initialized with the given message.
ICQAPICall_SendURL (version 1.0001)
BOOL WINAPI ICQAPICall_SendURL (int iUIN, char *pszMessage);
In (Arguments): iUIN, pszMessage
iUIN - the ICQ# to whom the message will be sent
pszURL - the URL text
Out (Returns): None
Description: The function opens the message request dialog of the given user with the text field initialized with the given message.
ICQAPICall_SendExternal (version 1.0001)
BOOL WINAPI ICQAPICall_SendExternal(int iUIN, char *pszExternal, char *pszMessage, BYTE bAutoSend);
In (Arguments): iUIN, pszExternal, pszMessage, bAutoSend
iUIN – the ICQ# to whom the external will be sent
pszExternal – the external application name as it appears in the ICQ user menu
pszMessage - the message text
bAutoSend – the value 1 to send the event without opening the send external dialog
Out (Returns): None
Description: The function opens the message request dialog of the given user with the text field initialized with the given message.
NOTIFICATIONS
ICQAPINotify_AppBarStateChange
void WINAPI ICQAPINotify_AppBarStateChange(int iDockingState);
Code: ICQAPINOTIFY_APPBAR_STATE_CHANGE
In (Arguments): iDockingState
iDockingState is the new docking state
0 - floating
1 - docked right
2 - docked left
3 - docked top
4 - docked bottom
Description: Sent if the contact list docking status has changed.
ICQAPINotify_FileReceived
void WINAPI ICQAPINotify_FileReceived (char *pszFileNames);
Code: ICQAPINOTIFY_FILE_RECEIVED
In (Arguments): pszFileNames
pszFileName - the name of the received file.
Description: Sent when a file transfer event ended successfully. When multiple files were sent, the notification will be sent after each received file.
ICQAPINotify_OnlineFullUserDataChange
void WINAPI ICQAPINotify_OnlineFullUserDataChange(int iUIN);
Code: ICQAPINOTIFY_ONLINE_FULLUSERDATA_CHANGE
In (Arguments): iUIN
iUIN is the ICQ# of the user
Description: Sent when user’s details where updated (e.g. when the owner pressed update, in the info dialog).
ICQAPINotify_OnlineListChange
void WINAPI ICQAPINotify_OnlineListChange(int iType);
Code: ICQAPINOTIFY_ONLINELIST_CHANGE
In (Arguments): iType
iType is the type of change:
1 - user gone on/off
2 - float window on/off
3 - user changed position in the list
Description: Sent when the online users list changes. A change can occur due to the following reasons:
1. A user went online / offline.
2. The owner dragged a user to the desktop or back (floating).
3. A user moved up / down in the list (e.g. a user moved to the top of the list because of an incoming event).
This notification will be sent if you have asked for ICQAPINOTIFY_ONLINELIST_CHANGE
ICQAPINotify_OnlineListHandleChange
void WINAPI ICQAPINotify_OnlineListHandleChange(HWND hWindow);
Code: ICQAPINOTIFY_ONLINE_LISTHANDLE_CHANGE
In (Arguments): hWindow
hWindow - the handle of the current contact list listbox
Description: Sent when the user switches between available contact lists (i.e. “Online” tab or “All” tab).
ICQAPINotify_OnlinePlacementChange
void WINAPI ICQAPINotify_OnlinePlacement_Change();
Code: ICQAPINOTIFY_ONLINE_PLACEMENT_CHANGE
In (Arguments): None
Description: Sent when the online tab is added/removed above the contact list (due to the user changing the preferences)
ICQAPINotify_OwnerChange
void WINAPI ICQAPINotify_OwnerChange(int iUIN);
Code: ICQAPINOTIFY_OWNER_CHANGE
In (Arguments): iUIN
iUIN - the UIN of the new owner
Description: Sent when the current owner has changed.
ICQAPINotify_OwnerFullDataChange
void WINAPI ICQAPINotify_OwnerFullDataChange();
Code: ICQAPINOTIFY_OWNERFULLDATA_CHANGE
Out (Arguments): None
Description: Sent when the owner updates his own details.
Utility Functions
ICQAPIUtil_FreeUser
void WINAPI ICQAPIUtil_FreeUser(BSICQAPI_User *pUser);
In (Arguments): pUser
pUser - a pointer to a user structure returned from a previous call to the ICQ API.
Description: The function free a user structure previously allocated by a call to the ICQ API (i.e. by calling ICQAPICall_GetOnlineListDetailed).
ICQAPIUtil_FreeUsers
void WINAPI ICQAPIUtil_FreeUsers(int iCount, BSICQAPI_User **ppUsers);
In (Arguments): iCount, ppUser
iCount - the number of users in the ppUsers array.
ppUser - a pointer to a users’ array returned from a previous call to the ICQ API.
Description: The function free a user structure previously allocated by a call to the ICQ API (i.e. by calling ICQAPICall_GetOnlineListDetailed).
ICQAPIUtil_SetUserNotificationFunc
void WINAPI ICQAPIUtil_SetUserNotificationFunc(UINT uNotificationCode, void *pUserFunc);
In (Arguments): uNotificationCode, pUserFunc
uNotificationCode - a notification code as specified in the Notification reference above.
pUserFunc - the user function to be activated by the notification. For each notification code there is a prototype of a function as specified in the Notification reference above.
Description: The function is used to hook a developer’s notification function to the ICQ API. This is the first of two steps required to get notifications from the ICQ Client. The second step is done via a call to the ICQAPICall_RegisterNotify as described in the ICQ API preface, and in the ICQ API Calls reference above.
Data Structures
BSICQAPI_FireWallData
typedef struct {
BYTE m_bEnabled;
BYTE m_bSocksEnabled;
short m_sSocksVersion;
char m_szSocksHost[512];
int m_iSocksPort;
BYTE m_bSocksAuthenticationMethod;
} BSICQAPI_FireWallData;
This data structure describes the firewall data the ICQ Client was configured with by the current owner.
m_bEnabled - ‘1’ value indicates fire wall is used
m_bSocksEnabled - ‘1’ value indicated Socks is used
m_sSocksVersion - the Socks version (currently 4 or 5)
m_szSocksHost - the name of the Socks host
m_iSocksPort - the name of the Socks Port
m_bSocksAuthenticationMethod - ‘1’ value indicates User and Password authentication is used.
BSICQAPI_User
typedef struct
{
int m_iUIN;
HWND m_hFloatWindow;
int m_iIP;
char m_szNickname[20];
char m_szFirstName[20];
char m_szLastName[20];
char m_szEmail[100];
char m_szCity[100];
char m_szState[100];
int m_iCountry;
char m_szCountryName[100];
char m_szHomePage[100];
int m_iAge;
char m_szPhone[20];
BYTE m_bGender;
int m_iHomeZip;
// Version 1.0001
int m_iStateFlags;
} BSICQAPI_User;
This the data structure contains the user information held by ICQ Client.
m_iUIN - the user’s ICQ #.
m_hFloatWindw - the handle of the “Float” window if the user is floating.
m_iIP - the user’s IP address.
m_szNickname - the user’s nickname.
m_szFirstName - the user’s first name.
m_szLastName - the user’s last name.
m_szEmail - the user’s email address.
m_szCity - the user’s city.
m_szState - the user’s state.
m_iCountry - the user’s country code.
m_szCountryName - the user’s country name.
m_szHomePage - the user’s homepage.
m_iAge - the user’s age.
m_szPhone - the user’s phone.
m_iGender - the user’s gender. The codes are : 0 - Not Specified, 1 - Female, 2 - Male.
m_iHomeZip - the user’s zip code.
m_iStateFlags – get one of the following values :
BICQAPI_USER_STATE_ONLINE 0
BICQAPI_USER_STATE_CHAT 1
BICQAPI_USER_STATE_AWAY 2
BICQAPI_USER_STATE_NA 3
BICQAPI_USER_STATE_OCCUPIED 4
BICQAPI_USER_STATE_DND 5
BICQAPI_USER_STATE_INVISIBLE 6
BICQAPI_USER_STATE_OFFLINE 7
