TICQClient


Contents:
  • About TICQClient
  • TICQClient units
  • Properties
  • Functions
  • Events
  • Contact information


    About TICQClient

    It's a small component showing how it's easy to implement basic functions of v8 protocol. Sources are quite good commented so it's very simply to extend functionality of this component. You have to install component from unit ICQClient.pas. It's not a realease, not a beta, just a test made for fun. Hope you enjoy it ;)


    TICQClient units

    ICQWorks.pas - contains all low level parsing functions & constants.
    MySocket.pas - small and fast TCP socket used in TICQClient.
    ICQClient.pas - component itself.
    ICQClient.dcr - component icon.

    First of all you have to install TICQClient component.
    Start Delphi, then Component > Install Component > here you have to choose file ICQClient.pas and press OK button, then in new window press Compile button.
    If you had previous versions installed, please reinstall(do the same) component to include new events.


    Properties

    property Status: LongWord
    Property allows to read/set client's status after logging to server.
    Status can be one of:
    S_ONLINE
    S_INVISIBLE
    S_AWAY
    S_NA
    S_OCCUPIED
    S_DND
    S_FFC

    property LoggedIn: Boolean
    If client has logged in the property will return TRUE.

    property UIN: LongWord
    Property allows to read/set current client's UIN, used on login.

    property Pasword: String
    Property allows to read/set current client's Password, used on login.

    property ICQServer: String
    ICQ server to connect to, you may use 'login.icq.com'

    property ICQPort: Word
    ICQ port to connect to, you may use '5190'

    property ConvertToPlaintext: Boolean
    If you set this property to TRUE, text received in RTF(RichText) format will be automaticly converted into plain.

    property ContactList: TStrings
    Client's contact list *sent only on login*. Each line indicates UIN number. If you want to add user into contact list after login take a look on AddContact procedure.

    property VisibleList: TStrings
    Client's visible list. Each line indicates UIN number. Visible list is sent to the server when you are logging/changing status to invisible. If you want to add user into visible list after logon (or you are in invisible status already) use AddContactVisible procedure.

    property InvisibleList: TStrings
    Client's invisible list. Each line indicates UIN number. Invisible list is sent to the server when you are logging/changing status to other then invisible. If you want to add user into invisible list after logon (or you are in visible status already) use AddContactInvisible procedure.


    Functions

    procedure Login(Status: LongWord = S_ONLINE)
    This function logges in client with Status, default set to S_ONLINE, can be used other listed in property Status.

    procedure Disconnect
    Disconnect from server.

    procedure SendMessage(UIN: LongWord; Msg: String)
    Send a message to UIN.

    procedure SendURL(UIN: LongWord; const URL, Description: String);
    Send an URL message to UIN.

    function AddContact(UIN: LongWord): Boolean
    Adds UIN to contact list after logon(when you are online), UIN automaticly added to ContactList TStrings. After adding the UIN you will receive status notifications. Returns True when UIN is added to the list(it wasn't there before).

    function AddContactVisible(UIN: LongWord): Boolean
    Adds UIN to visible list after logon, UIN automaticly added to VisibleList TStrings. After adding the UIN you will be visible to this UIN in invisible status. Returns True when UIN is added to the list(it wasn't there before).

    function AddContactInvisible(UIN: LongWord): Boolean
    Adds UIN to invisible list after logon, UIN automaticly added to InvisibleList TStrings. After adding the UIN you will be invisible to this UIN in any status. Returns True when UIN is added to the list(it wasn't there before).

    RemoveContact(UIN: LongWord) procedure
    Removes UIN from contact list. Use while you are online.

    RemoveContactVisible(UIN: LongWord) procedure
    Removes UIN from the visible list. Use while you are online.

    RemoveContactInvisible(UIN: LongWord) procedure
    Removes UIN from the invisible list. Use while you are online.

    RequestInfo(UIN: LongWord)
    Query info about UIN. As answer you will recieve theese events: OnUserWorkInfo, OnUserInfoMore, OnUserInfoAbout, OnUserInfoInterests, OnUserInfoMoreEmails, OnUserFound.

    procedure SearchByMail(Email: String)
    procedure SearchByUIN(UIN: LongWord)
    procedure SearchByName(FirstName, LastName, NickName, Email: String)
    Searches user by Mail, UIN or Other info. As answer you will receive OnUserFound notification when at least one user found or OnUserNotFound if such user does not exist.

    procedure SearchRandom(Group: Word)
    Searches random user from Group, where Group id could be found in RandGroups: array[1..11]...(ICQWorks.pas) constant. As answer you will receive OnUserFound notification, only one user will be found.

    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);
    Searches user in 'White Pages'. As answer you will receive OnUserFound notification when at least one user found or OnUserNotFound if such user does not exist.

    procedure SetSelfInfoGeneral(NickName, FirstName, LastName, Email, City, State, Phone, Fax, Street, Cellular, Zip, Country: String; TimeZone: Byte; PublishEmail: Boolean);
    Set general info about yourself. You can skip some parameters (eg. use '' - empty strings) to unspecify some info.

    procedure SetSelfInfoMore(Age: Word; Gender: Byte; HomePage: String; BirthYear: Word; BirthMonth, BirthDay: Byte; Language1, Language2, Language3: String);
    Set more info about yourself.

    procedure SetSelfInfoAbout(About: String);
    Set info about yourself.

    procedure RequestContactList;
    Requests server side contact list. For more info look at OnServerListRecv event.

    procedure DestroyUINList(var List: TList);
    Releases memory used while parsing the server side contact list.

    procedure SendSMS(const Destination, Text: String);
    Sends sms message to Destination with Text.
    Example:

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

    procedure SendMessageAdvanced(UIN: LongWord; const Msg: String; ID: Word; RTFFormat: Boolean);
    Sends Msg to UIN with advanced options, after UIN has got your message you will receive confirmation. ID - randomly generated value, may be used for packet acknowledgements (see OnAdvancedMsgAck event). If your Msg is in the RTF(RichText Format), then RTFFormat parameter should be True, otherwise - False. Beware of using the RTF Format, some clients(old versions of ICQ, linux & windows clones) don't support it.


    Events

    OnAddedYou(Sender: TObject; UIN: String)
    Called when someone adds you to his contact list.

    OnAdvancedMsgAck(Sender: TObject; UIN: String; ID: Word; AcceptType: Byte; AcceptMsg: String)
    A response to SendMessageAdvanced procedure. It's a confirmation that client received your message successfully. If you haven't received this event for some time you can resend your message.
    ID - id passed in SendMessageAdvanced procedure.
    AcceptType may be one of:
    ACC_NORMAL - normally accepted
    ACC_NO_OCCUPIED - not accepted, occupied status
    ACC_NO_DND - not accepted, dnd status
    ACC_AWAY - accepted but away status
    ACC_NA - accepted in NA status
    ACC_CONTACTLST - accepted to contact list (no blink in tray)
    AcceptMsg is an away message, such as: "User is currently N/A. You can leave him/her a message".

    OnConnectionFailed(Sender: TObject)
    Called when you cannot connect, or server in some reason disconnected you.

    OnLogin(Sender: TObject)
    Called after successfull login.

    OnMessageRecv(Sender: TObject; MsgType: Cardinal; Msg, UIN: String)
    Called when you receive a message, MsgType could be one of:
    M_PLAIN
    M_URL - if you receive an URL message, then it's devided into 2 parts: Description of URL + #$fe(delimeter byte) + URL.

    OnOfflineMsgRecv(Sender: TObject; MsgType: Word; Msg, UIN: String);
    Called when you receive a message, which was sent when you were offline.

    OnPktParse(Sender: TObject; Buffer: Pointer; BufLen: Cardinal; Incoming: Boolean);
    Called every time TICQClient sends or receives packet. Used by developers.

    OnServerListRecv(Sender: TObject; SrvContactList: TList);
    A response to RequestContactList procedure.
    After using the SrvContactList you *must* call DestroyUINList procedure with SrvContactList as a parameter, required to free allocated data, otherwise you'll have memory leaks. Each SrvContactList is a pointer on a TUINEntry stucture.

      TUINEntry = record
        UIN: LongWord;            //UIN in contact list
        Nick: ShortString;        //Nick of this UIN, can be null(empty)
        CType: Word;              //Type, can be U_NORMAL(Normal contact list entry), U_VISIBLE_LIST(user is in visible list)
                                  //, U_INVISIBLE_LIST(user is in invisible list), U_IGNORE_LIST(user is in ignore list)
        CTag: Word;               //Reserved for internal use
        CGroup: ShortString;      //Group, where UIN is located on
      end;
      
      Example:
      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 + ' is in group ' + UserInfo.CGroup
               + ' and his uin is ' + IntToStr(UserInfo.UIN));
           end;
         ICQClient1.DestroyUINList(SrvContactList);
      end;
      

    OnStatusChange(Sender: TObject; UIN: String; Status: Cardinal);
    Called when user from your contact list changes status or goes online. Statuses are listed in property Status.

    UserFound(Sender: TObject; UIN, Nick, FirstName, LastName, Email: String; Status: Word; Gender, Age: Byte; SearchComplete: Boolean);
    A reponse to SearchByMail, SearchByUIN, SearchByName, SearchRandom, SearchWhitePages procedures. SearchComplete is set to TRUE when there are no more such users (so this user is last in search response list).

    UserGeneralInfo(Sender: TObject; UIN, NickName, FirstName, LastName, Email, City, State, Phone, Fax, Street, Cellular, Zip, Country: String; TimeZone: Byte; PublishEmail: Boolean);
    A response to RequestInfo procedure. To convert TimeZone to normal format(eg. +2:00) you have to do the following:

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

    OnUserInfoAbout(Sender: TObject; UIN, About: String);
    A response to RequestInfo procedure.

    UserInfoBackground(Sender: TObject; UIN: String; Pasts, Affiliations: TStringList);
    A response to RequestInfo procedure. If you have set this event, you *must* destroy Pasts and Affilattions StringLists after using of them.

    OnInfoInterests(Sender: TObject; UIN: String; Interests: TStringList);
    A response to RequestInfo procedure. If you have set this event, you *must* destroy Interests StringList afrer using it(Interests.Free).

    OnUserInfoMore(Sender: TObject; UIN: String; Age: Word; Gender: Byte; HomePage: String; BirthYear, BirthMonth, BirthDay: Word; Lang1, Lang2, Lang3: String);
    A response to RequestInfo procedure.

    OnUserInfoMoreEmails(Sender: TObject; UIN: String; Emails: TStringList);
    A response to RequestInfo procedure. If you have set this event, you *must* destroy Emails StringList after using it(Emails.Free).

    OnUserNotFound(Sender: TObject);
    A reponse to SearchByMail, SearchByUIN, SearchByName, SearchRandom, SearchWhitePages procedures. Called when there are no users found.

    OnUserOffline(Sender: TObject; UIN: String);
    Called when user from your contact list goes offline.

    OnUserWorkInfo(Sender: TObject; UIN, WCity, WState, WPhone, WFax, FAddress, WZip, WCountry, WCompany, WDepartment, WPosition, WOccupation, WHomePage: String);
    A response to RequestInfo procedure.


    Contact info

    For updates checkout: http://soho.net.md.
    If you want to receive mails about TICQClient updates, mailto: mailto:alex@ritlabs.com?subject=join_ticqclient_update.
    Have you got any questions, offers, bugreports? Then mail me: alex@ritlabs.com, ICQ: #4024781.
    If someone would like to join the developing of TICQClient, please, mail me.


    (C) 2002, Alex Demchenko, Moldova, Chishinev