---

ICQ2000::Client Class Reference

The main library object. More...

#include <Client.h>

List of all members.

Public Methods
	Client ()
	Constructor for creating the Client object. More...
	Client (const unsigned int uin, const string &password)
	Constructor for creating the Client object. More...
	~Client ()
	Destructor for the Client object. More...
void	setUIN (unsigned int uin)
	Set your uin. More...
unsigned int	getUIN () const
	Get your uin. More...
void	setPassword (const string &password)
	Set the password to use at login. More...
string	getPassword () const
	Get the password you set for login. More...
bool	setTranslationMap (const string &szMapFileName)
	Set the translation map file to use for character set translation. More...
const string &	getTranslationMapFileName () const
	Get the File name of the translation map currently in use. More...
const string &	getTranslationMapName () const
	Get the Name of the translation map currently in use. More...
bool	usingDefaultMap () const
	Determine whether the default map (no translation) is in use. More...
void	SignalUserInfoChange (Contact *c)
	Method for indicating the User Info for a contact has changed. More...
void	SignalMessageQueueChanged (Contact *c)
	Method for indicating that the queue of message events automatically stored in a contact has changed. More...
void	SendEvent (MessageEvent *ev)
	Used for sending a message event from the client. More...
void	setStatus (const Status st, bool inv=false)
	Set your status. More...
Status	getStatus () const
	Get your current status. More...
bool	getInvisible () const
	Get your invisible status. More...
void	addContact (Contact &c)
	Add a contact to your list. More...
void	removeContact (const unsigned int uin)
	Remove a contact from your list. More...
Contact *	getContact (const unsigned int uin)
	Get the Contact object for a given uin. More...
void	fetchSimpleContactInfo (Contact *c)
	Request the simple contact information for a Contact. More...
void	fetchDetailContactInfo (Contact *c)
	Request the detailed contact information for a Contact. More...
void	fetchServerBasedContactList ()
SearchResultEvent *	searchForContacts (const string &nickname, const string &firstname, const string &lastname)
SearchResultEvent *	searchForContacts (const string &nickname, const string &firstname, const string &lastname, const string &email, unsigned short min_age, unsigned short max_age, Sex sex, unsigned char language, const string &city, const string &state, unsigned short country, const string &company_name, const string &department, const string &position, bool only_online)
SearchResultEvent *	searchForContacts (unsigned int uin)
void	setLoginServerHost (const string &host)
	set the hostname of the login server. More...
string	getLoginServerHost () const
	get the hostname for the currently set login server. More...
void	setLoginServerPort (const unsigned short &port)
	set the port on the login server to connect to. More...
unsigned short	getLoginServerPort () const
	get the currently set port on the login server. More...
void	setBOSServerOverridePort (const bool &b)
	set whether to override the port used to connect to the BOS server. More...
bool	getBOSServerOverridePort () const
	get whether the BOS redirect port will be overridden. More...
void	setBOSServerPort (const unsigned short &port)
	set the port to use to connect to the BOS server. More...
unsigned short	getBOSServerPort () const
	get the port that will be used on the BOS server. More...
void	setAcceptInDC (bool d)
	set whether to accept incoming direct connections. More...
bool	getAcceptInDC () const
	get whether to accept incoming direct connections. More...
void	setUseOutDC (bool d)
	set whether to make outgoing direct connections. More...
bool	getUseOutDC () const
	get whether to make outgoing direct connections. More...
void	Poll ()
	Perform any regular time dependant tasks. More...
void	socket_cb (int fd, SocketEvent::Mode m)
	Callback from client to tell library the socket is ready. More...
void	RegisterUIN ()
	Register a new UIN. More...
bool	isConnected () const
	Boolean to determine if you are connected or not. More...
Public Attributes
Signal1< void, ConnectedEvent *>	connected
	The signal to connect to for listening to ConnectedEvent's. More...
Signal1< void, DisconnectedEvent *>	disconnected
	The signal to connect to for listening to DisconnectedEvent's. More...
Signal1< bool, MessageEvent *, StopOnTrueMarshal >	messaged
	The signal to connect to for listening to incoming MessageEvent. More...
