Yate: ClientContact Class Reference

Yate

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Protected Attributes | Friends | List of all members
ClientContact Class Reference

A client contact. More...

`#include <yatecbase.h>`

Inheritance diagram for ClientContact:

## Public Types
enum | Subscription { SubFrom = 0x01, SubTo = 0x02 }

## Public Member Functions
| ClientContact (ClientAccount *owner, const char *id, const char *name=0, const char *uri=0)
| ClientContact (ClientAccount *owner, const NamedList &params, const char *id=0, const char *uri=0)
ClientAccount * | account ()
const String & | accountName () const
const URI & | uri () const
void | setUri (const char *u)
const String & | subscriptionStr () const
bool | subscriptionFrom () const
bool | subscriptionTo () const
bool | setSubscription (const String &value)
ObjList & | resources ()
bool | online () const
void | setOnline (bool on)
ObjList & | groups ()
bool | local (bool defVal=false) const
void | setLocal (bool on)
bool | remote (bool defVal=false) const
void | setRemote (bool on)
void | setDockedChat (bool on)
void | getContactSection (String &buf)
virtual const String & | toString () const
virtual MucRoom * | mucRoom ()
String & | buildInstanceId (String &dest, const String &inst=String::empty())
void | buildIdHash (String &buf, const String &prefix=String::empty())
bool | isChatWnd (Window *wnd)
bool | hasChat ()
virtual void | flashChat (bool on=true)
virtual bool | sendChat (const char *body, const String &res=String::empty(), const String &type=String::empty(), const char *state="active")
virtual void | getChatInput (String &text, const String &name="message")
virtual void | setChatInput (const String &text=String::empty(), const String &name="message")
virtual void | getChatHistory (String &text, bool richText=false, const String &name="history")
virtual void | setChatHistory (const String &text, bool richText=false, const String &name="history")
virtual void | addChatHistory (const String &what, NamedList *&params, const String &name="history")
virtual void | getChatProperty (const String &name, const String &prop, String &value)
virtual void | setChatProperty (const String &name, const String &prop, const String &value)
bool | isChatVisible ()
virtual bool | showChat (bool visible, bool active=false)
Window * | getChatWnd ()
virtual void | createChatWindow (bool force=false, const char *name=0)
virtual void | updateChatWindow (const NamedList &params, const char *title=0, const char *icon=0)
virtual bool | isChatActive ()
void | destroyChatWindow ()
virtual String * | findGroup (const String &group)
virtual bool | appendGroup (const String &group)
virtual bool | removeGroup (const String &group)
virtual bool | setGroups (const NamedList &list, const String &param)
virtual ClientResource * | status (bool ref=false)
virtual ClientResource * | findResource (const String &id, bool ref=false)
virtual ClientResource * | findAudioResource (bool ref=false)
virtual ClientResource * | findFileTransferResource (bool ref=false)
virtual ClientResource * | appendResource (const String &id)
virtual bool | insertResource (ClientResource *res)
virtual bool | removeResource (const String &id)
NamedList & | share ()
bool | haveShare () const
virtual void | updateShare ()
virtual void | saveShare ()
virtual void | clearShare ()
virtual bool | setShareDir (const String &name, const String &path, bool save=true)
virtual bool | removeShare (const String &name, bool save=true)
ObjList & | shared ()
bool | haveShared () const
virtual ClientDir * | getShared (const String &name, bool create=false)
virtual bool | removeShared (const String &name=String::empty(), ClientDir **removed=0)
Public Member Functions inherited from RefObject
| RefObject ()
virtual | ~RefObject ()
virtual void * | getObject (const String &name) const
virtual bool | alive () const
bool | ref ()
bool | deref ()
int | refcount () const
virtual void | destruct ()
Public Member Functions inherited from GenObject
| GenObject ()
virtual | ~GenObject ()
virtual const String & | traceId () const
NamedCounter * | getObjCounter () const
NamedCounter * | setObjCounter (NamedCounter *counter)

