TICQClient

О TICQClient'е
Это небольшая компонента, которая позволяет вам общаться с ICQ пользователями прямо из вашей программы. Исходники довольно хорошо описаны(правда, на английском), так что можно без проблем расширять возможности компоненты. Автор работает совершенно за бесплатно, так что за ошибки и разные недочеты и тд. и тп. бить меня не надо ;). Надеюсь, все это дело вам понравится.

ВНИМАНИЕ! Лучше использовать Help.chm сейчас, там более полная информация о компоненте, сорри, нехватает времени обновить русскую версию.

Модули TICQClient'а
ICQWorks.pas - содержит все низкоуровневые функции и константы.
MySocket.pas - простая и удобная реализация сокетов, используется в TICQClient'е.
ICQDirect.pas - объекты, реализующие поддержку прямых соединений.
ICQClient.pas - компонента.
ICQClient.dcr - иконка компоненты.

Для начала вы должны установить TICQClient. Запустите Delphi, потом в главном меню: Component > Install Component > тут вы должны выбрать файл ICQClient.pas и нажать кнопку OK, затем в появившемся окне - кнопку Compile.
Если были устновлены более ранние версии TICQClient'а, тогда вам нужно переустановить компонент таким же образом.

Важная информация об ICQ протоколе
ICQ протокол подразделяется на следующие части:

Properties(Свойства)

property Status: LongWord
Позволяет получить/установить online статус клиента, после логина на сервер.
Статус можен быть одним из:
S_ONLINE
S_INVISIBLE
S_AWAY
S_NA
S_OCCUPIED
S_DND
S_FFC

property LoggedIn: Boolean
Если вы залогинились на сервер, тогда свойство вернет TRUE.

property UIN: LongWord
Свойство позволяет получить/установить UIN пользователя. Используется при логине.

property Pasword: String
Свойство позволяет получить/установить пароль пользователя.

property ICQServer: String
ICQ сервер, следует использовать: 'login.icq.com'

property ICQPort: Word
ICQ port, следует использовать: '5190'

property ConvertToPlaintext: Boolean
Если это свойство установить в TRUE, тогда сообщения, приходящие в RTF(Rich Text Format) формате, автоматически будут сконвертированы в простой текст(plain text).
Пример RTF сообщения:
{\rtf1\ansi\ansicpg1251\deff0\deflang1049{\fonttbl{\f0\fnil\fcharset204{\*\fname Times New Roman;}Times New Roman CYR;}}
{\colortbl ;\red0\green64\blue0;}
\viewkind4\uc1\pard\cf1\f0\fs20\'ef\'f0\'e8\'e2\'e5\'f2\par
}
Эквивалент в простом тексте:
привет

property ContactList: TStrings
Контакт лист пользователя, *посылается только при логине*. Каждая строчка -- UIN номер. Если вы хотите добавить кого-либо в контакт лист после логина, используйте AddContact procedure.

property VisibleList: TStrings
Visible лист пользователя. Каждая строка -- UIN номер. Посылается, когда вы переходите в invisible статус. Добавлять пользователя можно в любое время.

property InvisibleList: TStrings
Invisible лист пользователя. Каждая строка -- UIN номер. Посылается, когда вы переходите в статус отличный от invisible. Добавлять пользователя можно в любое время.

property AutoAwayMessage: String
Авто-ответ пользователя. В обычной ICQ это ответ на 'Read Away-message'.

Functions(Функции)

procedure Login(Status: LongWord = S_ONLINE)
Процедура устанавливает соединение с сервером, вы сразу переходите в статус Status, который по умолчанию S_ONLINE, можно залогиниться и с другим статусом, спосок статусов в property Status.

procedure Disconnect
Отсоединиться от сервера.

procedure SendMessage(UIN: LongWord; Msg: String)
Послать сообщение UIN'у.

procedure SendURL(UIN: LongWord; const URL, Description: String);
Послать URL(ссылку) UIN'у.

function AddContact(UIN: LongWord): Boolean
Добавить UIN'а в ваш контакт лист после логина. UIN автоматически добавляется в ContactList TStrings. После добавления UIN'а в ваш контакт лист, вы будете получать извещения об изменениях его статуса. Возвращает True, если пользователь с таким UIN'ом не был в вашем листе раньше.