Signal1< void, MessageEvent *>	messageack
	The signal to connect to for listening to the acknowledgements that the library will generate for when the remote client sends back a message ack. More...
Signal1< void, ContactListEvent *>	contactlist
	The signal to connect to for listening to Contact list events. More...
Signal1< void, NewUINEvent *>	newuin
	The signal for when registering a new UIN has succeeded or failed after a call to RegisterUIN(). More...
Signal1< void, RateInfoChangeEvent *>	rate
	The signal for when the server signals the rate at which the client is sending has been changed. More...
Signal1< void, LogEvent *>	logger
	The signal for all logging messages that are passed back to the client. More...
Signal1< void, SocketEvent *>	socket
	The signal for socket events. More...
Signal1< void, MyStatusChangeEvent *>	statuschanged
	Signal to listen to for when the server has accepted a status change request. More...
Signal1< void, AwayMessageEvent *>	want_auto_resp
	Signal when someone requests your away message. More...
Signal1< void, SearchResultEvent *>	search_result
	Signal when a Search Result has been updated. More...

---

Detailed Description

The main library object.

This is the object the user interface instantiates for a connection, hooks up to signal on and has the methods to connect, disconnect and send events from.

---

Constructor & Destructor Documentation

ICQ2000::Client::Client (    )

Constructor for creating the Client object. Use this when uin/password are unavailable at time of creation, they can always be set later.

ICQ2000::Client::Client (  const unsigned int    uin, const string &    password )

Constructor for creating the Client object. Use this when the uin/password are available at time of creation, to save having to set them later. Parameters: uin  the owner's uin password  the owner's password

ICQ2000::Client::~Client (    )

Destructor for the Client object. This will free up all resources used by Client, including any Contact objects. It also automatically disconnects if you haven't done so already.

---

Member Function Documentation

void ICQ2000::Client::addContact (  Contact &    c )

Add a contact to your list. The contact passed by reference need only be a temporary. It is copied within the library before returning. Parameters: c  the contact passed by reference.

void ICQ2000::Client::fetchDetailContactInfo (  Contact *    c )

Request the detailed contact information for a Contact. When the server has replied with the details the library will signal a user info changed for this contact. Parameters: c  contact to fetch info for See also: ContactListEvent

void ICQ2000::Client::fetchSimpleContactInfo (  Contact *    c )

Request the simple contact information for a Contact. This consists of the contact alias, firstname, lastname and email. When the server has replied with the details the library will signal a user info changed for this contact. Parameters: c  contact to fetch info for See also: ContactListEvent

bool ICQ2000::Client::getAcceptInDC (    )  const

get whether to accept incoming direct connections. Returns: whether to accept incoming direct connections

bool ICQ2000::Client::getBOSServerOverridePort (    )  const

get whether the BOS redirect port will be overridden. Returns: override redirect port

unsigned short ICQ2000::Client::getBOSServerPort (    )  const

get the port that will be used on the BOS server. Returns: the port number

Contact * ICQ2000::Client::getContact (  const unsigned int    uin )

Get the Contact object for a given uin. Parameters: uin  the uin Returns: a pointer to the Contact object. NULL if no Contact with that uin exists on your list.

bool ICQ2000::Client::getInvisible (    )  const

Get your invisible status. Returns: Invisible boolean

string ICQ2000::Client::getLoginServerHost (    )  const

get the hostname for the currently set login server. Returns: the hostname

unsigned short ICQ2000::Client::getLoginServerPort (    )  const

get the currently set port on the login server. Returns: the port number

string ICQ2000::Client::getPassword (    )  const [inline]

Get the password you set for login. Returns: your password

Status ICQ2000::Client::getStatus (    )  const

Get your current status. Returns: your current status

const string & ICQ2000::Client::getTranslationMapFileName (    )  const

Get the File name of the translation map currently in use. Returns: filename of translation map

const string & ICQ2000::Client::getTranslationMapName (    )  const

Get the Name of the translation map currently in use. Returns: name of translation map

unsigned int ICQ2000::Client::getUIN (    )  const [inline]

