retronetworking
/
yate
11
0
Fork 1
Code Issues Pull Requests 1 Projects Releases Wiki Activity
yate/yatecbase.h

5994 lines
193 KiB
C++
Raw Permalink Blame History

/**
* yatecbase.h
* This file is part of the YATE Project http://YATE.null.ro
*
* Common base classes for all telephony clients
*
* Yet Another Telephony Engine - a fully featured software PBX and IVR
* Copyright (C) 2004-2014 Null Team
*
* This software is distributed under multiple licenses;
* see the COPYING file in the main directory for licensing
* information for this specific distribution.
*
* This use of this software may be subject to additional restrictions.
* See the LEGAL file in the main directory for details.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
*/
#ifndef __YATECBASE_H
#define __YATECBASE_H
#ifndef __cplusplus
#error C++ is required
#endif
#include <yatephone.h>
/**
* Holds all Telephony Engine related classes.
*/
namespace TelEngine {
class Flags32; // Keeps a 32bit length flag mask
class NamedInt; // A named integer value
class Window; // A generic window
class UIWidget; // A custom widget
class UIFactory; // Base factory used to build custom widgets
class Client; // The client
class ClientChannel; // A client telephony channel
class ClientDriver; // The client telephony driver
class ClientLogic; // Base class for all client logics
class DefaultLogic; // The client's default logic
class ClientWizard; // A client wizard
class ClientAccount; // A client account
class ClientAccountList; // A client account list
class ClientContact; // A client contact
class ClientResource; // A client contact's resource
class MucRoomMember; // A MUC room member
class MucRoom; // An account's MUC room contact
class DurationUpdate; // Class used to update UI durations
class ClientSound; // A sound file
class ClientFileItem; // Base class for file/dir items
class ClientDir; // A directory
class ClientFile; // A file
/**
* This class keeps a 32bit length flag mask
* @short A 32 bit length list of flags
*/
class YATE_API Flags32
{
public:
/**
* Constructor
*/
inline Flags32()
: m_flags(0)
{}
/**
* Constructor
* @param value Flags value
*/
inline Flags32(u_int32_t value)
: m_flags(value)
{}
/**
* Retrieve flags value
* @return The flags
*/
inline u_int32_t flags() const
{ return m_flags; }
/**
* Set flags
* @param mask Flag(s) to set
*/
inline void set(u_int32_t mask)
{ m_flags = m_flags | mask; }
/**
* Reset flags
* @param mask Flag(s) to reset
*/
inline void reset(u_int32_t mask)
{ m_flags = m_flags & ~mask; }
/**
* Check if a mask of flags is set
* @param mask Flag(s) to check
* @return The flags of mask which are set, 0 if no mask flag is set
*/
inline u_int32_t flag(u_int32_t mask) const
{ return (m_flags & mask); }
/**
* Set or reset flags
* @param mask Flag(s)
* @param on True to set, false to reset
*/
inline void changeFlag(u_int32_t mask, bool on) {
if (on)
set(mask);
else
reset(mask);
}
/**
* Set or reset flags, check if changed
* @param mask Flag(s)
* @param ok True to set, false to reset
* @return True if any flag contained in mask changed
*/
inline bool changeFlagCheck(u_int32_t mask, bool ok) {
if ((0 != flag(mask)) == ok)
return false;
changeFlag(mask,ok);
return true;
}
/**
* Change flags
* @param value New flags value
*/
inline void change(u_int32_t value)
{ m_flags = value; }
/**
* Conversion to u_int32_t operator
*/
inline operator u_int32_t() const
{ return m_flags; }
/**
* Asignement from int operator
*/
inline const Flags32& operator=(int value)
{ m_flags = value; return *this; }
protected:
u_int32_t m_flags;
};
/**
* This class holds a name integer value
* @short A named integer value
*/
class YATE_API NamedInt: public String
{
YCLASS(NamedInt,String)
public:
/**
* Constructor
* @param name Name
* @param val The value
*/
inline NamedInt(const char* name, int val = 0)
: String(name), m_value(val)
{}
/**
* Copy constructor
* @param other Source object
*/
inline NamedInt(const NamedInt& other)
: String(other), m_value(other.value())
{}
/**
* Retrieve the value
* @return The integer value
*/
inline int value() const
{ return m_value; }
/**
* Set the value
* @param val The new integer value
*/
inline void setValue(int val)
{ m_value = val; }
/**
* Add an item to a list. Replace existing item with the same name
* @param list The list
* @param obj The object
*/
static void addToListUniqueName(ObjList& list, NamedInt* obj);
/**
* Clear all items with a given value
* @param list The list
* @param val Value to remove
*/
static void clearValue(ObjList& list, int val);
/**
* Get an item's value from name
* @param list The list containing the item
* @param name Item name
* @param defVal Value to return if not found
* @return Item value
*/
static inline int lookup(const ObjList& list, const String& name, int defVal = 0) {
ObjList* o = list.find(name);
return o ? (static_cast<NamedInt*>(o->get()))->value() : defVal;
}
/**
* Get an item's name from value
* @param list The list containing the item
* @param val Item value
* @param defVal Name to return if not found
* @return Item name
*/
static inline const String& lookupName(const ObjList& list, int val,
const String& defVal = String::empty()) {
for (ObjList* o = list.skipNull(); o; o = o->skipNext()) {
NamedInt* ni = static_cast<NamedInt*>(o->get());
if (ni->value() == val)
return *ni;
}
return defVal;
}
protected:
int m_value;
private:
NamedInt() {}
};
/**
* A window is the basic user interface element.
* Everything inside is implementation specific functionality.
* @short An abstract user interface window
*/
class YATE_API Window : public GenObject
{
YCLASS(Window,GenObject)
friend class Client;
YNOCOPY(Window); // no automatic copies please
public:
/**
* Constructor, creates a new windows with an ID
* @param id String identifier of the new window
*/
explicit Window(const char* id = 0);
/**
* Destructor
*/
virtual ~Window();
/**
* Retrieve the standard name of this Window, used to search in lists
* @return Identifier of this window
*/
virtual const String& toString() const;
/*
* Get the window's title (may not be displayed on screen)
* @return Title of this window
*/
virtual void title(const String& text);
/**
* Set the contextual information previously associated with this window
* @param text New contextual information
*/
virtual void context(const String& text);
/**
* Set window parameters or widget contents
* @param params List of parameters to set in the window and its widgets
* @return True if all parameters could be set
*/
virtual bool setParams(const NamedList& params);
/**
* Force this window on top of another one which becomes its parent
* @param parent Window to force as parent of this one
*/
virtual void setOver(const Window* parent) = 0;
/**
* Check if this window has an element by name
* @param name Name of the element to search for
* @return True if one element with the given name exists
*/
virtual bool hasElement(const String& name) = 0;
/**
* Set an element as interactive in the window
* @param name Name of the element
* @param active True to make interactive, false to disallow interaction
* @return True if the operation was successfull
*/
virtual bool setActive(const String& name, bool active) = 0;
/**
* Set an element as receiving input in the window
* @param name Name of the element
* @param select Also select the content of the focused element
* @return True if the operation was successfull
*/
virtual bool setFocus(const String& name, bool select = false) = 0;
/**
* Set the visibility of an element in the window
* @param name Name of the element
* @param visible True to make element visible, false to hide it
* @return True if the operation was successfull
*/
virtual bool setShow(const String& name, bool visible) = 0;
/**
* Set the displayed text of an element in the window
* @param name Name of the element
* @param text Text value to set in the element
* @param richText True if the text contains format data
* @return True if the operation was successfull
*/
virtual bool setText(const String& name, const String& text,
bool richText = false) = 0;
/**
* Set the checked or toggled status of an element in the window
* @param name Name of the element
* @param checked True to make element checked or toggled
* @return True if the operation was successfull
*/
virtual bool setCheck(const String& name, bool checked) = 0;
/**
* Set the selection of an item in an element in the window
* @param name Name of the element
* @param item Name of the item that should be selected
* @return True if the operation was successfull
*/
virtual bool setSelect(const String& name, const String& item) = 0;
/**
* Flag an element as requiring immediate attention
* @param name Name of the element
* @param urgent True if the element requires immediate attention
* @return True if the operation was successfull
*/
virtual bool setUrgent(const String& name, bool urgent) = 0;
/**
* Check if an element has an item by its name
* @param name Name of the element to search for
* @param item Name of the item that should be searched
* @return True if one item with the given name exists in the element
*/
virtual bool hasOption(const String& name, const String& item) = 0;
/**
* Add an item to an element that supports such an operation (list)
* @param name Name of the element
* @param item Name of the item to add
* @param atStart True to insert item on the first position, false to append
* @param text Displayed text to associate with the item (not all lists support it)
* @return True if the operation was successfull
*/
virtual bool addOption(const String& name, const String& item, bool atStart = false,
const String& text = String::empty()) = 0;
/**
* Get an element's items
* @param name Name of the element to search for
* @param items List to fill with element's items
* @return True if the element exists
*/
virtual bool getOptions(const String& name, NamedList* items) = 0;
/**
* Remove an item from an element (list)
* @param name Name of the element
* @param item Name of the item to remove
* @return True if the operation was successfull
*/
virtual bool delOption(const String& name, const String& item) = 0;
/**
* Append or insert text lines to a widget
* @param name The name of the widget
* @param lines List containing the lines
* @param max The maximum number of lines allowed to be displayed. Set to 0 to ignore
* @param atStart True to insert, false to append
* @return True on success
*/
virtual bool addLines(const String& name, const NamedList* lines, unsigned int max,
bool atStart = false);
/**
* Add a row to a table owned by this window
* @param name Name of the element
* @param item Name of the item to add
* @param data Table's columns to set
* @param atStart True to insert, false to append
* @return True if the operation was successfull
*/
virtual bool addTableRow(const String& name, const String& item,
const NamedList* data = 0, bool atStart = false);
/**
* Append or update several table rows at once
* @param name Name of the element
* @param data Parameters to initialize the rows with
* @param prefix Prefix to match (and remove) in parameter names
* @return True if all the operations were successfull
*/
virtual bool setMultipleRows(const String& name, const NamedList& data, const String& prefix = String::empty());
/**
* Insert a row into a table owned by this window
* @param name Name of the element
* @param item Name of the item to insert
* @param before Name of the item to insert before
* @param data Table's columns to set
* @return True if the operation was successfull
*/
virtual bool insertTableRow(const String& name, const String& item,
const String& before, const NamedList* data = 0);
/**
* Delete a row from a table owned by this window
* @param name Name of the element
* @param item Name of the item to remove
* @return True if the operation was successfull
*/
virtual bool delTableRow(const String& name, const String& item);
/**
* Update a row from a table owned by this window
* @param name Name of the element
* @param item Name of the item to update
* @param data Data to update
* @return True if the operation was successfull
*/
virtual bool setTableRow(const String& name, const String& item, const NamedList* data);
/**
* Set a table row or add a new one if not found
* @param name Name of the element
* @param item Table item to set/add
* @param data Optional list of parameters used to set row data
* @param atStart True to add item at start, false to add them to the end
* @return True if the operation was successfull
*/
virtual bool updateTableRow(const String& name, const String& item,
const NamedList* data = 0, bool atStart = false);
/**
* Add or set one or more table row(s). Screen update is locked while changing the table.
* Each data list element is a NamedPointer carrying a NamedList with item parameters.
* The name of an element is the item to update.
* Set element's value to boolean value 'true' to add a new item if not found
* or 'false' to set an existing one. Set it to empty string to delete the item
* @param name Name of the table
* @param data The list of items to add/set/delete
* @param atStart True to add new items at start, false to add them to the end
* @return True if the operation was successfull
*/
virtual bool updateTableRows(const String& name, const NamedList* data,
bool atStart = false);
/**
* Retrieve a row from a table owned by this window
* @param name Name of the element
* @param item Name of the item to retrieve
* @param data List to fill with table's columns contents
* @return True if the operation was successfull
*/
virtual bool getTableRow(const String& name, const String& item, NamedList* data = 0);
/**
* Clear (delete all rows) a table owned by this window
* @param name Name of the element
* @return True if the operation was successfull
*/
virtual bool clearTable(const String& name);
/**
* Show or hide control busy state
* @param name Name of the element
* @param on True to show, false to hide
* @return True if all the operations were successfull
*/
virtual bool setBusy(const String& name, bool on) = 0;
/**
* Get an element's text
* @param name Name of the element
* @param text The destination string
* @param richText True to get the element's roch text if supported.
* @return True if the operation was successfull
*/
virtual bool getText(const String& name, String& text, bool richText = false) = 0;
/**
* Get the checked state of a checkable control
* @param name Name of the element
* @param checked The checked state of the control
* @return True if the operation was successfull
*/
virtual bool getCheck(const String& name, bool& checked) = 0;
/**
* Retrieve an element's selection
* @param name Name of the element
* @param item String to fill with selection's contents
* @return True if the operation was successfull
*/
virtual bool getSelect(const String& name, String& item) = 0;
/**
* Retrieve an element's multiple selection
* @param name Name of the element
* @param items List to be to filled with selection's contents
* @return True if the operation was successfull
*/
virtual bool getSelect(const String& name, NamedList& items) = 0;
/**
* Build a menu from a list of parameters.
* See Client::buildMenu() for more info
* @param params Menu build parameters
* @return True on success
*/
virtual bool buildMenu(const NamedList& params) = 0;
/**
* Remove a menu (from UI and memory)
* See Client::removeMenu() for more info
* @param params Menu remove parameters
* @return True on success
*/
virtual bool removeMenu(const NamedList& params) = 0;
/**
* Set an element's image
* @param name Name of the element
* @param image Image to set
* @param fit Fit image in element (defaults to false)
* @return True on success
*/
virtual bool setImage(const String& name, const String& image, bool fit = false) = 0;
/**
* Set a property for this window or for a widget owned by it
* @param name Name of the element
* @param item Property's name
* @param value Property's value
* @return True on success
*/
virtual bool setProperty(const String& name, const String& item, const String& value)
{ return false; }
/**
* Get a property from this window or from a widget owned by it
* @param name Name of the element
* @param item Property's name
* @param value Property's value
* @return True on success
*/
virtual bool getProperty(const String& name, const String& item, String& value)
{ return false; }
/**
* Populate the window if not already done
*/
inline void populate() {
if (m_populated)
return;
doPopulate();
m_populated = true;
}
/**
* Initialize the window if not already done
*/
inline void init() {
if (m_initialized)
return;
doInit();
m_initialized = true;
}
/**
* Show this window
*/
virtual void show() = 0;
/**
* Hide this window
*/
virtual void hide() = 0;
/**
* Resize this window
* @param width The new width
* @param height The new width
*/
virtual void size(int width, int height) = 0;
/**
* Move this window
* @param x The x coordinate of the upper left corner
* @param y The y coordinate of the upper left corner
*/
virtual void move(int x, int y) = 0;
/**
* Move this window related to its current position
* @param dx The value to be added to the current x coordinate of the upper left corner
* @param dy The value to be added to the current y coordinate of the upper left corner
*/
virtual void moveRel(int dx, int dy) = 0;
/**
* Checkes if this window is related to the given window
* @param wnd The window to check for any relation
* @return False if wnd is this window or a master one
*/
virtual bool related(const Window* wnd) const;
virtual void menu(int x, int y) = 0;
/**
* Check if this window can be closed
* @return True if this window can be closed, false to prevent hiding it
*/
virtual bool canClose()
{ return true; }
/**
* Retrieve the standard name of this Window
* @return Identifier of this window
*/
inline const String& id() const
{ return m_id; }
/*
* Get the window's title (may not be displayed on screen)
* @return Title of this window
*/
inline const String& title() const
{ return m_title; }
/**
* Get the contextual information previously associated with this window
* @return String contextual information
*/
inline const String& context() const
{ return m_context; }
/**
* Get the visibility status of this window
* @return True if window is visible, false if it's hidden
*/
inline bool visible() const
{ return m_visible; }
/**
* Set the visibility status of this window
* @param yes True if window should be visible
*/
inline void visible(bool yes)
{ if (yes) show(); else hide(); }
/**
* Check if this window is the active one
* @return True if window is active
*/
inline bool active() const
{ return m_active; }
/**
* Check if this window is a master (topmost) window
* @return True if this window is topmost
*/
inline bool master() const
{ return m_master; }
/**
* Check if this window is a popup window
* @return True if this window is initially hidden
*/
inline bool popup() const
{ return m_popup; }
/**
* Create a modal dialog
* @param name Dialog name (resource config section)
* @param title Dialog title
* @param alias Optional dialog alias (used as dialog object name)
* @param params Optional dialog parameters
* @return True on success
*/
virtual bool createDialog(const String& name, const String& title,
const String& alias = String::empty(), const NamedList* params = 0) = 0;
/**
* Destroy a modal dialog
* @param name Dialog name
* @return True on success
*/
virtual bool closeDialog(const String& name) = 0;
/**
* Check if a string is a parameter prefix handled by setParams().
* Exact prefix match is not a valid one
* @param prefix String to check
* @return True if the given prefix is a valid one
*/
static bool isValidParamPrefix(const String& prefix);
protected:
virtual void doPopulate() = 0;
virtual void doInit() = 0;
String m_id;
String m_title;
String m_context;
bool m_visible;
bool m_active;
bool m_master;
bool m_popup;
bool m_saveOnClose; // Save window's data when destroyed
private:
bool m_populated; // Already populated flag
bool m_initialized; // Already initialized flag
};
class YATE_API UIWidget : public String
{
YCLASS(UIWidget,String)
YNOCOPY(UIWidget); // no automatic copies please
public:
/**
* Constructor, creates a new widget
* @param name The widget's name
*/
inline explicit UIWidget(const char* name = 0)
: String(name)
{ }
/**
* Destructor
*/
virtual ~UIWidget()
{ }
/**
* Retrieve the standard name of this Window
* @return Identifier of this window
*/
inline const String& name() const
{ return toString(); }
/**
* Set widget's parameters
* @param params List of parameters
* @return True if all parameters could be set
*/
virtual bool setParams(const NamedList& params)
{ return false; }
/**
* Get widget's items
* @param items List to fill with widget's items
* @return False on failure (e.g. not initialized)
*/
virtual bool getOptions(NamedList& items)
{ return false; }
/**
* Add a row to a table
* @param item Name of the item to add
* @param data Table's columns to set
* @param atStart True to insert, false to append
* @return True if the operation was successfull
*/
virtual bool addTableRow(const String& item, const NamedList* data = 0,
bool atStart = false)
{ return false; }
/** Append or update several table rows at once
* @param data Parameters to initialize the rows with
* @param prefix Prefix to match (and remove) in parameter names
* @return True if all the operations were successfull
*/
virtual bool setMultipleRows(const NamedList& data, const String& prefix = String::empty())
{ return false; }
/**
* Add or set one or more table row(s). Screen update is locked while changing the table.
* Each data list element is a NamedPointer carrying a NamedList with item parameters.
* The name of an element is the item to update.
* Set element's value to boolean value 'true' to add a new item if not found
* or 'false' to set an existing one. Set it to empty string to delete the item
* @param data The list of items to add/set/delete
* @param atStart True to add new items at start, false to add them to the end
* @return True if the operation was successfull
*/
virtual bool updateTableRows(const NamedList* data, bool atStart = false)
{ return false; }
/**
* Insert a row into a table
* @param item Name of the item to insert
* @param before Name of the item to insert before
* @param data Table's columns to set
* @return True if the operation was successfull
*/
virtual bool insertTableRow(const String& item, const String& before,
const NamedList* data = 0)
{ return false; }
/**
* Delete a row from a table
* @param item Name of the item to remove
* @return True if the operation was successfull
*/
virtual bool delTableRow(const String& item)
{ return false; }
/**
* Update a table's row
* @param item Name of the item to update
* @param data Data to update
* @return True if the operation was successfull
*/
virtual bool setTableRow(const String& item, const NamedList* data)
{ return false; }
/**
* Retrieve a row from a table
* @param item Name of the item to retrieve
* @param data List to fill with table's columns contents
* @return True if the operation was successfull
*/
virtual bool getTableRow(const String& item, NamedList* data = 0)
{ return false; }
/**
* Clear (delete all rows) a table
* @return True if the operation was successfull
*/
virtual bool clearTable()
{ return false; }
/**
* Set the widget's selection
* @param item String containing the new selection
* @return True if the operation was successfull
*/
virtual bool setSelect(const String& item)
{ return false; }
/**
* Retrieve the widget's selection
* @param item String to fill with selection's contents
* @return True if the operation was successfull
*/
virtual bool getSelect(String& item)
{ return false; }
/**
* Retrieve widget's multiple selection
* @param items List to be to filled with selection's contents
* @return True if the operation was successfull
*/
virtual bool getSelect(NamedList& items)
{ return false; }
/**
* Append or insert text lines to this widget
* @param lines List containing the lines
* @param max The maximum number of lines allowed to be displayed. Set to 0 to ignore
* @param atStart True to insert, false to append
* @return True on success
*/
virtual bool addLines(const NamedList& lines, unsigned int max, bool atStart = false)
{ return false; }
/**
* Set the displayed text of this widget
* @param text Text value to set
* @param richText True if the text contains format data
* @return True on success
*/
virtual bool setText(const String& text, bool richText = false)
{ return false; }
/**
* Retrieve the displayed text of this widget
* @param text Text value
* @param richText True to retrieve formatted data
* @return True on success
*/
virtual bool getText(String& text, bool richText = false)
{ return false; }
/**
* Show or hide control busy state
* @param on True to show, false to hide
* @return True if all the operations were successfull
*/
virtual bool setBusy(bool on)
{ return false; }
};
/**
* Each instance of UIFactory creates special user interface elements by type.
* Keeps a global list with all factories. The list doesn't own the facotries
* @short A static user interface creator
*/
class YATE_API UIFactory : public String
{
YCLASS(UIFactory,String)
YNOCOPY(UIFactory); // no automatic copies please
public:
/**
* Constructor. Append itself to the factories list
*/
explicit UIFactory(const char* name);
/**
* Destructor. Remove itself from list
*/
virtual ~UIFactory();
/**
* Check if this factory can build an object of a given type
* @param type Object type to check
* @return True if this factory can build the object
*/
inline bool canBuild(const String& type)
{ return 0 != m_types.find(type); }
/**
* Ask this factory to create an object of a given type
* @param type Object's type
* @param name Object' name
* @param params Optional object parameters
* @return Valid pointer or 0 if failed to build it
*/
virtual void* create(const String& type, const char* name, NamedList* params = 0) = 0;
/**
* Ask all factories to create an object of a given type
* @param type Object's type
* @param name Object' name
* @param params Optional object parameters
* @param factory Optional factory name used to create the requested object. If non 0,
* this will be the only factory asked to create the object
* @return Valid pointer or 0 if failed to build it
*/
static void* build(const String& type, const char* name, NamedList* params = 0,
const char* factory = 0);
protected:
ObjList m_types; // List of object types this factory can build
private:
static ObjList s_factories; // Registered factories list
};
/**
* Singleton class that holds the User Interface's main methods
* @short Class that runs the User Interface
*/
class YATE_API Client : public MessageReceiver
{
YCLASS(Client,MessageReceiver)
friend class Window;
friend class ClientChannel;
friend class ClientDriver;
friend class ClientLogic;
public:
/**
* Message relays installed by this receiver.
*/
enum MsgID {
CallCdr = 0,
UiAction,
UserLogin,
UserNotify,
ResourceNotify,
ResourceSubscribe,
ClientChanUpdate,
UserRoster,
ContactInfo,
// Handlers not automatically installed
ChanNotify,
MucRoom,
// IDs used only to postpone messages
MsgExecute,
EngineStart,
TransferNotify,
UserData,
FileInfo,
// Starting value for custom relays
MsgIdCount
};
/**
* Client boolean options mapped to UI toggles
*/
enum ClientToggle {
OptMultiLines = 0, // Accept incoming calls
OptAutoAnswer, // Auto answer incoming calls
OptRingIn, // Enable/disable incoming ringer
OptRingOut, // Enable/disable outgoing ringer
OptActivateLastOutCall, // Set the last outgoing call active
OptActivateLastInCall, // Set the last incoming call active
OptActivateCallOnSelect, // Set the active call when selected in channel
// list (don't require double click)
OptKeypadVisible, // Show/hide keypad
OptOpenIncomingUrl, // Open an incoming URL in call.execute message
OptAddAccountOnStartup, // Open account add window on startup
OptDockedChat, // Show all contacts chat in the same window
OptDestroyChat, // Destroy contact chat when contact is removed/destroyed
OptNotifyChatState, // Notify chat states
OptShowEmptyChat, // Display received empty chat in chat history
OptSendEmptyChat, // Send empty chat
OptCount
};
/**
* Tray icon valuers used in stack
*/
enum TrayIconType {
TrayIconMain = 0,
TrayIconInfo = 1000,
TrayIconIncomingChat = 3000,
TrayIconNotification = 5000,
TrayIconIncomingCall = 10000,
};
/**
* Constructor
* @param name The client's name
*/
explicit Client(const char *name = 0);
/**
* Destructor
*/
virtual ~Client();
/**
* Start up the client thread
* @return True if the client thread is started, false otherwise
*/
virtual bool startup();
/**
* Run the client's main loop
*/
virtual void run();
/**
* Cleanup when thread terminates
*/
virtual void cleanup();
/**
* Execute the client
*/
virtual void main() = 0;
/**
* Lock the client
*/
virtual void lock() = 0;
/**
* Unlock the client
*/
virtual void unlock() = 0;
/**
* Lock the client only if we are using more then 1 thread
*/
inline void lockOther()
{ if (!m_oneThread) lock(); }
/**
* Unlock the client only if we are using more then 1 thread
*/
inline void unlockOther()
{ if (!m_oneThread) unlock(); }
/**
* Set the client's thread
* @param th The thread on which the client will run on
*/
inline void setThread(Thread* th)
{ m_clientThread = th; }
/**
* Handle all windows closed event from UI
*/
virtual void allHidden() = 0;
/**
* Load windows and optionally (re)initialize the client's options.
* @param file The resource file describing the windows. Set to 0 to use the default one
* @param init True to (re)initialize the client
*/
void loadUI(const char* file = 0, bool init = true);
/**
* Terminate application
*/
virtual void quit() = 0;
/**
* Open an URL (link) in the client's thread
* @param url The URL to open
* @return True on success
*/
bool openUrlSafe(const String& url);
/**
* Open an URL (link)
* @param url The URL to open
* @return True on success
*/
virtual bool openUrl(const String& url) = 0;
/**
* Process a received message. Check for a logic to process it
* @param msg Received message
* @param id Message id
* @return True if a logic processed the message (stop dispatching it)
*/
virtual bool received(Message& msg, int id);
/**
* Create a window with a given name
* @param name The window's name
* @param alias Window name alias after succesfully loaded.
* Set to empty string to use the given name
* @return True on success
*/
virtual bool createWindowSafe(const String& name,
const String& alias = String::empty());
/**
* Create a modal dialog owned by a given window
* @param name Dialog name (resource config section)
* @param parent Parent window
* @param title Dialog title
* @param alias Optional dialog alias (used as dialog object name)
* @param params Optional dialog parameters
* @return True on success
*/
virtual bool createDialog(const String& name, Window* parent, const String& title,
const String& alias = String::empty(), const NamedList* params = 0);
/**
* Ask to an UI factory to create an object in the UI's thread
* @param dest Destination to be filled with the newly create object's address
* @param type Object's type
* @param name Object's name
* @param params Optional object parameters
* @return True on success
*/
virtual bool createObject(void** dest, const String& type, const char* name,
NamedList* params = 0);
/**
* Hide/destroy a window with a given name
* @param name The window's name
* @param hide True to hide, false to close
* @return True on success
*/
virtual bool closeWindow(const String& name, bool hide = true);
/**
* Destroy a modal dialog
* @param name Dialog name
* @param wnd Window owning the dialog
* @param skip Optional window to skip if wnd is null
* @return True on success
*/
virtual bool closeDialog(const String& name, Window* wnd, Window* skip = 0);
/**
* Install/uninstall a debugger output hook
* @param active True to install, false to uninstall the hook
* @return True on success
*/
virtual bool debugHook(bool active);
/**
* Add a log line
* @param text Text to add
* @return True on success
*/
virtual bool addToLog(const String& text);
/**
* Set the status text
* @param text Status text
* @param wnd Optional window owning the status control
* @return True on success
*/
virtual bool setStatus(const String& text, Window* wnd = 0);
/**
* Set the status text safely
* @param text Status text
* @param wnd Optional window owning the status control
* @return True on success
*/
bool setStatusLocked(const String& text, Window* wnd = 0);
/**
* Set multiple window parameters
* @param params The parameter list
* @param wnd Optional window whose params are to be set
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
bool setParams(const NamedList* params, Window* wnd = 0, Window* skip = 0);
/**
* Handle actions from user interface. Enqueue an ui.event message if
* the action is not handled by a client logic
* @param wnd The window in which the user did something
* @param name The action's name
* @param params Optional action parameters
* @return True if the action was handled by a client logic
*/
virtual bool action(Window* wnd, const String& name, NamedList* params = 0);
/**
* Handle actions from checkable widgets. Enqueue an ui.event message if
* the action is not handled by a client logic
* @param wnd The window in which the user did something
* @param name The object's name
* @param active Object's state
* @return True if the action was handled by a client logic
*/
virtual bool toggle(Window* wnd, const String& name, bool active);
/**
* Handle 'select' actions from user interface. Enqueue an ui.event message if
* the action is not handled by a client logic
* @param wnd The window in which the user selected the object
* @param name The action's name
* @param item Item identifying the selection
* @param text Selection's text
* @return True if the action was handled by a client logic
*/
virtual bool select(Window* wnd, const String& name, const String& item, const String& text = String::empty());
/**
* Handle 'select' with multiple items actions from user interface. Enqueue an ui.event message if
* the action is not handled by a client logic
* @param wnd The window in which the user selected the object
* @param name The action's name
* @param items List containing the selection
* @return True if the action was handled by a client logic
*/
virtual bool select(Window* wnd, const String& name, const NamedList& items);
/**
* Check if the client is using more then 1 thread
* @return True if the client is using more then 1 thread
*/
inline bool oneThread() const
{ return m_oneThread; }
/**
* Get the currently selected line
* @return The selected line
*/
inline int line() const
{ return m_line; }
/**
* Set the selected line
* @param newLine The selected line
*/
void line(int newLine);
bool hasElement(const String& name, Window* wnd = 0, Window* skip = 0);
bool setActive(const String& name, bool active, Window* wnd = 0, Window* skip = 0);
bool setFocus(const String& name, bool select = false, Window* wnd = 0, Window* skip = 0);
bool setShow(const String& name, bool visible, Window* wnd = 0, Window* skip = 0);
bool setText(const String& name, const String& text, bool richText = false,
Window* wnd = 0, Window* skip = 0);
bool setCheck(const String& name, bool checked, Window* wnd = 0, Window* skip = 0);
bool setSelect(const String& name, const String& item, Window* wnd = 0, Window* skip = 0);
bool setUrgent(const String& name, bool urgent, Window* wnd = 0, Window* skip = 0);
bool hasOption(const String& name, const String& item, Window* wnd = 0, Window* skip = 0);
/**
* Get an element's items
* @param name Name of the element to search for
* @param items List to fill with element's items
* @param wnd Optional window owning the element
* @param skip Optional window to skip when searching for the element
* @return True if the element exists
*/
virtual bool getOptions(const String& name, NamedList* items,
Window* wnd = 0, Window* skip = 0);
bool addOption(const String& name, const String& item, bool atStart,
const String& text = String::empty(), Window* wnd = 0, Window* skip = 0);
bool delOption(const String& name, const String& item, Window* wnd = 0, Window* skip = 0);
/**
* Append or insert text lines to a widget
* @param name The name of the widget
* @param lines List containing the lines
* @param max The maximum number of lines allowed to be displayed. Set to 0 to ignore
* @param atStart True to insert, false to append
* @param wnd Optional window owning the widget
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
bool addLines(const String& name, const NamedList* lines, unsigned int max,
bool atStart = false, Window* wnd = 0, Window* skip = 0);
bool addTableRow(const String& name, const String& item, const NamedList* data = 0,
bool atStart = false, Window* wnd = 0, Window* skip = 0);
/**
* Append or update several table rows at once
* @param name Name of the element
* @param data Parameters to initialize the rows with
* @param prefix Prefix to match (and remove) in parameter names
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if all the operations were successfull
*/
bool setMultipleRows(const String& name, const NamedList& data, const String& prefix = String::empty(), Window* wnd = 0, Window* skip = 0);
/**
* Insert a row into a table owned by this window
* @param name Name of the element
* @param item Name of the item to insert
* @param before Name of the item to insert before
* @param data Table's columns to set
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if the operation was successfull
*/
bool insertTableRow(const String& name, const String& item,
const String& before, const NamedList* data = 0,
Window* wnd = 0, Window* skip = 0);
bool delTableRow(const String& name, const String& item, Window* wnd = 0, Window* skip = 0);
bool setTableRow(const String& name, const String& item, const NamedList* data,
Window* wnd = 0, Window* skip = 0);
bool getTableRow(const String& name, const String& item, NamedList* data = 0,
Window* wnd = 0, Window* skip = 0);
bool clearTable(const String& name, Window* wnd = 0, Window* skip = 0);
/**
* Set a table row or add a new one if not found
* @param name Name of the element
* @param item Table item to set/add
* @param data Optional list of parameters used to set row data
* @param atStart True to add item at start, false to add them to the end
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if the operation was successfull
*/
bool updateTableRow(const String& name, const String& item, const NamedList* data = 0,
bool atStart = false, Window* wnd = 0, Window* skip = 0);
/**
* Add or set one or more table row(s). Screen update is locked while changing the table.
* Each data list element is a NamedPointer carrying a NamedList with item parameters.
* The name of an element is the item to update.
* Set element's value to boolean value 'true' to add a new item if not found
* or 'false' to set an existing one. Set it to empty string to delete the item
* @param name Name of the table
* @param data The list of items to add/set/delete
* @param atStart True to add new items at start, false to add them to the end
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if the operation was successfull
*/
bool updateTableRows(const String& name, const NamedList* data, bool atStart = false,
Window* wnd = 0, Window* skip = 0);
/**
* Show or hide control busy state
* @param name Name of the element
* @param on True to show, false to hide
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if all the operations were successfull
*/
bool setBusy(const String& name, bool on, Window* wnd = 0, Window* skip = 0);
/**
* Get an element's text
* @param name Name of the element
* @param text The destination string
* @param richText True to get the element's roch text if supported.
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if the operation was successfull
*/
bool getText(const String& name, String& text, bool richText = false, Window* wnd = 0, Window* skip = 0);
bool getCheck(const String& name, bool& checked, Window* wnd = 0, Window* skip = 0);
bool getSelect(const String& name, String& item, Window* wnd = 0, Window* skip = 0);
/**
* Retrieve an element's multiple selection
* @param name Name of the element
* @param items List to be to filled with selection's contents
* @param wnd Optional window owning the element
* @param skip Optional window to skip if wnd is 0
* @return True if the operation was successfull
*/
bool getSelect(const String& name, NamedList& items, Window* wnd = 0, Window* skip = 0);
/**
* Build a menu from a list of parameters and add it to a target.
* @param params Menu build parameters (list name is the menu name).
* Each menu item is indicated by a parameter item:[item_name]=[display_text].
* A separator will be added if 'item_name' is empty.
* A new item will be created if 'display_text' is not empty.
* Set 'display_text' to empty string to use an existing item.
* Item image can be set by an 'image:item_name' parameter.
* If the item parameter is a NamedPointer carrying a NamedList a submenu will be created.
* Menu item properties can be set from parameters with format
* property:item_name:property_name=value.
* The following parameters can be set:
* - title: menu display text (defaults to menu name)
* - owner: optional menu owner (the window building the menu is
* assumed to be the owner if this parameter is empty)
* - target: optional menu target (defaults to owner)
* - before: optional item to insert before if the target is a menu container
* (another menu or a menu bar)
* - before_separator: check if a separator already exists before the item
* 'before' and insert the menu before the separator
* @param wnd Optional target window
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
bool buildMenu(const NamedList& params, Window* wnd = 0, Window* skip = 0);
/**
* Remove a menu (from UI and memory)
* @param params Menu remove parameters.
* The following parameters can be set:
* - owner: optional menu owner (the window building the menu is
* assumed to be the owner if this parameter is empty)
* @param wnd Optional target window
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
bool removeMenu(const NamedList& params, Window* wnd = 0, Window* skip = 0);
/**
* Set an element's image
* @param name Name of the element
* @param image Image to set
* @param wnd Optional target window
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
virtual bool setImage(const String& name, const String& image,
Window* wnd = 0, Window* skip = 0);
/**
* Set an element's image. Request to fit the image in element
* @param name Name of the element
* @param image Image to set
* @param wnd Optional target window
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
virtual bool setImageFit(const String& name, const String& image,
Window* wnd = 0, Window* skip = 0);
/**
* Set a property
* @param name Name of the element
* @param item Property's name
* @param value Property's value
* @param wnd Optional target window
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
virtual bool setProperty(const String& name, const String& item, const String& value,
Window* wnd = 0, Window* skip = 0);
/**
* Get a property
* @param name Name of the element
* @param item Property's name
* @param value Property's value
* @param wnd Optional target window
* @param skip Optional window to skip if wnd is 0
* @return True on success
*/
virtual bool getProperty(const String& name, const String& item, String& value,
Window* wnd = 0, Window* skip = 0);
void moveRelated(const Window* wnd, int dx, int dy);
inline bool initialized() const
{ return m_initialized; }
inline static Client* self()
{ return s_client; }
inline static void setSelf(Client* client)
{ s_client = client; }
/**
* Check if the client object still exists and the client or engine is not exiting
* @return True if the client is valid (running) or the method is called from client's thread
*/
static inline bool valid()
{ return self() && (self()->isUIThread() || !(exiting() || Engine::exiting())); }
/**
* Check if a message is sent by the client
* @param msg The message to check
* @return True if the message has a 'module' parameter with the client driver's name
*/
static bool isClientMsg(Message& msg);
inline static bool changing()
{ return (s_changing > 0); }
static Window* getWindow(const String& name);
static bool setVisible(const String& name, bool show = true, bool activate = false);
static bool getVisible(const String& name);
static bool openPopup(const String& name, const NamedList* params = 0, const Window* parent = 0);
static bool openMessage(const char* text, const Window* parent = 0, const char* context = 0);
static bool openConfirm(const char* text, const Window* parent = 0, const char* context = 0);
static ObjList* listWindows();
void idleActions();
/**
* Postpone a copy of a message to be dispatched from the UI thread
* @param msg Message to be postponed
* @param id Identifier of the message to be used on dispatch
* @param copyUserData Copy source user data in postponed message
* @return True if the UI thread was not current so the message was postponed
*/
bool postpone(const Message& msg, int id, bool copyUserData = false);
/**
* Show a file open/save dialog window
* This method isn't using the proxy thread since it's usually called on UI action
* @param parent Dialog window's parent
* @param params Dialog window's params. Parameters that can be specified include 'caption',
* 'dir', 'filters', 'selectedfilter', 'confirmoverwrite', 'choosedir'.
* @return True on success
*/
virtual bool chooseFile(Window* parent, NamedList& params)
{ return false; }
/**
* Request to a logic to set a client's parameter. Save the settings file
* and/or update interface
* @param param Parameter's name
* @param value The value of the parameter
* @param save True to save the configuration file
* @param update True to update the interface
* @return True on success, false if the parameter doesn't exist, the value
* is incorrect or failed to save the file
*/
virtual bool setClientParam(const String& param, const String& value,
bool save, bool update);
/**
* Remove the last character of the given widget
* @param name The widget (it might be the window itself)
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool backspace(const String& name, Window* wnd = 0);
/**
* Create and install a message relay owned by this client.
* The new relay will be unistalled when the client is terminated
* @param name Message name
* @param id Relay id
* @param prio Message priority
*/
void installRelay(const char* name, int id, int prio);
/**
* Call routing handler called by the driver
* @param msg The call.route message
*/
virtual bool callRouting(Message& msg)
{ return true;}
/**
* IM message routing handler called by the driver
* @param msg The im.route message
*/
virtual bool imRouting(Message& msg)
{ return true;}
/**
* Process an IM message
* @param msg The im.execute of chan.text message
*/
virtual bool imExecute(Message& msg);
/**
* Build an incoming channel.
* Answer it if succesfully connected and auto answer is set.
* Reject it if multiline is false and the driver is busy.
* Set the active one if requested by config and there is no active channel.
* Start the ringer if there is no active channel
* @param msg The call.execute message
* @param dest The destination (target)
* @return True if a channel was created and connected
*/
virtual bool buildIncomingChannel(Message& msg, const String& dest);
/**
* Build an outgoing channel
* @param params Call parameters
* @return True if a channel was created its router started
*/
virtual bool buildOutgoingChannel(NamedList& params);
/**
* Call execute handler called by the driver.
* Ask the logics to create the channel
* @param msg The call.execute message
* @param dest The destination (target)
* @return True if a channel was created and connected
*/
bool callIncoming(Message& msg, const String& dest);
/**
* Answer an incoming call
* @param id The accepted channel's id
* @param setActive True to activate the answered channel
* @return True on success
*/
void callAnswer(const String& id, bool setActive = true);
/**
* Terminate a call
* @param id The channel's id
* @param reason Optional termination reason
* @param error Optional termination error
* @return True on success
*/
void callTerminate(const String& id, const char* reason = 0, const char* error = 0);
/**
* Get the active channel if any
* @return Referenced pointer to the active channel or 0
*/
ClientChannel* getActiveChannel();
/**
* Start/stop ringer. The ringer is started only if not disabled
* @param in True if the request is for the incoming call alert, false if it
* is for the outgoing call ringing alert
* @param on True to start, false to stop the sound
* @return True on success
*/
virtual bool ringer(bool in, bool on);
/**
* Create a sound object. Append it to the global list
* @param name The name of sound object
* @param file The file to play (should contain the whole path and the file name)
* @param device Optional device used to play the file. Set to 0 to use the default one
* @return True on success, false if a sound with the given name already exists
*/
virtual bool createSound(const char* name, const char* file, const char* device = 0)
{ return false; }
/**
* Send digits on selected channel
* @param digits The digits to send
* @param id The channel id. Use the active one if empty
* @return True on success
*/
bool emitDigits(const char* digits, const String& id = String::empty());
/**
* Send a digit on selected channel
* @param digit The digit to send
* @param id The channel id. Use the active one if empty
* @return True on success
*/
inline bool emitDigit(char digit, const String& id = String::empty()) {
char s[2] = {digit,0};
return emitDigits(s,id);
}
/**
* Get a boolean option of this client
* @param toggle Options's id to retrieve
* @return True on success
*/
inline bool getBoolOpt(ClientToggle toggle)
{ return toggle < OptCount ? m_toggles[toggle] : false; }
/**
* Set a boolean option of this client
* @param toggle Options's id to set
* @param value Value to set
* @param updateUi True to update UI
* @return True if the option's value changed
*/
bool setBoolOpt(ClientToggle toggle, bool value, bool updateUi = false);
/**
* Build a date/time string from UTC time
* @param dest Destination string
* @param secs Seconds since EPOCH
* @param format Format string used to build the destination
* @param utc True to build UTC time instead of local time
* @return True on success
*/
virtual bool formatDateTime(String& dest, unsigned int secs, const char* format,
bool utc = false)
{ return false; }
/**
* Check if the client is exiting
* @return True if the client therad is exiting
*/
static inline bool exiting()
{ return s_exiting; }
/**
* Retrieve the active state of a window
* @param name Window name
* @return True if the window is found and it's active
*/
static bool getActive(const String& name);
/**
* Build a message to be sent by the client.
* Add module, line and operation parameters
* @param msg Message name
* @param account The account sending the message
* @param oper Optional operation parameter
* @return Message pointer
*/
static Message* buildMessage(const char* msg, const String& account,
const char* oper = 0);
/**
* Build a resource.notify message
* @param online True to build an 'online' message, false to build an 'offline' one
* @param account The account sending the message
* @param from Optional resource to add to message
* @return Message pointer
*/
static Message* buildNotify(bool online, const String& account,
const ClientResource* from = 0);
/**
* Build a resource.subscribe or resource.notify message to request a subscription
* or respond to a request
* @param request True to build a request, false to build a response
* @param ok True to build a subscribe(d) message, false to build an unsubscribe(d) message
* @param account The account to use for the message
* @param contact The destination contact
* @param proto Optional protocol
* @return Valid Message pointer
*/
static Message* buildSubscribe(bool request, bool ok, const String& account,
const String& contact, const char* proto = 0);
/**
* Build an user.roster message
* @param update True to build an update, false to build a delete request
* @param account The account to use for the message
* @param contact The contact to update or delete
* @param proto Optional protocol
* @return Valid Message pointer
*/
static Message* buildUserRoster(bool update, const String& account,
const String& contact, const char* proto = 0);
/**
* Add a logic to the list. The added object is not owned by the client
* @param logic Pointer to the logic to add
* @return True on success. False if the pointer is 0 or already added
*/
static bool addLogic(ClientLogic* logic);
/**
* Remove a logic from the list without destroying it
* @param logic Pointer to the logic to remove
*/
static void removeLogic(ClientLogic* logic);
/**
* Convenience method to retrieve a logic
* @param name The logic's name
* @return ClientLogic pointer or 0
*/
static ClientLogic* findLogic(const String& name);
/**
* Build an 'ui.event' message
* @param event Event's name
* @param wnd Optional window to add to message
* @param name Optional 'name' parameter value
* @param params Other optional parameters to be added to the message
* @return Valid Message pointer
*/
static Message* eventMessage(const String& event, Window* wnd = 0,
const char* name = 0, NamedList* params = 0);
/**
* Save a configuration file. Call openMessage() on failure
* @param cfg The configuration file to save
* @param parent The parent of the error window if needded
* @param showErr True to open a message popup on failure
* @return True on success
*/
static bool save(Configuration& cfg, Window* parent = 0, bool showErr = true);
/**
* Check if a string names a client's boolean option
* @param name String to check
* @return Valid client option index or OptCount if not found
*/
static ClientToggle getBoolOpt(const String& name);
/**
* Set the flag indicating that the client should tick the logics
*/
static inline void setLogicsTick()
{ s_idleLogicsTick = true; }
/**
* Append URI escaped String items to a String buffer
* @param buf Destination string
* @param list Source list
* @param sep Destination list separator. It will be escaped in each added string
* @param force True to allow appending empty strings
*/
static void appendEscape(String& buf, ObjList& list, char sep = ',', bool force = false);
/**
* Splits a string at a delimiter character. URI unescape each string in result
* @param buf Source string
* @param sep Character where to split the string. It will be unescaped in each string
* @param emptyOk True if empty strings should be inserted in list
* @return A newly allocated list of strings, must be deleted after use
*/
static ObjList* splitUnescape(const String& buf, char sep = ',', bool emptyOk = false);
/**
* Remove characters from a given string
* @param buf Source string
* @param chars Characters to remove from input string
*/
static void removeChars(String& buf, const char* chars);
/**
* Fix a phone number. Remove extra '+' from begining.
* Remove requested characters. Adding '+' to characters to remove won't remove
* the plus sign from the begining.
* Clear the number if a non digit char is found
* @param number Phone number to fix
* @param chars Optional characters to remove from number
*/
static void fixPhoneNumber(String& number, const char* chars = 0);
/**
* Add a tray icon to a window's stack. Update it if already there.
* Show it if it's the first one and the client is started.
* This method must be called from client's thread
* @param wndName The window owning the icon
* @param prio Tray icon priority. The list is kept in ascending order
* @param params Tray icon parameters. It will be consumed
* @return True on success
*/
static bool addTrayIcon(const String& wndName, int prio, NamedList* params);
/**
* Remove a tray icon from a window's stack.
* Show the next one if it's the first
* This method must be called from client's thread
* @param wndName The window owning the icon
* @param name Tray icon name
* @return True on success
*/
static bool removeTrayIcon(const String& wndName, const String& name);
/**
* Update the first tray icon in a window's stack.
* Remove any existing icon the the stack is empty
* This method must be called from client's thread
* @param wndName The window owning the icon
* @return True on success
*/
static bool updateTrayIcon(const String& wndName);
/**
* Generate a GUID string in the format 8*HEX-4*HEX-4*HEX-4*HEX-12*HEX
* @param buf Destination string
* @param extra Optional string whose hash will be inserted in the GUID
*/
static void generateGuid(String& buf, const String& extra = String::empty());
/**
* Replace plain text chars with HTML escape or markup
* @param buf Destination string
* @param spaceEol True to replace end of line with space instead of html markup
*/
static void plain2html(String& buf, bool spaceEol = false);
/**
* Find a list parameter by its value
* @param list The list
* @param value Parameter value
* @param skip Optional parameter to skip
* @return NamedString pointer, 0 if not found
*/
static NamedString* findParamByValue(NamedList& list, const String& value,
NamedString* skip = 0);
/**
* Decode flags from dictionary values found in a list of parameters
* Flags are allowed to begin with '!' to reset
* @param dict The dictionary containing the flags
* @param params The list of parameters used to update the flags
* @param prefix Optional parameter prefix
* @return Decoded flags
*/
static int decodeFlags(const TokenDict* dict, const NamedList& params,
const String& prefix = String::empty());
/**
* Decode flags from dictionary values and comma separated list.
* Flags are allowed to begin with '!' to reset
* @param dict The dictionary containing the flags
* @param flags The list of flags
* @param defVal Default value to return if empty or no non 0 value is found in dictionary
* @return Decoded flags
*/
static int decodeFlags(const TokenDict* dict, const String& flags, int defVal = 0);
/**
* Add path separator at string end. Set destination string.
* Source and dstination may be the same string
* @param dest Destination string
* @param path Source string
* @param sep Path separator, use Engine::pathSeparator() if 0
*/
static void addPathSep(String& dest, const String& path, char sep = 0);
/**
* Fix path separator. Set it to platform default
* @param path The path
*/
static void fixPathSep(String& path);
/**
* Remove path separator from string end. Set destination string.
* Source and dstination may be the same string
* @param dest Destination string
* @param path Source string
* @param sep Path separator, use Engine::pathSeparator() if 0
* @return True if destination string is not empty
*/
static bool removeEndsWithPathSep(String& dest, const String& path, char sep = 0);
/**
* Set destination from last item in path.
* Source and dstination may be the same string
* @param dest Destination string
* @param path Source string
* @param sep Path separator, use Engine::pathSeparator() if 0
* @return True if destination string is not empty
*/
static bool getLastNameInPath(String& dest, const String& path, char sep = 0);
/**
* Remove last name in path, set destination from remaining.
* If the path ends with 'sep', only 'sep' is removed
* If the path don't contain 'sep' dest is set to empty.
* Source and dstination may be the same string
* @param dest Destination string
* @param path Source string
* @param sep Path separator, use Engine::pathSeparator() if 0
* @param equalOnly Optional string to match last item.
* Don't remove (set destination to empty) if not equal
* @return True if removed
*/
static bool removeLastNameInPath(String& dest, const String& path, char sep = 0,
const String& equalOnly = String::empty());
/**
* Add a formatted log line
* @param format Text format
* @return True on success
*/
static bool addToLogFormatted(const char* format, ...);
static Configuration s_settings; // Client settings
static Configuration s_actions; // Logic preferrences
static Configuration s_accounts; // Accounts
static Configuration s_contacts; // Contacts
static Configuration s_providers; // Provider settings
static Configuration s_history; // Call log
static Configuration s_calltoHistory; // Dialed destinations history
// Holds a not selected/set value match
static Regexp s_notSelected;
// Regexp used to check if a string is a GUID in the format
// 8*HEX-4*HEX-4*HEX-4*HEX-12*HEX
static Regexp s_guidRegexp;
// Paths
static String s_skinPath;
static String s_soundPath;
// Ring name for incoming channels
static String s_ringInName;
// Ring name for outgoing channels
static String s_ringOutName;
// Status widget's name
static String s_statusWidget;
// Widget displaying the debug text
static String s_debugWidget;
// The list of cient's toggles
static String s_toggles[OptCount];
// Maximum remote users allowed to enter in conference
static int s_maxConfPeers;
// Engine started flag
static bool s_engineStarted;
protected:
/**
* Create the default logic
* The default implementation creates a DefaultLogic object
* @return ClientLogic pointer or 0
*/
virtual ClientLogic* createDefaultLogic();
virtual bool createWindow(const String& name,
const String& alias = String::empty()) = 0;
virtual void loadWindows(const char* file = 0) = 0;
virtual void initWindows();
virtual void initClient();
virtual void exitClient()
{}
virtual bool isUIThread()
{ return Thread::current() == m_clientThread; }
inline bool needProxy() const
{ return m_oneThread && !(Client::self() && Client::self()->isUIThread()); }
bool driverLockLoop();
static bool driverLock(long maxwait = 0);
static void driverUnlock();
static bool s_exiting; // Exiting flag
ObjList m_windows;
bool m_initialized;
int m_line;
bool m_oneThread;
bool m_toggles[OptCount];
ObjList m_relays; // Message relays installed by this receiver
ClientLogic* m_defaultLogic; // The default logic
static Client* s_client;
static int s_changing;
static ObjList s_logics;
static bool s_idleLogicsTick; // Call logics' timerTick()
Thread* m_clientThread;
};
/**
* This class implements a Channel used by client programs
* @short Channel used by client programs
*/
class YATE_API ClientChannel : public Channel
{
YCLASS(ClientChannel,Channel)
friend class ClientDriver;
YNOCOPY(ClientChannel); // no automatic copies please
public:
/**
* Channel notifications
*/
enum Notification {
Startup,
Destroyed,
Active,
OnHold,
Mute,
Noticed,
AddrChanged,
Routed,
Accepted,
Rejected,
Progressing,
Ringing,
Answered,
Transfer,
Conference,
AudioSet,
Unknown
};
/**
* Channel slave type
*/
enum SlaveType {
SlaveNone = 0,
SlaveTransfer,
SlaveConference,
};
/**
* Incoming (from engine) constructor
* @param msg The call.execute message
* @param peerid The peer's id
*/
ClientChannel(const Message& msg, const String& peerid);
/**
* Outgoing (to engine) constructor
* @param target The target to call
* @param params Call parameters
* @param st Optional slave
* @param masterChan Master channel id if slave, ignored otherwise
*/
ClientChannel(const String& target, const NamedList& params, int st = SlaveNone,
const String& masterChan = String::empty());
/**
* Constructor for utility channels used to play notifications
* @param soundId The id of the sound to play
*/
explicit ClientChannel(const String& soundId);
virtual ~ClientChannel();
/**
* Init and start router for an outgoing (to engine), not utility, channel
* @param target The target to call
* @param params Call parameters
* @return True on success
*/
bool start(const String& target, const NamedList& params);
virtual bool msgProgress(Message& msg);
virtual bool msgRinging(Message& msg);
virtual bool msgAnswered(Message& msg);
virtual bool msgDrop(Message& msg, const char* reason);
virtual bool callRouted(Message& msg);
virtual void callAccept(Message& msg);
virtual void callRejected(const char* error, const char* reason, const Message* msg);
/**
* Answer an incoming call. Set media channels. Enqueue a clientchan.update message
* @param setActive True to activate the channel
*/
void callAnswer(bool setActive = true);
/**
* Get the slave type of this channel
* @return The slave type of this channel
*/
inline int slave() const
{ return m_slave; }
/**
* Retrieve channel slaves.
* This method is not thread safe
* @return Channel slaves list
*/
inline ObjList& slaves()
{ return m_slaves; }
/**
* Retrieve channel slaves number. This method is thread safe
* @return Channel slaves list
*/
inline unsigned int slavesCount() const {
Lock lock(m_mutex);
return m_slaves.count();
}
/**
* Add a slave id. This method is thread safe
* @param sid Slave id to add
*/
inline void addSlave(const String& sid) {
Lock lock(m_mutex);
if (!m_slaves.find(sid))
m_slaves.append(new String(sid));
}
/**
* Remove a slave id. This method is thread safe
* @param sid Slave id to remove
*/
inline void removeSlave(const String& sid) {
Lock lock(m_mutex);
m_slaves.remove(sid);
}
/**
* Get the master channel id if any
* @return The master channel id of this channel
*/
inline const String& master() const
{ return m_master; }
/**
* Retrieve channel client parameters
* @return Channel client parameters list
*/
inline const NamedList& clientParams() const
{ return m_clientParams; }
/**
* Get the remote party of this channel
* @return The remote party of this channel
*/
inline const String& party() const
{ return m_party; }
/**
* Get the remote party name of this channel
* @return The remote party name of this channel
*/
inline const String& partyName() const
{ return m_partyName ? m_partyName : m_party; }
/**
* Check if this channel is in conference
* @return True if this channel is in conference
*/
inline bool conference() const
{ return m_conference; }
/**
* Get the transferred peer's id
* @return The transferred peer's id
*/
inline const String& transferId() const
{ return m_transferId; }
/**
* Get the client data
* @return RefObject pointer or 0
*/
inline RefObject* clientData() const
{ return m_clientData; }
/**
* Set/reset the client data.
* If a new client data is set its reference counter is increased
* @param obj The new client data
*/
inline void setClientData(RefObject* obj = 0) {
TelEngine::destruct(m_clientData);
if (obj && obj->ref())
m_clientData = obj;
}
/**
* Attach/detach media channels
* @param open True to open, false to close
* @param replace True to replace media if already open. Ignored if open is false
* @return True on success
*/
bool setMedia(bool open = false, bool replace = false);
/**
* Set/reset this channel's data source/consumer
* @param active True to set active, false to set inactive (mute)
* @param update True to enqueue an update message
* @return True on success
*/
bool setActive(bool active, bool update = true);
/**
* Set/reset this channel's muted flag. Set media if 'on' is false and the channel is active
* @param on True to reset outgoing media, false to set outgoing media
* @param update True to enqueue an update message
* @return True on success
*/
bool setMuted(bool on, bool update = true);
/**
* Set/reset the transferred peer's id. Enqueue clientchan.update if changed.
* Open media when reset if the channel is active and answered
* @param target The transferred peer's id. Leave it blank to reset
*/
void setTransfer(const String& target = String::empty());
/**
* Set/reset the conference data. Enqueue clientchan.update if changed.
* Open media when reset if the channel is active and answered
* @param target The confeernce room's name. Leave it blank to reset
*/
void setConference(const String& target = String::empty());
/**
* Get the peer consumer's data format
* @return The peer consumer's data format
*/
inline const String& peerOutFormat() const
{ return m_peerOutFormat; }
/**
* Get the peer source's data format
* @return The peer source's data format
*/
inline const String& peerInFormat() const
{ return m_peerInFormat; }
/**
* Check if this channel is the active one
* @return True if this channel is the active one
*/
inline bool active() const
{ return m_active; }
/**
* Check if this channel is muted
* @return True if this channel is muted
*/
inline bool muted() const
{ return m_muted; }
/**
* Check if this channel was noticed
* @return True if this channel was noticed
*/
inline bool isNoticed() const
{ return m_noticed; }
/**
* Notice this channel. Enqueue a clientchan.update message
*/
void noticed();
/**
* Get this channel's line
* @return This channel's line
*/
inline int line() const
{ return m_line; }
/**
* Set this channel's line
* @param newLine This channel's line
*/
void line(int newLine);
/**
* Update channel. Enqueue a clientchan.update message with the given operation.
* Enqueue other channel status messages if required
* @param notif The value of the notify parameter
* @param chan Set the channel as message's user data
* @param updatePeer True to update peer's data formats
* @param engineMsg Optional message to enqueue in the engine
* @param minimal Set to true to fill in only a minimum of engine message's parameters
* @param data Set the channel as engine message's user data
*/
void update(int notif, bool chan = true,
bool updatePeer = true, const char* engineMsg = 0,
bool minimal = false, bool data = false);
/**
* Retrieve peer used to reconnect. This method is thread safe
* @param buf Destination buffer
*/
inline void getReconnPeer(String& buf) {
Lock lck(m_mutex);
buf = m_peerId;
}
/**
* Check if the peer used to reconnect is alive
* @return True if the peer used to reconnect is alive
*/
inline bool hasReconnPeer()
{ return 0 != getReconnPeer(false); }
/**
* Get peer used to reconnect
* @param ref True to return a referenced pointer
* @return CallEndpoint pointer or 0 if not found
*/
CallEndpoint* getReconnPeer(bool ref = true);
/**
* Drop peer used to reconnect
*/
void dropReconnPeer(const char* reason = 0);
/**
* Lookup for a notification id
* @param notif The notification's name
* @param def Default value to return if not found
* @return The result
*/
static int lookup(const char* notif, int def = Unknown)
{ return TelEngine::lookup(notif,s_notification,def); }
/**
* Lookup for a notification name
* @param notif The notification's id
* @param def Default value to return if not found
* @return The result
*/
static const char* lookup(int notif, const char* def = 0)
{ return TelEngine::lookup(notif,s_notification,def); }
/**
* Lookup for a slave type
* @param notif The slave type name
* @param def Default value to return if not found
* @return The result
*/
static int lookupSlaveType(const char* notif, int def = SlaveNone)
{ return TelEngine::lookup(notif,s_slaveTypes,def); }
/**
* Channel notifications dictionary
*/
static const TokenDict s_notification[];
/**
* Channel notifications dictionary
*/
static const TokenDict s_slaveTypes[];
protected:
virtual void destroyed();
virtual void connected(const char* reason);
virtual void disconnected(bool final, const char* reason);
// Check for a source in channel's peer or a received message's user data
inline bool peerHasSource(Message& msg) {
CallEndpoint* ch = getPeer();
if (!ch)
ch = static_cast<CallEndpoint*>(msg.userObject(YATOM("CallEndpoint")));
return ch && ch->getSource();
}
// Check if our consumer's source sent any data
// Don't set the silence flag is already reset
void checkSilence();
int m_slave; // Slave type
String m_master; // Master channel id
String m_party; // Remote party
String m_partyName; // Remote party name
String m_peerOutFormat; // Peer consumer's data format
String m_peerInFormat; // Peer source's data format
String m_reason; // Termination reason
String m_peerId; // Peer's id (used to re-connect)
bool m_noticed; // Incoming channel noticed flag
int m_line; // Channel's line (address)
bool m_active; // Channel active flag
bool m_silence; // True if the peer did't sent us any audio data
bool m_conference; // True if this channel is in conference
bool m_muted; // True if this channel is muted (no data source))
String m_transferId; // Transferred id or empty if not transferred
RefObject* m_clientData; // Obscure data used by client logics
bool m_utility; // Regular client channel flag
String m_soundId; // The id of the sound to play
ObjList m_slaves; // Data managed by the default logic
NamedList m_clientParams; // Channel client parameters
};
/**
* Abstract client Driver that implements some of the specific functionality
* @short Base Driver with client specific functions
*/
class YATE_API ClientDriver : public Driver
{
YCLASS(ClientDriver,Driver)
friend class ClientChannel; // Reset active channel's id
YNOCOPY(ClientDriver); // No automatic copies please
public:
ClientDriver();
virtual ~ClientDriver();
virtual void initialize() = 0;
virtual bool msgExecute(Message& msg, String& dest);
virtual void msgTimer(Message& msg);
virtual bool msgRoute(Message& msg);
virtual bool received(Message& msg, int id);
/**
* Get the active channel's id
* @return The active channel's id
*/
inline const String& activeId() const
{ return m_activeId; }
/**
* Set/reset the active channel.
* Does nothing if the selected channel is the active one.
* Put the active channel on hold before trying to set the active channel
* @param id The new active channel's id. Set to empty if don't want
* to set a new active channel
* @return True on success
*/
bool setActive(const String& id = String::empty());
/**
* Find a channel by its line
* @param line The line to find
* @return ClientChannel pointer of 0
*/
ClientChannel* findLine(int line);
/**
* Get the global client driver object's address
* @return The global client driver object's address
*/
inline static ClientDriver* self()
{ return s_driver; }
/**
* Get the current audio device's name
* @return The current audio device's name
*/
inline static const String& device()
{ return s_device; }
/**
* Drop all calls belonging to the active driver
* @param reason Optional drop reason
*/
static void dropCalls(const char* reason = 0);
/**
* Attach/detach client channels peers' source/consumer
* @param id The id of the channel to tranfer
* @param target The transfer target. Leave blank to reset the channel's transfer id
* @return True on success
*/
static bool setAudioTransfer(const String& id, const String& target = String::empty());
/**
* Attach/detach a client channel to/from a conference room
* @param id The id of the channel to process
* @param in True to enter the conference room, false to exit from it
* @param confName Optional id of the conference. Set to 0 to use the default one
* Ignored if 'in' is false
* @param buildFromChan Build conference name from channel id if true
* @return True on success
*/
static bool setConference(const String& id, bool in, const String* confName = 0,
bool buildFromChan = false);
/**
* Get a referenced channel found by its id
* @param id The id of the channel to find
* @return Referenced ClientChannel pointer or 0
*/
static ClientChannel* findChan(const String& id);
/**
* Get a referenced channel whose stored peer is the given one
* @param peer Peer id to check
* @return Referenced ClientChannel pointer or 0
*/
static ClientChannel* findChanByPeer(const String& peer);
/**
* Get the active channel
* @return Referenced ClientChannel pointer or 0
*/
static inline ClientChannel* findActiveChan()
{ return self() ? findChan(self()->activeId()) : 0; }
/**
* Drop a channel
* @param chan Channel id
* @param reason Optional reason
* @param peer Set it to true to drop a client channel peer used to reconnect
*/
static void dropChan(const String& chan, const char* reason = 0, bool peer = false);
/**
* The name to use when the client is in conference
*/
static String s_confName;
/**
* Indicates wether a channel should drop its former peer when
* terminated while in conference
*/
static bool s_dropConfPeer;
protected:
void setup();
static ClientDriver* s_driver;
static String s_device;
String m_activeId; // The active channel's id
};
/**
* This class implements the logic behind different actions in the client.
* It specifies the way the graphical interface of the client will behave
* in different circumstances.
* @short Base class for all client logics
*/
class YATE_API ClientLogic : public GenObject
{
YCLASS(ClientLogic,GenObject)
friend class Client;
YNOCOPY(ClientLogic); // no automatic copies please
public:
/**
* Destructor. Remove itself from the client's list
*/
virtual ~ClientLogic();
/**
* Get the name of this logic
* @return This logic's name
*/
inline const String& name() const
{ return m_name; }
/**
* Get the priority of this logic
* @return This logic's priority
*/
inline int priority() const
{ return m_prio; }
/**
* Function that returns the name of the logic
* @return The name of this client logic
*/
virtual const String& toString() const;
/**
* Process a request to set client parameters
* @param params The parameter list
* @return True on success
*/
bool setParams(const NamedList& params);
/**
* Handle actions from user interface
* @param wnd The window in which the user did something
* @param name The action's name
* @param params Optional action parameters
* @return True if the action was handled
*/
virtual bool action(Window* wnd, const String& name, NamedList* params = 0)
{ return false; }
/**
* Handle actions from checkable widgets
* @param wnd The window in which the user did something
* @param name The object's name
* @param active Object's state
* @return True if the action was handled by a client logic
*/
virtual bool toggle(Window* wnd, const String& name, bool active)
{ return false; }
/**
* Handle 'select' actions from user interface
* @param wnd The window in which the user did something
* @param name The object's name
* @param item Item identifying the selection
* @param text Selection's text
* @return True if the action was handled
*/
virtual bool select(Window* wnd, const String& name, const String& item,
const String& text = String::empty())
{ return false; }
/**
* Handle 'select' with multiple items actions from user interface
* @param wnd The window in which the user did something
* @param name The object's name
* @param items List of selected items
* @return True if the action was handled
*/
virtual bool select(Window* wnd, const String& name, const NamedList& items)
{ return false; }
/**
* Set a client's parameter. Save the settings file and/or update interface
* @param param Parameter's name
* @param value The value of the parameter
* @param save True to save the configuration file
* @param update True to update the interface
* @return True on success
*/
virtual bool setClientParam(const String& param, const String& value,
bool save, bool update)
{ return false; }
/**
* Process an IM message
* @param msg The im.execute or chan.text message
*/
virtual bool imIncoming(Message& msg)
{ return false; }
/**
* Call execute handler called by the client.
* The default logic ask the client to build an incoming channel
* @param msg The call.execute message
* @param dest The destination (target)
* @return True if a channel was created and connected
*/
virtual bool callIncoming(Message& msg, const String& dest)
{ return false; }
/**
* Check presence of all necessary data to make a call
* @param params List of call parameters
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool validateCall(NamedList& params, Window* wnd = 0)
{ return true; }
/**
* Called when the user trigger a call start action
* The default logic fill the parameter list and ask the client to create an outgoing channel
* @param params List of call parameters
* @param wnd Optional window containing the widget that triggered the action
* @param cmd Optional command (widget name)
* @return True on success
*/
virtual bool callStart(NamedList& params, Window* wnd = 0,
const String& cmd = String::empty())
{ return false; }
/**
* Called when the user selected a line
* @param name The line name
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool line(const String& name, Window* wnd = 0);
/**
* Show/hide widget(s) or window(s) on 'display'/'show' action.
* @param params Widget(s) or window(s) to show/hide
* @param widget True if the operation indicates widget(s), false otherwise
* @param wnd Optional window owning the widget(s) to show or hide
* @return False if failed to show/hide all widgets/windows
*/
virtual bool display(NamedList& params, bool widget, Window* wnd = 0);
/**
* Erase the last digit from the given widget and set focus on it
* @param name The widget (it might be the window itself)
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool backspace(const String& name, Window* wnd = 0);
/**
* Enqueue an engine.command message
* @param name The command line
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool command(const String& name, Window* wnd = 0);
/**
* Enqueue an engine.debug message.
* @param name The debug action content (following the prefix). The format
* of this parameter must be 'module:active-true:active-false'.
* The line parameter of the message will be filled with 'active-true' if
* active is true and with 'active-false' if active is false
* @param active The widget's state
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool debug(const String& name, bool active, Window* wnd = 0);
/**
* Called when the user wants to add a new account or edit an existing one
* @param newAcc True to add a new account, false to edit an exisiting one
* @param params Initial parameters
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool editAccount(bool newAcc, NamedList* params, Window* wnd = 0)
{ return false; }
/**
* Called when the user wants to save account data
* @param params Initial parameters
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool acceptAccount(NamedList* params, Window* wnd = 0)
{ return false; }
/**
* Called when the user wants to delete an existing account
* @param account The account's name. Set to empty to delete the current selection
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool delAccount(const String& account, Window* wnd = 0)
{ return false; }
/**
* Add/set an account. Login if required
* @param account The account's parameters. The name of the list must be the account's name
* @param login True to login the account
* @param save True to save the accounts file. If true and file save fails the method will fail
* @return True on success
*/
virtual bool updateAccount(const NamedList& account, bool login, bool save)
{ return false; }
/**
* Login/logout an account
* @param account The account's parameters. The name of the list must be the account's name
* @param login True to login the account, false to logout
* @return True on success
*/
virtual bool loginAccount(const NamedList& account, bool login)
{ return false; }
/**
* Add/set a contact
* @param contact The contact's parameters. The name of the list must be the contacts's id (name).
* If it starts with 'client/' this is a contact updated from server: it can't be changed
* @param save True to save data to contacts file
* @param update True to update the interface
* @return True on success
*/
virtual bool updateContact(const NamedList& contact, bool save, bool update)
{ return false; }
/**
* Called when the user wants to save account data
* @param params Initial parameters
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool acceptContact(NamedList* params, Window* wnd = 0)
{ return false; }
/**
* Called when the user wants to add a new contact or edit an existing one
* @param newCont True to add a new contact, false to edit an existing one
* @param params Optional initial parameters
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool editContact(bool newCont, NamedList* params = 0, Window* wnd = 0)
{ return false; }
/**
* Called when the user wants to delete an existing contact
* @param contact The contact's id. Set to empty to delete the current selection
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool delContact(const String& contact, Window* wnd = 0)
{ return false; }
/**
* Called when the user wants to call an existing contact
* @param params Optional parameters
* @param wnd Optional window containing the widget that triggered the action
* @return True on success
*/
virtual bool callContact(NamedList* params = 0, Window* wnd = 0)
{ return false; }
/**
* Add/set account providers data
* @param provider The provider's parameters. The name of the list must be the provider's id (name)
* @param save True to save data to providers file
* @param update True to update the interface
* @return True on success
*/
virtual bool updateProviders(const NamedList& provider, bool save, bool update)
{ return false; }
/**
* Update the call log history
* @param params Call log data
* @param save True to save data to history file
* @param update True to update the interface
* @return True
*/
virtual bool callLogUpdate(const NamedList& params, bool save, bool update)
{ return false; }
/**
* Remove a call log item
* @param billid The bill id of the call
* @return True on success
*/
virtual bool callLogDelete(const String& billid)
{ return false; }
/**
* Clear the specified log and the entries from the history file and save the history file
* @param table Tebale to clear
* @param direction The call direction to clear (incoming,outgoing).
* Note that the direction is the value saved from call.cdr messages.
* If empty, all log entries will be cleared
* @return True
*/
virtual bool callLogClear(const String& table, const String& direction)
{ return false; }
/**
* Make an outgoing call to a target picked from the call log
* @param billid The bill id of the call
* @param wnd Optional window starting the action
* @return True on success (call initiated)
*/
virtual bool callLogCall(const String& billid, Window* wnd = 0)
{ return false; }
/**
* Create a contact from a call log entry
* @param billid The bill id of the call
* @return True on success (address book popup window was displayed)
*/
virtual bool callLogCreateContact(const String& billid)
{ return false; }
/**
* Process help related actions
* @param action The action's name
* @param wnd The window owning the control
* @return True on success
*/
virtual bool help(const String& action, Window* wnd)
{ return false; }
/**
* Called by the client after loaded the callto history file
* @return True to tell the client to stop notifying other logics
*/
virtual bool calltoLoaded()
{ return false; }
/**
* Called by the client after loaded the windows
*/
virtual void loadedWindows()
{}
/**
* Called by the client after loaded and intialized the windows
*/
virtual void initializedWindows()
{}
/**
* Called by the client after loaded and intialized the windows and
* loaded configuration files.
* The default logic update client settings
* @return True to stop processing this notification
*/
virtual bool initializedClient()
{ return false; }
/**
* Called by the client before exiting.
* The default logic save client settings
*/
virtual void exitingClient()
{}
/**
* Process ui.action message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleUiAction(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process call.cdr message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleCallCdr(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process user.login message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleUserLogin(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process user.notify message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleUserNotify(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process user.roster message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleUserRoster(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process resource.notify message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleResourceNotify(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process resource.subscribe message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleResourceSubscribe(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process clientchan.update message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleClientChanUpdate(Message& msg, bool& stopLogic)
{ return false; }
/**
* Process contact.info message
* @param msg Received message
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool handleContactInfo(Message& msg, bool& stopLogic)
{ return false; }
/**
* Default message processor called for id's not defined in client.
* Descendants may override it to process custom messages installed by
* them and relayed through the client
* @param msg Received message
* @param id Message id
* @param stopLogic Set to true on exit to tell the client to stop asking other logics
* @return True to stop further processing by the engine
*/
virtual bool defaultMsgHandler(Message& msg, int id, bool& stopLogic)
{ return false; }
/**
* Engine start notification
* @param msg The engine.start message
*/
virtual void engineStart(Message& msg)
{}
/**
* Add a duration object to this client's list
* @param duration The object to add
* @param autoDelete True to delete the object when the list is cleared
* @return True on success
*/
virtual bool addDurationUpdate(DurationUpdate* duration, bool autoDelete = false);
/**
* Remove a duration object from list
* @param name The name of the object to remove
* @param delObj True to destroy the object, false to remove it