RemoveContact(UIN: LongWord) procedure
Удаляет UIN из вашего контакт листа. Ипользуйте пока вы в онлайне.

RemoveContactVisible(UIN: LongWord) procedure
Удаляет UIN из вашего visible листа. Используйте пока вы в онлайне.

RemoveContactInvisible(UIN: LongWord) procedure
Удаляет UIN из invisible листа. Используйте пока вы в онлайне.

RequestInfo(UIN: LongWord)
Запросить информацию об UIN'е. В ответ вы получите следующие извещения: OnUserWorkInfo, OnUserInfoMore, OnUserInfoAbout, OnUserInfoInterests, OnUserInfoMoreEmails, OnUserFound.

procedure SearchByMail(Email: String)
procedure SearchByUIN(UIN: LongWord)
procedure SearchByName(FirstName, LastName, NickName, Email: String)
Поиск пользователя по Mail'у, UIN'у или другой инфе. В ответ вы получите OnUserFound извещение(event) если хотябы один человек был найден или OnUserNotFound если таких не существует.

procedure SearchRandom(Group: Word)
Поиск случайного пользователя по группе, где номер группы может быть одним из RandGroups: array[1..11]...(ICQWorks.pas) контанты. В ответ вы получите OnUserFound извещение, только один пользователь будет обязательно найден. (Это ограничение ICQ).

procedure SearchWhitePages(First, Last, Nick, Email: String; MinAge, MaxAge: Word; Gender: Byte; Language, City, State: String; Country, Company, Department, Position: String; Occupation, Past, PastDesc, Interests, InterDesc, Affiliation, AffiDesc, HomePage: String; Online: Boolean);
Поиск в 'White Pages'. В ответ вы получите OnUserFound извещение(event) если хотябы один человек был найден или OnUserNotFound если таких не существует.

procedure SetSelfInfoGeneral(NickName, FirstName, LastName, Email, City, State, Phone, Fax, Street, Cellular, Zip, Country: String; TimeZone: Byte; PublishEmail: Boolean);
Залить на сервер инфо о себе. Парамерты могут быть пустыми строками('').

procedure SetSelfInfoMore(Age: Word; Gender: Byte; HomePage: String; BirthYear: Word; BirthMonth, BirthDay: Byte; Language1, Language2, Language3: String);
Залить на сервер дополнительную инфу о себе.

procedure SetSelfInfoAbout(About: String);
Залить на сервер about инфу о себе.

procedure RequestContactList;
Запросить контакт лист с сервера. Для более подробной информации смотрите: OnServerListRecv event.

procedure DestroyUINList(var List: TList);
Освободить память, в которой временно хранится контакт лист принятый с сервера.

procedure SendSMS(const Destination, Text: String);
Посылает SMS к Destination с текстом Text.
Пример:

  ICQClient1.SendSMS('+3739401111', 'Hello, World!');
  

procedure SendMessageAdvanced(UIN: LongWord; const Msg: String; ID: Word; RTFFormat: Boolean);
Посылает сообщение с дополнительными возможностями. После того как UIN получил ваше сообщение вы получите подтвреждение. ID - случайное значение, такое же приходит к вам в подтверждениях(см. OnAdvancedMsgAck event). Если ваше сообщение в RTF(Rich Text Format) формате, тогда RTFFormat должен быть True, бойтесь использовать RTF формат, потому как некоторые ICQ клоны его не поддерживают, в частности клоны под linux и win32, такие как: Miranda, YSM, mICQ, &RQ, StrICQ и другие.

function SendMessageDirect(UIN: LongWord; const Msg: String; RTFFormat: Boolean): Word; (DC)
Для большей информации смотрите SendMessageAdnaced procedure. Пока эта функция не поддерживает подтверждений, т.е. вы их получать не будете, хотя это возможно реализовать. Возвращает ID как результат - уникальный идентификатор если прямое соединение с UIN было установлено, иначе - 0. В ответ вы получите OnDirectPacketAck event с этим ID.