Get your uin. Returns: your UIN

bool ICQ2000::Client::getUseOutDC (    )  const

get whether to make outgoing direct connections. Returns: whether to make outgoing direct connections

bool ICQ2000::Client::isConnected (    )  const

Boolean to determine if you are connected or not. Returns: connected

void ICQ2000::Client::Poll (    )

Perform any regular time dependant tasks. Poll must be called regularly (at least every 60 seconds) but I recommended 5 seconds, so timeouts work with good granularity. It is not related to the socket callback and socket listening. The client must call this Poll fairly regularly, to ensure that timeouts on message sending works correctly, and that the server is pinged once every 60 seconds.

void ICQ2000::Client::RegisterUIN (    )

Register a new UIN. Although support for this has been coded there isn't any support for settings your details yet, so being able to create a new user is largely useless. Todo: settings your user information

void ICQ2000::Client::removeContact (  const unsigned int    uin )

Remove a contact from your list. Parameters: uin  the uin of the contact to be removed

void ICQ2000::Client::SendEvent (  MessageEvent *    ev )

Used for sending a message event from the client. The Client should create the specific MessageEvent by dynamically allocating it with new. The library will take care of deleting it when appropriate. The MessageEvent will persist whilst the message has not be confirmed as delivered or failed yet. Exactly the same MessageEvent is signalled back in the messageack signal callback, so a client could use pointer equality comparison to match messages it has sent up to their acks.

void ICQ2000::Client::setAcceptInDC (  bool    d )

set whether to accept incoming direct connections. @d whether to accept incoming direct connections

void ICQ2000::Client::setBOSServerOverridePort (  const bool &    b )

set whether to override the port used to connect to the BOS server. If you would like to ignore the port that the login server tells you to connect to on the BOS server and instead use your own, set this to true and call setBOSServerPort with the port you would like to use. This method is largely unnecessary, if you set a different login port - for example to get through firewalls that block 5190, the login server will accept it fine and in the redirect message doesn't specify a port, so the library will default to using the same one as it used to connect to the login server anyway. Parameters: b  override redirect port

void ICQ2000::Client::setBOSServerPort (  const unsigned short &    port )

set the port to use to connect to the BOS server. This will only be used if you also called setBOSServerOverridePort(true). Parameters: port  the port number

void ICQ2000::Client::setLoginServerHost (  const string &    host )

set the hostname of the login server. You needn't touch this normally, it will default automatically to login.icq.com. Parameters: host  The host name of the server

void ICQ2000::Client::setLoginServerPort (  const unsigned short &    port )

set the port on the login server to connect to. Parameters: port  the port number

void ICQ2000::Client::setPassword (  const string &    password )  [inline]

Set the password to use at login. Parameters: password  your password

void ICQ2000::Client::setStatus (  const Status    st, bool    inv = false )

Set your status. This is used to set your status, as well as to connect and disconnect from the network. When you wish to connect to the ICQ network, set status to something other than STATUS_OFFLINE and connecting will be initiated. When you wish to disconnect set the status to STATUS_OFFLINE and disconnection will be initiated. Parameters: st  the status inv  whether to be invisible or not

bool ICQ2000::Client::setTranslationMap (  const string &    szMapFileName )

Set the translation map file to use for character set translation. Parameters: szMapFileName  the name of the translation map file Returns: whether setting translation map was a success

void ICQ2000::Client::setUIN (  unsigned int    uin )  [inline]

Set your uin. Use to set what the uin you would like to log in as, before connecting. Parameters: uin  your UIN

void ICQ2000::Client::setUseOutDC (  bool    d )

set whether to make outgoing direct connections. @d whether to make outgoing direct connections

void ICQ2000::Client::SignalMessageQueueChanged (  Contact *    c )

Method for indicating that the queue of message events automatically stored in a contact has changed. Todo: This will probably change so that it isn't necessary to call this anymore.

void ICQ2000::Client::SignalUserInfoChange (  Contact *    c )