## Static Public Member Functions
static String & | buildContactId (String &dest, const String &account, const String &contact)
static void | splitContactId (const String &src, String &account)
static void | splitContactInstanceId (const String &src, String &account, String &contact, String *instance=0)
static String & | buildContactInstanceId (String &dest, const String &cId, const String &inst=String::empty())
Static Public Member Functions inherited from RefObject
static bool | alive (const RefObject *obj)
static bool | efficientIncDec ()
Static Public Member Functions inherited from GenObject
static void * | getObject (const String &name, const GenObject *obj)
static bool | getObjCounting ()
static void | setObjCounting (bool enable)
static NamedCounter * | getObjCounter (const String &name, bool create=true)
static ObjList & | getObjCounters ()

## Public Attributes
String | m_name
NamedList | m_params

## Static Public Attributes
static String | s_chatPrefix
static String | s_dockedChatWnd
static String | s_dockedChatWidget
static String | s_mucsWnd
static String | s_chatInput

## Protected Member Functions
| ClientContact (ClientAccount *owner, const char *id, bool mucRoom)
void | removeFromOwner ()
virtual void | destroyed ()
Protected Member Functions inherited from RefObject
virtual void | zeroRefs ()
bool | resurrect ()

## Protected Attributes
ClientAccount * | m_owner
bool | m_online
String | m_id
String | m_subscription
Flags32 | m_sub
URI | m_uri
ObjList | m_resources
ObjList | m_groups
bool | m_dockedChat
String | m_chatWndName
NamedList | m_share
ObjList | m_shared

## Friends
class | ClientAccount

## Detailed Description

A client contact.

A client contact The contact is using the owner's mutex to lock it's operations

## Member Enumeration Documentation

enum Subscription

Subscription flags

## Constructor & Destructor Documentation

ClientContact | ( | ClientAccount * | owner,
|  | const char * | id,
|  | const char * | name = `0`,
|  | const char * | uri = `0`
| ) |  |
| explicit

Constructor. Append itself to the owner's list

Parameters

  owner | The contact's owner
  id | The contact's id
  name | Optional display name. Defaults to the id's value if 0
  uri | Optional contact URI

ClientContact | ( | ClientAccount * | owner,
|  | const NamedList & | params,
|  | const char * | id = `0`,
|  | const char * | uri = `0`
| ) |  |
| explicit

Constructor. Build a contact from a list of parameters. Append itself to the owner's list

Parameters

  owner | The contact's owner
  params | The list of parameters used to build this contact
  id | Optional contact id
  uri | Optional contact URI

ClientContact | ( | ClientAccount * | owner,
|  | const char * | id,
|  | bool | mucRoom
| ) |  |
| explicitprotected

Constructor. Append itself to the owner's list

Parameters

  owner | The contact's owner
  id | The contact's id
  mucRoom | True if this contact is a MUC room

## Member Function Documentation

ClientAccount* account | ( |  | ) |
| inline

Get this contact's account

Returns
  This contact's account

const String& accountName | ( |  | ) | const
| inline

Get this contact account's name (id)

Returns
  This contact account name (id) or an empty string if none

References String::empty(), and ClientAccount::toString().

Referenced by MucRoom::buildMucRoom(), and ClientContact::getContactSection().

virtual void addChatHistory | ( | const String & | what,
|  | NamedList *& | params,
|  | const String & | name = `"history"`
| ) |  |
| virtual

Add an entry to chat history

Parameters

  what | Item to add (chat_in, chat_out, ...)
  params | Chat history item parameters (it will be consumed and zeroed)
  name | Chat history widget name

virtual bool appendGroup | ( | const String & | group | ) |
| virtual

Append a group to this contact

Parameters

  group | Group's name

Returns
  False if the group already exists

virtual ClientResource* appendResource | ( | const String & | id | ) |
| virtual

Append a resource having a given id

Parameters

  id | The id of the desired resource

Returns
  ClientResource pointer or 0 if a resource with the given name already exists

Reimplemented in MucRoom.

static String& buildContactId | ( | String & | dest,
|  | const String & | account,
|  | const String & | contact
| ) |  |
| inlinestatic

Build a contact id to be used in UI (all strings are URI escaped using extra '|' character)

Parameters

  dest | Destination string
  account | Account owning the contact
  contact | The contact's id

Returns
  Destination string

References String::toLower(), and String::uriEscape().

Referenced by ClientContact::getContactSection().