procedure RegisterNewUIN(const Password: String);
Зарегистрировать новый UIN, параметр Password -- это пароль с каким вы хотите использовать новый номер. Процедура должна использоваться когда вы в офлайне(тобишь она сама логиниться и делает что надо :). Если вам выделили новый номер, тогда вы получите OnNewUINRegistered event, иначе OnNewUINRefused event(например, когда вы хотите слишком много номеров).

procedure RequestAwayMsg(UIN: LongWord; ID: Word; ReqStatus: Byte);
Запросить авто-ответ UIN'а. ID - случайное значение которое придет вам в ответах на RequestAwayMsg. ReqStatus - это тип авто-ответа, может быть одним из:
GET_AWAY, - запросить away авто-ответ
GET_OCCUPIED, - запросить occupied авто-ответ
GET_NA, - запросить NA авто-ответ
GET_DND, - запросить DND авто-ответ
GET_FFC - запросить FFC(Free For Chat) авто-ответ.
Другими словами ReqStatus -- это текущий статус UIN'а.
В ответ вы получитеOnAutoMsgResponse event.

UnregisterUIN(const Password: String);
Стереть с лица земли ваш UIN! Бойтесь использовать эту процедуру, т.к. можно навредить самому себе :) Password -- это ваш текущий пароль. Если пароль который вы передали будет кривой, то вы получите OnUnregisterBadPassword event, иначе OnUnregisterOk event(и будете автоматически отключены от сервера).

procedure ChangePassword(const NewPassword: String);
Меняет текущий пароль пользователя на NewPassword. Должно все это менятся пока вы в онлайне. property Password: String при этом не изменяется(вы должны это сделать самостоятельно). После успешной смены пароля вы получите OnChangePasswordOk event.

function DirectConnectionEstabilished(UIN: LongWord): Boolean; (DC)
Возвращает True если примое соединение с UIN было установлено.

function SendContacts(UIN: LongWord; Contacts: TStringList): Word; (DC)
Посылает контакты UIN'у. Каждая строка Contacts TStirngList имеет следующий формат:
UIN человека=его NickName, NickName может быть неуказан(пустым).
Возвращает ID как результат - уникальный идентификатор если прямое соединение с UIN было установлено, иначе - 0. В ответ вы получите OnDirectPacketAck event с этим ID.
Пример:

  procedure TMainForm.Button2Click(Sender: TObject);
  var
    List: TStringList;
  begin
    List := TStringList.Create;
    List.Add('52341243=Monica');
    List.Add('12333391=Бритний Спеарзсс');
    List.Add('8213876=');
    List.Add('1234333=Bob');
    List.Add('925464568=');
    ICQClient1.SendContacts(4024781, List);
    List.Free;
  end;
  

function RequestContacts(UIN: LongWord; const Reason: String): Word; (DC) Посылает запрос контактов UIN'у.
Возвращает ID как результат - уникальный идентификатор если прямое соединение с UIN было установлено, иначе - 0. В ответ вы получите OnDirectPacketAck event с этим ID.
Пример:

  procedure TMainForm.Button1Click(Sender: TObject);
  begin
    ICQClient1.RequestContacts(4024781, 'Кинь мне пару контактов плз :)');
  end;
  

Events(События)

OnAddedYou(Sender: TObject; UIN: String)
Вызывается, когда UIN добавляет вас в свой контакт лист.

OnAdvancedMsgAck(Sender: TObject; UIN: String; ID: Word; AcceptType: Byte; AcceptMsg: String)
Ответ на SendMessageAdvanced procedure.
Это подтверждение, что пользователь получил ваше сообщение. Если это извещение не получено, вы можете послать выше сообщение еще пару раз.
ID - случайное значение, которое было передано в SendMessageAdvanced procedure.
AcceptType может быть одним из:
ACC_NORMAL - нормально принято
ACC_NO_OCCUPIED - не принято, occupied статус
ACC_NO_DND - не принято, dnd статус
ACC_AWAY - принято но в away статусе
ACC_NA - принято, но в na статусе
ACC_CONTACTLST - принято в contact list (не мигать в трэе)
AcceptMsg - это авто-ответ, вроде: "User is currently N/A. You can leave him/her a message".

