Main Page   Namespace List   Class Hierarchy   Compound List   File List   Compound Members   Related Pages  

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.

 Client (const unsigned int uin, const std::string &password)
 Constructor for creating the Client object.

 ~Client ()
 Destructor for the Client object.

void setUIN (unsigned int uin)
 Set your uin.

unsigned int getUIN () const
 Get your uin.

void setPassword (const std::string &password)
 Set the password to use at login.

std::string getPassword () const
 Get the password you set for login.

ContactRef getSelfContact ()
bool setTranslationMap (const std::string &szMapFileName)
 Set the translation map file to use for character set translation.

const std::string & getTranslationMapFileName () const
 Get the File name of the translation map currently in use.

const std::string & getTranslationMapName () const
 Get the Name of the translation map currently in use.

bool usingDefaultMap () const
 Determine whether the default map (no translation) is in use.

void SendEvent (MessageEvent *ev)
 Used for sending a message event from the client.

void setStatus (const Status st)
 Set your status, without effecting invisibility (your last requested invisible state will be used).

void setStatus (const Status st, bool inv)
 Set your status.

void setInvisible (bool inv)
 Set your invisibility, without effecting status (your last requested status will be used).

void setWebAware (bool wa)
Status getStatus () const
 Get your current status.

bool getInvisible () const
 Get your invisible status.

Status getStatusWanted () const
 Get the last requested status.

bool getInvisibleWanted () const
 Get the last invisibility status wanted.

bool getWebAware () const
void uploadSelfDetails ()
void addContact (ContactRef c)
 Add a contact to your list.

void removeContact (const unsigned int uin)
 Remove a contact from your list.

void addVisible (ContactRef c)
 Add a contact to your visible list.

void removeVisible (const unsigned int uin)
 Remove a contact from your visible list.

void addInvisible (ContactRef c)
 Add a contact to your invisible list.

void removeInvisible (const unsigned int uin)
 Remove a contact from your invisible list.

ContactRef getContact (const unsigned int uin)
 Get the Contact object for a given uin.

ContactList & getContactList ()
 Get the ContactList object used for the main library.

void fetchSimpleContactInfo (ContactRef c)
 Request the simple contact information for a Contact.

void fetchDetailContactInfo (ContactRef c)
 Request the detailed contact information for a Contact.

void fetchServerBasedContactList ()
void fetchSelfSimpleContactInfo ()
void fetchSelfDetailContactInfo ()
SearchResultEventsearchForContacts (const std::string &nickname, const std::string &firstname, const std::string &lastname)
SearchResultEventsearchForContacts (const std::string &nickname, const std::string &firstname, const std::string &lastname, const std::string &email, AgeRange age, Sex sex, unsigned char language, const std::string &city, const std::string &state, unsigned short country, const std::string &company_name, const std::string &department, const std::string &position, bool only_online)
SearchResultEventsearchForContacts (unsigned int uin)
SearchResultEventsearchForContacts (const std::string &keyword)
void setLoginServerHost (const std::string &host)
 set the hostname of the login server.

std::string getLoginServerHost () const
 get the hostname for the currently set login server.

void setLoginServerPort (const unsigned short &port)
 set the port on the login server to connect to

unsigned short getLoginServerPort () const
 get the currently set port on the login server.

void setBOSServerOverridePort (const bool &b)
 set whether to override the port used to connect to the BOS server.

bool getBOSServerOverridePort () const
 get whether the BOS redirect port will be overridden.

void setBOSServerPort (const unsigned short &port)
 set the port to use to connect to the BOS server.

unsigned short getBOSServerPort () const
 get the port that will be used on the BOS server.

void setSMTPServerHost (const std::string &host)
std::string getSMTPServerHost () const
void setSMTPServerPort (unsigned short port)
unsigned short getSMTPServerPort () const
void setAcceptInDC (bool d)
 set whether to accept incoming direct connections

bool getAcceptInDC () const
 get whether to accept incoming direct connections

void setUseOutDC (bool d)
 set whether to make outgoing direct connections

bool getUseOutDC () const
 get whether to make outgoing direct connections