static String& buildContactInstanceId | ( | String & | dest,
|  | const String & | cId,
|  | const String & | inst = `String::empty()`
| ) |  |
| inlinestatic

Build a contact instance id to be used in UI

Parameters

  dest | Destination string
  cId | Contact id
  inst | Instance name

Returns
  Destination string

References String::uriEscape().

Referenced by ClientContact::buildInstanceId().

void buildIdHash | ( | String & | buf,
|  | const String & | prefix = `String::empty()`
| ) |  |
| inline

Build a string from prefix and contact id hash

Parameters

  buf | Destination string
  prefix | Optional prefix

References Hasher::hexDigest().

String& buildInstanceId | ( | String & | dest,
|  | const String & | inst = `String::empty()`
| ) |  |
| inline

Build a contact instance id to be used in UI

Parameters

  dest | Destination string
  inst | Instance name

Returns
  Destination string

References ClientContact::buildContactInstanceId().

virtual void clearShare | ( |  | ) |
| virtual

Clear share list

virtual void createChatWindow | ( | bool | force = `false`,
|  | const char * | name = `0`
| ) |  |
| virtual

Create the chat window

Parameters

  force | True to destroy the current one if any
  name | The window's name. Defaults to global name if empty

void destroyChatWindow | ( |  | ) |

Close the chat window or destroy docked chat item

virtual void destroyed | ( |  | ) |
| protectedvirtual

Remove from owner. Destroy the chat window. Release data

Reimplemented from RefObject.

Reimplemented in MucRoom.

virtual ClientResource* findAudioResource | ( | bool | ref = `false` | ) |
| virtual

Get the first resource with audio capability

Parameters

  ref | True to obtain a referenced pointer

Returns
  ClientResource pointer or 0 if not found

virtual ClientResource* findFileTransferResource | ( | bool | ref = `false` | ) |
| virtual

Get the first resource with file transfer capability capability

Parameters

  ref | True to obtain a referenced pointer

Returns
  ClientResource pointer or 0 if not found

virtual String* findGroup | ( | const String & | group | ) |
| virtual

Find a group this contact might belong to

Parameters

  group | The name of the group to find

Returns
  String pointer or 0 if not found

virtual ClientResource* findResource | ( | const String & | id,
|  | bool | ref = `false`
| ) |  |
| virtual

Find a resource having a given id

Parameters

  id | The id of the desired resource
  ref | True to obtain a referenced pointer

Returns
  ClientResource pointer or 0 if not found

Reimplemented in MucRoom.

virtual void flashChat | ( | bool | on = `true` | ) |
| virtual

Flash chat window/item to notify the user

Parameters

  on | True to start, false to stop flashing

virtual void getChatHistory | ( | String & | text,
|  | bool | richText = `false`,
|  | const String & | name = `"history"`
| ) |  |
| virtual

Retrieve the contents of the chat history widget

Parameters

  text | Chat history text
  richText | Retrieve rich/plain text flag
  name | Chat history widget name

virtual void getChatInput | ( | String & | text,
|  | const String & | name = `"message"`
| ) |  |
| virtual

Retrieve the contents of the chat input widget

Parameters

  text | Chat input text
  name | Chat input widget name

virtual void getChatProperty | ( | const String & | name,
|  | const String & | prop,
|  | String & | value
| ) |  |
| virtual

Retrieve a chat widget' property

Parameters

  name | Widget name
  prop | Property name
  value | Destination buffer

Window* getChatWnd | ( |  | ) |

Get the chat window

Returns
  Valid Window pointer or 0

void getContactSection | ( | String & | buf | ) |
| inline

Remove account prefix from contact id and URI unescape the result

Parameters

  buf | Destination buffer

References ClientContact::accountName(), ClientContact::buildContactId(), String::empty(), String::startSkip(), ClientContact::toString(), and String::uriUnescape().

virtual ClientDir* getShared | ( | const String & | name,
|  | bool | create = `false`
| ) |  |
| virtual

Retrieve shared data for a given resource

Parameters

  name | Resource name
  create | True to create if not found

Returns
  True if changed

ObjList& groups | ( |  | ) |
| inline

Get the group list of this contact

Returns
  The group list of this contact

bool hasChat | ( |  | ) |

Check if this contact has a chat widget (window or docked item)