OnAutoMsgResponse(Sender: TObject; UIN: String; ID: Word; RespStatus: Byte; Msg: String);
Ответ на RequestAwayMsg procedure. ID & RespStatus такие же как вы передавали в RequestAwayMsg procedure, Msg -- это текст авто-ответа.

OnChangePasswordOk(Sender: TObject);
Ответ на ChangePassword procedure. Означает, что ваш пароль был успешно изменен.

OnConnectionFailed(Sender: TObject)
Вызывается, когда вы не можете подключиться к серверу либо сервер вас отключил по другим причинам.

OnContactListRecv(Sender: TObject; UIN: String; ContactList: TStringList); (DC)
Вызывается, когда UIN посылет вам свои контакты. Каждая строка в ContactList имеет следующий формат: UIN пользователя=его NickName. После использования ContactList TStringList вы *должны* его уничтожить (ContactList.Free).

OnContactListRequest(Sender: TObject; UIN, Reason: String); (DC)
Вызывается когда UIN запрашивает у вас контакты, не дайте ему умереть со скуки :)

OnDirectPacketAck(Sender: TObject; ID: Word); (DC)
Ответ на любой отосланый прямой пакет(SendMessageDirect, RequestContacts, и тд.), который был успешно получен и обработан ICQ'ей которой вы его посылали. ID = значение которое возвращают DC (Direct Connection) функции.

OnLogin(Sender: TObject)
Вызывается при успешном логине.

OnMessageRecv(Sender: TObject; Msg, UIN: String);
Вызывается при получении сообщения (через сервер или напрямую).

OnNewUINRefused(Sender: TObject);
Ответ на RegisterNewUIN procedure. Означает, что сервер не может выделить вам номер, может вы хотите их слишком много или делаете это слишком часто? ;)

OnNewUINRegistered(Sender: TObject; UIN: String);
Ответ на RegisterNewUIN procedure. Вам выделен новый UIN, можете смело использовать его при следующем логине.

OnOfflineMsgRecv(Sender: TObject; Msg, UIN: String);
Вызывается когда UIN послал сообщение, пока вы были в офлайне.

OnOfflineURLRecv(Sender: TObject; Description, URL, UIN: String);
Вызывается когда URL послал сообщение, пока вы были в офлайне.

OnPktDirectParse(Sender: TObject; Buffer: Pointer; BufLen: Cardinal; Incoming: Boolean); (DC)
Вызывается каждый раз, когда TICQClient посылает или получает какой-либо пакет посланый через прямое соединение. Используется обычно разработчиками. Пакеты могут быть шифроваными.

OnPktParse(Sender: TObject; Buffer: Pointer; BufLen: Cardinal; Incoming: Boolean);
Вызывается каждый раз, когда TICQClient посылает или получает какой-либо пакет. Используется обычно разработчиками.

OnServerListRecv(Sender: TObject; SrvContactList: TList);
Ответ на RequestContactList procedure.
В конце вы *обязательно* должны вызвать DestroyUINList procedure с параметром = SrvContactList, иначе у вашего приложения будут утечки памяти. Каждый элемент SrvContactList'а это указатель на следующую структуру:

  TUINEntry = record
    UIN: LongWord;            //UIN в контакт листе
    Nick: ShortString;        //Nick, может быть пустым
    CType: Word;              //Type, может быть U_NORMAL(нормальный пользователь), U_VISIBLE_LIST(пользователь в visible листе)
                              //, U_INVISIBLE_LIST(пользователь в invisible листе), U_IGNORE_LIST(пользователь в ignore листе)
    CTag: Word;               //Зарезервировано для внутренного использования
    CGroup: ShortString;      //Группа в которой содержится пользователь (например General, Friends, etc).
  end;
  

  procedure TMainForm.ICQClient1ServerListRecv(Sender: TObject;
    SrvContactList: TList);
  var
    i: Word;
    UserInfo: TUINEntry;
  begin
     if SrvContactList.Count > 0 then
       for i := 0 to SrvContactList.Count - 1 do
       begin
         UserInfo := PUINEntry(SrvContactList.Items[i])^;
         Memo1.Lines.Add(UserInfo.Nick + ' в группе ' + UserInfo.CGroup
           + ' и его UIN ' + IntToStr(UserInfo.UIN));
       end;
     ICQClient1.DestroyUINList(SrvContactList);
  end;
  