void setPortRangeLowerBound (unsigned short lower)
 set the lower bound of the portrange for incoming connections (esp.

void setPortRangeUpperBound (unsigned short upper)
 set the upper bound of the portrange for incoming connections (esp.

unsigned short getPortRangeLowerBound () const
 get lower bound of the portrange used for incoming connections

unsigned short getPortRangeUpperBound () const
 get upper bound of the portrange used for incoming connections

void setUsePortRange (bool b)
 set whether a portrange should be used for incoming connections

bool getUsePortRange () const
 get whether a portrange should be used for incoming connections

void Poll ()
 Perform any regular time dependant tasks.

void socket_cb (int fd, SocketEvent::Mode m)
 Callback from client to tell library the socket is ready.

void RegisterUIN ()
 Register a new UIN.

bool isConnected () const
 Boolean to determine if you are connected or not.


Public Attributes

SigC::Signal1< void, ConnectingEvent * > connecting
 The signal to connect to for listening to ConnectingEvent's.

SigC::Signal1< void, ConnectedEvent * > connected
 The signal to connect to for listening to ConnectedEvent's.

SigC::Signal1< void, DisconnectedEvent * > disconnected
 The signal to connect to for listening to DisconnectedEvent's.

SigC::Signal1< void, MessageEvent * > messaged
 The signal to connect to for listening to incoming MessageEvent.

SigC::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.

SigC::Signal1< void, ContactListEvent * > contactlist
 The signal to connect to for listening to Contact list events.

SigC::Signal1< void, UserInfoChangeEvent * > contact_userinfo_change_signal
 The signal to connect to for listening for Contact Userinfo events.

SigC::Signal1< void, StatusChangeEvent * > contact_status_change_signal
 The signal to connect to for listening for Contact Status change events.

SigC::Signal1< void, NewUINEvent * > newuin
 The signal for when registering a new UIN has succeeded or failed after a call to RegisterUIN().

SigC::Signal1< void, RateInfoChangeEvent * > rate
 The signal for when the server signals the rate at which the client is sending has been changed.

SigC::Signal1< void, LogEvent * > logger
 The signal for all logging messages that are passed back to the client.

SigC::Signal1< void, SocketEvent * > socket
 The signal for socket events.

SigC::Signal1< void, UserInfoChangeEvent * > self_contact_userinfo_change_signal
 The signal to connect to for listening for Self Contact Userinfo events.

SigC::Signal1< void, StatusChangeEvent * > self_contact_status_change_signal
 The signal to connect to for listening for Self Contact Status change events.

SigC::Signal1< void, ICQMessageEvent * > want_auto_resp
 Signal when someone requests your away message.

SigC::Signal1< void, SearchResultEvent * > search_result
 Signal when a Search Result has been updated.

SigC::Signal1< void, ServerBasedContactEvent * > server_based_contact_list


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 std::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 ContactRef    c
 

Add a contact to your list.

Parameters:
c  the contact passed as a reference counted object (ref_ptr<Contact> or ContactRef).

void ICQ2000::Client::addInvisible ContactRef    c
 

Add a contact to your invisible list.

Parameters:
c  the contact passed as a reference counted object (ref_ptr<Contact> or ContactRef).

void ICQ2000::Client::addVisible ContactRef    c
 

Add a contact to your visible list.

Parameters:
c  the contact passed as a reference counted object (ref_ptr<Contact> or ContactRef).

void ICQ2000::Client::fetchDetailContactInfo ContactRef    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 ContactRef    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

ContactRef 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.

ContactList & ICQ2000::Client::getContactList  
 

Get the ContactList object used for the main library.

Returns:
a reference to the ContactList

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
 

Get the password you set for login.

Returns:
your password

unsigned short ICQ2000::Client::getPortRangeLowerBound   const
 

get lower bound of the portrange used for incoming connections

Returns:
lower bound

unsigned short ICQ2000::Client::getPortRangeUpperBound   const
 

get upper bound of the portrange used for incoming connections

Returns:
upper bound

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
 

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::getUsePortRange   const
 

get whether a portrange should be used for incoming connections

Returns:
whether to use a portrange

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::removeContact const unsigned int    uin
 

Remove a contact from your list.

Parameters:
uin  the uin of the contact to be removed

void ICQ2000::Client::removeInvisible const unsigned int    uin
 

Remove a contact from your invisible list.

Parameters:
uin  the uin of the contact to be removed

void ICQ2000::Client::removeVisible const unsigned int    uin
 

Remove a contact from your visible 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::setInvisible bool    inv
 

Set your invisibility, without effecting status (your last requested status will be used).

Parameters:
inv  invisibility

void ICQ2000::Client::setLoginServerHost const std::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 std::string &    password
 

Set the password to use at login.

Parameters:
password  your password

void ICQ2000::Client::setPortRangeLowerBound unsigned short    lower
 

set the lower bound of the portrange for incoming connections (esp.

behind a firewall) you have to restart the TCPServer(s) for this to take effect

Parameters:
lower  lower bound

void ICQ2000::Client::setPortRangeUpperBound unsigned short    upper
 

set the upper bound of the portrange for incoming connections (esp.

behind a firewall) you have to restart the TCPServer(s) for this to take effect

Parameters:
upper  upper bound

void ICQ2000::Client::setStatus const Status    st,
bool    inv
 

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

void ICQ2000::Client::setStatus const Status    st
 

Set your status, without effecting invisibility (your last requested invisible state will be used).

Parameters:
st  the status

bool ICQ2000::Client::setTranslationMap const std::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
 

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::setUsePortRange bool    b
 

set whether a portrange should be used for incoming connections

Parameters:
b  whether to use a portrange

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

SigC::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

SigC::Signal1<void,ConnectingEvent*> ICQ2000::Client::connecting
 

The signal to connect to for listening to ConnectingEvent's.

A ConnectingEvent is signalled when the client is trying to go online.

See also:
connected, ConnectingEvent

SigC::Signal1<void,StatusChangeEvent*> ICQ2000::Client::contact_status_change_signal
 

The signal to connect to for listening for Contact Status change events.

See also:
StatusChangeEvent

SigC::Signal1<void,UserInfoChangeEvent*> ICQ2000::Client::contact_userinfo_change_signal
 

The signal to connect to for listening for Contact Userinfo events.

See also:
UserInfoChangeEvent

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

The signal to connect to for listening to Contact list events.

See also:
ContactListEvent

SigC::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

SigC::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

SigC::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

SigC::Signal1<void,MessageEvent*> ICQ2000::Client::messaged
 

The signal to connect to for listening to incoming MessageEvent.

This includes far more than just messages.

See also:
MessageEvent

SigC::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

SigC::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

SigC::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.

SigC::Signal1<void,StatusChangeEvent*> ICQ2000::Client::self_contact_status_change_signal
 

The signal to connect to for listening for Self Contact Status change events.

See also:
StatusChangeEvent

SigC::Signal1<void,UserInfoChangeEvent*> ICQ2000::Client::self_contact_userinfo_change_signal
 

The signal to connect to for listening for Self Contact Userinfo events.

See also:
UserInfoChangeEvent

SigC::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

SigC::Signal1<void,ICQMessageEvent*> 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:
Generated on Sun Jul 21 10:57:33 2002 for libicq2000 by doxygen1.2.16