Returns
  True if this contact has a chat window or docked item

bool haveShare | ( |  | ) | const
| inline

Check if the list of share contains something

Returns
  True if share list is not empty

References NamedList::getParam().

bool haveShared | ( |  | ) | const

Check if the list of shared contains something

Returns
  True if shared list is not empty

virtual bool insertResource | ( | ClientResource * | res | ) |
| virtual

Insert a resource in the list by its priority. If the resource is already there it will be extracted and re-inserted

Parameters

  res | The resource to insert

Returns
  True on success, false a resource with the same name already exists

Reimplemented in MucRoom.

virtual bool isChatActive | ( |  | ) |
| virtual

Check if the contact chat is active

Returns
  True if the contact's chat window/page is active

bool isChatVisible | ( |  | ) |
| inline

Check if this contact's chat window is visible

Returns
  True if this contact's chat window is visible

bool isChatWnd | ( | Window * | wnd | ) |
| inline

Check if a window is this contact's chat

Parameters

  wnd | The window to check

Returns
  True if the given window is this contact's chat

References Window::toString().

bool local | ( | bool | defVal = `false` | ) | const
| inline

Check if the contact is locally saved

Parameters

  defVal | Default value to return if parameter is invalid

Returns
  True if the contact is locally saved

References NamedList::getBoolValue(), and TelEngine::YSTRING().

virtual MucRoom* mucRoom | ( |  | ) |
| inlinevirtual

Return a MucRoom contact from this one

Returns
  MucRoom pointer or 0

Reimplemented in MucRoom.

Referenced by ClientContact::setDockedChat().

bool online | ( |  | ) | const
| inline

Check if the contact is online (the online flag is set or has at least 1 resource in list)

Returns
  True if the contact is online

References ObjList::skipNull().

bool remote | ( | bool | defVal = `false` | ) | const
| inline

Check if the contact is saved on server

Parameters

  defVal | Default value to return if parameter is invalid

Returns
  True if the contact is saved on server

References NamedList::getBoolValue(), and TelEngine::YSTRING().

void removeFromOwner | ( |  | ) |
| protected

Remove from owner

virtual bool removeGroup | ( | const String & | group | ) |
| virtual

Remove a contact's group

Parameters

  group | Group's name

Returns
  False if the group was not found

virtual bool removeResource | ( | const String & | id | ) |
| virtual

Remove a resource having a given id

Parameters

  id | The id of the desired resource

Returns
  True if the resource was removed

virtual bool removeShare | ( | const String & | name,
|  | bool | save = `true`
| ) |  |
| virtual

Remove a share item

Parameters

  name | Share name
  save | True to save now if changed

Returns
  True if changed

virtual bool removeShared | ( | const String & | name = `String::empty()`,
|  | ClientDir ** | removed = `0`
| ) |  |
| virtual

Remove shared data

Parameters

  name | Resource name to remove, empty to remove all
  removed | Optional pointer to removed directory

Returns
  True if changed

ObjList& resources | ( |  | ) |
| inline

Get the resource list of this contact

Returns
  The resource list of this contact

virtual void saveShare | ( |  | ) |
| virtual

Save share list

virtual bool sendChat | ( | const char * | body,
|  | const String & | res = `String::empty()`,
|  | const String & | type = `String::empty()`,
|  | const char * | state = `"active"`
| ) |  |
| virtual

Send chat to contact (enqueue a msg.execute message)

Parameters

  body | Chat body
  res | Optional target instance
  type | Optional message type parameter
  state | Optional chat state

Returns
  True on success

virtual void setChatHistory | ( | const String & | text,
|  | bool | richText = `false`,
|  | const String & | name = `"history"`
| ) |  |
| virtual

Set the contents of the chat history widget

Parameters

  text | Chat history text
  richText | Set rich/plain text flag
  name | Chat history widget name

virtual void setChatInput | ( | const String & | text = `String::empty()`,
|  | const String & | name = `"message"`
| ) |  |
| virtual

Set the chat input widget text

Parameters

  text | Chat input text
  name | Chat input widget name

virtual void setChatProperty | ( | const String & | name,
|  | const String & | prop,
|  | const String & | value
| ) |  |
| virtual

Set a chat widget' property