OnStatusChange(Sender: TObject; UIN: String; Status: Cardinal);
Вызывается когда UIN из вашего контакт листа меняет стататус или идет в онлайн. Статусы можно найти в property Status. Так же можно использовать StatusToStr(Value: LongWord): String function из ICQWorks.pas, чтоб сконвертировать из числового представления статуса в строковое.

OnUnregisterBadPassword(Sender: TObject);
Ответ на UnregisterUIN procedure. Значит, что пароль переданый в UnregisterUIN был неверным.

OnUnregisterOk(Sender: TObject);
Ответ на UnregisterUIN procedure. Вызвается как только ваш UIN был стерт. После этого вы будете автоматически отключены от сервера.

OnURLRecv(Sender: TObject; Description, URL, UIN: String);
Вызывается когда вы получаете URL (через сервер или напрямую).

OnUserFound(Sender: TObject; UIN, Nick, FirstName, LastName, Email: String; Status: Word; Gender, Age: Byte; SearchComplete: Boolean);
Ответ на SearchByMail, SearchByUIN, SearchByName, SearchRandom, SearchWhitePages procedures. SearchComplete = TRUE, когда вы получаете последнего найденого пользователя(т.е. окончание списка найденых людей).

OnUserGeneralInfo(Sender: TObject; UIN, NickName, FirstName, LastName, Email, City, State, Phone, Fax, Street, Cellular, Zip, Country: String; TimeZone: Byte; PublishEmail: Boolean);
Ответ на RequestInfo procedure. Чтобы сконвертировать TimeZone в нормальное представление(типа +2:00), вы должны сделать слудущее:

  var
    S: String;
  <....>
  S := IntToStr(- ShortInt(TimeZone) div 2) + ':' + IntToStr(Abs(ShortInt(TimeZone) mod 2 * 30));
  

OnUserInfoAbout(Sender: TObject; UIN, About: String);
Ответ на RequestInfo procedure.

UserInfoBackground(Sender: TObject; UIN: String; Pasts, Affiliations: TStringList);
Ответ на RequestInfo procedure. Если у вас вызывается это событие, тогда вы *обязательно должны* разрушить Pasts и Affiliations StringLists, после их использования(Pasts.Free; Affiliations.Free);

OnInfoInterests(Sender: TObject; UIN: String; Interests: TStringList);
Ответ на RequestInfo procedure. Если у вас вызывается это событие, тогда вы *обязательно должны* разрушить Interests StringList, после его использования(Interests.Free).

OnUserInfoMore(Sender: TObject; UIN: String; Age: Word; Gender: Byte; HomePage: String; BirthYear, BirthMonth, BirthDay: Word; Lang1, Lang2, Lang3: String);
Ответ на RequestInfo procedure.

OnUserInfoMoreEmails(Sender: TObject; UIN: String; Emails: TStringList);
Ответ на RequestInfo procedure. Если у вас вызывается это событие, тогда вы *обязательно должны* разрушить Emails StringList, после его использования(Emails.Free).

OnUserNotFound(Sender: TObject);
Ответ на SearchByMail, SearchByUIN, SearchByName, SearchRandom, SearchWhitePages procedures. Вызывается, когда такой пользователь не найден.

OnUserOffline(Sender: TObject; UIN: String);
Вызывается когда UIN из вашего листа уходит в офлайн.

OnUserWorkInfo(Sender: TObject; UIN, WCity, WState, WPhone, WFax, FAddress, WZip, WCountry, WCompany, WDepartment, WPosition, WOccupation, WHomePage: String);
Ответ на RequestInfo procedure.

Contact info
Последние обновления можно найти всегда по адресу: http://www.cobans.net.
Если вы хотите получать email'ы об обновлении TICQClient'а, тогда пишите: mailto:alex@ritlabs.com?subject=join_ticqclient_update.
Есть какие-либо предложения, ошибки, пожелания? Тогда пишите: alex@ritlabs.com, ICQ: #4024781.
Если вы хотите вступить в клуб разработчиков TICQClient'а, пишите!