Руководство по применению ICQ API
На этой странице вам представлены функции из набора ICQ API,
предоставляемые разработчику фирмой Mirabilis. Для использования
этих функций вам необходимо зарегистрироваться на сайте
http://www.icq.com/api/downloadapi.html и получить индивидуальный
код разработчика (лицензионный ключ). После регистрации вам
предоставится возможность получить архив, содержащий
библиотеку IcqMAPI.dll, файл заголовков и документацию.
Описания функций API будут даны в следующем формате:
Вызов функции:
IN (arguments) – список аргументов и их описание
OUT (returns) - список возвращаемых значений и их описание
Description – более подробное описание цели запроса функции и как
ICQ использует эту функцию
Сообщение (уведомление) функции:
Code - текст сообщения (ICQAPINOTIFY_xxx)
In (Arguments) - список аргументов и их описание
Description – более подробное описание назначения сообщения
Использование ICQ API
ICQ API - набор функций, выполненных в DLL. API позволяет асинхронизирвать
процессы запроса данных от ICQ клиента, выполнения первоначальных действий
в клиенте и получения сообщения от клиента. Чтобы использовать API,
приложение должно в начале вызвать один раз функцию
ICQAPICALL_SETLICENSEKEY. Только после этого
возможен вызов остальных функций.
Номер текущей версии ICQ API можно узнать, используя
функцию ICQAPICALL_GETVERSION.
ICQ API состоит из вызовов и сообщений (уведомлений). Все вызовы
синхронизированы с блокировкой по времени в 1 секунду (timeout)
таким образом, что если ICQ клиент не ответил за 1 секунду, то запрос
расценивается как невыполненный. Каждый запрос возвращает булево
значение - False или True в зависимости от его невыполнения/выполнения
соответственно. Сообщения отсылаются от ICQ клиента и они тоже
синхронизированы с блокировкой по времени в 1 секунду - если приложение
не ответило за это время, то сообщения не отослано и приложение
больше никаких сообщений не получит.
Если ваше приложение требует постоянных сообщений от ICQ (использованием
функции ICQAPICALL_REGISTERNOTIFY), то чтобы отказаться от этого следует
воспользоваться функцией ICQAPICall_UnRegisterNotfiy.
Чтобы затребовать постоянное получение сообщений, нужно выполнить 2
простых действия :
Функция должна запрашивать сообщение - это делается с помощью сервисной
функции ICQAPIUtil_SetUserNotificationFunc. Эта функция содержит код
затребования сообщения и функцию уведомления разработчика. Данная
функция должна быть определена WINAPI (то есть __ stdcall) модификатором.
После установки всех функций сообщений, нужно
использовать функцию ICQAPICALL_REGISTERNOTIFY .
Описание всех вышеперечисленных функций вы найдете ниже.
Файлы ICQ API
ICQMSGAPI.LIB - библиотечный файл ICQAPI
ICQMSGAPI.DLL - ICQAPI dll непосредственно.
ICQAPINOTIFICATIONS.H -главный заголовочный файл ICQ API,включает
следующие заголовочные файлы:
ICQAPICALLS.H
ICQAPIDATA.H
ICQAPIINTERFACE.H
Справка API
Вызовы
ICQAPICall_GetDockingState
ICQAPICall_GetFirewallSettings
ICQAPICall_GetFullOwnerData
ICQAPICall_GetFullUserData
ICQAPICall_GetOnlineListDetails
ICQAPICall_GetOnlineListPlacement
ICQAPICall_RegisterNotify
ICQAPICall_SetLicenseKey
ICQAPICall_SendFile
ICQAPICall_UnRegisterNotify
ICQAPICall_GetVersion
ICQAPICall_GetWindowHandle
// Версия 1.0001
ICQAPICall_GetOnlineListType
ICQAPICall_GetGroupOnlineListDetails
ICQAPICall_SetOwnerState
ICQAPICall_SetOwnerPhoneState
ICQAPICall_SendMessage
ICQAPICall_SendURL
ICQAPICall_SendExternal
Сообщения
ICQAPINotify_OnlineListChange
ICQAPINotify_FullUserDataChange
ICQAPINotify_AppBarStateChange
ICQAPINotify_OnlinePlacementChange
ICQAPINotify_OwnerChange
ICQAPINotify_OwnerFullUserDataChange
ICQAPINotify_OnlineListHandleChange
ICQAPINotify_FileReceived
Сервисные функции
ICQAPIUtil_FreeUser
ICQAPIUtil_FreeUsers
ICQAPIUtil_SetUserNotificationFunc
Структуры данных
1.BSICQAPI_FireWallData
2.BSICQAPI_User
Вызовы
ICQAPICall_GetDockingState
BOOL WINAPI ICQAPICall_GetDockingState(int &iDockingState);
IN (arguments) - нет
OUT (returns) - iDockingState
Description - функция возвращает текущее состояние главного ICQ окна
ICQAPICall_GetFirewallSettings
BOOL WINAPI ICQAPICall_GetFirewallSettings(
BSICQAPI_FireWallData &oFireWallData);
IN (arguments) - нет
OUT (returns) - oFireWallData
oFireWallData - структура, содержащая данные, конфигурированные в клиенте
Description - функция возвращает данные, конфигурированные в клиенте
ICQAPICall_GetFullOwnerData
BOOL WINAPI ICQAPICall_GetFullOwnerData(
BSICQAPI_User **ppUser, int iVersion);
IN (arguments) - ppUser , iVersion
ppUser - указатель на ссылку на структуру данных
пользователя (BSICQAPI_USER).
iVersion - номер версии ICQ API
OUT (returns) - pUser
ppUser - указатель на структуру, заполненную текущими данными владельца
Description - функция назначает структуру данных пользователя и заполняет
ее текущими данными владельца. Вызывающий оператор должен освободить
структуру, используя ICQAPIUTIL_FREEUSER.
ICQAPICall_GetFullUserData2
BOOL WINAPI ICQAPICall_GetFullUserData(BSICQAPI_User *pUser, int iVersion);
IN (arguments) - PUser - указатель на структуру данных пользователя
(BSICQAPI_USER) с набором полей, соответcвующих полям UIN ICQ
iVersion - номер версии ICQ API
OUT (returns) - pUser
PUser - структура, заполненная пользовательскими данными
Description - функция заполняет данную структуру
пользователяDetails пользователя из ICQ.
ICQAPICall_GetOnlineListDetails
BOOL WINAPI ICQAPICall_GetOnlineListDetails(int &iCount,
BPSICQAPI_User **ppUsers);
IN (arguments) - нет
OUT (returns) - iCount, ppUsers
iCount - количество пользователей
ppUsers - указатель на массив пользователей
Description - полученные данные упорядочены в соответствии с
online-списком, сверху вниз. Массив пользователей проинициализирован
номерами ICQ пользователей (поле m_iUIN) и Window Handle (
_hFloatWindow), если пользователь стоит в списке "floating".
Массив пользователей должен быть освобожден
вызывом ICQAPIUTIL_FREEUSERS.
ICQAPICall_GetOnlinePlacement
BOOL WINAPI ICQAPICall_GetOnlineListPlacement(int &iIsShowOnlineList);
IN (arguments) - нет
OUT (returns) - iIsShowOnlineList
Description - iIsShowOnlineList - ненулевое значение этой
переменной указывает, что список online -пользователей
размещен наверху контакт листа ICQ
ICQAPICall_RegisterNotify
BOOL WINAPI ICQAPICall_RegisterNotify(int iVersion,
int iCount, BYTE *piEvents);
In (Arguments): iVersion, iCount, piEvents
iVersion - номер версии ICQ API
iCount - размер массива PiEvents
piEvents - массив сообщений о событиях, о которых приложение должно
быть проинформировано
Out (Returns): нет
Description: Вызов этой функции регистрирует приложение в списке ICQ
уведомлений. Приложение будет получать сообщения, которые оно требует.
Эти сообщения содержатся в массиве piEvents. Приложение может выполнять
вызов этой функции многократно. Заметьте, что если приложение уже
зарегистрировано, то указанные уведомления будут заменены текущими.
ICQAPICall_SetLicenseKey
BOOL WINAPI ICQAPICall_SetLicenseKey(char *pszName, char *pszPassword,
char *pszLicense);
In (Arguments): pszName, pszPassword, pszLicense
pszName -имя разработчика приложения.
pszPassword пароль разработчика приложения
pszLicense - ключ лицензии, который разработчик получил
на врем работы с API
Out (Returns): нет
Description: функция позволяет использовать ICQ API.
Должна быть вызвана один раз за сеанс.
ICQAPICall_SendFile
BOOL WINAPI ICQAPICall_SendFile(int iUIN, char *pszFileNames);
In (Arguments): iUIN, pszFileNames
iUIN - номер пользователя ICQ, которому должны быть посланы файлы
pszFileNames - список файлов, разделенный запятыми
Data (Returns): нет
Description: функция открывает окно отсылки файлов
ICQAPICall_UnRegisterNotify
BOOL WINAPI ICQAPICall_UnRegisterNotify();
In (Arguments): нет
Out (Returns): нет
Description: используйте вызов этой функции, чтоб отключить ваше
приложение от механизма отсылки уведомлений, установленного
вызовом функции ICQAPICALL_REGISTERNOTIFY.
ICQAPICall_GetVersion
BOOL WINAPI ICQAPICall_GetVersion(int &iVersion);
In (Arguments): нет
Out (Returns): iVersion
iVersion - версия API , которую использует ICQ клиент.
Description: Все приложения, которые планируют проверять
совместимость с ICQ API, должны выполнять этот запрос
ICQAPICall_GetWindowHandle
BOOL WINAPI ICQAPICall_GetWindowHandle(HWND &hWindow);
In (Arguments): нет
Out (Returns): hWindow - хэндл (handle) главного окна ICQ
Description: получает хэндл главного окна ICQ клиента
ICQAPICall_GetOnlineListType
BOOL WINAPI ICQAPICall_GetOnlineListType(int &iListType);
In (Arguments): нет
Out (Returns): iListType
iListType - текущий режим контакт листа ICQ – 0 – обычный режим ,
1 – групповой режим
Description: возвращает код списка, в данный момент
показанного в в главном окне ICQ клиента
ICQAPICall_GetGroupOnlineListDetails (версия 1.0001)
BOOL WINAPI ICQAPICall_GetGroupOnlineListDetails(int &iGroupCount,
BPSICQAPI_Group **ppGroups);
In (Arguments): нет
Out (Returns): iGroupCount, ppGroups
iGroupCount - количество групп, возвращенный в массив ppGroups.
ppGroups - массив указателей на группы пользователей
Description: полученные данные упорядочены в соответствии с
online-списком, сверху вниз. Массив групп ppGroups
проинициализирован номером группы и массивом пользователей,
который в свою очередь проинициализирован номерами ICQ
пользователей (поле m_iUIN). Группы должны быть освобождены
одна за другой вызовом функции ICQAPIUtil_FreeGroup.
ICQAPICall_SetOwnerState ( версия 1.0001)
BOOL WINAPI ICQAPICall_SetOwnerState (int iState);
In (Arguments): iState
iState – статус владельца
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): нет
Description: функция устанавливает текущий статус владельца,
прописанный в переменной iState
ICQAPICall_SetOwnerPhoneState (версия 1.0001)
BOOL WINAPI ICQAPICall_SetOwnerPhoneState(
int iPhoneState);
In (Arguments): iPhoneState
iPhoneState - 0 - Unavailable, 1 - Available
Out (Returns): нет
Description: Функция устанавливает текущее состояние телефона (Phone State)
ICQAPICall_SendMessage (версия 1.0001)
BOOL WINAPI ICQAPICall_SendMessage(int iUIN, char *pszMessage);
In (Arguments): iUIN, pszMessage
iUIN - номер ICQ пользователя, которому должно быть послано сообщение
Out (Returns): нет
Description: функция открывает окно посылки сообщения пользователю.
ICQAPICall_SendURL (версия 1.0001)
BOOL WINAPI ICQAPICall_SendURL (int iUIN, char *pszMessage);
In (Arguments): iUIN, pszMessage
iUIN - номер ICQ пользователя, которому должно быть
послано сообщение, содержащее URL
pszURL - текст URL
Out (Returns): нет
Description: функция открывает окно посылки сообщения пользователю.
ICQAPICall_SendExternal (версия 1.0001)
BOOL WINAPI ICQAPICall_SendExternal(int iUIN,
char *pszExternal,char *pszMessage,BYTE bAutoSend);
In (Arguments): iUIN, pszExternal, pszMessage, bAutoSend
iUIN – номер ICQ пользователя, которому должно быть послано external
pszExternal – внешнее имя приложения, такое, как оно появится
в ICQ меню пользователя
pszMessage - текст сообщения
bAutoSend – 1, если не надо открывать окно посылки события
Out (Returns): нет
Description: функция открывает окно посылки сообщения пользователю.
Сообщения
ICQAPINotify_AppBarStateChange
void WINAPI ICQAPINotify_AppBarStateChange(int iDockingState);
Code: ICQAPINOTIFY_APPBAR_STATE_CHANGE
In (Arguments): iDockingState
iDockingState - новое состояние окна ICQ (расположение на экране)
0 - плавающее (floating)
1 - справа
2 - слева
3 - вверху
4 - внизу
Description: Посылается, если было изменено расположение окна
ICQAPINotify_FileReceived
void WINAPI ICQAPINotify_FileReceived (char *pszFileNames);
Code: ICQAPINOTIFY_FILE_RECEIVED
In (Arguments): pszFileNames
pszFileName - имя полученного файла
Description: Посылается, когдда пересылка файла благополчно
завершена. Если отсылается несколько файлов, такое
сообщение должно посылаться после каждого полученного файла.
ICQAPINotify_OnlineFullUserDataChange
void WINAPI ICQAPINotify_OnlineFullUserDataChange(int iUIN);
Code: ICQAPINOTIFY_ONLINE_FULLUSERDATA_CHANGE
In (Arguments): iUIN - номер ICQ пользователя
Description: Посылается, когда пользователь изменил данные о себе в info
ICQAPINotify_OnlineListChange
void WINAPI ICQAPINotify_OnlineListChange(int iType);
Code: ICQAPINOTIFY_ONLINELIST_CHANGE
In (Arguments): iType
iType - это тип изменения:
1 - пользователь ушел в он-лайн/офф-лайн
2 - плавающее (float) окно в он-лайне/офф-лайне (поместил
пользователя в floating окно или нет)
3 - пользователь изменил позицию в листе (с приходом какого-либо события)
Description: Посылается, когда изменяется online список пользователя
ICQAPINotify_OnlineListHandleChange
void WINAPI ICQAPINotify_OnlineListHandleChange(HWND hWindow);
Code: ICQAPINOTIFY_ONLINE_LISTHANDLE_CHANGE
In (Arguments): hWindow
hWindow - хэндл (handle) текущего списка в контакт листе
Description: Посылается, когда пользователь переключается
между списками(Online Users/All Users)
ICQAPINotify_OnlinePlacementChange
void WINAPI ICQAPINotify_OnlinePlacement_Change();
Code: ICQAPINOTIFY_ONLINE_PLACEMENT_CHANGE
In (Arguments): нет
Description: Посылается, когда Online список в контакт
листе пополняется или редактируется
(если пользователь меняет Preferences)
ICQAPINotify_OwnerChange
void WINAPI ICQAPINotify_OwnerChange(int iUIN);
Code: ICQAPINOTIFY_OWNER_CHANGE
In (Arguments): iUIN
iUIN - номер ICQ нового владельца
Description: Посылается при смене текущего владельца
ICQAPINotify_OwnerFullDataChange
void WINAPI ICQAPINotify_OwnerFullDataChange();
Code: ICQAPINOTIFY_OWNERFULLDATA_CHANGE
Out (Arguments): нет
Description: посылается, когда владелец редактирует свои Details
Сервисные функции
ICQAPIUtil_FreeUser
void WINAPI ICQAPIUtil_FreeUser(BSICQAPI_User *pUser);
In (Arguments): pUser
pUser - указатель на пользовательскую структуру данных,
возвращенную после предыдущего обращения к ICQ API
Description: функция очищает структуру от содержащихся в ней
после вызова функции ICQAPICall_GetOnlineListDetailed данных.
ICQAPIUtil_FreeUsers
void WINAPI ICQAPIUtil_FreeUsers(int iCount, BSICQAPI_User **ppUsers);
In (Arguments): iCount, ppUser
iCount - количество пользователей в массиве ppUsers.
ppUser - указатель на массив данных пользователя,
полученный после последнего обращения к ICQAPI
Description: функция очищает структуру от содержащихся в ней
после вызова функции ICQAPICall_GetOnlineListDetailed данных.
ICQAPIUtil_SetUserNotificationFunc
void WINAPI ICQAPIUtil_SetUserNotificationFunc(
UINT uNotificationCode, void *pUserFunc);
In (Arguments): uNotificationCode, pUserFunc
uNotificationCode - код сообщения
pUserFunc - функция пользователя, активируемая сообщением.
Для каждого сообщения существует прототип функции.
Description: Функция используется для подключения функции
разработчика приложения к ICQ API. Это первый их двух шагов,
которые нужно сделать, чтоб получить сообщение от ICQ клиента.
Второй шаг состоит в обращении к функции ICQAPICall_RegisterNotify.
Структуры данных
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;
Эта структура данных описывает firewall данные, ICQ Клиент был
конфигурирован с текущим владельцем.
m_bEnabled - ‘1’ означает, что используется firewall
m_bSocksEnabled - ‘1’ означает, что используется Socks
m_sSocksVersion - версия Socks (текущая 4 или 5)
m_szSocksHost - имя хоста Socks
m_iSocksPort - имя порта Socks
m_bSocksAuthenticationMethod - ‘1’ означает, что используется
аутентификация пользователя при помощи логина и пароля
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;
// Версия 1.0001
int m_iStateFlags;
} BSICQAPI_User;
Это структура данных содержит информацию пользователя,
содержащуюся в ICQ клиенте.
m_iUIN - номер ICQ пользователя.
m_hFloatWindw - хэндл (handle) “Float” -окна,
если пользователь занесен во Floating
m_iIP - IP-адрес пользователя
m_szNickname - ник пользователя
m_szFirstName - имя пользователя
m_szLastName - фамилия пользователя
m_szEmail - E-mail адрес пользователя
m_szCity - город пользователя
m_szState - штат
m_iCountry - код страны
m_szCountryName - страна
m_szHomePage - личная страничка
m_iAge - возраст
m_szPhone - телефон
m_iGender - полe : 0 - не определен, 1 - Female, 2 - Male.
m_iHomeZip - zip код пользователя.
m_iStateFlags – получает одно из следующих значений :
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
Для получения более подробной информации об ICQ API
обратитесь на сайт http://www.icq.com/api/
Для технической поддержки - http://www.icq.com/support/
|