Method for indicating the User Info for a contact has changed. The reason this is not automatically signalled when the set methods are called on Contact are because large numbers of setting contact properties, such as on startup of a client would be very inefficient then. It is trusted that a Client will call this method when it has finished changing properties on a Contact, just as the library will. Parameters: c  the contact

void ICQ2000::Client::socket_cb (  int    fd, SocketEvent::Mode    m )

Callback from client to tell library the socket is ready. The client must call this method when select says that the file descriptor is available for mode (read, write or exception). The client will know what socket descriptors to select on, and with what mode from the SocketEvent's it receives. It is worth looking at the shell.cpp example in the examples directory and fully understanding how it works with select. Parameters: fd  the socket descriptor m  the mode that the socket is available on

bool ICQ2000::Client::usingDefaultMap (    )  const

Determine whether the default map (no translation) is in use. Returns: whether using the default map

---

Member Data Documentation

Signal1<void,ConnectedEvent*> ICQ2000::Client::connected

The signal to connect to for listening to ConnectedEvent's. A ConnectedEvent is signalled when the client is online proper. See also: disconnected, ConnectedEvent

Signal1<void,ContactListEvent*> ICQ2000::Client::contactlist

The signal to connect to for listening to Contact list events. See also: ContactListEvent

Signal1<void,DisconnectedEvent*> ICQ2000::Client::disconnected

The signal to connect to for listening to DisconnectedEvent's. A DisconnectedEvent is signalled when you were disconnected from the server. This could have been because it was requested, or the server might have chucked you off. More information can be in the DisconnectedEvent. DisconnectedEvent's don't necessarily match a ConnectedEvent, if you try connecting with an incorrect password, you will never get a ConnectedEvent before the DisconnectedEvent signalling incorrect password. See also: connected, DisconnectedEvent

Signal1<void,LogEvent*> ICQ2000::Client::logger

The signal for all logging messages that are passed back to the client. This leads to a very flexible logging system, as the user interface may decide where to write the log message to (stdout, a dialog box, etc..) and also may pick which type of log messages to display and which to ignore. See also: LogEvent

Signal1<void,MessageEvent*> ICQ2000::Client::messageack

The signal to connect to for listening to the acknowledgements that the library will generate for when the remote client sends back a message ack. Additionally it will it is used for signalling to the Client message delivery failures and when messages are being reattempted to be send through the server. See also: messaged, MessageEvent

Signal1<bool,MessageEvent*,StopOnTrueMarshal> ICQ2000::Client::messaged

The signal to connect to for listening to incoming MessageEvent. This includes far more than just messages. See also: MessageEvent

Signal1<void,NewUINEvent*> ICQ2000::Client::newuin

The signal for when registering a new UIN has succeeded or failed after a call to RegisterUIN(). See also: NewUINEvent, RegisterUIN

Signal1<void,RateInfoChangeEvent*> ICQ2000::Client::rate

The signal for when the server signals the rate at which the client is sending has been changed. See also: RateInfoChangeEvent

Signal1<void,SearchResultEvent*> ICQ2000::Client::search_result

Signal when a Search Result has been updated. The last signal on a search result will be with SearchResultEvent::isFinished() set to true. After this the event is finished and deleted from memory by the library.

Signal1<void,SocketEvent*> ICQ2000::Client::socket

The signal for socket events. All clients must listen to this and implement their particular scheme of blocking on multiple sockets for read/write/exception, usually the select system call in someway. Often toolkits will hide all the details of select inside them, such as the way gtk or gtkmm do. See also: SocketEvent

Signal1<void,MyStatusChangeEvent*> ICQ2000::Client::statuschanged

Signal to listen to for when the server has accepted a status change request. Your change in status has been acknowledged by the server then, and other clients will see the new status. In a User Interface the setting of the status should be done separately from the updating the display of it. The updating the display of it should only be done once you have received this signal. See also: MyStatusChangeEvent

Signal1<void,AwayMessageEvent*> ICQ2000::Client::want_auto_resp

Signal when someone requests your away message. The client should setMessage in the AutoMessageEvent to what your away message is. This allows dynamic away messages for different people.

---

The documentation for this class was generated from the following files:

• Client.h
• Client.cpp

---