Parameters

  name | Widget name
  prop | Property name
  value | Property value

void setDockedChat | ( | bool | on | ) |
| inline

Set/reset the docked chat flag for non MucRoom contact

Parameters

  on | The new value for docked chat flag

References ClientContact::mucRoom().

virtual bool setGroups | ( | const NamedList & | list,
|  | const String & | param
| ) |  |
| virtual

Replace contact's groups from a list of parameters

Parameters

  list | The list of parameters
  param | The parameter name to handle

Returns
  True if the list changed

void setLocal | ( | bool | on | ) |
| inline

Set contact locally saved flag

Parameters

  on | The new value for locally saved flag

References String::boolText(), and NamedList::setParam().

void setOnline | ( | bool | on | ) |
| inline

Set the online flag

Parameters

  on | The new value for online flag

void setRemote | ( | bool | on | ) |
| inline

Set contact server saved flag

Parameters

  on | The new value for server saved flag

References String::boolText(), and NamedList::setParam().

virtual bool setShareDir | ( | const String & | name,
|  | const String & | path,
|  | bool | save = `true`
| ) |  |
| virtual

Set a directory we share with this contact If share name is not empty it must be unique. Fails if another share has the same name

Parameters

  name | Share name
  path | Directory path
  save | True to save now if changed

Returns
  True if changed

bool setSubscription | ( | const String & | value | ) |

Set contact's subscription

Parameters

  value | Subscription value

Returns
  True if changed

void setUri | ( | const char * | u | ) |
| inline

Set this contact's URI

Parameters

  u | New contact URI

NamedList& share | ( |  | ) |
| inline

Retrieve files and folders we share with this contact

Returns
  List of files and folders we share with this contact

ObjList& shared | ( |  | ) |
| inline

Retrieve shared data

Returns
  Shared data list

virtual bool showChat | ( | bool | visible,
|  | bool | active = `false`
| ) |  |
| virtual

Show or hide this contact's chat window or docked item

Parameters

  visible | True to show, false to hide the window or destroy the docked item
  active | True to activate the window or select the docked item if shown

Returns
  True on success

static void splitContactId | ( | const String & | src,
|  | String & | account
| ) |  |
| inlinestatic

Retrieve the account part of a contact id

Parameters

  src | Source string
  account | Account id (URI unescaped)

References String::find(), String::substr(), and String::uriUnescape().

static void splitContactInstanceId | ( | const String & | src,
|  | String & | account,
|  | String & | contact,
|  | String * | instance = `0`
| ) |  |
| static

Split a contact instance id in account/contact/instance parts

Parameters

  src | Source string
  account | Account id (URI unescaped)
  contact | Contact id
  instance | Optional pointer to a String to be filled with instance id (URI unescaped)

virtual ClientResource* status | ( | bool | ref = `false` | ) |
| virtual

Find the resource with the lowest status

Parameters

  ref | True to obtain a referenced pointer

Returns
  ClientResource pointer or 0 if not found

Reimplemented in MucRoom.

bool subscriptionFrom | ( |  | ) | const
| inline

Check if contact is subscribed to our presence

Returns
  True if contact is subscribed to our presence

References Flags32::flag().

const String& subscriptionStr | ( |  | ) | const
| inline

Retrieve contact subscription

Returns
  Contact subscription string

bool subscriptionTo | ( |  | ) | const
| inline

Check we are subscribed to contact's presence

Returns
  True if we are subscribed to contact's presence

References Flags32::flag().

virtual const String& toString | ( |  | ) | const
| inlinevirtual

Get a string representation of this object

Returns
  The contact's id

Reimplemented from GenObject.

Referenced by ClientContact::getContactSection().

virtual void updateChatWindow | ( | const NamedList & | params,
|  | const char * | title = `0`,
|  | const char * | icon = `0`
| ) |  |
| virtual

Update contact parameters in chat window

Parameters

  params | Parameters to set
  title | Optional window title to set (ignored if docked)
  icon | Optional window icon to set (ignored if docked)

virtual void updateShare | ( |  | ) |
| virtual

(re)load share list

const URI& uri | ( |  | ) | const
| inline

Get this contact's URI

Returns
  This contact's URI

Referenced by MucRoom::buildMucRoom().

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

- yatecbase.h