TRightICQ

ICQ API for Borland Delphi - version 1.00
Help file and documentation

copyright 1999 RightClick Softworks

This is a trial version of the TRightICQ component which will only function with the Borland Delphi IDE.
For current pricing and licensing information, please email us, or visit our web site:

email. Info@RightClick.ca
web. www.RightClick.ca/software/icq

Please review the License Information section at the bottom of this document.

TRightICQ

Unit
RightICQ

Description
The TRightICQ component is used for accessing the capabilities of the Mirabilis ICQ API (version 1.0001).

The component requires the ICQMAPI.DLL file to be in the application directory, or in the Windows\System directory in order to function.

Using the component, the developer can obtain information about ICQ users, the current user's ICQ configuration, and interact with other users by sending messages and files. The component also enables notification of various events including alterations to ICQ configuration, updated user information, and notifications of incoming files and messages.

Other Data Objects

TUserData = class(Tobject)
UserID : integer;
hFloatWindow : HWND;
IP : integer;
Nickname : string;
FirstName : string;
LastName : string;
Email : string;
City : string;
State : string;
Country : integer;
CountryName : string;
HomePage : string;
Age : integer;
Phone : string;
Gender : BYTE;
HomeZip : integer;
StateFlags : integer;

TGroupData = class(Tobject)
name : string;
UserCount : integer;
UserList : TList;



TRightICQ Properties

DevName
DevPassword
DevLicense
May be left blank. When these properties are left blank they will default to the RightClick Softworks developer information.
These properties can be used to hold the developer's personal Name, Password, and License as assigned by Mirabilis when the ICQ API was downloaded from the Mirabilis web site.


TRightICQ Methods

RegisterNotify : boolean;
This call registers the application to receive ICQ notifications in the form of TRightICQ events. That is, if RegisterNotify is not called, no events will received by the component from ICQ.

The method's return value indicates success or failure.

GetDockingState(var dockingState : integer) : boolean;
The method's return value indicates success or failure.

Accepts a DockingState argument that will indicate the current docking state of the ICQ main window as follows:
0 - floating
1 - docked right
2 - docked left
3 - docked top
4 - docked bottom

GetFirewallSettings(var FW : TFirewallData) : boolean;
The function fills the given firewall structure with the current firewall details. The method's return value indicates success or failure.

GetFullOwnerData(var UserData : TUserData) : boolean;
The function accepts a TUserData structure and fills it with the current owner details. The method's return value indicates success or failure.

GetFullUserData(UserID : integer; var UserData : TUserData) : boolean;
The function accepts a TUserData structure and fills it with the current details of the details of the user indicated by the UserID argument. For the correct details to be obtained, the given user must be in the current ICQ user list. The method's return value indicates success or failure.

GetOnlineListDetails(var userCount : integer; var UserList : TList): boolean;
The function accepts a TList object and populates it with TUserData objects in the order of the online list. The userCount variable indicates the number of TUserData objects in the list. If the user is "floating" the TUserData object contains a valid windows handle to that "floating" user.

Each TUserData object (and the TList) is created by the method but must be freed manually.

GetOnlineListPlacement( var IsShowOnlineList: integer): boolean;
The method's return value indicates success or failure. Accepts a IsShowOnlineList argument; nonzero indicates that the Online tab appears above the contact list.

SendFile(UserID : integer; files : string) : boolean;
The function opens ICQ's send file dialog with the indicated UserID and files.
The method's return value indicates success or failure.

GetVersion : integer;
Returns the version number of the current ICQ API implementation.

GetWindowHandle : HWND;
Returns the window handle of the ICQ Client main window.

GetOnlineListType(var ListType : integer) : boolean;
The method's return value indicates success or failure. Accepts a ListType argument which indicates the mode of the list currently shown in the ICQ Client main window: 0 indicates regular mode; 1 indicates group mode.

GetGroupOnlineListDetails(var groupCount : integer; var GroupList : TList): boolean;
The function accepts a TList object and populates it with TGroupData objects in the order of the online list, top to bottom. The groupCount variable indicates the number of TGroupData objects in the list.

Each TGroupData object (and the TList) is created by the method but must be freed manually.

SetOwnerState(State : integer): boolean;
The method's return value indicates success or failure.
The function sets the current owner state to what is specified by State:
0 = ONLINE
1 = CHAT
2 = AWAY
3 = NA
4 = OCCUPIED
5 = DND
6 = INVISIBLE
7 = OFFLINE

SetOwnerPhoneState(PhoneState : integer): boolean;
The method's return value indicates success or failure.
The function sets the current phone owner state to what is specified by PhoneState (same as changing it through the services menu on the client):
0 = Unavailable
1 = Available

SendMessage(UserID : integer; text : string): boolean;
The function opens ICQ's message request dialog for the user indicated by UserID and with the text field initialized with the given message.
The method's return value indicates success or failure.

SendURL(UserID : integer; text : string): boolean;
The function opens ICQ's message request dialog for the user indicated by UserID and with the text field initialized with the given message.
The method's return value indicates success or failure.

SendExternal(UserID : integer; extApp, text : string; AutoSend : boolean): boolean;
The function sends an external application message to the user indicated by UserID; the external application is indicated by extApp (the external application name as it appears on the ICQ user menu); the message text is indicated by text. If AutoSend is set to TRUE, send the event without opening the send external dialog.
The method's return value indicates success or failure.


TRightICQ Events

OnAppBarStateChange(DockingState: Integer);
Sent if the contact list docking status has changed.
DockingState indicates the new docking state where:
0 = floating
1 = docked right
2 = docked left
3 = docked top
4 = docked bottom

OnFileReceived(filename: String);
Sent when a file transfer event ended successfully. When multiple files were sent, the notification will be sent after each received file. Filename indicates the name of the file received.

OnOnlineFullUserDataChange(UserID: Integer);
Sent when user's details where updated (e.g. when the owner pressed update, in the info dialog). UserID indicates the ICQ users ID # of the user.

OnOnlineListChange(iType: Integer);
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).
iType indicates the type of change, where:
1 = user gone on/off
2 = float window on/off

OnOnlineListHandleChange(hWindow: HWND);
Sent when the user switches between available contact lists (i.e. "Online" tab or "All" tab).
hWindow indicates the handle of the current contact listbox.

OnOnlinePlacementChange;
Sent when the online tab is added/removed above the contact list (due to the user changing the preferences)

OnOwnerChange(UserID: Integer);
Sent when the current owner has changed.
UserID indicates the ICQ user ID # of the new owner.

OnOwnerFullUserDataChange;
Sent when the owner updates his own details.


License Information

The TRightICQ is distributed with Mirabilis' ICQMAPI.DLL file. The TRightICQ component is entirely dependent on the Mirabilis ICQ API and functionality is therefore subject to the terms and conditions of the Mirabilis ICQ API available from the Mirabilis website: www.mirabilis.com