- Main Page
- Related Pages
- Classes
- Files
- Examples

- File List
- File Members

# skype-embedded_2.h

Go to the documentation of this file.

    00001 #include "SidPlatform.hpp"
    00002
    00003 #ifndef Skype_EMBEDDED_H_INCLUDED
    00004 #define Skype_EMBEDDED_H_INCLUDED
    00005
    00006 #include "sidg_Skyperefs.hpp"
    00007 #include "sidg_msgs_Skype.hpp"
    00008
    00009 #define __EA(a) #a
    00010
    00011 #ifdef SE_USE_NAMESPACE
    00012 namespace Skype
    00013 {
    00014 #endif
    00015
    00016 class Skype;
    00017 class ContactGroup;
    00018 class Contact;
    00019 class ContactSearch;
    00020 class Participant;
    00021 class Conversation;
    00022 class Message;
    00023 class Video;
    00024 class Voicemail;
    00025 class Sms;
    00026 class Transfer;
    00027 class Account;
    00028
    00029 /*! \class ContactGroup skype-embedded_2.h "skype-embedded_2.h"
    00030  *  \brief
    00031  *  \nosubgrouping
    00032  *  Collects and manages Contacts related by type, status, or some other arbitrary criteria. @brief SkypeKit recognizes
    00033  *  two distinct ContactGroup flavors - "hardwired" and "custom". SkypeKit both defines the criteria for and dynamically
    00034  *  manages all "hardwired" ContactGroups. Individual users explicitly create and manage all "custom" ContactGroups.  @n
    00035  *  @n "Hardwired" groups are primarily organizational tools, for example, they enable you to display a list of all
    00036  *  Contacts awaiting authorization by you. "Custom" groups are also organizational tools, for example, they enable you
    00037  *  to display a list of all Contacts in a particular geographical area or belonging to a particular professional
    00038  *  association, social clubs, and so forth. Primarily, though, "custom" groups are functional tools that enable you to
    00039  *  establish conference calls, group chats, and so forth. @n  @n "Hardwired" ContactGroups are defined for and
    00040  *  available to all users. SkypeKit determines membership in a particular "hardwired" group dynamically whenever a user
    00041  *  invokes Skype.GetHardwiredContactGroup for that group. Subsequent changes to a Contact's status might result in its
    00042  *  being added to (for example, the Contact is now authorized) or removed from (for example, the Contact is now removed
    00043  *  or blocked) one or more "hardwired" groups. @n  @n SkypeKit fires OnChange events for all affected ContractGroup
    00044  *  instances. Essentially all ContactGroup methods related to explicitly adding and removing members and conversations
    00045  *  from the group return false, and CanAdd and CanRemove additionally return a false result. @n  @n "Custom"
    00046  *  ContactGroups can be defined by a particular Skype user through the UI. Your UI should implement Creation, deletion
    00047  *  and filtering contact list by custom contact groups, as well as adding and removing contacts in those groups. @n  @n
    00048  *  A Contact can belong to multiple non-mutually exclusive "hardwired" groups at the same time, for example, an
    00049  *  authorized contact is typically in your "buddy" group, but a Contact cannot belong to CONTACTS_AUTHORIZED_BY_ME if
    00050  *  they are awaiting authorization. Similarly, a Contact can belong to multiple "custom" groups and mutual exclusivity
    00051  *  is typically not an issue. @n
    00052  */
    00053 class ContactGroup : public SEObject
    00054 {
    00055         /** \cond INTERNAL */
    00056         friend class Skype;
    00057 protected:
    00058         ContactGroup(unsigned int oid, SERootObject* root);
    00059         /** \endcond */
    00060 public:
    00061         virtual ~ContactGroup();
    00062         typedef ContactGroupRef Ref;
    00063         typedef ContactGroupRefs Refs;
    00064         enum { MODULE_ID = 10 };
    00065         ContactGroupRef ref() {
    00066                 return ContactGroupRef(object_id);
    00067         }
    00068
    00069 private:
    00070         String getNamespace() const;
    00071         const PMAP* getPMap() const;
    00072         const EMAP* getEMap() const;
    00073         unsigned int moduleID() const;
    00074         void __clear_cache(void*);
    00075
    00076 public:
    00077         /** Properties of the ContactGroup class */
    00078         enum PROPERTY {
    00079                 P_TYPE = 155                    /*!< ContactGroup::TYPE, type: TYPE*/,
    00080                 P_CUSTOM_GROUP_ID = 154         /*!< unique 32-bit ID for custom groups, type: uint*/,
    00081                 P_GIVEN_DISPLAYNAME = 151       /*!< change via ContactGroup::GiveDisplayname(), type: Sid::String*/,
    00082                 P_NROFCONTACTS                  /*!< Number of contacts in the group. NB! The value of this property does not get updated until 5 seconds after account login. During these initial 5 seconds, the value of this property remains 0. The reason for this 5 second delay is to reduce the flurry of property update traffic that occurs during the CBL synchronization phase, following successful login. Note that if you absolutely need to have this value immediately after login, you can still get it by retrieving the contact list with ContactGroup::GetContacts method and examining its size.  @n , type: uint*/,
    00083                 P_NROFCONTACTS_ONLINE           /*!< number of contacts online in the group, type: uint*/
    00084         };
    00085
    00086         /** The list of all possible ContactGroup types. A value of this type can be passed to Skype class GetHardwiredContactGroup to retrieve the relevant ContactGroup object. @n  */
    00087         enum TYPE {
    00088                 ALL_KNOWN_CONTACTS = 1        /*!< The superset of all "hardwired" contact groups. @n */,
    00089                 ALL_BUDDIES                   /*!< The set of all authorized contacts, that is, contacts that were last the target of Contact::SetBuddyStatus(false) plus all SkypeOut contacts. @n */,
    00090                 SKYPE_BUDDIES                 /*!< The set of all authorized Skype contacts (Contact:_SKYPENAME is non-null).  @n Note that this excludes Skype contacts that have either never been the target of Contact::SetBuddyStatus(true) or were last the target of Contactact::SetBuddyStatus(false). @n */,
    00091                 SKYPEOUT_BUDDIES              /*!< The set of all SkypeOut contacts (Contact:_PSTNNUMBER is non-null). PSTN contacts can be added to the contact list by retrieving a new contact object with Skype::GetContact, passing in the phone number as string, and then either using Contact::SetBuddyStatus(true) or adding the contact to the SKYPEOUT_BUDDIES group with ContactGroup::AddContact. @n */,
    00092                 ONLINE_BUDDIES                /*!< The subset of ALL_BUDDIES that are currently online, including those currently marked as DO_NOT_DISTURBED and AWAY. @n */,
    00093                 UNKNOWN_OR_PENDINGAUTH_BUDDIES/*!< The set of all contacts whose Contact:_TYPE reflects UNRECOGNIZED OR have not authorized the local user yet. @n */,
    00094                 RECENTLY_CONTACTED_CONTACTS   /*!< This filter returns top 10 most recently contacted contacts, based on Contact::P_LASTUSED_TIMESTAMP property values. This is not configurable. Note that the P_LASTUSED_TIMESTAMP property does not propagate between different Skype instances - thus this filter only works in context of the local database. Recent contacts that were in touch with the user on some other Skype installation will not show up in this filter. @n */,
    00095                 CONTACTS_WAITING_MY_AUTHORIZATION/*!< Contacts to whose authorization request the user has not responded yet. The UI should enable the user to accept, decline the authorization request and in case of decline, optionally block further incoming communication from the contact. See: Contact::SetBuddyStatus, Contact::SetBlocked and Contact::IgnoreAuthRequest for more information. @n */,
    00096                 CONTACTS_AUTHORIZED_BY_ME     /*!< All contacts authorized by the user. @n */,
    00097                 CONTACTS_BLOCKED_BY_ME        /*!< Group of contacts the user has blocked from further incoming communications. If the UI enables contact blocking, it should also provide interface for the user to unblock the blocked contacts. Note that a contact can simultaneously be in both CONTACTS_BLOCKED_BY_ME and CONTACTS_AUTHORIZED_BY_ME groups. @n */,
    00098                 UNGROUPED_BUDDIES             /*!< The set of all "buddies" that are not also a member of a custom group. @n */,
    00099                 CUSTOM_GROUP                  /*!< A custom group defined by user. @n */,
    00100                 PROPOSED_SHARED_GROUP         /*!< The shared contact group functionality is no longer supported. This contact group type can be ignored. @n */,
    00101                 SHARED_GROUP                  /*!< The shared contact group functionality is no longer supported. This contact group type can be ignored. @n */,
    00102                 EXTERNAL_CONTACTS             /*!< The set of all contacts that were originally imported from an external address book. @n */
    00103         };
    00104
    00105         /** Setter for ContactGroup class GIVEN_DISPLAYNAME property. @n  */
    00106         bool GiveDisplayName(
    00107                 const Sid::String& name
    00108         );
    00109
    00110         /** Removes the contact group. This is synced across instances logged in with the same account - which can take several minutes for the sync to happen. @n  */
    00111         bool Delete(
    00112                 bool& result
    00113         );
    00114
    00115         /** Returns list of conversations in the ContactGroup. @n  */
    00116         bool GetConversations(
    00117                 ConversationRefs& conversations
    00118         );
    00119
    00120         /** Checks if the current user can add given conversation to the ContactGroup. Returns false for most of the hardwired contact groups for example. @n  */
    00121         bool CanAddConversation(
    00122                 bool& result, /*!< Returns true if Conversation can be added to this ContactGroup. @n */
    00123                 const ConversationRef conversation = 0 /*!< Conversation to be checked. @n */
    00124         );
    00125
    00126         /** Adds given conversation to the ContactGroup. @n  */
    00127         bool AddConversation(
    00128                 const ConversationRef& conversation
    00129         );
    00130
    00131         /** Checks if the current user can remove given conversation from the ContactGroup. Again, returns false for most hardwired contact groups. @n  */
    00132         bool CanRemoveConversation(
    00133                 bool& result /*!< true if RemoveConversation(contact) works on this group*/
    00134         );
    00135
    00136         /** Removes given conversation from the ContactGroup. @n  */
    00137         bool RemoveConversation(
    00138                 const ConversationRef& conversation
    00139         );
    00140
    00141         /** conversation added or removed from this group */
    00142         virtual void OnChangeConversation(
    00143                 const ConversationRef& conversation
    00144         );
    00145
    00146         /** Retrieves contact list. @n  */
    00147         bool GetContacts(
    00148                 ContactRefs& contacts
    00149         );
    00150
    00151         /** Checks if the current user can add given contact to the ContactGroup.  @n  */
    00152         bool CanAddContact(
    00153                 bool& result, /*!< returns true if AddContact(contact) works on this group. @n */
    00154                 const ContactRef contact = 0 /*!< Contact to be checked. @n */
    00155         );
    00156
    00157         /** Adds contact to a contact group. This only works for non-hardwired contact groups. @n  */
    00158         bool AddContact(
    00159                 const ContactRef& contact
    00160         );
    00161
    00162         /** Checks if the current user can remove given contact from the ContactGroup. @n  */
    00163         bool CanRemoveContact(
    00164                 bool& result /*!< true if RemoveContact(contact) works on this group*/
    00165         );
    00166
    00167         /** Removes contact from the ContactGroup. @n  */
    00168         bool RemoveContact(
    00169                 const ContactRef& contact
    00170         );
    00171
    00172         /** A contact has been added or removed to this ContactGroup. @n NB! On rare occasions, the ContectRef argument to this callback can be NULL. You should always check whether the reference is valid, before accessing methods or properties. @n  */
    00173         virtual void OnChange(
    00174                 const ContactRef& contact
    00175         );
    00176
    00177         /** ContactGroup::P_TYPE property get accessor */
    00178         bool GetPropType(TYPE& type);
    00179
    00180         /** ContactGroup::P_CUSTOM_GROUP_ID property get accessor */
    00181         bool GetPropCustomGroupId(uint& custom_group_id);
    00182
    00183         /** ContactGroup::P_GIVEN_DISPLAYNAME property get accessor */
    00184         bool GetPropGivenDisplayname(Sid::String& given_displayname);
    00185
    00186         /** ContactGroup::P_NROFCONTACTS property get accessor */
    00187         bool GetPropNrofcontacts(uint& nrofcontacts);
    00188
    00189         /** ContactGroup::P_NROFCONTACTS_ONLINE property get accessor */
    00190         bool GetPropNrofcontactsOnline(uint& nrofcontacts_online);
    00191
    00192 };
    00193
    00194
    00195 /*! \class Contact skype-embedded_2.h "skype-embedded_2.h"
    00196  *  \brief
    00197  *  \nosubgrouping
    00198  *  Address book entry. Encapsulates methods like GetIdentity, GetAvatar, SendAuthRequest, OpenConversation etc. Single
    00199  *  contact can have additional phone numbers attached to it (ASSIGNED_PHONE1 .. ASSIGNED_PHONE3). Note that in the
    00200  *  context of a conversation, Contacts are represented by Participant objects. @brief Contact member functions all
    00201  *  return a Boolean indicating the success (true) or failure (false) of processing the request itself (transport,
    00202  *  runtime availability, and so forth)?not the success or failure of its associated functionality. For example,
    00203  *  Contact::IsMemberOf returns true if it was able to make a determination, and its result parameter reflects whether
    00204  *  this Contact is a member of the target group. Similarly, Contact::IsMemberOf returns false if it was unable to make
    00205  *  a determination, and the value of its result parameter is undefined. @n
    00206  */
    00207 class Contact : public SEObject
    00208 {
    00209         /** \cond INTERNAL */
    00210         friend class Skype;
    00211 protected:
    00212         Contact(unsigned int oid, SERootObject* root);
    00213         /** \endcond */
    00214 public:
    00215         virtual ~Contact();
    00216         typedef ContactRef Ref;
    00217         typedef ContactRefs Refs;
    00218         enum { MODULE_ID = 2 };
    00219         ContactRef ref() {
    00220                 return ContactRef(object_id);
    00221         }
    00222
    00223 private:
    00224         String getNamespace() const;
    00225         const PMAP* getPMap() const;
    00226         const EMAP* getEMap() const;
    00227         unsigned int moduleID() const;
    00228         void __clear_cache(void*);
    00229
    00230 public:
    00231         /** Properties of the Contact class */
    00232         enum PROPERTY {
    00233                 P_TYPE = 202                    /*!< type: Contact::TYPE*/,
    00234                 P_SKYPENAME = 4                 /*!< defined if it is a SKYPE contact, type: Sid::String*/,
    00235                 P_PSTNNUMBER = 6                /*!< type: Sid::String*/,
    00236                 P_FULLNAME = 5                  /*!< type: Sid::String*/,
    00237                 P_BIRTHDAY = 7                  /*!< integer of YYYYMMDD format, type: uint*/,
    00238                 P_GENDER                        /*!< 1-male, 2-female, type: uint*/,
    00239                 P_LANGUAGES                     /*!< ISO language code list, space separated, type: Sid::String*/,
    00240                 P_COUNTRY                       /*!< ISO country code, type: Sid::String*/,
    00241                 P_PROVINCE                      /*!< type: Sid::String*/,
    00242                 P_CITY                          /*!< type: Sid::String*/,
    00243                 P_PHONE_HOME                    /*!< This corresponds to the Account::P_PHONE_HOME property. The value is set by the remote user in Account profile. As Contact property, this is read-only. @n , type: Sid::String*/,
    00244                 P_PHONE_OFFICE                  /*!< This corresponds to the Account::P_PHONE_OFFICE property. The value is set by the remote user in Account profile. As Contact property, this is read-only. If the Contact has not populated his Account profile with sufficient phone numbers, the UI should implement locally adding additional phone numbers to Contact P_ASSIGNED_PHONE1 .. P_ASSIGNED_PHONE3 properties (and corresponding labels). See Contact::SetPhoneNumber method for more information. @n , type: Sid::String*/,
    00245                 P_PHONE_MOBILE                  /*!< This corresponds to the Account::P_PHONE_MOBILE property. The value is set by the remote user in Account profile. As Contact property, this is read-only. @n , type: Sid::String*/,
    00246                 P_EMAILS                        /*!< will be hashed before advertising/querying, space separated, type: Sid::String*/,
    00247                 P_HOMEPAGE                      /*!< type: Sid::String*/,
    00248                 P_ABOUT                         /*!< arbitrary introductory text, type: Sid::String*/,
    00249                 P_AVATAR_IMAGE = 37             /*!< Contact avatar pictures are in JPG format. The original size of avatar pictures are in no more than 96 x 96 pixels in size. However, as they can be smaller, scaling the pictures up too much to fit your UI can lead to distorted images. @n , type: Sid::Binary*/,
    00250                 P_MOOD_TEXT = 26                /*!< Personal mood message (visible to authorized users only).  @n , type: Sid::String*/,
    00251                 P_RICH_MOOD_TEXT = 205          /*!< XML version of personal mood text, type: Sid::String*/,
    00252                 P_TIMEZONE = 27                 /*!< 24*3600+diff_to_UTC_in_seconds. NB! changes with DST @n , type: uint*/,
    00253                 P_CAPABILITIES = 36             /*!< binary tag that can be queried via Contact::HasCapability(), type: Sid::Binary*/,
    00254                 P_PROFILE_TIMESTAMP = 19        /*!< UNIX timestamp of last profile change, type: uint*/,
    00255                 P_NROF_AUTHED_BUDDIES = 28      /*!< count of this user's authorized contacts @n , type: uint*/,
    00256                 P_IPCOUNTRY                     /*!< ISO country code assigned by the IP, type: Sid::String*/,
    00257                 P_AVATAR_TIMESTAMP = 182        /*!< UNIX timestamp of when current avatar was set, type: uint*/,
    00258                 P_MOOD_TIMESTAMP                /*!< NOT SET FOR CONTACTS. For Account object, UNIX timestamp of when current mood was set, type: uint*/,
    00259                 P_RECEIVED_AUTHREQUEST = 20     /*!< set if the contact is waiting to be authorized. The value contains auth. request text @n , type: Sid::String*/,
    00260                 P_AUTHREQ_TIMESTAMP = 25        /*!< timestamp of last received auth-request, type: uint*/,
    00261                 P_LASTONLINE_TIMESTAMP = 35     /*!< X timestamp of last successful ping to that user, type: uint*/,
    00262                 P_AVAILABILITY = 34             /*!< Contact::AVAILABILITY, type: AVAILABILITY*/,
    00263                 P_DISPLAYNAME = 21              /*!< always set (assigned by lib by looking at various fields), type: Sid::String*/,
    00264                 P_REFRESHING                    /*!< true if querying additional information from p2p or server @n , type: bool*/,
    00265                 P_GIVEN_AUTHLEVEL               /*!< Contact::AUTHLEVEL, change via Contact::GiveAuthlevel(), type: AUTHLEVEL*/,
    00266                 P_GIVEN_DISPLAYNAME = 33        /*!< change via Contact::GiveDisplayname(), type: Sid::String*/,
    00267                 P_ASSIGNED_COMMENT = 180        /*!< change via Contact::AssignComment(), type: Sid::String*/,
    00268                 P_LASTUSED_TIMESTAMP = 39       /*!< UNIX timestamp of last outbound session (call, chat, FT, etc), type: uint*/,
    00269                 P_AUTHREQUEST_COUNT = 41        /*!< for contacts that have CONTACT_RECEIVED_AUTHREQUEST, how many times in a row they have requested it without positive answer, type: uint*/,
    00270                 P_ASSIGNED_PHONE1 = 184         /*!< Office phone no. of the contact. This property should NOT be used for SkypeOut contacts @n , type: Sid::String*/,
    00271                 P_ASSIGNED_PHONE1_LABEL         /*!< Value "1" in this property will be translated as "Office" by Skype Windows desktop client, according to UI language settings @n , type: Sid::String*/,
    00272                 P_ASSIGNED_PHONE2               /*!< Mobile phone no. of the contact @n , type: Sid::String*/,
    00273                 P_ASSIGNED_PHONE2_LABEL         /*!< Value "2" in this property will be translated as "Mobile" by Skype Windows desktop client, according to UI language settings @n , type: Sid::String*/,
    00274                 P_ASSIGNED_PHONE3               /*!< "Other phone no. of the contact, type: Sid::String*/,
    00275                 P_ASSIGNED_PHONE3_LABEL         /*!< Value "3" in this property will be translated as "Other" by Skype Windows desktop client, according to UI language settings @n , type: Sid::String*/,
    00276                 P_POPULARITY_ORD = 42           /*!< Contact's order by presence popularity @n , type: uint*/
    00277         };
    00278
    00279         /** Same as with CAPABILITY, enumerator is used by both Contact and Account objects. @n  */
    00280         enum TYPE {
    00281                 UNRECOGNIZED = 0              /*!< Contact/account has no pre-identified type. This type is reported by default for SkypeKit clients. @n */,
    00282                 SKYPE                         /*!< Normal Skype contact. @n */,
    00283                 PSTN                          /*!< Normal PSTN contact. @n */,
    00284                 EMERGENCY_PSTN                /*!< Emergency number (i.e. 911). @n */,
    00285                 FREE_PSTN,
    00286                 UNDISCLOSED_PSTN              /*!< Undisclosed PSTN number. @n */,
    00287                 EXTERNAL                      /*!< This type is currently used by Windows desktop clients for contacts imported from Outlook. @n */
    00288         };
    00289
    00290         /** Describes the recognized relational states between a local account and a remote contact. @n  */
    00291         enum AUTHLEVEL {
    00292                 NONE = 0                      /*!< Authorization request is either ignored or pending. In this state several functionalities may be blocked, depending on settings. For example, accounts may only allow seeing online presence to be viewable or only receive calls from authorized contacts. @n */,
    00293                 AUTHORIZED_BY_ME              /*!< Contact has been authorized by the local account. @n */,
    00294                 BLOCKED_BY_ME                 /*!< Contact has been blocked by the local account. This prevents incoming calls, chat messages, additional authorization requests etc. @n */
    00295         };
    00296
    00297         /** Describes the superset list of possible Account and Contact online statuses. In case of Account they apply to local user, in case of Contact they apply to remote contacts. @n  */
    00298         enum AVAILABILITY {
    00299                 UNKNOWN = 0                   /*!< Contact online status cannot be determined. This availability state should not normally reach the SkypeKit UI level. @n */,
    00300                 PENDINGAUTH = 8               /*!< Seeing Contact online status is blocked because authorization between contact and local account has not taken place. @n */,
    00301                 BLOCKED                       /*!< Remote contact has been blocked by local account. This applies to online accounts. @n */,
    00302                 BLOCKED_SKYPEOUT = 11         /*!< Remote SkypeOut contact has been blocked by local account. @n */,
    00303                 SKYPEOUT = 10                 /*!< Contact does not have an online status because he is a PSTN contact. @n */,
    00304                 OFFLINE = 1                   /*!< Contact appears to be offline. @n */,
    00305                 OFFLINE_BUT_VM_ABLE = 12      /*!< Contact appears to be offline but has voicemail enabled. @n */,
    00306                 OFFLINE_BUT_CF_ABLE           /*!< Contact appears to be offline but has enabled call forwarding, so calls may actually get through to him. @n */,
    00307                 ONLINE = 2                    /*!< Contact / Account is online @n */,
    00308                 AWAY                          /*!< Contact / Account is online but away from keyboard. This can be either turned on manually or by automatic timer. In Windows desktop client, the timer can be configured with minute precision. @n */,
    00309                 NOT_AVAILABLE                 /*!< This online status is marked as deprecated. If a remote contact indicates its status as NOT_AVAILABLE, the UI should handle this as equivalent of AWAY status. @n */,
    00310                 DO_NOT_DISTURB                /*!< Contact / Account is online but does not wish to be disturbed. This status supersedes AWAY status when the account is DO_NOT_DISTURB the AWAY timer should not modify the status. @n */,
    00311                 SKYPE_ME = 7                  /*!< This online status is marked as deprecated. If a remote contact indicates its status as SKYPE_ME, the UI should handle this as equivalent of ONLINE status. @n */,
    00312                 INVISIBLE = 6                 /*!< Account status is set to INVISIBLE. This status in not applicable to remote Contacts. When the remote contact has set his availability to INVISIBLE, he will appear as OFFLINE to others. @n */,
    00313                 CONNECTING = 14               /*!< only possible for local user/account*/,
    00314                 ONLINE_FROM_MOBILE,
    00315                 AWAY_FROM_MOBILE              /*!< *_FROM_MOBILE only possible for remote user*/,
    00316                 NOT_AVAILABLE_FROM_MOBILE,
    00317                 DO_NOT_DISTURB_FROM_MOBILE,
    00318                 SKYPE_ME_FROM_MOBILE = 20
    00319         };
    00320
    00321         bool GetIdentity(
    00322                 Sid::String& identity /*!< returns CONTACT_SKYPENAME or CONTACT_PSTNNUMBER value*/
    00323         );
    00324
    00325         /** Returns Conrtact's avatar image (JPG). @n  */
    00326         bool GetAvatar(
    00327                 bool& present, /*!< @li true: the Contact has a custom avatar image @li false: the Contact does not have a custom avatar image @n */
    00328                 Sid::Binary& avatar /*!< The avatar image data (JPG). If present is false, this will be the Skype-assigned default avatar @n */
    00329         );
    00330
    00331         /** returns verified-by-Skype e-mail for this contact if exists and verifiable */
    00332         bool GetVerifiedEmail(
    00333                 Sid::String& email
    00334         );
    00335
    00336         /** returns verified-by-Skype company for this contact if exists and verifiable */
    00337         bool GetVerifiedCompany(
    00338                 Sid::String& company
    00339         );
    00340
    00341         /** Checks whether the contact is member of a contact group given in group reference argument. @n  */
    00342         bool IsMemberOf(
    00343                 const ContactGroupRef& group, /*!< The target contact group @n */
    00344                 bool& result /*!< @li true: the Contact is a member of the target contact group @li false: the Contact is not a member of the target contact group @n */
    00345         );
    00346
    00347         /** Checks whether the contact is member of a pre-defined contact group given in the TYPE argument (type for this property comes from the ContactGroup class). @n  */
    00348         bool IsMemberOfHardwiredGroup(
    00349                 const ContactGroup::TYPE& groupType, /*!< The type designator of the target pre-defined contact group. For example, specify this parameter as ContactGroup::TYPE.RECENTLY_CONTACTED_CONTACTS to determine if you've had a recent conversation with this Contact. @n */
    00350                 bool& result /*!< @li true: the Contact is a member of the target contact group @li false: the Contact is not a member of the target contact group @n */
    00351         );
    00352
    00353         /** Blocks or unblocks any further incoming communication attempts from this contact. @n  */
    00354         bool SetBlocked(
    00355                 const bool& blocked, /*!< @li true: block this contact @li false: unblock this contact @n */
    00356                 const bool abuse = false /*!< Optional parameter to report abuse by this Skype user when blocking this Contact. Note that you can specifiy this parameter as true only when blocking a Contact. Defaults to false if omitted. @n */
    00357         );
    00358
    00359         /** Rejects and removes a pending authorization request from this Contact. @n  */
    00360         bool IgnoreAuthRequest(
    00361         );
    00362
    00363         /** sets CONTACT_GIVEN_DISPLAYNAME. clears if size(name)==0 */
    00364         bool GiveDisplayName(
    00365                 const Sid::String& name
    00366         );
    00367
    00368         /** Adds or removes this Contact from the ALL_BUDDIES hardwired group. @n  */
    00369         bool SetBuddyStatus(
    00370                 const bool& isMyBuddy, /*!< @li true: add this contact to the ALL_BUDDIES group @li false: delete contact from the ALL_BUDDIES group @n */
    00371                 const bool syncAuth = true /*!< This argument is deprecated and should not be used. @n */
    00372         );
    00373
    00374         enum EXTRA_AUTHREQ_FIELDS {
    00375                 SEND_VERIFIED_EMAIL = 1       /*!< send verified e-mail blob with this auth request*/,
    00376                 SEND_VERIFIED_COMPANY         /*!< send verified company blob with this auth request*/
    00377         };
    00378
    00379         /** Sends a contact authorization request to this user. @n  */
    00380         bool SendAuthRequest(
    00381                 const Sid::String& message, /*!< Text that typically introduces the requesting user and details the reason for the authorization request. This text will be set as Message::P_BODY_XML property of the notification Message the remote user will receive upon getting the authortization request. While this can be the empty string, it cannot be null. @n */
    00382                 const uint extras_bitmask = 0 /*!< Indicates additional information to include with this authorization request: @li 0 (zero): do not include any additional information @li SEND_VERIFIED_EMAIL: include the requestor's verified e-mail address @li SEND_VERIFIED_COMPANY: include verified information regarding the requestor's company @li SEND_VERIFIED_EMAIL + SEND_VERIFIED_COMPANY: include both e-mail and company information @n */
    00383         );
    00384
    00385         /** the contact has accepted my auth request */
    00386         bool HasAuthorizedMe(
    00387                 bool& result
    00388         );
    00389
    00390         /** Sets the three P_ASSIGNED_PHONEx and P_ASSIGNED_PHONEx_LABEL properties, where x reflects the value of num.  @n  @n The Skype Windows desktop client uses the following conventions when interpreting and assigning values to these properties. While your solution can assign arbitrary values to these properties, we strongly recommend using these conventions to ensure interoperability with the Skype Windows desktop client. Keep in mind that the "number" of these property pairs has no relationship to how the Skype Windows client interprets their label property value strings. For example, the Skype Windows client will interpret P_ASSIGNED_PHONE3_LABEL as "Home" if its value is the string "0".  @n  @n Label strings: @n  @n Populate the label properties with string representations of the numbers "0" through "3", rather than descriptive strings like "Home", "Mobile", and so forth. The Skype desktop clients interpret the numeric string values as: @li "0" (zero) - "Home" @li "1" (one) - "Office" @li "2" - "Mobile" @li "3" - "Other" @n  @n Keep in mind that the "number" of a property pair has no relationship to its label string. For example, the Skype Windows client will interpret P_ASSIGNED_PHONE3_LABEL as "Home" if its value is the string "0". @n  @n Phone number strings: @n  @n The Skype Windows desktop client has distinct conventions for Skype Contacts and PSTN (SkypeOut) Contacts: any or all of the property pairs can be used for Skype Contacts; P_ASSIGNED_PHONE1 cannot be used for PSTN Contacts and P_ASSIGNED_PHONE1_LABEL has special meaning for PSTN Contacts. @n Specifically, the Skype desktop clients use P_ASSIGNED_PHONE1_LABEL as the label for a PSTN Contact's primary number (regardless of whether it's home, mobile, or office), and use P_PSTNNUMBER to hold the actual number. @n  @n  */
    00391         bool SetPhoneNumber(
    00392                 const uint& num, /*!< The property pair being set, which must be in the range 0..3 @n */
    00393                 const Sid::String& label, /*!< The label text for the property being set @n */
    00394                 const Sid::String& number /*!< The phone number for the property being set @n */
    00395         );
    00396
    00397         /** Retrieves a dialog conversation with the Contact. @n  */
    00398         bool OpenConversation(
    00399                 ConversationRef& conversation /*!< Retrieved dialog. @n */
    00400         );
    00401
    00402         /** This enumerator is used by both Contact and Account objects. Thus the items here can have slightly different meaning, depending on which context you will examine their values. In case of Contact, the values apply to a user - across all the instances that user has logged in with Skype. In case of Account, the capability is that of a local, currently logged in instance of Skype client. @n  @n The values that CAPABILITY items can have are also dependant on class context. In context of Contact, a capability can be CAPABILITY_MIXED. Which in case of CAPABILITY_VIDEO, for example, would mean that the remote use has logged in with different clients, some of which support video calls and some of which don't. In context of Account - there are no mixed result. Currently logged in Skype instance either supports video or it doesn't. @n  */
    00403         enum CAPABILITY {
    00404                 CAPABILITY_VOICEMAIL = 0      /*!< For Account object, this is the same as CAPABILITY_CAN_BE_SENT_VM - it indicates that the currently logged in Skype instance supports voicemails. For Contact objects, it means that their remote system supports sending voicemails - there is no technical method for Skype to detect whether they are capable of receiving voicemails, so the assumption is that they can. @n */,
    00405                 CAPABILITY_SKYPEOUT           /*!< Indicates that the contact/account has SkypeOut and is thus capable of making PSTN calls. @n */,
    00406                 CAPABILITY_SKYPEIN            /*!< Indicates that the contact/account has SkypeIn and is thus capable of answering PSTN calls. @n */,
    00407                 CAPABILITY_CAN_BE_SENT_VM     /*!< For contacts, this is a combination of CAPABILITY_VOICEMAIL for local account (local Skype client supports sending voicemails) and CAPABILITY_VOICEMAIL of the Contact - if the contact supports sending voicemails then hopefully they can also receive them. @n */,
    00408                 CAPABILITY_CALL_FORWARD       /*!< Indicates that Account/Contact supports call forwarding. @n */,
    00409                 CAPABILITY_VIDEO              /*!< Indicates that Account/Contact supports call video calls. @n */,
    00410                 CAPABILITY_TEXT               /*!< In context of Contact, this indicates that the user is noticed running at least one Skype implementation that supports text messaging. Basically, it applies to a user. When applied to Account, the meaning is slightly different. In that case it indicates that currently running Skype implementation supports chat messaging. So, for Account objects, this is a node (rather than user) capability. @n */,
    00411                 CAPABILITY_SERVICE_PROVIDER   /*!< Indicates that the contact/account is flagged as SkypePrime service provider. This is linked to Account class SERVICE_PROVIDER_INFO property. @n */,
    00412                 CAPABILITY_LARGE_CONFERENCE   /*!< This is a legacy item, from the old times when conference calls with more than 5 people were limited to SkypePro accounts. In other words, this item is no longer relevant and will likely be removed at some point in future. @n */,
    00413                 CAPABILITY_COMMERCIAL_CONTACT,
    00414                 CAPABILITY_PSTN_TRANSFER      /*!< Indicates that Account/Contact supports call transfers to PSTN numbers. @n */,
    00415                 CAPABILITY_TEXT_EVER          /*!< Indicates that the user has had his chat capability removed by Skype. Basically, this means that the user is reported as spammer too many times. This applies for both Contact and Account objects - which means your client can check locally, if the currently logged in user has been marked as a spammer. @n */,
    00416                 CAPABILITY_VOICE_EVER         /*!< Indicates that the user (Account or Contact) has had his voice call capability removed by Skype. @n */,
    00417                 CAPABILITY_MOBILE_DEVICE      /*!< Indicates that the instance of Skype client Account/Contact is or in Contact's case has at least occasionally been flagged as a mobile device. @n */,
    00418                 CAPABILITY_PUBLIC_CONTACT
    00419         };
    00420
    00421         /** List of possible states of each of the Contact class CAPABILITY items. @n  */
    00422         enum CAPABILITYSTATUS {
    00423                 NO_CAPABILITY = 0             /*!< Contact does not have the capability @n */,
    00424                 CAPABILITY_MIXED              /*!< Contact has occasionally logged in with Skype client that supports the capability. For example, a contact may have Skype client on several machines, only some of which have webcam - in which case CAPABILITY_VIDEO would have its value set as CAPABILITY_MIXED. @n */,
    00425                 CAPABILITY_EXISTS             /*!< Contact has the capability @n */
    00426         };
    00427
    00428         /** Retrieves a Contact::Capability value. Sets P_REFRESHING to true while querying from server. This method is functionally the same as Contact::GetCapabilityStatus except that it returns a bool value rather than Contact::CAPABILITYSTATUS @n  */
    00429         bool HasCapability(
    00430                 const CAPABILITY& capability, /*!< The target capability @n */
    00431                 bool& result, /*!< @li true: the Contact has the target capability through at least one of the Skype clients they have logged into. Corresponds to CAPABILITY_MIXED and CAPABILITY_EXISTS @li false: the Contact does not have the target capability. Corresponds to NO_CAPABILITY @n */
    00432                 const bool queryServer = false /*!< @li true: obtains the data from the p2p network/server, and sets P_REFRESHING to true for the duration  @li false: obtains the data from the local client @n */
    00433         );
    00434
    00435         /** Retrieves a Contact::Capability value. Sets P_REFRESHING to true while querying from server. @n  */
    00436         bool GetCapabilityStatus(
    00437                 const CAPABILITY& capability, /*!< The target capability, see Contact::Capability enumerator. @n */
    00438                 CAPABILITYSTATUS& status, /*!< Status of the target capability. @n */
    00439                 const bool queryServer = false /*!< @li true: obtains the data from the p2p network/server, and sets P_REFRESHING to true for the duration  @li false: obtains the data from the local client @n */
    00440         );
    00441
    00442         /** Refreshes all properties, capabilities, and statuses associated with this Contact from p2p/CBL, and sets P_REFRESHING to true for the duration. @n  */
    00443         bool RefreshProfile(
    00444         );
    00445
    00446         /** Contact::P_TYPE property get accessor */
    00447         bool GetPropType(Contact::TYPE& type);
    00448
    00449         /** Contact::P_SKYPENAME property get accessor */
    00450         bool GetPropSkypename(Sid::String& skypename);
    00451
    00452         /** Contact::P_PSTNNUMBER property get accessor */
    00453         bool GetPropPstnnumber(Sid::String& pstnnumber);
    00454
    00455         /** Contact::P_FULLNAME property get accessor */
    00456         bool GetPropFullname(Sid::String& fullname);
    00457
    00458         /** Contact::P_BIRTHDAY property get accessor */
    00459         bool GetPropBirthday(uint& birthday);
    00460
    00461         /** Contact::P_GENDER property get accessor */
    00462         bool GetPropGender(uint& gender);
    00463
    00464         /** Contact::P_LANGUAGES property get accessor */
    00465         bool GetPropLanguages(Sid::String& languages);
    00466
    00467         /** Contact::P_COUNTRY property get accessor */
    00468         bool GetPropCountry(Sid::String& country);
    00469
    00470         /** Contact::P_PROVINCE property get accessor */
    00471         bool GetPropProvince(Sid::String& province);
    00472
    00473         /** Contact::P_CITY property get accessor */
    00474         bool GetPropCity(Sid::String& city);
    00475
    00476         /** Contact::P_PHONE_HOME property get accessor */
    00477         bool GetPropPhoneHome(Sid::String& phone_home);
    00478
    00479         /** Contact::P_PHONE_OFFICE property get accessor */
    00480         bool GetPropPhoneOffice(Sid::String& phone_office);
    00481
    00482         /** Contact::P_PHONE_MOBILE property get accessor */
    00483         bool GetPropPhoneMobile(Sid::String& phone_mobile);
    00484
    00485         /** Contact::P_EMAILS property get accessor */
    00486         bool GetPropEmails(Sid::String& emails);
    00487
    00488         /** Contact::P_HOMEPAGE property get accessor */
    00489         bool GetPropHomepage(Sid::String& homepage);
    00490
    00491         /** Contact::P_ABOUT property get accessor */
    00492         bool GetPropAbout(Sid::String& about);
    00493
    00494         /** Contact::P_AVATAR_IMAGE property get accessor */
    00495         bool GetPropAvatarImage(Sid::Binary& avatar_image);
    00496
    00497         /** Contact::P_MOOD_TEXT property get accessor */
    00498         bool GetPropMoodText(Sid::String& mood_text);
    00499
    00500         /** Contact::P_RICH_MOOD_TEXT property get accessor */
    00501         bool GetPropRichMoodText(Sid::String& rich_mood_text);
    00502
    00503         /** Contact::P_TIMEZONE property get accessor */
    00504         bool GetPropTimezone(uint& timezone);
    00505
    00506         /** Contact::P_CAPABILITIES property get accessor */
    00507         bool GetPropCapabilities(Sid::Binary& capabilities);
    00508
    00509         /** Contact::P_PROFILE_TIMESTAMP property get accessor */
    00510         bool GetPropProfileTimestamp(uint& profile_timestamp);
    00511
    00512         /** Contact::P_NROF_AUTHED_BUDDIES property get accessor */
    00513         bool GetPropNrofAuthedBuddies(uint& nrof_authed_buddies);
    00514
    00515         /** Contact::P_IPCOUNTRY property get accessor */
    00516         bool GetPropIpcountry(Sid::String& ipcountry);
    00517
    00518         /** Contact::P_AVATAR_TIMESTAMP property get accessor */
    00519         bool GetPropAvatarTimestamp(uint& avatar_timestamp);
    00520
    00521         /** Contact::P_MOOD_TIMESTAMP property get accessor */
    00522         bool GetPropMoodTimestamp(uint& mood_timestamp);
    00523
    00524         /** Contact::P_RECEIVED_AUTHREQUEST property get accessor */
    00525         bool GetPropReceivedAuthrequest(Sid::String& received_authrequest);
    00526
    00527         /** Contact::P_AUTHREQ_TIMESTAMP property get accessor */
    00528         bool GetPropAuthreqTimestamp(uint& authreq_timestamp);
    00529
    00530         /** Contact::P_LASTONLINE_TIMESTAMP property get accessor */
    00531         bool GetPropLastonlineTimestamp(uint& lastonline_timestamp);
    00532
    00533         /** Contact::P_AVAILABILITY property get accessor */
    00534         bool GetPropAvailability(AVAILABILITY& availability);
    00535
    00536         /** Contact::P_DISPLAYNAME property get accessor */
    00537         bool GetPropDisplayname(Sid::String& displayname);
    00538
    00539         /** Contact::P_REFRESHING property get accessor */
    00540         bool GetPropRefreshing(bool& refreshing);
    00541
    00542         /** Contact::P_GIVEN_AUTHLEVEL property get accessor */
    00543         bool GetPropGivenAuthlevel(AUTHLEVEL& given_authlevel);
    00544
    00545         /** Contact::P_GIVEN_DISPLAYNAME property get accessor */
    00546         bool GetPropGivenDisplayname(Sid::String& given_displayname);
    00547
    00548         /** Contact::P_ASSIGNED_COMMENT property get accessor */
    00549         bool GetPropAssignedComment(Sid::String& assigned_comment);
    00550
    00551         /** Contact::P_LASTUSED_TIMESTAMP property get accessor */
    00552         bool GetPropLastusedTimestamp(uint& lastused_timestamp);
    00553
    00554         /** Contact::P_AUTHREQUEST_COUNT property get accessor */
    00555         bool GetPropAuthrequestCount(uint& authrequest_count);
    00556
    00557         /** Contact::P_ASSIGNED_PHONE1 property get accessor */
    00558         bool GetPropAssignedPhone1(Sid::String& assigned_phone1);
    00559
    00560         /** Contact::P_ASSIGNED_PHONE1_LABEL property get accessor */
    00561         bool GetPropAssignedPhone1Label(Sid::String& assigned_phone1_label);
    00562
    00563         /** Contact::P_ASSIGNED_PHONE2 property get accessor */
    00564         bool GetPropAssignedPhone2(Sid::String& assigned_phone2);
    00565
    00566         /** Contact::P_ASSIGNED_PHONE2_LABEL property get accessor */
    00567         bool GetPropAssignedPhone2Label(Sid::String& assigned_phone2_label);
    00568
    00569         /** Contact::P_ASSIGNED_PHONE3 property get accessor */
    00570         bool GetPropAssignedPhone3(Sid::String& assigned_phone3);
    00571
    00572         /** Contact::P_ASSIGNED_PHONE3_LABEL property get accessor */
    00573         bool GetPropAssignedPhone3Label(Sid::String& assigned_phone3_label);
    00574
    00575         /** Contact::P_POPULARITY_ORD property get accessor */
    00576         bool GetPropPopularityOrd(uint& popularity_ord);
    00577
    00578 };
    00579
    00580
    00581 /*! \class ContactSearch skype-embedded_2.h "skype-embedded_2.h"
    00582  *  \brief
    00583  *  \nosubgrouping
    00584  *  This class encapsulates functionality for looking up contacts on the Skype network. Contacts can be searched by
    00585  *  portion of their name, e-mail address, language preferences, etc. @brief @n  @n Contact search is asynchronous.
    00586  *  ContactSearch::Submit is a non-blocking function that initiates the search. Upon finding a matching contact,
    00587  *  ContactSearch::OnNewResult event gets fired, that gives you the reference to the discovered contact. You can get up
    00588  *  to 100 matching contacts per search. Note that you will need to keep a live reference of the ContactSearch object
    00589  *  while the search is doing its work.  @n  @n So, to perform a contact search:  @li create a contact search object @li
    00590  *  specify search terms and conditions @li submit search @li in ContactSearch::OnNewResult callback, update your UI @li
    00591  *  in ContactSearch::OnChange, check for terminal values of P_CONTACT_SEARCH_STATUS and update the UI accordingly. @n
    00592  *  @n When the search has done its job, the ContactSearch::P_CONTACT_SEARCH_STATUS property will go to one of the
    00593  *  terminal values. @n  @n The terminal values are: @li FINISHED - the search has stopped. Note that this does not mean
    00594  *  any matches were actually found. @li FAILED - the search has failed. @li EXTENDABLE - this state should be
    00595  *  considered the same as FINISHED. The feature of extending long search results is about to be deprecated. It is still
    00596  *  possible for search objects to occasionally reach that state, so it should be handled in the UI (as FINISHED), but
    00597  *  the extending feature itself should not be implemented in your UI. @n  @n There are three methods to create the
    00598  *  ContactSearch objects. @n  @n A) Skype::CreateIdentitySearch @n  @n This method takes a string argument and looks
    00599  *  for exact matches against Contact::P_SKYPENAME property. So for example, identity search for "echo" will return 0
    00600  *  results and search for "echo123" will return exactly one.  @n  @n Identity in this case means skypename - contact
    00601  *  search does not work with PSTN type contacts. However, it does work for SKYPE type contacts that have supplied
    00602  *  P_PHONE_HOME, P_PHONE_OFFICE or P_PHONE_MOBILE values in their account data. To search for those, you will need to
    00603  *  use complex search (see below). @n  @n Note that you should always check for boolean return value of the
    00604  *  CreateIdentitySearch method. If the user submits a string that is not a valid skypename, the method will return
    00605  *  false and the ContactSearchRef argument will return as NULL. @n  @n B) Skype::CreateBasicContactSearch @n  @n This
    00606  *  method takes a string argument and looks for non-exact matches against both P_SKYPENAME and P_FULLNAME properties of
    00607  *  the contact. If you intend to implement a simple, one-input search feature - this is the best method for you. The
    00608  *  non-exact matching operates similarly to the SQL LIKE condition. @n  @n C) Skype::CreateContactSearch @n  @n This
    00609  *  method enables you to implement advanced contact search, matching against multiple seach criteria. It takes no input
    00610  *  arguments and expects search criteria to be added to the already constructed search object. @n  @n Criteria can be
    00611  *  added with ContactSearch::AddStrTerm and ContactSearch::AddIntTerm methods. @n  @n These methods take Contact class
    00612  *  porperty ID, condition, and the match pattern as inputs. @n  @n Only the following Contact properties can be used
    00613  *  for search: @li P_SKYPENAME  @li P_FULLNAME @li P_BIRTHDAY (uint) @li P_GENDER (uint: 1-male, 2-female) @li
    00614  *  P_LANGUAGES @li P_COUNTRY @li P_PROVINCE @li P_CITY @li P_PHONE_HOME @li P_PHONE_OFFICE @li P_PHONE_MOBILE @li
    00615  *  P_EMAILS @li P_HOMEPAGE @li P_ABOUT @n  @n String searches are case insensitive, i.e. search for echo123 also
    00616  *  matches ECHO123 @n  @n When adding multiple criteria, default behaviour is that the criterions are additive. I.e. a
    00617  *  term skypename == "joe" followed by term country == "us" will result in intersection between all joes and everybody
    00618  *  in US. @n  @n You can explicitly add an "OR" instead of "AND" between conditions, using the AddOr method. @n  @n By
    00619  *  default, AND criteria are grouped together, before OR's, so that: @n  @n AddTerm(condition1) @n AddTerm(condition2)
    00620  *  @n AddOr() @n AddTerm(condition3) @n AddTerm(condition4) @n  @n will result in the following logical statement: @n
    00621  *  (condition1 AND condition2) OR (condition3 AND condition4) @n  @n However, you can add "global" critera, by using
    00622  *  the add_to_subs argument of the AddXX methods. @n  @n AddTerm(condition1) @n AddTerm(condition2) @n AddOr() @n
    00623  *  AddTerm(condition3) @n AddTerm(condition4, add_to_subs=true) @n  @n which would result in: @n (condition1 AND
    00624  *  condition2 AND condition4) OR (condition3 AND condition4) @n  @n  @n Every one of the contact properties can only be
    00625  *  used once, per search. For example, you cannot create a search for two different P_FULLNAME patterns. The &valid
    00626  *  argument will still return tue if you do this, but the last criteria for any given property will override all
    00627  *  previous ones. So, a search like this: @n  @n cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "John Smith",
    00628  *  isValid); @n cs->AddOr(); @n cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "Ivan Sidorov", isValid); @n  @n
    00629  *  will only return matches for "Ivan Sidorov" and none for "John Smith". @n  @n Some of the contact properties are
    00630  *  automatically combined for purposes of search. @n  @n A search for P_SKYPENAME also returns matches from the
    00631  *  P_FULLNAME property and vice versa. @n  @n So that this: @n cs->AddStrTerm(Contact::P_SKYPENAME, ContactSearch::EQ,
    00632  *  "john.smith", isValid); @n  @n ..and this: @n cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "John Smith",
    00633  *  isValid); @n  @n ..and this: @n cs->AddStrTerm(Contact::P_SKYPENAME, ContactSearch::EQ, "john.smith", isValid); @n
    00634  *  cs->AddOr(); @n cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "John Smith", isValid); @n  @n ..all search
    00635  *  from both the P_FULLNAME and P_SKYPENAME fields. @n  @n  @n Before using ContactGroup::Submit to start the search,
    00636  *  you should always check whether the search criteria ended up being valid. This you can do with
    00637  *  ContactSearch::IsValid method. @n  @n As you probably noticed, each of the AddXX methods also return a validity
    00638  *  check boolean. However, it is a better practice to do the overall check as well, even if all the individual search
    00639  *  criteria ended up looking Ok. @n  @n For example, lets take a search for contact's e-mail. This can be done with two
    00640  *  different methods. Firstly we can use the ContactSearch::AddEmailTerm method. This method will actually validate
    00641  *  whether the input is a valid e-mail address: @n  @n cs->AddEmailTerm ("test@test@test", isValid);  @n will return
    00642  *  the isValid argument as false. @n  @n However, you can also add the e-mail search criterion as a simple string, like
    00643  *  this: @n  @n cs->AddStrTerm(Contact::P_EMAILS, ContactSearch::EQ, "test@test@test@", isValid); @n in which case the
    00644  *  isValid will return true. @n  @n However, if you then check entire search object with:  @n  @n cs->IsValid(isValid);
    00645  *  @n  @n the isValid will correctly return false. @n
    00646  */
    00647 class ContactSearch : public SEObject
    00648 {
    00649         /** \cond INTERNAL */
    00650         friend class Skype;
    00651 protected:
    00652         ContactSearch(unsigned int oid, SERootObject* root);
    00653         /** \endcond */
    00654 public:
    00655         virtual ~ContactSearch();
    00656         typedef ContactSearchRef Ref;
    00657         typedef ContactSearchRefs Refs;
    00658         enum { MODULE_ID = 1 };
    00659         ContactSearchRef ref() {
    00660                 return ContactSearchRef(object_id);
    00661         }
    00662
    00663 private:
    00664         String getNamespace() const;
    00665         const PMAP* getPMap() const;
    00666         const EMAP* getEMap() const;
    00667         unsigned int moduleID() const;
    00668         void __clear_cache(void*);
    00669
    00670 public:
    00671         /** Properties of the ContactSearch class */
    00672         enum PROPERTY {
    00673                 P_CONTACT_SEARCH_STATUS = 200   /*!< type: STATUS*/
    00674         };
    00675
    00676         /** Possible values for the ContactSearch.P_STATUS property. @n  */
    00677         enum STATUS {
    00678                 CONSTRUCTION = 1              /*!< Transient state, obtained after submission and actually initiating the search on the network. @n */,
    00679                 PENDING                       /*!< Waiting for results to show up. This is a transient state. @n */,
    00680                 EXTENDABLE                    /*!< Enough matches are found. No more OnNewResult events will fire. The feature of extending long search results is about to be deprecated. It is still possible for search objects to occasionally reach that state, so it should be handled in the UI (as FINISHED), but the extending feature itself should not be implemented in your UI.  @n */,
    00681                 FINISHED                      /*!< The search is finished. No more matches are expected. This is a terminal state. @n */,
    00682                 FAILED                        /*!< ContactSearch failed. Better check if the search terms made any sense, with ContactSearch::IsValid. This is a terminal state. @n */
    00683         };
    00684
    00685         /** construct CONTACT_BIRTHDAY term based on current time */
    00686         bool AddMinAgeTerm(
    00687                 const uint& min_age_in_years,
    00688                 bool& valid,
    00689                 const bool add_to_subs = false
    00690         );
    00691
    00692         /** construct CONTACT_BIRTHDAY term based on current time */
    00693         bool AddMaxAgeTerm(
    00694                 const uint& max_age_in_years,
    00695                 bool& valid,
    00696                 const bool add_to_subs = false
    00697         );
    00698
    00699         /** Adds a search term against Contact::P_EMAILS property and pre-validates the value given in the email argument. @n  */
    00700         bool AddEmailTerm(
    00701                 const Sid::String& email, /*!< e-mail addres to search for. @n */
    00702                 bool& valid, /*!< Returns false if the value in email property did not look like a valid email address. @n */
    00703                 const bool add_to_subs = false /*!< This argument enables you to group conditions. See ContactSearch class details for more information. @n */
    00704         );
    00705
    00706         bool AddLanguageTerm(
    00707                 const Sid::String& language,
    00708                 bool& valid,
    00709                 const bool add_to_subs = false
    00710         );
    00711
    00712         /** List of available  matching conditions that can be used in AddTerm methods. @n  */
    00713         enum CONDITION {
    00714                 EQ = 0                        /*!< Equals @n */,
    00715                 GT                            /*!< Is greater than @n */,
    00716                 GE                            /*!< Is greater or equal. @n */,
    00717                 LT                            /*!< Is less than @n */,
    00718                 LE                            /*!< Less or equal @n */,
    00719                 PREFIX_EQ                     /*!< Start of a word macthes exactly (string properties only). @n */,
    00720                 PREFIX_GE                     /*!< Start of a word is greater or equal (string properties only). @n */,
    00721                 PREFIX_LE                     /*!< Start of a word is less or equal (string properties only). @n */,
    00722                 CONTAINS_WORDS                /*!< Contains the word (string properties only). @n */,
    00723                 CONTAINS_WORD_PREFIXES        /*!< One of the words starts with searched value (string properties only). @n */
    00724         };
    00725
    00726         /** Adds a string search term to a custom contact search object.  @n  */
    00727         bool AddStrTerm(
    00728                 const int& prop, /*!< Following Contact class string propkeys can be used for Contact search: @li Contact::P_SKYPENAME @li Contact::P_FULLNAME @li Contact::P_LANGUAGES @li Contact::P_COUNTRY @li Contact::P_PROVINCE @li Contact::P_CITY @li Contact::P_PHONE_HOME @li Contact::P_PHONE_OFFICE @li Contact::P_PHONE_MOBILE @li Contact::P_EMAILS @li Contact::P_HOMEPAGE @li Contact::P_ABOUT @n Note that while Contact::P_EMAILS is technically a string and can be used in this method, it is recommended that you use ContactSearch.AddEmailTerm method instead. @n */
    00729                 const CONDITION& cond, /*!< Search condition (ContactSearch::CONDITION) @n */
    00730                 const Sid::String& value, /*!< Value to match against. @n */
    00731                 bool& valid, /*!< Returns true if the ContactSearch term-set remains valid after adding this term. @n */
    00732                 const bool add_to_subs = false /*!< This argument enables you to group conditions. See ContactSearch class details for more information. @n */
    00733         );
    00734
    00735         /** Adds a search term to a custom contact search object. For now, there are only two searchable Contact properties that are integers, so this can oly be used for Contact::P_BIRTHDAY and Contact::P_GENDER. @n  */
    00736         bool AddIntTerm(
    00737                 const int& prop, /*!< Propkey to search for. Either Contact::P_BIRTHDAY or Contact::P_GENDER @n */
    00738                 const CONDITION& cond, /*!< Search condition (ContactSearch::CONDITION) @n */
    00739                 const uint& value, /*!< Value to match against. @n */
    00740                 bool& valid, /*!< Returns true if the ContactSearch term-set remains valid after adding this term. @n */
    00741                 const bool add_to_subs = false /*!< This argument enables you to group conditions. See ContactSearch class details for more information. @n */
    00742         );
    00743
    00744         /** used to group terms (AddTerm(1), AddTerm(2), Or(), AddTerm(3), AddTerm(4), etc) */
    00745         bool AddOr(
    00746         );
    00747
    00748         /** checks that terms list is non-empty and does not contain unsupported keys */
    00749         bool IsValid(
    00750                 bool& result
    00751         );
    00752
    00753         /** launch search */
    00754         bool Submit(
    00755         );
    00756
    00757         /** extend if search is EXTENDABLE */
    00758         bool Extend(
    00759         );
    00760
    00761         /** releases results that are not referenced from elsewhere */
    00762         bool Release(
    00763         );
    00764
    00765         /** result list is dynamically updated */
    00766         bool GetResults(
    00767                 ContactRefs& contacts,
    00768                 const uint from = 0,
    00769                 const uint count = MAX_UINT
    00770         );
    00771
    00772         /** This callback is fired when a new matching contact has been found during the search. @n  */
    00773         virtual void OnNewResult(
    00774                 const ContactRef& contact,
    00775                 const uint& rankValue
    00776         );
    00777
    00778         /** ContactSearch::P_CONTACT_SEARCH_STATUS property get accessor */
    00779         bool GetPropContactSearchStatus(STATUS& contact_search_status);
    00780
    00781 };
    00782
    00783 /** sync failure reasons when starting a transfer */
    00784 enum TRANSFER_SENDFILE_ERROR {
    00785         TRANSFER_OPEN_SUCCESS = 0,
    00786         TRANSFER_BAD_FILENAME,
    00787         TRANSFER_OPEN_FAILED,
    00788         TRANSFER_TOO_MANY_PARALLEL
    00789 };
    00790
    00791 enum LEAVE_REASON {
    00792         LEAVE_REASON_NONE = 0,
    00793         RETIRED_USER_INCAPABLE = 2    /*!< automatic, user cannot chat (only some older versions might set this)*/,
    00794         RETIRED_ADDER_MUST_BE_FRIEND  /*!< automatic*/,
    00795         RETIRED_ADDER_MUST_BE_AUTHORIZED/*!< automatic*/,
    00796         RETIRED_DECLINE_ADD           /*!< manual reason (afaik no UI uses this)*/,
    00797         RETIRED_UNSUBSCRIBE           /*!< manual reason*/,
    00798         LIVE_NO_ANSWER = 100,
    00799         LIVE_MANUAL                   /*!< live: User hung up*/,
    00800         LIVE_BUSY,
    00801         LIVE_CONNECTION_DROPPED,
    00802         LIVE_NO_SKYPEOUT_SUBSCRIPTION,
    00803         LIVE_INSUFFICIENT_FUNDS,
    00804         LIVE_INTERNET_CONNECTION_LOST,
    00805         LIVE_SKYPEOUT_ACCOUNT_BLOCKED,
    00806         LIVE_PSTN_COULD_NOT_CONNECT_TO_SKYPE_PROXY,
    00807         LIVE_PSTN_INVALID_NUMBER,
    00808         LIVE_PSTN_NUMBER_FORBIDDEN,
    00809         LIVE_PSTN_CALL_TIMED_OUT,
    00810         LIVE_PSTN_BUSY,
    00811         LIVE_PSTN_CALL_TERMINATED,
    00812         LIVE_PSTN_NETWORK_ERROR,
    00813         LIVE_NUMBER_UNAVAILABLE,
    00814         LIVE_PSTN_CALL_REJECTED,
    00815         LIVE_PSTN_MISC_ERROR,
    00816         LIVE_INTERNAL_ERROR,
    00817         LIVE_UNABLE_TO_CONNECT,
    00818         LIVE_RECORDING_FAILED         /*!< live: Voicemail recording failed*/,
    00819         LIVE_PLAYBACK_ERROR           /*!< live: Voicemail playback failed*/,
    00820         LIVE_LEGACY_ERROR,
    00821         LIVE_BLOCKED_BY_PRIVACY_SETTINGS,
    00822         LIVE_ERROR                    /*!< live: Fallback error*/,
    00823         LIVE_TRANSFER_FAILED,
    00824         LIVE_TRANSFER_INSUFFICIENT_FUNDS,
    00825         LIVE_BLOCKED_BY_US,
    00826         LIVE_EMERGENCY_CALL_DENIED
    00827 };
    00828
    00829
    00830 /*! \class Participant skype-embedded_2.h "skype-embedded_2.h"
    00831  *  \brief
    00832  *  \nosubgrouping
    00833  *  Conversation participant class. Instances of this class represent contacts when in the context of conversations.
    00834  *  Amongst others, this class has a Ring method for requesting live status with the target contact. This class also
    00835  *  holds typing indicator property and access rights for the contact in context of public conversations. @n
    00836  */
    00837 class Participant : public SEObject
    00838 {
    00839         /** \cond INTERNAL */
    00840         friend class Skype;
    00841 protected:
    00842         Participant(unsigned int oid, SERootObject* root);
    00843         /** \endcond */
    00844 public:
    00845         virtual ~Participant();
    00846         typedef ParticipantRef Ref;
    00847         typedef ParticipantRefs Refs;
    00848         enum { MODULE_ID = 19 };
    00849         ParticipantRef ref() {
    00850                 return ParticipantRef(object_id);
    00851         }
    00852
    00853 private:
    00854         String getNamespace() const;
    00855         const PMAP* getPMap() const;
    00856         const EMAP* getEMap() const;
    00857         unsigned int moduleID() const;
    00858         void __clear_cache(void*);
    00859
    00860 public:
    00861         /** Properties of the Participant class */
    00862         enum PROPERTY {
    00863                 P_CONVO_ID = 930                /*!< [ALL] ID of corresponding conversation. Here and below, [ALL] tag indicates that the property has meaning and is set in context of all participants in the conversation. [OTHERS] tag has meaning only for participants who are not the local user. @n , type: ConversationRef*/,
    00864                 P_IDENTITY                      /*!< [ALL] skypename OR pstn_number OR namespace:identity, type: Sid::String*/,
    00865                 P_RANK                          /*!< [ALL] Participant::RANK, type: RANK*/,
    00866                 P_REQUESTED_RANK                /*!< Not set (should be: requested Participant::RANK, higher than the current one), type: RANK*/,
    00867                 P_TEXT_STATUS                   /*!< [ALL] the typing indicator, type: TEXT_STATUS*/,
    00868                 P_VOICE_STATUS                  /*!< [ALL] voice status, type: VOICE_STATUS*/,
    00869                 P_VIDEO_STATUS                  /*!< [ALL] video status, type: VIDEO_STATUS*/,
    00870                 P_LIVE_IDENTITY = 943           /*!< [ALL] identity that was used to establish current live session with that participant (can be different from participant identity), type: Sid::String*/,
    00871                 P_LIVE_PRICE_FOR_ME = 938       /*!< [OTHERS] 'price_per_minute_float currency' - eg '0.01 EUR'. Note that this property obtains value only after the participant goes into live state. It cannot be used to display call rates before the call starts. @n , type: Sid::String*/,
    00872                 P_LIVE_FWD_IDENTITIES = 948     /*!< [OTHERS] list of identities where the live session is being forwarded (if they are disclosed), space separated, type: Sid::String*/,
    00873                 P_LIVE_START_TIMESTAMP = 939    /*!< [ALL] time of joining the live session, type: uint*/,
    00874                 P_SOUND_LEVEL = 941             /*!< [ALL] current 'loudness' level when SPEAKING (0..10), type: uint*/,
    00875                 P_DEBUGINFO                     /*!< [OTHERS] call (audio and video) debug info, type: Sid::String*/,
    00876                 P_LAST_VOICE_ERROR = 947        /*!< [OTHERS] DEPRECATED, use last_leavereason instead, type: Sid::String*/,
    00877                 P_QUALITY_PROBLEMS = 949        /*!< [ALL] space separated tokens values: CPU_INUSE CPU_SLOW CPU_HIGH HIGH_ECHO HIGH_NOISE MUTED_INPUT LOW_INPUT MUTED_INPUT_ACTIVITY FW_STRONG FW_BAD NOT_UDP CALL_BW_LOW RECORD_ERROR + values in video debug info, type: Sid::String*/,
    00878                 P_LIVE_TYPE                     /*!< [ALL] participant type during livesession as specified in IDENTITYTYPE, type: contact::IDENTITYTYPE*/,
    00879                 P_LIVE_COUNTRY                  /*!< [OTHERS] participant livesession country code - used for emergency calls only atm, type: Sid::String*/,
    00880                 P_TRANSFERRED_BY                /*!< [OTHERS] Transferor identity (transferee side) @n , type: Sid::String*/,
    00881                 P_TRANSFERRED_TO                /*!< [OTHERS] Identity of recipient of transfer (transferor side, caller side) @n , type: Sid::String*/,
    00882                 P_ADDER                         /*!< [ALL] Identity of the user who added this participant to the conversation, type: Sid::String  @n , type: Sid::String*/,
    00883                 P_LAST_LEAVEREASON              /*!< [OTHERS] last reason for leaving conversation or live session.                   provides an enum alternative to last_voice_error as well                   as the reason this participant RETIRED, if so, type: LEAVE_REASON*/
    00884         };
    00885
    00886         /** Recognized values for the P_RANK property. The P_RANK controls participant's privileges in the conversation. See Participant::CanSetRankTo and Participant::SetRankTo methods. @n  */
    00887         enum RANK {
    00888                 CREATOR = 1                   /*!< Creator of the chat. There can be only one participant with this type per conversation. Other participants cannot be promoted to Creator rank. @n */,
    00889                 ADMIN                         /*!< Participant who has administrator privileges @n */,
    00890                 SPEAKER                       /*!< Participant who can speak and write @n */,
    00891                 WRITER                        /*!< Participant who can write but not speak @n */,
    00892                 SPECTATOR                     /*!< Participant who can read but not write/speak @n */,
    00893                 APPLICANT                     /*!< Participant who is applying to join the conversation. Member cannot be demoted to applicants once they have been accepted.  @n */,
    00894                 RETIRED                       /*!< Participant who has eft or has been kicked from the conversation @n */,
    00895                 OUTLAW                        /*!< Participant who has been banned from the chat @n */
    00896         };
    00897
    00898         /** Recognized values for the P_TEXT_STATUS property. The P_TEXT_STATUS property has two uses. Firstly, you can use it to implement typing indicators in your UI, to notify the local user that an incoming chat message from this Participant is imminent.  @n  @n To set the P_TEXT_STATUS value, so that remote client UIs can display the local user's typing indicator in their UI, use Conversation::SetMyTextStatusTo method. @n  @n Transmission of P_TEXT_STATUS updates to remote participants of conversations is controlled via SETUPKEY_DISABLE_CHAT_ACTIVITY_INDICATION setup key. @n  @n Secondly, the TEXT_NA value enables you to detect participants who are running clients with no chat capability. @n  */
    00899         enum TEXT_STATUS {
    00900                 TEXT_UNKNOWN = 0              /*!< Fallback state in case the text status is not (yet) deternmined. @n */,
    00901                 TEXT_NA                       /*!< Text status is not applicable as the participant is using a Skype client that does not support chat (for example: voice-only USB phones). @n */,
    00902                 READING                       /*!< Participant is currently not typing. @n */,
    00903                 WRITING                       /*!< Participant is currently typing. @n */,
    00904                 WRITING_AS_ANGRY              /*!< This state should be set when following two conditions are true: @li interval between keypresses are less than 20 ms; @li at least one of the keys adjacent to current key are pressed down. @n */,
    00905                 WRITING_AS_CAT                /*!< The "Cat on keyboard detection" algorthm in Skype is implemented in the UI level, and as such is not present in the SkypeKit API. Should you wish to implement similar algorthm in your own UI, you can get the basic logic from the PawSense FAQ - http://www.bitboost.com/pawsense/pawsense-faq.html @n */
    00906         };
    00907
    00908         /** Recognized values for the P_VOICE_STATUS property.  @n  */
    00909         enum VOICE_STATUS {
    00910                 VOICE_UNKNOWN = 0             /*!< Participant voice status is not (yet) determined. @n */,
    00911                 VOICE_NA                      /*!< Participant is using a Skype client with no audio capability. @n */,
    00912                 VOICE_AVAILABLE               /*!< Participant is using a Skype client that supports audio. @n */,
    00913                 VOICE_CONNECTING              /*!< Participant is in process of joining current live session. This is a transitional state. @n */,
    00914                 RINGING                       /*!< Participant has been invited to join the live session but has not yet accepted. @n */,
    00915                 EARLY_MEDIA                   /*!< Participant is in process of joining current live session. This is another transitional state. @n */,
    00916                 LISTENING                     /*!< Participant has joined the current live session but is currently not transmitting audio. @n */,
    00917                 SPEAKING                      /*!< Participant has joined the current live session and is transmitting audio. The UI can either use this state to display appropriate "speaking" notification, or alternatively use Participant::P_SOUND_LEVEL if you want your speaking indicator to also reflect audio volume coming from the Participant. @n */,
    00918                 VOICE_ON_HOLD                 /*!< Participant has joined the current live session but the audio is currently on hold. @n */,
    00919                 VOICE_STOPPED                 /*!< Participant will be placed in this state for some seconds after live session has finished. This is another transitional state. @n */
    00920         };
    00921
    00922         /** Recognized values for the P_VIDEO_STATUS property. This property applies to Participant's video send capability, not capability to receive video. @n  */
    00923         enum VIDEO_STATUS {
    00924                 VIDEO_UNKNOWN = 0             /*!< Video status is not (yet) determined. @n */,
    00925                 VIDEO_NA                      /*!< Indicates that this Participant does not have video available.. @n */,
    00926                 VIDEO_AVAILABLE               /*!< Indicates that video is available for this participant. When the Participant::P_VIDEO_STATUS obtains this state, it is possible to retrieve the Video object, using Participant::GetVideo method. Further operations, such as starting or stopping the video send/receive will then go through the Video object. @n */,
    00927                 VIDEO_CONNECTING              /*!< Transitional state indicating that the Participant is attempting to initiate video send. @n */,
    00928                 STREAMING                     /*!< Indicates that the participant is currently sending video. @n */,
    00929                 VIDEO_ON_HOLD                 /*!< Indicates that the participant video send is currently paused. @n */
    00930         };
    00931
    00932         enum DTMF {
    00933                 DTMF_0 = 0,
    00934                 DTMF_1,
    00935                 DTMF_2,
    00936                 DTMF_3,
    00937                 DTMF_4,
    00938                 DTMF_5,
    00939                 DTMF_6,
    00940                 DTMF_7,
    00941                 DTMF_8,
    00942                 DTMF_9,
    00943                 DTMF_STAR,
    00944                 DTMF_POUND
    00945         };
    00946
    00947         /** Checks whether the current user can set this Participant's conversation privileges to the specified RANK. This enables you to gray out or disable in your UI all the unavailable options for Participant::SetRankTo method. @n  */
    00948         bool CanSetRankTo(
    00949                 const RANK& rank, /*!< Participant::RANK value to check for. @n */
    00950                 bool& result /*!< Returns true if local user can set participant's rank to the value given in rank argument. @n */
    00951         );
    00952
    00953         /** Sets Participant's conversation privileges to the given RANK @n  */
    00954         bool SetRankTo(
    00955                 const RANK& rank /*!< Target Participant::RANK value. @n */
    00956         );
    00957
    00958         /** Initiates live conversation attempt with Participant. @n  */
    00959         bool Ring(
    00960                 const Sid::String identityToUse = "", /*!< Ring an alternate identity, such as a PSTN number. @n */
    00961                 const bool videoCall = false, /*!< Enable video. @n */
    00962                 const uint nrofRedials = 0, /*!< Unused. @n */
    00963                 const uint redialPeriod = 0, /*!< Unused. @n */
    00964                 const bool autoStartVM = false, /*!< Unused. On dialog, if falling on VM, greeting and recording will be automatically started. @n */
    00965                 const Sid::String origin = "" /*!< When call is initiated from web link, must contain the URI that was used*/
    00966         );
    00967
    00968         /** Rings this participant, using P_LIVE_IDENTITY property if set. @n  */
    00969         bool RingIt(
    00970         );
    00971
    00972         /** Sets LIVE_IDENTITY property, an alternate identity to use when ringing, such as a PSTN. @n  */
    00973         bool SetLiveIdentityToUse(
    00974                 const Sid::String identityToUse = "" /*!< Empty string will reset it to default, i.e IDENTITY property value @n */
    00975         );
    00976
    00977         /** Retrieves a reference to the Video object that corresponds to the Participant. It can be either local video - you can check if this participant's name (P_IDENTITY property) matches the name of the currently logged in account (P_SKYPENAME property) or incoming video from a remote participant.  @n  @n Note that for GetVideo to be successful, the video has to be available for that participant. This can be checked for by examining Participant VIDEO_STATUS property - once it becomes VIDEO_AVAILABLE - you can use GetVideo to obtain the Video object. @n  */
    00978         bool GetVideo(
    00979                 VideoRef& video /*!< Returns reference to a constructed video object. @n */
    00980         );
    00981
    00982         /** Removes this participant from the current live session. Note that this does not remove the participant from conversation (for this, use Participant::Retire). It only removes participant from live state. @n  */
    00983         bool Hangup(
    00984         );
    00985
    00986         /** Forcibly removes this participant from conversation. This method is for removing other people from conversations (for example: as administrative punishment for flooding conversation with spam messages). For local user to leave a conversation, use Conversation::RetireFrom instead. @n  */
    00987         bool Retire(
    00988         );
    00989
    00990         /** This event gets fired on receiving a DTMF signal sent by Participant. Note that this event will only fire if the Participant is also using a Skype client. Skype audio library does not monitor incoming voice streams for dial tones. DTMF events are propagated to remote participants via data channel. Incoming DTMF tones transmitted from, for example, mobile phones, will not cause this event to fire. In case of incoming DTMF signals from Skype clients, DTMF tones are also inserted into the audio stream. You don't have to inject those into local audio playback yourself. @n
    00991         * @param dtmf Returns Participant::DTMF value. @n
    00992         */
    00993         virtual void OnIncomingDTMF(
    00994                 const DTMF& dtmf
    00995         );
    00996
    00997         /** Participant::P_CONVO_ID property get accessor */
    00998         bool GetPropConvoId(ConversationRef& convo_id);
    00999
    01000         /** Participant::P_IDENTITY property get accessor */
    01001         bool GetPropIdentity(Sid::String& identity);
    01002
    01003         /** Participant::P_RANK property get accessor */
    01004         bool GetPropRank(RANK& rank);
    01005
    01006         /** Participant::P_REQUESTED_RANK property get accessor */
    01007         bool GetPropRequestedRank(RANK& requested_rank);
    01008
    01009         /** Participant::P_TEXT_STATUS property get accessor */
    01010         bool GetPropTextStatus(TEXT_STATUS& text_status);
    01011
    01012         /** Participant::P_VOICE_STATUS property get accessor */
    01013         bool GetPropVoiceStatus(VOICE_STATUS& voice_status);
    01014
    01015         /** Participant::P_VIDEO_STATUS property get accessor */
    01016         bool GetPropVideoStatus(VIDEO_STATUS& video_status);
    01017
    01018         /** Participant::P_LIVE_IDENTITY property get accessor */
    01019         bool GetPropLiveIdentity(Sid::String& live_identity);
    01020
    01021         /** Participant::P_LIVE_PRICE_FOR_ME property get accessor */
    01022         bool GetPropLivePriceForMe(Sid::String& live_price_for_me);
    01023
    01024         /** Participant::P_LIVE_FWD_IDENTITIES property get accessor */
    01025         bool GetPropLiveFwdIdentities(Sid::String& live_fwd_identities);
    01026
    01027         /** Participant::P_LIVE_START_TIMESTAMP property get accessor */
    01028         bool GetPropLiveStartTimestamp(uint& live_start_timestamp);
    01029
    01030         /** Participant::P_SOUND_LEVEL property get accessor */
    01031         bool GetPropSoundLevel(uint& sound_level);
    01032
    01033         /** Participant::P_DEBUGINFO property get accessor */
    01034         bool GetPropDebuginfo(Sid::String& debuginfo);
    01035
    01036         /** Participant::P_LAST_VOICE_ERROR property get accessor */
    01037         bool GetPropLastVoiceError(Sid::String& last_voice_error);
    01038
    01039         /** Participant::P_QUALITY_PROBLEMS property get accessor */
    01040         bool GetPropQualityProblems(Sid::String& quality_problems);
    01041
    01042         /** Participant::P_LIVE_TYPE property get accessor */
    01043         bool GetPropLiveType(uint& live_type);
    01044
    01045         /** Participant::P_LIVE_COUNTRY property get accessor */
    01046         bool GetPropLiveCountry(Sid::String& live_country);
    01047
    01048         /** Participant::P_TRANSFERRED_BY property get accessor */
    01049         bool GetPropTransferredBy(Sid::String& transferred_by);
    01050
    01051         /** Participant::P_TRANSFERRED_TO property get accessor */
    01052         bool GetPropTransferredTo(Sid::String& transferred_to);
    01053
    01054         /** Participant::P_ADDER property get accessor */
    01055         bool GetPropAdder(Sid::String& adder);
    01056
    01057         /** Participant::P_LAST_LEAVEREASON property get accessor */
    01058         bool GetPropLastLeavereason(LEAVE_REASON& last_leavereason);
    01059
    01060 };
    01061
    01062
    01063 /*! \class Conversation skype-embedded_2.h "skype-embedded_2.h"
    01064  *  \brief
    01065  *  \nosubgrouping
    01066  *  The Conversation class encapsulates all types of communication possible with Skype client. Instant messaging, calls,
    01067  *  video calls, file transfers, SMS, screen sharing - all take place within the context of a Conversation. Contacts are
    01068  *  represented in Conversation as Participant objects. This also applies to contacts of PSTN type. All events in a
    01069  *  conversation are represented as Message objects.  @n
    01070  */
    01071 class Conversation : public SEObject
    01072 {
    01073         /** \cond INTERNAL */
    01074         friend class Skype;
    01075 protected:
    01076         Conversation(unsigned int oid, SERootObject* root);
    01077         /** \endcond */
    01078 public:
    01079         virtual ~Conversation();
    01080         typedef ConversationRef Ref;
    01081         typedef ConversationRefs Refs;
    01082         enum { MODULE_ID = 18 };
    01083         ConversationRef ref() {
    01084                 return ConversationRef(object_id);
    01085         }
    01086
    01087 private:
    01088         String getNamespace() const;
    01089         const PMAP* getPMap() const;
    01090         const EMAP* getEMap() const;
    01091         unsigned int moduleID() const;
    01092         void __clear_cache(void*);
    01093
    01094 public:
    01095         /** Properties of the Conversation class */
    01096         enum PROPERTY {
    01097                 P_IDENTITY = 972                /*!< contact identity in case of dialogs, chat name in case of conferences, type: Sid::String*/,
    01098                 P_TYPE = 902                    /*!< type of the conversation, type: Conversation::TYPE*/,
    01099                 P_LIVE_HOST = 918               /*!< host of current live session. none => no session. myself in case of 1:1 calls, type: Sid::String*/,
    01100                 P_LIVE_START_TIMESTAMP = 974    /*!< moment when first participant other than host joined the current or last live session, type: uint*/,
    01101                 P_LIVE_IS_MUTED = 996           /*!< if live session is muted, type: bool*/,
    01102                 P_ALERT_STRING = 920            /*!< '' everything matches, '=' nothing matches, '=string' string matches, type: Sid::String*/,
    01103                 P_IS_BOOKMARKED                 /*!< if conversation is bookmarked/flagged, type: bool*/,
    01104                 P_GIVEN_DISPLAYNAME = 925       /*!< local name assigned via Rename, type: Sid::String*/,
    01105                 P_DISPLAYNAME = 924             /*!< resulting display name of the conversation (based on given name, topic, participant list, etc), type: Sid::String*/,
    01106                 P_LOCAL_LIVESTATUS = 927        /*!< if the conversation is live and in which status it is then, type: LOCAL_LIVESTATUS*/,
    01107                 P_INBOX_TIMESTAMP               /*!< timestamp to sort the conversations in inbox by. 0 means not in inbox, type: uint*/,
    01108                 P_INBOX_MESSAGE_ID = 973        /*!< ID of the message that caused INBOX_TIMESTAMP to be set, type: MessageRef*/,
    01109                 P_UNCONSUMED_SUPPRESSED_MESSAGES = 975/*!< number of messages in UNCONSUMED_SUPPRESSED consumption status, type: uint*/,
    01110                 P_UNCONSUMED_NORMAL_MESSAGES    /*!< number of messages in UNCONSUMED_NORMAL consumption status, type: uint*/,
    01111                 P_UNCONSUMED_ELEVATED_MESSAGES  /*!< DEPRECATED, not set anymore, type: uint*/,
    01112                 P_UNCONSUMED_MESSAGES_VOICE = 970/*!< if there are unconsumed voice or call messages in the conversation, type: bool*/,
    01113                 P_ACTIVE_VM_ID                  /*!< ID of voice message that is being played or recorded in this conversation, type: VoicemailRef*/,
    01114                 P_CONSUMPTION_HORIZON = 979     /*!< consumption cutoff timestamp: messages after (but not including) this are considered unconsumed, type: uint*/,
    01115                 P_LAST_ACTIVITY_TIMESTAMP = 981 /*!< timestamp of last activity in conversation, type: uint*/,
    01116                 P_SPAWNED_FROM_CONVO_ID = 915   /*!< dialog this conference was spawned from, type: ConversationRef*/,
    01117                 P_CREATOR = 903                 /*!< identity of conversation creator (doesn't apply to dialogs), type: Sid::String*/,
    01118                 P_CREATION_TIMESTAMP            /*!< timestamp of creation, tells you how far you can retrieve messages, type: uint*/,
    01119                 P_MY_STATUS = 919               /*!< my status in this conversation (connecting, participating, retired, etc) (doesn't apply to dialogs), type: MY_STATUS*/,
    01120                 P_OPT_JOINING_ENABLED = 922     /*!< if it's a public conversation (doesn't apply to dialogs), type: bool*/,
    01121                 P_OPT_ENTRY_LEVEL_RANK = 906    /*!< rank that is auto-assigned at join (doesn't apply to dialogs), type: Participant::RANK*/,
    01122                 P_OPT_DISCLOSE_HISTORY          /*!< if history visible to new consumers (doesn't apply to dialogs), type: bool*/,
    01123                 P_OPT_ADMIN_ONLY_ACTIVITIES = 909/*!< activities that only ADMIN can do. Bitmap of ALLOWED_ACTIVITY values (doesn't apply to dialogs), type: ALLOWED_ACTIVITY*/,
    01124                 P_PASSWORDHINT = 980            /*!< public conversation password hint, use SetPassword to set (doesn't apply to dialogs), type: Sid::String*/,
    01125                 P_META_NAME = 910               /*!< deprecated, not used, type: Sid::String*/,
    01126                 P_META_TOPIC                    /*!< conversation topic (doesn't apply to dialogs), type: Sid::String*/,
    01127                 P_META_GUIDELINES = 913         /*!< guidelines (doesn't apply to dialogs), type: Sid::String*/,
    01128                 P_META_PICTURE                  /*!< conversation picture, in jpeg format (doesn't apply to dialogs), type: Sid::Binary*/
    01129         };
    01130
    01131         /** Setupkey SETUPKEY_ENABLE_BIRTHDAY_NOTIFICATION type:int default value:"1" @n Enables/disables birthday notification messages. @li 0 - disable;  @li 1 - enable; @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01132         #define SETUPKEY_ENABLE_BIRTHDAY_NOTIFICATION "Lib/Conversation/EnableBirthday"
    01133
    01134         /** Setupkey SETUPKEY_INBOX_UPDATE_TIMEOUT type:int  @n Timeout in seconds, how old the Conversation::P_INBOX_TIMESTAMP has to be for it to be re-sorted in the inbox. @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01135         #define SETUPKEY_INBOX_UPDATE_TIMEOUT "Lib/Conversation/InboxUpdateTimeout"
    01136
    01137         /** Setupkey SETUPKEY_RECENTLY_LIVE_TIMEOUT type:int default value:"20" @n The number of seconds a formerly live conversation will remain the Conversation::LIVE_CONVERSATIONS filter. Note that while the conversation remains in Conversation::LIVE_CONVERSATIONS filter, Skype::OnConversationListChange events will not fire if there is another call coming up within the same conversation. Seeting this key to 0 will cause conversations to exit the Conversation::LIVE_CONVERSATIONS list immediately, after live state drops. @n  @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01138         #define SETUPKEY_RECENTLY_LIVE_TIMEOUT "Lib/Conversation/RecentlyLiveTimeout"
    01139
    01140         /** Setupkey SETUPKEY_DISABLE_CHAT type:int  Disables chat (for voice only clients). @n This setup key is machine-specific and affects all local accounts. @n  */
    01141         #define SETUPKEY_DISABLE_CHAT "Lib/Chat/DisableChat"
    01142
    01143         /** Setupkey SETUPKEY_DISABLE_CHAT_HISTORY type:int  @n Disables storage of chat history. @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01144         #define SETUPKEY_DISABLE_CHAT_HISTORY "Lib/Message/DisableHistory"
    01145
    01146         /** Setupkey SETUPKEY_CHAT_HISTORY_DAYS type:int  @n Time limit for keeping local chat message history. @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01147         #define SETUPKEY_CHAT_HISTORY_DAYS "Lib/Chat/HistoryDays"
    01148
    01149         /** Setupkey SETUPKEY_CHATDB_LIMIT_KB type:int default value:"0" Use this key to limit the size of the chat db. Value is in KB. By default there is no limit. A minimum of 16 MB is recommended. */
    01150         #define SETUPKEY_CHATDB_LIMIT_KB "Lib/Chat/ChatDBLimitKb"
    01151
    01152         /** Setupkey SETUPKEY_DISABLE_CHAT_ACTIVITY_INDICATION type:int  @n Enables/disables transmitting typing indicator signals to othe participants of conversations. @li 0 - disable;  @li 1 - enable; @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01153         #define SETUPKEY_DISABLE_CHAT_ACTIVITY_INDICATION "Lib/Chat/DisableActivityIndication"
    01154
    01155         /** Setupkey SETUPKEY_CALL_NOANSWER_TIMEOUT type:int default value:"15" @n Timeout in seconds after which the incoming live session will stop ringing (and if possible, proceed to voicemail or call forward). @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01156         #define SETUPKEY_CALL_NOANSWER_TIMEOUT "Lib/Call/NoAnswerTimeout"
    01157
    01158         /** Setupkey SETUPKEY_CALL_SEND_TO_VM type:int  @n Autoforwarding of incoming calls to voicemail. @li 0 - off @li 1 - on @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01159         #define SETUPKEY_CALL_SEND_TO_VM "Lib/Call/SendToVM"
    01160
    01161         /** Setupkey SETUPKEY_CALL_APPLY_CF type:int  @n Enables/disables call forwarding. @li 0 - disable;  @li 1 - enable; @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01162         #define SETUPKEY_CALL_APPLY_CF "Lib/Call/ApplyCF"
    01163
    01164         /** Setupkey SETUPKEY_CALL_EMERGENCY_COUNTRY type:string  @n Country code for emergency calls @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01165         #define SETUPKEY_CALL_EMERGENCY_COUNTRY "Lib/Call/EmergencyCountry"
    01166
    01167         enum TYPE {
    01168                 DIALOG = 1                    /*!< 1:1 conversations, there is a one dialog per identity*/,
    01169                 CONFERENCE                    /*!< equivalent of a multichat*/,
    01170                 TERMINATED_CONFERENCE         /*!< a conference that has been terminated (disbanded chat)*/,
    01171                 LEGACY_VOICE_CONFERENCE       /*!< voice-only conference, when host is using a legacy non-conversation client*/,
    01172                 LEGACY_SHAREDGROUP            /*!< chat used for legacy shared groups, can be ignored*/
    01173         };
    01174
    01175         enum MY_STATUS {
    01176                 CONNECTING = 1                /*!< connecting to conference*/,
    01177                 RETRY_CONNECTING,
    01178                 DOWNLOADING_MESSAGES          /*!< unused*/,
    01179                 QUEUED_TO_ENTER               /*!< conference is full for now, being queued*/,
    01180                 APPLICANT                     /*!< I'm applying to join the conference*/,
    01181                 APPLICATION_DENIED            /*!< My application to join the conference was denied*/,
    01182                 INVALID_ACCESS_TOKEN          /*!< The password I provided is incorrect*/,
    01183                 CONSUMER                      /*!< I'm part of the conference, I can participate*/,
    01184                 RETIRED_FORCEFULLY            /*!< I was kicked from the conference*/,
    01185                 RETIRED_VOLUNTARILY           /*!< I left the conference*/
    01186         };
    01187
    01188         enum LOCAL_LIVESTATUS {
    01189                 NONE = 0                      /*!< there isn't a live session*/,
    01190                 STARTING                      /*!< trying to start or join a live session*/,
    01191                 RINGING_FOR_ME                /*!< there is a live session ringing*/,
    01192                 IM_LIVE                       /*!< the conference is live for me*/,
    01193                 ON_HOLD_LOCALLY = 5           /*!< I put the live session on hold*/,
    01194                 ON_HOLD_REMOTELY              /*!< the live session was put on hold by someone else*/,
    01195                 OTHERS_ARE_LIVE               /*!< there is a live session on-going, I'm not participating but I could join*/,
    01196                 OTHERS_ARE_LIVE_FULL = 11     /*!< there is a live session on-going without me, but I can't join because it's full*/,
    01197                 PLAYING_VOICE_MESSAGE = 8     /*!< playing a voicemail (dialog only)*/,
    01198                 RECORDING_VOICE_MESSAGE       /*!< recording a voicemail (dialog only)*/,
    01199                 RECENTLY_LIVE                 /*!< a live session just finished, we stay in this state for RECENTLY_LIVE_TIMEOUT setup key*/,
    01200                 TRANSFERRING = 12             /*!< call is being transferred*/
    01201         };
    01202
    01203         /** values for opt_admin_only_activities property */
    01204         enum ALLOWED_ACTIVITY {
    01205                 SET_META = 1                  /*!< allowed to set the CONVERSATION_META properties*/,
    01206                 ADD_CONSUMERS                 /*!< allowed to add participants to the conference*/,
    01207                 SPEAK = 4                     /*!< allowed to speak, but not write*/,
    01208                 SPEAK_AND_WRITE = 8           /*!< allowed to speak and write*/
    01209         };
    01210
    01211         /** Setter method for Conversation option properties. Option properties are all Conversation properties starting with OPT_ prefix. @n  */
    01212         bool SetOption(
    01213                 const int& propKey, /*!< Conversation property key, for example: Conversation::OPT_JOINING_ENABLED @n */
    01214                 const uint& value /*!< New value for the option property. @n */
    01215         );
    01216
    01217         /** Setter for Conversation class META_TOPIC. This topic will be set for remote participants as well. @n  */
    01218         bool SetTopic(
    01219                 const Sid::String& topic, /*!< New conversation topic. @n */
    01220                 const bool isXML = false /*!< Notifies remote UIs that the new topic contains xml tags. @n */
    01221         );
    01222
    01223         /** Setter for Conversation META_GUIDELINES. This property will be visible to remote participants of the conversation. @n  */
    01224         bool SetGuidelines(
    01225                 const Sid::String& guidelines, /*!< New value for the META_GUIDELINES property. @n */
    01226                 const bool isXML = false /*!< Set true to notify remote UIs that the new guideline contains XML tags. @n */
    01227         );
    01228
    01229         /** Sets the conversation's avatar to the specified JPEG image, which is propagated to both local and remote participants. Before calling this method, you should use Skype::ValidateAvatar to verify that jpeg references a valid JPEG image. @n  */
    01230         bool SetPicture(
    01231                 const Sid::Binary& jpeg /*!< Conversation avatar binary. @n */
    01232         );
    01233
    01234         /** When called from dialog conversation, this spawns a new conversation, with existing two dialog participants plus new contact identities given in the identitiesToAdd list. You do not need to add existing dialog participants to the string list. In fact, passing only the existing participants in the identities list will cause the method call to fail (return false), the same as if the list was empty. This method will also return false if the original conversation was not a dialog (contained more than two participants). Also note that this method always creates a new Conversation - even if a conversation with exactly the same participant list existed before. @n  */
    01235         bool SpawnConference(
    01236                 const Sid::List_String& identitiesToAdd, /*!< String list of additional participant identities. You do not need to add existing two participants from the original dialog to this list. @n */
    01237                 ConversationRef& conference /*!< Returns the resulting conversation or 0 if the method call failed. @n */
    01238         );
    01239
    01240         /** Takes one or more Contact identities and creates corresponding Participant objects within the context of this Conversation, which must be of type CONFERENCE. If you have an existing dialog conversation, use SpawnConference instead. @n  */
    01241         bool AddConsumers(
    01242                 const Sid::List_String& identities /*!< Contact identities to be added to the Conversation. @n */
    01243         );
    01244
    01245         /** Merges two live conversations. For example, if the user already has a live conversation up - let's call it conversation A. Then a new incoming call occurs - another conversation obtains LOCAL_LIVESTATUS == Conversation::RINGING_FOR_ME, let's call it conversation B. The user wishes to pick up the new incoming call and add it to the existing one. For this you can first call B->JoinLiveSession and then merge two calls with A->Assimilate(B, A). The second argument will return the merged conversation. Note that there are actually three conversation objects involved: A (before merge), B and C (after the merge). Normally it would make sense to have the first conversation (A) as the second argument, so that it gets overwritten with the assimilation result. @n  */
    01246         bool Assimilate(
    01247                 const ConversationRef& otherConversation, /*!< The new conversation to be merged with the one already in live state. @n */
    01248                 ConversationRef& conversation /*!< Returns a 3rd live conversation, result of merging two existing ones. @n */
    01249         );
    01250
    01251         /** starts, answers or joins a live session (first one to join becomes LIVE_HOST) */
    01252         bool JoinLiveSession(
    01253                 const Sid::String accessToken = "" /*!< if starting a live session, allows to set a custom access token*/
    01254         );
    01255
    01256         /** This is an alternative to calling Ring method for each Participant individually. This also works with dialogs (with identities containing only one item). @n  */
    01257         bool RingOthers(
    01258                 const Sid::List_String identities = Sid::List_String(), /*!< List of Participants to ring. Leaving the list empty will result in ringing all participants of at least speaker level. @n */
    01259                 const bool videoCall = false, /*!< If true, indicates that we want to do a video call (video still needs to be separately enabled) @n */
    01260                 const Sid::String origin = "" /*!< When call is initiated from web link, this argument must contain the URI that was used @n */
    01261         );
    01262
    01263         /** Sets VOICE_STATUS to LISTENING in the Participant instance associated with us, causing any input from our microphone to be ignored. This is a Conversation class method, rather than Participant class, because this only applies to local participant. @n  */
    01264         bool MuteMyMicrophone(
    01265         );
    01266
    01267         /** Sets VOICE_STATUS to SPEAKING in the Participant instance associated with us, causing any input from our microphone to be sent to the call host. This is a Conversation class method, rather than Participant class, because this only applies to local participant. @n  */
    01268         bool UnmuteMyMicrophone(
    01269         );
    01270
    01271         /** Puts the conversation on hold - Conversation LOCAL_LIVESTATUS changes to ON_HOLD_LOCALLY and to ON_HOLD_REMOTELY for remote participants. @n  */
    01272         bool HoldMyLiveSession(
    01273         );
    01274
    01275         /** Resumes call from local hold. @n  */
    01276         bool ResumeMyLiveSession(
    01277         );
    01278
    01279         /** Hang up or refuse to answer an incoming call. Set postVoiceAutoresponse to true to enable a caller to leave a voicemail message. @n  */
    01280         bool LeaveLiveSession(
    01281                 const bool postVoiceAutoresponse = false
    01282         );
    01283
    01284         /** Begin recording a voice mail for this conversation's remote participant. Applies to conversations of type DIALOG only. @n  */
    01285         bool StartVoiceMessage(
    01286         );
    01287
    01288         /** This method is for doing call transfers. NB! Call transfers only work in one-on-one conversations (dialogs). Before attempting call transfer, you should check availability of transfer recipients with Conversation class CanTransferLiveSession method. If the current conversation has a live session up, that session (call) will be transferred to targets specified in the identities list. Note that identities is a string list - all identities in that list will get incoming calls. The first one of them to pick up the call - wins, and rest of the transfer targets will stop ringing. @n  @n Let's take a closer look how this works in practice. We have three call participants involved in the process, and two separate conversations. Let there be three callers: Caller A (call originator), Caller B (transferor) and Caller C (recipient of transfer). @n  @li Caller A - calls Caller B; Caller B picks up the call - live conversation C1 is now up with A and B in it. @li After awhile, Caller B initiates call transfers to Caller C (and optionally to Callers D, E, F.. ). LOCAL_LIVESTATUS of C1 will get set to TRANSFERRING for both A and B. @li Caller C picks up the call. Conversation C1 will go off live status. For Caller B, conversation C1 LOCAL_LIVESTATUS will change to RECENTLY_LIVE. Another live conversation - C2 gets spawned, with Caller A and Caller C in it. For caller C, participant object representing caller A will have TRANSFERRED_BY property set to identity of caller A. For Caller B (in now no longer live conversation C1), participant object representing caller A gets its TRANSFERRED_TO property set to identity of caller C. @n  */
    01289         bool TransferLiveSession(
    01290                 const Sid::List_String& identities, /*!< String list of transfer target identities. As soon as first one in this list picks up the call, others will stop ringing. @n */
    01291                 const Sid::String transferTopic = "" /*!< Optional conversation topic. This value will get set as META_TOPIC property of the conversation at the transferee end. Note that this is the only case where META_TOPIC field is used in context of dialog conversations. Thus assumption that remote UI will display topic field in case of dialogs may not be 100% correct. @n */
    01292         );
    01293
    01294         /** Checks if the identity is available for receiving a transferred live session. If you are going to attempt to go for multiple transfer targets, you should use this check for all the target identities. @n  */
    01295         bool CanTransferLiveSession(
    01296                 const Sid::String& identity, /*!< Target identity. @n */
    01297                 bool& result /*!< Returns true if call transfer to given target is possible. @n */
    01298         );
    01299
    01300         /** Sends DTMF tone to a live conversation. @n  */
    01301         bool SendDTMF(
    01302                 const Participant::DTMF& dtmf, /*!< Outgoing dtmf tone, possible values come from Participant::DTMF enumerator. @n */
    01303                 const uint lengthInMS = 260 /*!< Duration in milliseconds. Defaults to 260 ms. Note that the DTMF tone can be also cancelled with Conversation::StopSendDTMF method. @n */
    01304         );
    01305
    01306         /** Stops the current DTMF tone being played into conversation. For example, use this method to cancel DTMF signals started with Conversation::SendDTMF before the duration given in lengthInMS runs out. @n  */
    01307         bool StopSendDTMF(
    01308         );
    01309
    01310         /** Sets local user typing indicator in the Conversation. Remote Participants can display these in their UI. @n  */
    01311         bool SetMyTextStatusTo(
    01312                 const Participant::TEXT_STATUS& status /*!< Typing indicator status value - Participant::TEXT_STATUS @n */
    01313         );
    01314
    01315         /** Posts the specified text the conversation, and populates message with a reference to the corresponding Message object (if no error occurred during execution). The isXML argument can be used if the client UI has already taken care of converting message text to xml (for example, your UI might enable users to use bold tags in text messages.) @n  */
    01316         bool PostText(
    01317                 const Sid::String& text, /*!< Text value of the outgoing message (gets set as BODY_XML property of the Message object). @n */
    01318                 MessageRef& message, /*!< Returns the Message object created as a result of this method (if successful). @n */
    01319                 const bool isXML = false /*!< For cases where the text argument was already encoded as xml message. @n */
    01320         );
    01321
    01322         /** Takes a list of Contacts as an argument and posts the list into the Conversation. The purpose of this feature is to enable sharing contacts between users, without resorting to contact search. Instead, if user A has contacts B and C, he can post contact C into chat with contact B. At this point, Contact B can add contact C to his contact list. From remote side, the posted contacts will appear as messages with type Message::POSTED_CONTACTS appearing in the conversation. The UI should allow adding these contacts from messages with this type into the contact list. @n  @n The list of posted contacts can be retrieved with the Message::GetContacts method.  @n  @n Additionally, the UI then can parse the posted Contact data out of the Message::P_BODY_XML property. The list of contacts is wrapped between <contacts ..> </contacts> tags. Each contact item in the xml has following format: @li t - contact type. "s" - skype contact; "p" - phone number; @li s - skypename, present only in skypename contacts (t="s") @li p - phone number, present only in phone number contacts (t="p") @li f - contact's full name, if available @li d - contact's display name, if available @n  @n Note that only the type (t) field is mandatory. Depending on type, either skypename (s) or phone number (p) fields are always present. Full name and display name fields are optional. @n  @n Example BODY_XML with skypname contact:  @n @code @n <contacts alt="alt text"><c t="s" s="skypename" f="full name"/></contacts> @n @endcode @n  @n Example BODY_XML with PSTN contact:  @n @code @n <contacts alt="alt text"><c t="p" p="+37212345678" d="Some PSTN number"/></contacts> @n @endcode  @n  @n Example BODY_XML with multiple contacts:  @n @code @n <contacts alt="alt text"><c t="p" p="+37212345678" d="Some PSTN number"/><c t="s" s="someskypename"/></contacts> @n @endcode @n  */
    01323         bool PostContacts(
    01324                 const ContactRefs& contacts /*!< List of Contact objects, to be posted in the conversation. @n */
    01325         );
    01326
    01327         /** Takes a list of fully-qualified filenames and initiates corresponding file transfers in the conversation. From the remote side, incoming file transfers will appear as a conversation message with type POSTED_FILES. Once such a message is detected, the list of file transfer objects can be retrieved with Message::GetTransfers. At that point, remote participants will need to accept or decline those transfers. @n  */
    01328         bool PostFiles(
    01329                 const Sid::List_Filename& paths, /*!< list of fully-qualified filenames to be transferred @n */
    01330                 const Sid::String& body, /*!< Optional BODY_XML property for POSTED_FILES type messages that show up in remote UI. @n */
    01331                 TRANSFER_SENDFILE_ERROR& error_code, /*!< Error code, possible values come from the TRANSFER_SENDFILE_ERROR enumerator. This will be set for the first failed fail. The failed file is identified in the error_file return argument. @n */
    01332                 Sid::Filename& error_file /*!< Filename of the file that triggered error. @n */
    01333         );
    01334
    01335         /** Stops the active voicemail recording and sends it (dialog only) */
    01336         bool PostVoiceMessage(
    01337                 const VoicemailRef& voicemail, /*!< This argument is deprecated as of SDK version 3.2. Instead of manually constructing Voicemail object, you can call Conversation::StartVoiceMessage method to start recording a voicemail in context of a dialog. PostVoiceMessage will stop recording this voicemail and post it in the dialog. If instead of sending Voicemail, the user decides to cancel it, you should use Conversation::LeaveLiveSession method (Voicemail::Cancel is deprecated). @n */
    01338                 const Sid::String& body /*!< Optional text message that remote UI can display in conversation, to notify the user of a new voicemail. @n */
    01339         );
    01340
    01341         /** Takes an SMS instance created by Skype::CreateOutgoingSms and posts it in the conversation. Note that you will need to set both Sms body text (Sms::SetBody) and recipient list (Sms::SetTargets) before you can post the object. @n  */
    01342         bool PostSMS(
    01343                 const SmsRef& sms, /*!< SMS object. @n */
    01344                 const Sid::String body = "" /*!< This argument is currently ignored. The message text needs to be set with Sms::SetBody method, prior to passing the Sms object to this method @n */
    01345         );
    01346
    01347         /** Retrieves a binary join blob for joining public conversations, which are always of type CONFERENCE. If called for a dialog, the blob argument will contain the empty string. The best way to create a Public Chat is to first create a fresh conversation with Skype class CreateConference, then minimally apply the public chat options OPT_JOINING_ENABLED and OPT_ENTRY_LEVEL_RANK - options, like this (C++):  @n @code @n C->SetOption(Conversation::OPT_JOINING_ENABLED, true); @n @endcode @n  @n When that is done, you can call GetJoinBlob to retrieve the blob string. Use the blob string to generate and post an HTML link whose href attribute looks like this: href="skype:?chat&blob=_BLOB_GOES_HERE" A person running Skype desktop client can click this link to join the conversation and have that conversation opened in his UI. Note that the conversation host (creator) needs to be online for new joiners-via-link to start participating in the Public Chat. */
    01348         bool GetJoinBlob(
    01349                 Sid::String& blob /*!< Returns the public conversation join blob. @n */
    01350         );
    01351
    01352         /** Tries to join a public conversation (aka public chat). This method is only useful if you have used Skype::GetConversationByBlob method with alsoJoin argument set to false. @n  */
    01353         bool Join(
    01354         );
    01355
    01356         /** Submits password for joining password-protected conversation. @n  */
    01357         bool EnterPassword(
    01358                 const Sid::String& password /*!< Password string. @n */
    01359         );
    01360
    01361         /** Sets password protection/new password for the conversation. @n  */
    01362         bool SetPassword(
    01363                 const Sid::String& password, /*!< New password. @n */
    01364                 const Sid::String& hint /*!< Password hint. @n */
    01365         );
    01366
    01367         /** Leaves the conference. Not applicable to dialogs. @n  */
    01368         bool RetireFrom(
    01369         );
    01370
    01371         /** Deletes this conversation, which must be of type CONFERENCE - dialogs between local user and any of his contacts are always persistant. Note that this also removes corresponding Message and Participant objects. @n  */
    01372         bool Delete(
    01373         );
    01374
    01375         /** Changes the META_NAME property of the conversation. Note that unlike topic and guidelines, this rename is just local - remote participants can have their own private names for conversations. @n  */
    01376         bool RenameTo(
    01377                 const Sid::String& name /*!< New name for the conversation. Passing an empty string in this argument causes the META_NAME to unset. @n */
    01378         );
    01379
    01380         /** Setter for Conversation class IS_BOOKMARKED. @n  */
    01381         bool SetBookmark(
    01382                 const bool& bookmark /*!< Set true to set the bookmark, false to remove the bookmark. @n */
    01383         );
    01384
    01385         /** Setter for Conversation class ALERT_STRING property. The main use of this property is checking bodies of incoming messages in the conversation for the alert string and producing notifications in UI for the user, when appropriate. @n  */
    01386         bool SetAlertString(
    01387                 const Sid::String& alertString /*!< Substring to check in BODY_XML property of incoming messages. @n */
    01388         );
    01389
    01390         /** Removes conversation from Inbox. @n  */
    01391         bool RemoveFromInbox(
    01392         );
    01393
    01394         /** Sets Conversation inbox_timestamp property. If the timestamp argument is left empty or is greater than conversation consumption horizon, then the conversation will be restored to the inbox. @n  */
    01395         bool AddToInbox(
    01396                 const uint timestamp = 0 /*!< If left empty or set to 0, the inbox_timestamp property is set to current time. @n */
    01397         );
    01398
    01399         /** This method can be used to set the consumption (read) status of messages in the conversation. It sets Message::CONSUMPTION_STATUS to Message::CONSUMED for all messages in the conversation, older than the given timestamp. If the second argument is set to true, it also modifies messages more recent than the timestamp, by marking them as unconsumed. @n  */
    01400         bool SetConsumedHorizon(
    01401                 const uint& timestamp, /*!< Consumption cutoff timestamp. Setting this to current time will mark all messages in the conversation as consumed. @n */
    01402                 const bool also_unconsume = false /*!< If set to true, this also marks messages newer than the cutoff timestamp as unconsumed. For example, setting timestamp to 0 and also_unconsumed to true, will unconsume all messages in the conversation. @n */
    01403         );
    01404
    01405         /** sets consumption horizon to last inbox message id timestamp */
    01406         bool MarkUnread(
    01407         );
    01408
    01409         /** Checks if the conversation is a member of the given ContactGroup @n  */
    01410         bool IsMemberOf(
    01411                 const ContactGroupRef& group, /*!< ContactGroup @n */
    01412                 bool& result /*!< True if this conversation is a member of the ContactGroup specified by the group argument contains the conversation @n */
    01413         );
    01414
    01415         enum PARTICIPANTFILTER {
    01416                 ALL = 0                       /*!< All participants (may included some that are RETIRED or OUTLAW, but not all of them)*/,
    01417                 CONSUMERS                     /*!< Participants that can receive messages, including myself*/,
    01418                 APPLICANTS                    /*!< Only people who are applying to join the conversation*/,
    01419                 CONSUMERS_AND_APPLICANTS      /*!< Consumers and applicants*/,
    01420                 MYSELF                        /*!< Myself*/,
    01421                 OTHER_CONSUMERS               /*!< All consumers except myself*/
    01422         };
    01423
    01424         /** Retrieves the list of this conversation's current participants, which you can optionally request to be filtered. If no Participants pass the filter, an empty list will be returned (the method itself still returns true). @n  */
    01425         bool GetParticipants(
    01426                 ParticipantRefs& participants, /*!< List of conversation Participant objects that passed the filter. @n */
    01427                 const Conversation::PARTICIPANTFILTER filter = Conversation::ALL /*!< Conversation::PARTICIPANTFILTER - defaults to Conversation::ALL @n */
    01428         );
    01429
    01430         /** Returns recent messages. The messages are returned in two lists - new messages (unconsumed) and recent message history (context messages). The context message list contains messages that are already above the consumption horizon but are fairly recent, making it likely that displaying them in UI would be good default behaviour. @n  */
    01431         bool GetLastMessages(
    01432                 MessageRefs& contextMessages, /*!< Already consumed messages, provided for context*/
    01433                 MessageRefs& unconsumedMessages, /*!< Unconsumed messages*/
    01434                 const uint requireTimestamp = 0 /*!< If set to a non-zero value, includes messages no earlier than this timestamp, if not, includes messages from the last 24 hours only @n */
    01435         );
    01436
    01437         /** Finds the most recent Message object in the conversation that contains the substring specified by the text argument. If no matching messages are found, this method will return false. The search proceeds backwards in time, starting from the timestamp argument. To continue searching, you can start with timestamp=MAX_UINT, retrieve the TIMESTAMP property of the matching message, decrement it by one, and submit it as timestamp for the next FindMessage call. @n  */
    01438         bool FindMessage(
    01439                 const Sid::String& text, /*!< Substring to search for. @n */
    01440                 MessageRef& message, /*!< Returns matching message or 0 if there was no match. As the likelihood of this object being invalid is quite high, you should always check for method return value before you start calling methods of this object. @n */
    01441                 const uint fromTimestampUp = MAX_UINT
    01442         );
    01443
    01444         enum LIST_TYPE {
    01445                 ALL_CONVERSATIONS = 0         /*!< bookmarked or in_inbox or live or with_meta_info or activity in last 30 days*/,
    01446                 INBOX_CONVERSATIONS           /*!< only last 6 months conversations are kept there*/,
    01447                 BOOKMARKED_CONVERSATIONS      /*!< is_bookmarked is set*/,
    01448                 LIVE_CONVERSATIONS            /*!< local_livestatus is different from NONE*/,
    01449                 REALLY_ALL_CONVERSATIONS = 5  /*!< all conversations, without any of the limits of ALL_CONVERSATIONS*/
    01450         };
    01451
    01452         /** This callback gets fired when participants join or leave the conversation. @n  */
    01453         virtual void OnParticipantListChange(
    01454         );
    01455
    01456         /** Called for each message in currently loaded conversations */
    01457         virtual void OnMessage(
    01458                 const MessageRef& message
    01459         );
    01460
    01461         /** This callback gets fired when a new Conversation is created using SpawnConference. @n
    01462         * @param spawned Conversation object that got created. @n
    01463         */
    01464         virtual void OnSpawnConference(
    01465                 const ConversationRef& spawned
    01466         );
    01467
    01468         /** Conversation::P_IDENTITY property get accessor */
    01469         bool GetPropIdentity(Sid::String& identity);
    01470
    01471         /** Conversation::P_TYPE property get accessor */
    01472         bool GetPropType(Conversation::TYPE& type);
    01473
    01474         /** Conversation::P_LIVE_HOST property get accessor */
    01475         bool GetPropLiveHost(Sid::String& live_host);
    01476
    01477         /** Conversation::P_LIVE_START_TIMESTAMP property get accessor */
    01478         bool GetPropLiveStartTimestamp(uint& live_start_timestamp);
    01479
    01480         /** Conversation::P_LIVE_IS_MUTED property get accessor */
    01481         bool GetPropLiveIsMuted(bool& live_is_muted);
    01482
    01483         /** Conversation::P_ALERT_STRING property get accessor */
    01484         bool GetPropAlertString(Sid::String& alert_string);
    01485
    01486         /** Conversation::P_IS_BOOKMARKED property get accessor */
    01487         bool GetPropIsBookmarked(bool& is_bookmarked);
    01488
    01489         /** Conversation::P_GIVEN_DISPLAYNAME property get accessor */
    01490         bool GetPropGivenDisplayname(Sid::String& given_displayname);
    01491
    01492         /** Conversation::P_DISPLAYNAME property get accessor */
    01493         bool GetPropDisplayname(Sid::String& displayname);
    01494
    01495         /** Conversation::P_LOCAL_LIVESTATUS property get accessor */
    01496         bool GetPropLocalLivestatus(LOCAL_LIVESTATUS& local_livestatus);
    01497
    01498         /** Conversation::P_INBOX_TIMESTAMP property get accessor */
    01499         bool GetPropInboxTimestamp(uint& inbox_timestamp);
    01500
    01501         /** Conversation::P_INBOX_MESSAGE_ID property get accessor */
    01502         bool GetPropInboxMessageId(MessageRef& inbox_message_id);
    01503
    01504         /** Conversation::P_UNCONSUMED_SUPPRESSED_MESSAGES property get accessor */
    01505         bool GetPropUnconsumedSuppressedMessages(uint& unconsumed_suppressed_messages);
    01506
    01507         /** Conversation::P_UNCONSUMED_NORMAL_MESSAGES property get accessor */
    01508         bool GetPropUnconsumedNormalMessages(uint& unconsumed_normal_messages);
    01509
    01510         /** Conversation::P_UNCONSUMED_ELEVATED_MESSAGES property get accessor */
    01511         bool GetPropUnconsumedElevatedMessages(uint& unconsumed_elevated_messages);
    01512
    01513         /** Conversation::P_UNCONSUMED_MESSAGES_VOICE property get accessor */
    01514         bool GetPropUnconsumedMessagesVoice(bool& unconsumed_messages_voice);
    01515
    01516         /** Conversation::P_ACTIVE_VM_ID property get accessor */
    01517         bool GetPropActiveVmId(VoicemailRef& active_vm_id);
    01518
    01519         /** Conversation::P_CONSUMPTION_HORIZON property get accessor */
    01520         bool GetPropConsumptionHorizon(uint& consumption_horizon);
    01521
    01522         /** Conversation::P_LAST_ACTIVITY_TIMESTAMP property get accessor */
    01523         bool GetPropLastActivityTimestamp(uint& last_activity_timestamp);
    01524
    01525         /** Conversation::P_SPAWNED_FROM_CONVO_ID property get accessor */
    01526         bool GetPropSpawnedFromConvoId(ConversationRef& spawned_from_convo_id);
    01527
    01528         /** Conversation::P_CREATOR property get accessor */
    01529         bool GetPropCreator(Sid::String& creator);
    01530
    01531         /** Conversation::P_CREATION_TIMESTAMP property get accessor */
    01532         bool GetPropCreationTimestamp(uint& creation_timestamp);
    01533
    01534         /** Conversation::P_MY_STATUS property get accessor */
    01535         bool GetPropMyStatus(MY_STATUS& my_status);
    01536
    01537         /** Conversation::P_OPT_JOINING_ENABLED property get accessor */
    01538         bool GetPropOptJoiningEnabled(bool& opt_joining_enabled);
    01539
    01540         /** Conversation::P_OPT_ENTRY_LEVEL_RANK property get accessor */
    01541         bool GetPropOptEntryLevelRank(Participant::RANK& opt_entry_level_rank);
    01542
    01543         /** Conversation::P_OPT_DISCLOSE_HISTORY property get accessor */
    01544         bool GetPropOptDiscloseHistory(bool& opt_disclose_history);
    01545
    01546         /** Conversation::P_OPT_ADMIN_ONLY_ACTIVITIES property get accessor */
    01547         bool GetPropOptAdminOnlyActivities(ALLOWED_ACTIVITY& opt_admin_only_activities);
    01548
    01549         /** Conversation::P_PASSWORDHINT property get accessor */
    01550         bool GetPropPasswordhint(Sid::String& passwordhint);
    01551
    01552         /** Conversation::P_META_NAME property get accessor */
    01553         bool GetPropMetaName(Sid::String& meta_name);
    01554
    01555         /** Conversation::P_META_TOPIC property get accessor */
    01556         bool GetPropMetaTopic(Sid::String& meta_topic);
    01557
    01558         /** Conversation::P_META_GUIDELINES property get accessor */
    01559         bool GetPropMetaGuidelines(Sid::String& meta_guidelines);
    01560
    01561         /** Conversation::P_META_PICTURE property get accessor */
    01562         bool GetPropMetaPicture(Sid::Binary& meta_picture);
    01563
    01564 };
    01565
    01566
    01567 /*! \class Message skype-embedded_2.h "skype-embedded_2.h"
    01568  *  \brief
    01569  *  \nosubgrouping
    01570  *  Events in a conversation context are expressed as Messages. It is therefore useful to think of Message objects as
    01571  *  events, rather than specifically text chat messages. @brief @n  @n Message member functions all return a Boolean
    01572  *  indicating the success (true) or failure (false) of processing the request itself (transport, runtime availability,
    01573  *  and so forth) - not the success or failure of its associated functionality. For example, Message::Edit returns true
    01574  *  if it was able to make a determination, and its result parameter reflects whether this Message can be edited.
    01575  *  Similarly, Message::Edit returns false if it was unable to make a determination, and the value of its result
    01576  *  parameter is undefined. @n  @n Message member functions that are specific to a Message TYPE return false if this
    01577  *  Message is not of that type. For example, Message::GetVoiceMessage will return false if this Message's type is not
    01578  *  POSTED_VOICE_MESSAGE. @n  @n The actual meaning of a Message can be determined by its P_TYPE property. The meanings
    01579  *  of most other Message properties depend on the value of P_TYPE. For example, let's take P_BODY_XML property. @n  @n
    01580  *  Following messages have a text entered by the user as a body. It may contain emoticons, URLs, etc. @li POSTED_TEXT
    01581  *  @li POSTED_EMOTE @li SET_METADATA @li REQUESTED_AUTH @n  @n Following messages have a custom XML format for the body
    01582  *  (see the specific section on these message types for details): @li POSTED_CONTACTS @li POSTED_VOICE_MESSAGE @li
    01583  *  POSTED_FILES @li POSTED_SMS @li STARTED_LIVESESSION and ENDED_LIVESESSION (same format) @n  @n Following messages do
    01584  *  not use the body property: @li SPAWNED_CONFERENCE @li ADDED_CONSUMERS @li ADDED_APPLICANTS @li RETIRED_OTHERS @li
    01585  *  RETIRED @li SET_RANK @li HAS_BIRTHDAY @li GRANTED_AUTH @li BLOCKED @n  @n Messages such as POSTED_TEXT use a small
    01586  *  subset of a HTML-like markup to control the visual representation of the text. This markup is used by POSTED_TEXT
    01587  *  and POSTED_EMOTE, but also for the conversation topic (CONVERSATION_META_TOPIC property and the body of the
    01588  *  SET_METADATA message) and for authorization requests. @n  @n Having chat messages in XML format means that all
    01589  *  formatting is indicated by XML tags. This includes emoticons and URls. The big advantage is that it makes the
    01590  *  parsing of the message by the UI much easier. The UI does not need to do emoticons or URL detection, this is already
    01591  *  done and it only needs to look for the XML tags. @n  @n For text messages, it is possible for the UI to simply
    01592  *  ignore (meaning strip) the XML and the message will be understandable fine, it will only have lost some formatting.
    01593  *  @n  @n But it is obviously nicer to display at least the most commonly used tags. @n  @n To strip the XML: @li if
    01594  *  they have the alt="sometext" attribute set, return sometext as the output of that tag and ignore the rest of tag and
    01595  *  all nested sub tags @li if no alt="" attribute set, use tag content as output - <sometag>hereissomething</sometag>
    01596  *  is output as hereissomething@li if no alt="" and no tag content, ignore the tag altogether (return nothing) @n Skype
    01597  *  for Windows supports displaying many XML tags, but only a sub-set is regularly used and should be supported by the
    01598  *  UI for a good experience. These are the ones described here. @n Animated emoticons @n Emoticons are encoded with the
    01599  *  "ss" tag. The element content is the plain text representation. It has a "type" attribute indicating the emoticons
    01600  *  canonical name. Example:  @n @code @n Hi <ss type="smile">:-)</ss>  @n @endcode @n  @n Flag emoticons @n Flag
    01601  *  emoticons are little flags. They are encoded with the "flag" tag. The element contents is the plain text
    01602  *  representation and it has a "country" attribute which is a 2-letter ISO-3166 country code. The user can enter a flag
    01603  *  using "(flag:XX)", where XX is a valid ISO country code. Example:  @n @code @n I am in <flag country="cc">CC</flag>
    01604  *  @n @endcode @n  @n Links @n If the library detects a URL, it will encode it using the html "a" tag, with the "href"
    01605  *  attribute indicating the URL. The plain text representation is what the user originally typed. Example:  @n @code @n
    01606  *  I am in <a href="http://wwww.skype.com">www.skype.com</a> @n @endcode @n  @n Alert matches @n When a conversation is
    01607  *  configured to display only alerts if specific words are present in the message (see "/alertson [text to match]"
    01608  *  command), if a message matches the alert, it will be marked with the <alertmatch> tag. This allows the UI to
    01609  *  highlight the word matching. Example:  @n @code @n Maybe <alertmatch>Vincent</alertmatch> knows the answer  @n
    01610  *  @endcode @n  @n Bold, italic, etc @n Skype for Windows also supports displaying bold and italic text, using the "b"
    01611  *  and "i" tags. @n  @n Encoding messages @n When sending a chat message via PostText(), there is the possibility to
    01612  *  indicate if the library should do the XML encoding, or if the message has already been encoded. Usually, the UI can
    01613  *  let library do the encoding. This is the case when the message does not contain any specific formatting. It may
    01614  *  contain emoticons or URls, which will be detected by the library encoder and converted into XML tags. @n If the
    01615  *  message has some more complex encoding, such as a quote or some bold text, it is up to the UI to encode the message.
    01616  *  @n
    01617  */
    01618 class Message : public SEObject
    01619 {
    01620         /** \cond INTERNAL */
    01621         friend class Skype;
    01622 protected:
    01623         Message(unsigned int oid, SERootObject* root);
    01624         /** \endcond */
    01625 public:
    01626         virtual ~Message();
    01627         typedef MessageRef Ref;
    01628         typedef MessageRefs Refs;
    01629         enum { MODULE_ID = 9 };
    01630         MessageRef ref() {
    01631                 return MessageRef(object_id);
    01632         }
    01633
    01634 private:
    01635         String getNamespace() const;
    01636         const PMAP* getPMap() const;
    01637         const EMAP* getEMap() const;
    01638         unsigned int moduleID() const;
    01639         void __clear_cache(void*);
    01640
    01641 public:
    01642         /** Properties of the Message class */
    01643         enum PROPERTY {
    01644                 P_CONVO_ID = 960                /*!< DB ID of corresponding conversation, type: ConversationRef*/,
    01645                 P_CONVO_GUID = 120              /*!< GUID of the Conversation. The GUID is a "global ID" - these values are shared accross Skype client instances and accross all the participants of the conversation. @n , type: Sid::String*/,
    01646                 P_AUTHOR = 122                  /*!< Identity of the sender. While this is almost always the same as SKYPENAME property of the Contact, in some rare cases it can also be a phone number - for example, incoming voicemail notification Messages (message type = POSTED_VOICE_MESSAGE). @n , type: Sid::String*/,
    01647                 P_AUTHOR_DISPLAYNAME            /*!< displayname of the sender at the time of posting, type: Sid::String*/,
    01648                 P_GUID = 792                    /*!< Unlike the message id, the GUID is the same on all instances and for all participants. @n , type: Sid::Binary*/,
    01649                 P_ORIGINALLY_MEANT_FOR = 790    /*!< This property gets set when a conference is spawned from dialog Conversation. In that case recent message history from the original dialog is copied to the target conversation. For all the copied messages, the ORIGINALLY_MEANT_FOR property will be set to identity of the remote participant of the original dialog. @n , type: Sid::String*/,
    01650                 P_TIMESTAMP = 121               /*!< UNIX timestamp (sent time, adjusted for local clock), type: uint*/,
    01651                 P_TYPE = 961                    /*!< type: Message::TYPE*/,
    01652                 P_SENDING_STATUS                /*!< type: Message::SENDING_STATUS*/,
    01653                 P_CONSUMPTION_STATUS = 968      /*!< type: Message::CONSUMPTION_STATUS*/,
    01654                 P_EDITED_BY = 222               /*!< Identity of the author that last edited this message. NULL if message has not been edited @n , type: Sid::String*/,
    01655                 P_EDIT_TIMESTAMP                /*!< UNIX timestamp of last edit, type: uint*/,
    01656                 P_PARAM_KEY = 963               /*!< Message type-specific parameter. See Message::SET_METADATA_KEY for more information. @n , type: uint*/,
    01657                 P_PARAM_VALUE                   /*!< Message type-specific parameter @n , type: uint*/,
    01658                 P_BODY_XML = 127                /*!< Message type-specific parameter @n , type: Sid::String*/,
    01659                 P_IDENTITIES = 125              /*!< Message type-specific parameter. Depending of Message type, this property contains: @li STARTED_LIVESESSION - list of participants in the cal; @li ENDED_LIVESESSION - list of participants in the call; @li POSTED_SMS - list of recipients of the message; @li SPAWNED_CONFERENCE - the list of identities that were added; @li ADDED_CONSUMERS - the list of identities that were added; @li RETIRED_OTHERS - the skypename of the participant who was kicked; @li SET_RANK - the skypename of the participant whose rank was changed; @li REQUESTED_AUTH - Message::P_AUTHOR and Message::P_IDENTITIES are set to the users receiving and requesting the authorization, depending if the message was received or sent; @li GRANTED_AUTH - the skypename of the user we granted authorization; @li BLOCKED - the skypename of the user who was blocked; @li HAS_BIRTHDAY - skypename of current logged in user. @n , type: Sid::String*/,
    01660                 P_REASON = 966                  /*!< Message type-specific parameter. Possible values for STARTED/ENDED_LIVESESSION (only set for dialogs): @li no_answer  @li manual  @li busy  @li connection_dropped @li no_skypeout_subscription; @li insufficient_funds @li internet_connection_lost @li skypeout_account_blocked @li pstn_could_not_connect_to_skype_proxy @li pstn_invalid_number @li pstn_number_forbidden @li pstn_call_timed_out @li pstn_busy @li pstn_call_terminated @li pstn_network_error @li number_unavailable @li pstn_call_rejected @li pstn_misc_error @li internal_error @li unable_to_connect @li connection_dropped @li recording_failed @li playback_error @li legacy_error @li blocked_by_privacy_settings @li error @li transfer_failed @li transfer_insufficient_funds @li blocked_by_us @li emergency_call_denied @n  @n This information is now available as an enum in LEAVEREASON @n , type: Sid::String*/,
    01661                 P_LEAVEREASON = 126             /*!< Leave reason for message of the RETIRED type, and STARTED/ENDED_LIVESESSION.                   Use for STARTED/ENDED_LIVESESSION is to provide simpler, enum based                   handling and deprecates the reason property (only set for dialogs), type: LEAVE_REASON*/,
    01662                 P_PARTICIPANT_COUNT = 982       /*!< Number of people who received this message (including local user) @n , type: uint*/
    01663         };
    01664
    01665         /** The P_TYPE property determines the actual meaning of the Message object. Only Messages of POSTED_TEXT type contain actual text messages. The meaning and content of the rest of the message properties are largely dependant of the value of the Message::P_TYPE. @n  */
    01666         enum TYPE {
    01667                 SET_METADATA = 2              /*!< Conference metadata were changed*/,
    01668                 SPAWNED_CONFERENCE = 4        /*!< A conference was spawned from this dialog*/,
    01669                 ADDED_CONSUMERS = 10          /*!< Some users were added to the conference*/,
    01670                 ADDED_APPLICANTS              /*!< Some users are applying to be added to the conference*/,
    01671                 RETIRED_OTHERS                /*!< User was kicked from the conference*/,
    01672                 RETIRED                       /*!< User left the conference*/,
    01673                 SET_RANK = 21                 /*!< Changed the rank of a user in the Conversation (multichat administration) @n */,
    01674                 STARTED_LIVESESSION = 30      /*!< A live session started*/,
    01675                 ENDED_LIVESESSION = 39        /*!< A live session ended*/,
    01676                 REQUESTED_AUTH = 50           /*!< User requested authorization*/,
    01677                 GRANTED_AUTH                  /*!< User was granted authorization. Notification message that user is now an authorized contact (of the local user). @n */,
    01678                 BLOCKED = 53                  /*!< User was blocked*/,
    01679                 POSTED_TEXT = 61              /*!< A text message*/,
    01680                 POSTED_EMOTE = 60             /*!< An emote ('John Doe is laughing', cf /me chat command)*/,
    01681                 POSTED_CONTACTS = 63          /*!< The message represents (a set of) contact card(s) posted in the conversation. One message can contain more than one contact cards. The contacts can be retrieved from the message by parsing them out from the P_BODY_XML property. For more information, see Conversation::PostContacts @n */,
    01682                 POSTED_SMS                    /*!< The message represents an SMS object that was posted in the Conversation. See Conversation::PostSMS for more details. The Sms object itself can be retrieved from the Message with Message::GetSms The message BODY_XML contains a set of SMS properties, such as status, failurereason, targets, price and timestamp. @n */,
    01683                 POSTED_ALERT                  /*!< Deprecated, never sent*/,
    01684                 POSTED_VOICE_MESSAGE = 67     /*!< A voicemail*/,
    01685                 POSTED_FILES                  /*!< The message represents a (list of) file transfers that were posted in the Conversation with Conversation::PostFiles. Transfer objects can be retrieved from the Message with Message::GetTransfers @n */,
    01686                 POSTED_INVOICE                /*!< Currently unused. @n */,
    01687                 HAS_BIRTHDAY = 110            /*!< The message represents a Contact birthday notification. @n */
    01688         };
    01689
    01690         enum SENDING_STATUS {
    01691                 SENDING = 1                   /*!< Message has not been delivered to at least one of the participants @n */,
    01692                 SENT                          /*!< Message has been delivered to at least one other participant @n */,
    01693                 FAILED_TO_SEND                /*!< Message could not be delivered (for SMS this reflects the actual SMS, not the chat message) @n */
    01694         };
    01695
    01696         /** Indicates if a message has been consumed (meaning read) or not */
    01697         enum CONSUMPTION_STATUS {
    01698                 CONSUMED = 0                  /*!< Message has been read. Note that this is a read-only property. Consumption status of individual messages can not be set selectively. Message consumption status is determined at the conversation level, based conversation consumption horizon and individual message timestamps. Conversation consumption horizon can be updated with Conversation::SetConsumedHorizon method.  @n */,
    01699                 UNCONSUMED_SUPPRESSED         /*!< Do not notify the user that they have this unread message @n */,
    01700                 UNCONSUMED_NORMAL             /*!< Notify the user that they have this unread message @n */,
    01701                 UNCONSUMED_ELEVATED           /*!< This message consumption state is marked as DEPRECATED @n */
    01702         };
    01703
    01704         /** For messages of type SET_METADATA that alert participants to changes to the associated Conversation's metadata, indicates which metadata property changed and its P_BODY_XML property contains the changed data. Your UI is expected to detect messages with PARAM_KEY set and to update its visual representation of Conversation accordingly. @n You can use the associated Conversation's properties and methods to obtain the updated metadata rather than parse the message body XML, for example, Conversation::P_META_PICTURE and Conversation::Conversation::GetPropMetaPicture. @n  */
    01705         enum SET_METADATA_KEY {
    01706                 SET_META_NAME = 3640          /*!< Notification message that conversation name has changed. @n */,
    01707                 SET_META_TOPIC = 3644         /*!< Notification message that conversation topic has changed. @n */,
    01708                 SET_META_GUIDELINES = 3652    /*!< Notification message that conversation guidelines have changed. @n */,
    01709                 SET_META_PICTURE = 3658       /*!< Notification message that conversation picture has changed. @n */
    01710         };
    01711
    01712         /** Indicates the reason a user could not join or left a Conversation. SkypeKit automatically sets "could not join"-related values. "Left voluntarily"-related values are set as a result of explicit user actions. @n  */
    01713         enum LEAVEREASON {
    01714                 USER_INCAPABLE = 2            /*!< User cannot chat (user is currently logged in with a client that has chat disabled - see Contact::CAPABILITY.CAPABILITY_TEXT) @n */,
    01715                 ADDER_MUST_BE_FRIEND          /*!< Attempt to add local user to a conversation by an unknown contact @n */,
    01716                 ADDER_MUST_BE_AUTHORIZED      /*!< Attempt to add local user to a conversation by an unauthorized contact @n */,
    01717                 DECLINE_ADD                   /*!< Local user declined an "invitation" to join a chat @n */,
    01718                 UNSUBSCRIBE                   /*!< User decided to end participation in an on-going multi-chat @n */
    01719         };
    01720
    01721         /** For Message types having a body, determines whether that body is editable by the user.  @n  */
    01722         bool CanEdit(
    01723                 bool& result
    01724         );
    01725
    01726         /** For Message types that include a body and are editable:  @li alters BODY_XML of the message object @li sets EDITED_BY and EDIT_TIMESTAMP properties  @li propagates the changes to remote users. @n  */
    01727         bool Edit(
    01728                 const Sid::String& newText, /*!< New value of the message BODY_XML property. @n */
    01729                 const bool isXML = false, /*!< Specify isXML as true if the message body is formatted as XML; omit it or specify it as false if the message body is plain text. @n */
    01730                 const bool undo = false /*!< Reverts the message body to the original version. newText parameter is ignored when this is set*/
    01731         );
    01732
    01733         /** For messages of type POSTED_CONTACTS, parses the body XML and formats the data as a list of Contact instances. @n  */
    01734         bool GetContacts(
    01735                 ContactRefs& contacts
    01736         );
    01737
    01738         /** For messages of type POSTED_FILES, parses the body XML and creates a list of Transfer instances. @n  */
    01739         bool GetTransfers(
    01740                 TransferRefs& transfers
    01741         );
    01742
    01743         /** For messages of type POSTED_VOICE_MESSAGE, parses the body XML and creates a Voicemail instance. @n  */
    01744         bool GetVoiceMessage(
    01745                 VoicemailRef& voicemail
    01746         );
    01747
    01748         /** For messages of type POSTED_SMS, parses the body XML and creates an SMS instances @n  */
    01749         bool GetSMS(
    01750                 SmsRef& sms
    01751         );
    01752
    01753         /** Deletes this message from the local database. These deletions do not propagate to the other Skype instances that the user may have on other computers. Nor do they affect other participants that have the same message. This method is specifically from removing Message objects from the database - not for removing Messages from conversations. To remove a Message from a conversation, use Message::Edit method to replace the existing body text with an empty string. @n  */
    01754         bool DeleteLocally(
    01755         );
    01756
    01757         /** Message::P_CONVO_ID property get accessor */
    01758         bool GetPropConvoId(ConversationRef& convo_id);
    01759
    01760         /** Message::P_CONVO_GUID property get accessor */
    01761         bool GetPropConvoGuid(Sid::String& convo_guid);
    01762
    01763         /** Message::P_AUTHOR property get accessor */
    01764         bool GetPropAuthor(Sid::String& author);
    01765
    01766         /** Message::P_AUTHOR_DISPLAYNAME property get accessor */
    01767         bool GetPropAuthorDisplayname(Sid::String& author_displayname);
    01768
    01769         /** Message::P_GUID property get accessor */
    01770         bool GetPropGuid(Sid::Binary& guid);
    01771
    01772         /** Message::P_ORIGINALLY_MEANT_FOR property get accessor */
    01773         bool GetPropOriginallyMeantFor(Sid::String& originally_meant_for);
    01774
    01775         /** Message::P_TIMESTAMP property get accessor */
    01776         bool GetPropTimestamp(uint& timestamp);
    01777
    01778         /** Message::P_TYPE property get accessor */
    01779         bool GetPropType(Message::TYPE& type);
    01780
    01781         /** Message::P_SENDING_STATUS property get accessor */
    01782         bool GetPropSendingStatus(Message::SENDING_STATUS& sending_status);
    01783
    01784         /** Message::P_CONSUMPTION_STATUS property get accessor */
    01785         bool GetPropConsumptionStatus(Message::CONSUMPTION_STATUS& consumption_status);
    01786
    01787         /** Message::P_EDITED_BY property get accessor */
    01788         bool GetPropEditedBy(Sid::String& edited_by);
    01789
    01790         /** Message::P_EDIT_TIMESTAMP property get accessor */
    01791         bool GetPropEditTimestamp(uint& edit_timestamp);
    01792
    01793         /** Message::P_PARAM_KEY property get accessor */
    01794         bool GetPropParamKey(uint& param_key);
    01795
    01796         /** Message::P_PARAM_VALUE property get accessor */
    01797         bool GetPropParamValue(uint& param_value);
    01798
    01799         /** Message::P_BODY_XML property get accessor */
    01800         bool GetPropBodyXml(Sid::String& body_xml);
    01801
    01802         /** Message::P_IDENTITIES property get accessor */
    01803         bool GetPropIdentities(Sid::String& identities);
    01804
    01805         /** Message::P_REASON property get accessor */
    01806         bool GetPropReason(Sid::String& reason);
    01807
    01808         /** Message::P_LEAVEREASON property get accessor */
    01809         bool GetPropLeavereason(LEAVE_REASON& leavereason);
    01810
    01811         /** Message::P_PARTICIPANT_COUNT property get accessor */
    01812         bool GetPropParticipantCount(uint& participant_count);
    01813
    01814 };
    01815
    01816
    01817 /*! \class Video skype-embedded_2.h "skype-embedded_2.h"
    01818  *  \brief
    01819  *  \nosubgrouping
    01820  *  This class contains basic video control functionality for live conversations with video. Basically, Video objects
    01821  *  represent specific Participant's video state in a live Conversation. The Video class can represent both local
    01822  *  (outgoing) and remote (incoming) video streams. Note that as of SkypeKit SDK version 3.2, this class no longer
    01823  *  handles video rendering in the UI. @brief Currently available SkypeKit runtimes do not support multi-party video.
    01824  *  The API however is designed with future compatibility in mind, so the Video class is attached to Participant class
    01825  *  rather than Conversation class. Once multi-party video will become available for SkypeKit, the logic should go like
    01826  *  this: @n  @n Let there be 4-way live conversation C and participants P1, P2, P3 and P4. P1 is the local user. Remote
    01827  *  participants P2 and P3 are capable of sending video. Remote user P4 is not capable of sending video. You would then
    01828  *  end up with 4 video objects: V1, V2, V3 and V0. @n  @li C->P1->V1-> outgoing video stream @li C->P2->V2-> incoming
    01829  *  video stream 1 @li C->P3->V3-> incoming video stream 2 @li C->P4-> no video object as participant P4 does not
    01830  *  advertise supporting video @li V0-> local webcam preview - this is not attached to any particular conversation,
    01831  *  however the corresponding video object can be retrieved with Skype::GetPreviewVideo method. @n  @n As getting from a
    01832  *  live conversation to running video streams involves three classes, it can be somewhat less than obvious. The basic
    01833  *  state transition logic goes like this: @n  @n You start out with a Conversation, that suddenly becomes live @n  @n
    01834  *  CONVERSATION::LOCAL_LIVESTATUS = IM_LIVE @n At this point you have access to participant list of that conversation.
    01835  *  The next step will be to catch Partcipant property changes for PARTICIPANT::VIDEO_STATUS to see if any of the people
    01836  *  in conversation have Video available. Note that you should not make assumptions on when this availability happens.
    01837  *  Remote users may switch their video on-off as they please. @n  @n PARTICIPANT::VIDEO_STATUS = VIDEO_AVAILABLE @n If
    01838  *  you get to VIDEO_AVAILABLE (not necessarily for all Participants), you can retrieve Video object, with
    01839  *  Participant::GetVideo method. @n  @n Now you will need to handle Video::STATUS property changes. In case of
    01840  *  successful video call, the sequence of Video::STATUS and Participant::VIDEO_STATUS changes for each Participant and
    01841  *  Video object should look like this: @n  @li Video::STATUS = AVAILABLE @li Video::STATUS = STARTING @li Video::STATUS
    01842  *  = CHECKING_SUBSCRIPTION @li Video::STATUS = STARTING @n  @n Participant::VIDEO_STATUS = VIDEO_CONNECTING @li
    01843  *  Video::STATUS = RUNNING @li Participant::VIDEO_STATUS = STREAMING @n Both Video::STATUS == RUNNING and
    01844  *  Participant::VIDEO_STATUS == STREAMING are indicative that the video for that particular participant is up and
    01845  *  running, and your UI should update itself accordingly. @n  @n NB! Note that it is not enough to check for
    01846  *  Video::STATUS property updates. By the time you obtain the Video object in your client, it may already it may
    01847  *  already have progressed to a further status. You should always check the status property immediately after obtaining
    01848  *  the Video object. @n
    01849  */
    01850 class Video : public SEObject
    01851 {
    01852         /** \cond INTERNAL */
    01853         friend class Skype;
    01854 protected:
    01855         Video(unsigned int oid, SERootObject* root);
    01856         /** \endcond */
    01857 public:
    01858         virtual ~Video();
    01859         typedef VideoRef Ref;
    01860         typedef VideoRefs Refs;
    01861         enum { MODULE_ID = 11 };
    01862         VideoRef ref() {
    01863                 return VideoRef(object_id);
    01864         }
    01865
    01866 private:
    01867         String getNamespace() const;
    01868         const PMAP* getPMap() const;
    01869         const EMAP* getEMap() const;
    01870         unsigned int moduleID() const;
    01871         void __clear_cache(void*);
    01872
    01873 public:
    01874         /** Properties of the Video class */
    01875         enum PROPERTY {
    01876                 P_STATUS = 130                  /*!< Video::STATUS, type: STATUS*/,
    01877                 P_ERROR                         /*!< 'errorcode errortext' , type: Sid::String*/,
    01878                 P_DEBUGINFO                     /*!< space-separated string of tokens, type: Sid::String*/,
    01879                 P_DIMENSIONS                    /*!< This property does not currently work, always containing an empty string. For desktop video, you can get the frame dimensions from the video frame buffers API instead - the buffer struct retrieved with ipc.getFrame() or ipc.getNewFrame() has width and height fields, which you can then use in your UI. With RTP video solutions, you already have the frame sizes in your videohost code. Communicating these to the UI process is currently up to you. @n , type: Sid::String*/,
    01880                 P_MEDIA_TYPE                    /*!< Indicates whether the video object is streaming webcam video or screensharing session, values: MEDIA_SCREENSHARING, MEDIA_VIDEO @n , type: MEDIATYPE*/,
    01881                 P_CONVO_ID = 1104               /*!< conference id to be able to identify remote/local video in the same call, type: ConversationRef*/,
    01882                 P_DEVICE_PATH                   /*!< device path used by video object, type: Sid::String*/
    01883         };
    01884
    01885         /** Setupkey SETUPKEY_VIDEO_DEVICE type:string  @n Selected video device name @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01886         #define SETUPKEY_VIDEO_DEVICE "Lib/Video/Device"
    01887
    01888         /** Setupkey SETUPKEY_VIDEO_DEVICE_PATH type:string  @n Currently selected video device path. @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01889         #define SETUPKEY_VIDEO_DEVICE_PATH "Lib/Video/DevicePath"
    01890
    01891         /** Setupkey SETUPKEY_VIDEO_AUTOSEND type:int  @n Setting this to 1 starts sending video automatically when call starts @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01892         #define SETUPKEY_VIDEO_AUTOSEND "Lib/Video/AutoSend"
    01893
    01894         /** Setupkey SETUPKEY_VIDEO_DISABLE type:int  @n Setting this to 1 disables all video functionality. @n This setup key is machine-specific and affects all local accounts. @n  */
    01895         #define SETUPKEY_VIDEO_DISABLE "*Lib/Video/Disable"
    01896
    01897         /** Setupkey SETUPKEY_VIDEO_RECVPOLICY type:string default value:"contacts" @n noone | contacts | callpolicy @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01898         #define SETUPKEY_VIDEO_RECVPOLICY "Lib/Video/RecvPolicy"
    01899
    01900         /** Setupkey SETUPKEY_VIDEO_ADVERTPOLICY type:string default value:"contacts" @n noone | contacts | everyone @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    01901         #define SETUPKEY_VIDEO_ADVERTPOLICY "Lib/Video/AdvertPolicy"
    01902
    01903         enum STATUS {
    01904                 NOT_AVAILABLE = 0,
    01905                 AVAILABLE,
    01906                 STARTING,
    01907                 REJECTED,
    01908                 RUNNING,
    01909                 STOPPING,
    01910                 PAUSED,
    01911                 NOT_STARTED,
    01912                 HINT_IS_VIDEOCALL_RECEIVED,
    01913                 UNKNOWN,
    01914                 RENDERING,
    01915                 CHECKING_SUBSCRIPTION,
    01916                 SWITCHING_DEVICE
    01917         };
    01918
    01919         enum MEDIATYPE {
    01920                 MEDIA_SCREENSHARING = 1,
    01921                 MEDIA_VIDEO = 0
    01922         };
    01923
    01924         enum VIDEO_DEVICE_CAPABILITY {
    01925                 VIDEOCAP_HQ_CAPABLE = 0,
    01926                 VIDEOCAP_HQ_CERTIFIED,
    01927                 VIDEOCAP_REQ_DRIVERUPDATE,
    01928                 VIDEOCAP_USB_HIGHSPEED
    01929         };
    01930
    01931         bool SetScreen(
    01932                 const uint& windowh
    01933         );
    01934
    01935         /** This method starts either video send or video receive, depending on whether the video object is sender or receiver. In case of desktop video, the receiver side needs to instantiate a renderer object and associate it with the receiveing video (Video::SetRemoteRendererId).  @n  */
    01936         bool Start(
    01937         );
    01938
    01939         /** This method stops either video send or video receive, depending on whether the video object is sender or receiver. In case of desktop video, the receiver side needs to dis-associate the video object from the renderer, by calling Video::SetRemoteRendererId(0).  @n  */
    01940         bool Stop(
    01941         );
    01942
    01943         bool SubmitCaptureRequest(
    01944                 bool& ret,
    01945                 uint& requestId
    01946         );
    01947
    01948         virtual void OnCaptureRequestCompleted(
    01949                 const uint& requestId,
    01950                 const bool& isSuccessful,
    01951                 const Sid::Binary& image,
    01952                 const int& width,
    01953                 const int& height
    01954         );
    01955
    01956         /** This method has no known effect in current version. @n  */
    01957         bool SetScreenCaptureRectangle(
    01958                 const int& x0,
    01959                 const int& y0,
    01960                 const uint& width,
    01961                 const uint& height,
    01962                 const int monitorNumber = 0,
    01963                 const uint windowHandle = 0
    01964         );
    01965
    01966         bool SetRenderRectangle(
    01967                 const int& x0,
    01968                 const int& y0,
    01969                 const uint& width,
    01970                 const uint& height
    01971         );
    01972
    01973         bool SetRemoteRendererId(
    01974                 const uint& id
    01975         );
    01976
    01977         /** This method has no effect in current version. @n  */
    01978         bool SelectVideoSource(
    01979                 const Video::MEDIATYPE& mediaType,
    01980                 const Sid::String webcamName = "",
    01981                 const Sid::String devicePath = "",
    01982                 const bool updateSetup = false
    01983         );
    01984
    01985         bool GetCurrentVideoDevice(
    01986                 MEDIATYPE& mediatype,
    01987                 Sid::String& deviceName,
    01988                 Sid::String& devicePath
    01989         );
    01990
    01991         /** Video::P_STATUS property get accessor */
    01992         bool GetPropStatus(STATUS& status);
    01993
    01994         /** Video::P_ERROR property get accessor */
    01995         bool GetPropError(Sid::String& error);
    01996
    01997         /** Video::P_DEBUGINFO property get accessor */
    01998         bool GetPropDebuginfo(Sid::String& debuginfo);
    01999
    02000         /** Video::P_DIMENSIONS property get accessor */
    02001         bool GetPropDimensions(Sid::String& dimensions);
    02002
    02003         /** Video::P_MEDIA_TYPE property get accessor */
    02004         bool GetPropMediaType(MEDIATYPE& media_type);
    02005
    02006         /** Video::P_CONVO_ID property get accessor */
    02007         bool GetPropConvoId(ConversationRef& convo_id);
    02008
    02009         /** Video::P_DEVICE_PATH property get accessor */
    02010         bool GetPropDevicePath(Sid::String& device_path);
    02011
    02012 };
    02013
    02014
    02015 /*! \class Voicemail skype-embedded_2.h "skype-embedded_2.h"
    02016  *  \brief
    02017  *  \nosubgrouping
    02018  *  Wrapper class that includes voicemail-specific methods and properties. @brief In the Skype Conversation API,
    02019  *  Voicemail is actually something of a misnomer for what would be more accurately called Voice Message. @n  @n The
    02020  *  traditional Voicemail use case involves recording a voice message when an incoming call does not get answered in a
    02021  *  pre-determined amount of time. In the Skype Conversation API, voicemail does not depend on a call going unanswered -
    02022  *  you can post a voice message asynchronously into any dialog conversation at any time. @n  @n In fact, a high-level
    02023  *  action flow directing unanswered incoming live sessions to voicemail is not something provided by the Conversation
    02024  *  API - implementation of this use case is largely up to your UI. @n  @n The fact that your UI must retrieve incoming
    02025  *  Voicemails by monitoring changes to a Conversation instance's Messages illustrates this conceptual difference
    02026  *  between traditional voicemail and voice messages. The message type Message::POSTED_VOICE_MESSAGE indicates that a
    02027  *  Message instance should be handled as a voice message instead of by displaying its body text in the Conversation UI.
    02028  *  Message::GetVoiceMessage enables you to retrieve the associated Voicemail instance; Voicemail::StartPlayback enables
    02029  *  you to listen to the message audio. @n  @n To put it another way, the object chain goes like this:  @n @code @n
    02030  *  Contact->Conversation->Message->Voicemail  @n @endcode  @n  @n There are three basic types of Voicemail objects: @li
    02031  *  INCOMING - received voice messages that can be retrieved from Message objects; @li OUTGOING - outbound voice
    02032  *  messages that can be created with Conversation::StartVoiceMessage; @li GREETING - voice messages that represent
    02033  *  auto-answer greetings, either recorded by the user (CUSTOM_GREETING) or included as part of SkypeKit
    02034  *  (DEFAULT_GREETING). This is the audio that gets played back to sender of the voice message before he can start
    02035  *  recording his voice message. @n  @n Before trying to send out a voicemail, you should ensure that target Contact has
    02036  *  the capability to receive them. Use Contact::GetCapabilityStatus to check for Contact::CAPABILITY_CAN_BE_SENT_VM. @n
    02037  *  @n Recording and Sending a Voice Message @n  @n The first step is to obtain a dialog Conversation with the target
    02038  *  Contact. In that conversation, you can initiate the outgoing voice message with Conversation::StartVoiceMessage @n
    02039  *  @n Note that this call does not return an actual Voicemail object. To catch when an object gets created, you will
    02040  *  need to check Conversation::P_ACTIVE_VM_ID property updates. @n  @n After invoking Conversation::StartVoiceMessage,
    02041  *  SkypeKit instantiates a Voicemail instance for the target Contact's greeting (with type CUSTOM_GREETING or
    02042  *  DEFAULT_GREETING). At this point, the Conversation::P_ACTIVE_VM_ID property update fires, newVM contains a reference
    02043  *  to the greeting, and playback of the greeting for the sender starts automatically.  @n  @n Once the greeting
    02044  *  playback finishes, SkypeKit instantiates a second Voicemail instance for the outgoing voice message. At this point,
    02045  *  the Conversation::P_ACTIVE_VM_ID property update fires again, newVM now contains a reference to the outgoing
    02046  *  message, and recording starts automatically. If you want to include notification and/or error handling for whether
    02047  *  this message was sent successfully, you should make a copy of newVM now. @n  @n Once the user finishes (or abandons)
    02048  *  recording of their message, they want to either send the message or to cancel it. To send the message, use
    02049  *  Conversation::PostVoiceMessage; to cancel the message, use Conversation::LeaveLiveSession. @n  @n Both of these
    02050  *  actions results in the Conversation::P_ACTIVE_VM_ID property update firing for a third time, setting the value to
    02051  *  NULL. However, the Voicemail object will actually continue its existence past this point. Saving a reference to the
    02052  *  message's Voicemail object when you start recording it enables you to keep receiving Voicemail property updates.
    02053  *  This in turn enables your UI to check whether voice message send succeeded or failed. @n  @n The relevant terminal
    02054  *  state Voicemail::P_STATUS property values are: @li Voicemail::CANCELLED - recording and/or sending of this message
    02055  *  was cancelled @li Voicemail::UPLOADED - message sent @li Voicemail::FAILED - message could not be sent @n  @n
    02056  *  Receiving and Playing Back a Voice Message @n  @n On the remote side, the Voicemail appears as a Message object of
    02057  *  type Message::POSTED_VOICE_MESSAGE. The message's author property contains the Skype Name of the Voicemail
    02058  *  originator, and its BodyXml property contains the message length and title text in following format: @n  @n @code @n
    02059  *  <voicemail alt="Sent voicemail to people in this conversation."><message length="5" ></message></voicemail>  @n
    02060  *  @endcode @n  @n Receiver side UI can then retrieve the Voicemail object from the message with
    02061  *  Message::GetVoiceMessage and @n start local playback with Message::StartPlayback. @n
    02062  */
    02063 class Voicemail : public SEObject
    02064 {
    02065         /** \cond INTERNAL */
    02066         friend class Skype;
    02067 protected:
    02068         Voicemail(unsigned int oid, SERootObject* root);
    02069         /** \endcond */
    02070 public:
    02071         virtual ~Voicemail();
    02072         typedef VoicemailRef Ref;
    02073         typedef VoicemailRefs Refs;
    02074         enum { MODULE_ID = 7 };
    02075         VoicemailRef ref() {
    02076                 return VoicemailRef(object_id);
    02077         }
    02078
    02079 private:
    02080         String getNamespace() const;
    02081         const PMAP* getPMap() const;
    02082         const EMAP* getEMap() const;
    02083         unsigned int moduleID() const;
    02084         void __clear_cache(void*);
    02085
    02086 public:
    02087         /** Properties of the Voicemail class */
    02088         enum PROPERTY {
    02089                 P_TYPE = 100                    /*!< type: TYPE*/,
    02090                 P_PARTNER_HANDLE                /*!< registered username of the other party, type: Sid::String*/,
    02091                 P_PARTNER_DISPNAME              /*!< user's display name of the other party, type: Sid::String*/,
    02092                 P_STATUS                        /*!< type: STATUS*/,
    02093                 P_FAILUREREASON                 /*!< type: FAILUREREASON*/,
    02094                 P_SUBJECT                       /*!< DEPRECATED: subject line, type: Sid::String*/,
    02095                 P_TIMESTAMP                     /*!< timestamp of creation, type: uint*/,
    02096                 P_DURATION                      /*!< duration in seconds, type: uint*/,
    02097                 P_ALLOWED_DURATION              /*!< max allowed duration in seconds, type: uint*/,
    02098                 P_PLAYBACK_PROGRESS             /*!< VM playback progress in seconds, type: uint*/,
    02099                 P_CONVO_ID = 830                /*!< CONVERSATION_ID of corresponding conversation, type: ConversationRef*/,
    02100                 P_CHATMSG_GUID                  /*!< GUID of the message that the VM is tied to, type: Sid::Binary*/
    02101         };
    02102
    02103         enum TYPE {
    02104                 INCOMING = 1,
    02105                 DEFAULT_GREETING = 4,
    02106                 CUSTOM_GREETING = 2,
    02107                 OUTGOING
    02108         };
    02109
    02110         enum STATUS {
    02111                 NOTDOWNLOADED = 1,
    02112                 DOWNLOADING,
    02113                 UNPLAYED,
    02114                 BUFFERING,
    02115                 PLAYING,
    02116                 PLAYED,
    02117                 BLANK,
    02118                 RECORDING,
    02119                 RECORDED,
    02120                 UPLOADING,
    02121                 UPLOADED,
    02122                 DELETING,
    02123                 FAILED,
    02124                 DELETING_FAILED,
    02125                 CHECKING,
    02126                 CANCELLED
    02127         };
    02128
    02129         enum FAILUREREASON {
    02130                 MISC_ERROR = 1,
    02131                 CONNECT_ERROR,
    02132                 NO_VOICEMAIL_CAPABILITY,
    02133                 NO_SUCH_VOICEMAIL,
    02134                 FILE_READ_ERROR,
    02135                 FILE_WRITE_ERROR,
    02136                 RECORDING_ERROR,
    02137                 PLAYBACK_ERROR,
    02138                 NO_PERMISSION,
    02139                 RECEIVER_DISABLED_VOICEMAIL   /*!< receiver turned off voicemail*/,
    02140                 SENDER_NOT_AUTHORIZED         /*!< receiver has not authorized you and privacy is not set to anyone*/,
    02141                 SENDER_BLOCKED                /*!< receiver blocked sender*/
    02142         };
    02143
    02144         /** Start recording your own auto-answer greeting message (leave message after the beep...) only. Recording of outgoing Voicemail messages start automatically (using Conversation::StartVoiceMessage) after playback of the remote side greeting message has finished. @n  */
    02145         bool StartRecording(
    02146         );
    02147
    02148         /** Stop recording of your own auto-answer greeting message only. To stop recording of and send an outgoing Voicemail, use Conversation::PostVoiceMessage. @n  */
    02149         bool StopRecording(
    02150         );
    02151
    02152         /** Initiates playback of a voice message @n  */
    02153         bool StartPlayback(
    02154         );
    02155
    02156         /** Terminates playback of a voice message @n  */
    02157         bool StopPlayback(
    02158         );
    02159
    02160         /** first from server, and then the local copy */
    02161         bool Delete(
    02162         );
    02163
    02164         /** Canceling recording of your own auto-answer greeting message. To stop recording of and cancel an outgoing Voicemail, use Conversation::LeaveLiveSession. @n  */
    02165         bool Cancel(
    02166         );
    02167
    02168         /** check if we can send voicemail (unauth,blocked,no priv etc cases). only OUTGOING */
    02169         bool CheckPermission(
    02170                 bool& result
    02171         );
    02172
    02173         /** Voicemail::P_TYPE property get accessor */
    02174         bool GetPropType(TYPE& type);
    02175
    02176         /** Voicemail::P_PARTNER_HANDLE property get accessor */
    02177         bool GetPropPartnerHandle(Sid::String& partner_handle);
    02178
    02179         /** Voicemail::P_PARTNER_DISPNAME property get accessor */
    02180         bool GetPropPartnerDispname(Sid::String& partner_dispname);
    02181
    02182         /** Voicemail::P_STATUS property get accessor */
    02183         bool GetPropStatus(STATUS& status);
    02184
    02185         /** Voicemail::P_FAILUREREASON property get accessor */
    02186         bool GetPropFailurereason(FAILUREREASON& failurereason);
    02187
    02188         /** Voicemail::P_SUBJECT property get accessor */
    02189         bool GetPropSubject(Sid::String& subject);
    02190
    02191         /** Voicemail::P_TIMESTAMP property get accessor */
    02192         bool GetPropTimestamp(uint& timestamp);
    02193
    02194         /** Voicemail::P_DURATION property get accessor */
    02195         bool GetPropDuration(uint& duration);
    02196
    02197         /** Voicemail::P_ALLOWED_DURATION property get accessor */
    02198         bool GetPropAllowedDuration(uint& allowed_duration);
    02199
    02200         /** Voicemail::P_PLAYBACK_PROGRESS property get accessor */
    02201         bool GetPropPlaybackProgress(uint& playback_progress);
    02202
    02203         /** Voicemail::P_CONVO_ID property get accessor */
    02204         bool GetPropConvoId(ConversationRef& convo_id);
    02205
    02206         /** Voicemail::P_CHATMSG_GUID property get accessor */
    02207         bool GetPropChatmsgGuid(Sid::Binary& chatmsg_guid);
    02208
    02209 };
    02210
    02211
    02212 /*! \class Sms skype-embedded_2.h "skype-embedded_2.h"
    02213  *  \brief
    02214  *  \nosubgrouping
    02215  *  Wrapper class that includes SMS-specific properties and methods, such as P_BODY and GetTargetPrice. Instantiate SMS
    02216  *  instances using Skype::CreateOutgoingSms; post SMS messages to a Conversation using Conversation::PostSMS. @brief
    02217  *  @n  @n Each SMS can have multiple targets (normalized phone numbers). Note that in a Conversation context, every SMS
    02218  *  instance has a corresponding Message instance. Once you've posted an SMS, you can retrieve its corresponding Message
    02219  *  instance using Sms::GetPropChatmsgId. That Message instance's P_BODY_XML property contains the SMS message data,
    02220  *  such as price, target phone number(s), failure codes, and so forth, which you can parsed out and display in the UI.
    02221  *  To put it another way, the object chain goes like this: @n  @n @code @n Conversation->Message->SMS  @n @endcode @n
    02222  *  @n Note that SkypeKit SDK supports outgoing SMS messages only. SkypeKit clients, even when logged in with accounts
    02223  *  that have SkypeIn numbers, cannot receive SMS messages. @n
    02224  */
    02225 class Sms : public SEObject
    02226 {
    02227         /** \cond INTERNAL */
    02228         friend class Skype;
    02229 protected:
    02230         Sms(unsigned int oid, SERootObject* root);
    02231         /** \endcond */
    02232 public:
    02233         virtual ~Sms();
    02234         typedef SmsRef Ref;
    02235         typedef SmsRefs Refs;
    02236         enum { MODULE_ID = 12 };
    02237         SmsRef ref() {
    02238                 return SmsRef(object_id);
    02239         }
    02240
    02241 private:
    02242         String getNamespace() const;
    02243         const PMAP* getPMap() const;
    02244         const EMAP* getEMap() const;
    02245         unsigned int moduleID() const;
    02246         void __clear_cache(void*);
    02247
    02248 public:
    02249         /** Properties of the Sms class */
    02250         enum PROPERTY {
    02251                 P_TYPE = 190                    /*!< type: TYPE*/,
    02252                 P_STATUS                        /*!< type: STATUS*/,
    02253                 P_FAILUREREASON                 /*!< Set asynchronously and meaningful only after invoking Conversation::PostSMS and detecting Sms::STATUS of SOME_TARGETS_FAILED or FAILED. @n , type: FAILUREREASON*/,
    02254                 P_IS_FAILED_UNSEEN = 48         /*!< set to 1 when status goes to FAILED. use MarkSeen() to clear, type: bool*/,
    02255                 P_TIMESTAMP = 198               /*!< unix timestamp of message submission, type: uint*/,
    02256                 P_PRICE = 193                   /*!< The total price of sending this SMS message (sum of the individual prices to send to each recipient). Defaults to -1 on instantiation and incremented by the price for each recipient once that recipient's status reflects TARGET_ACCEPTABLE. Use Sms::GetTargetPrice to retrieve individual target prices. @n  @n A value of MAX_UINT indicates that SkypeKit is actively querying and/or updating the value. Note that P_PRICE is an integer value. Calculate the actual price (in units specified by P_PRICE_CURRENCY) using P_PRICE_PRECISION as: @n  @n @code @n actualPrice = price / 10^pricePrecision;  @n @endcode @n , type: uint*/,
    02257                 P_PRICE_PRECISION = 49          /*!< The decimal precision of the SMS price values, both individual and total. For example, a value of 2 indicates that you should divide the price (represented as an integer) by 100 (10^2) to obtain the actual price. @n , type: uint*/,
    02258                 P_PRICE_CURRENCY = 194          /*!< should be same as account currency at the time of composing/sending, type: Sid::String*/,
    02259                 P_REPLY_TO_NUMBER = 199         /*!< number that should receive the replies, type: Sid::String*/,
    02260                 P_TARGET_NUMBERS = 195          /*!< space-separated normalised pstn numbers, type: Sid::String*/,
    02261                 P_TARGET_STATUSES               /*!< binary blob. track with OnPropertyChange(), access with GetTargetStatus(target), type: Sid::Binary*/,
    02262                 P_BODY                          /*!< actual payload, type: Sid::String*/,
    02263                 P_CHATMSG_ID = 840              /*!< reference to Message, type: MessageRef*/
    02264         };
    02265
    02266         enum TYPE {
    02267                 OUTGOING = 2                  /*!< a normal outgoing SMS message*/,
    02268                 CONFIRMATION_CODE_REQUEST     /*!< a message requesting a SMS confirmation code be sent to the number provided*/,
    02269                 CONFIRMATION_CODE_SUBMIT      /*!< a message returning the SMS confirmation code received as a result of a CONFIRMATION_CODE_REQUEST to authorize it*/
    02270         };
    02271
    02272         enum STATUS {
    02273                 COMPOSING = 3,
    02274                 SENDING_TO_SERVER,
    02275                 SENT_TO_SERVER,
    02276                 DELIVERED,
    02277                 SOME_TARGETS_FAILED,
    02278                 FAILED
    02279         };
    02280
    02281         enum FAILUREREASON {
    02282                 MISC_ERROR = 1,
    02283                 SERVER_CONNECT_FAILED,
    02284                 NO_SMS_CAPABILITY,
    02285                 INSUFFICIENT_FUNDS,
    02286                 INVALID_CONFIRMATION_CODE,
    02287                 USER_BLOCKED,
    02288                 IP_BLOCKED,
    02289                 NODE_BLOCKED,
    02290                 NO_SENDERID_CAPABILITY
    02291         };
    02292
    02293         enum TARGETSTATUS {
    02294                 TARGET_ANALYZING = 1,
    02295                 TARGET_UNDEFINED,
    02296                 TARGET_ACCEPTABLE,
    02297                 TARGET_NOT_ROUTABLE,
    02298                 TARGET_DELIVERY_PENDING,
    02299                 TARGET_DELIVERY_SUCCESSFUL,
    02300                 TARGET_DELIVERY_FAILED
    02301         };
    02302
    02303         /** Retrieves the send status of this SMS to a particular recipient (P_TARGET_STATUSES) either prior to or after invoking Conversation::PostSMS. @n  */
    02304         bool GetTargetStatus(
    02305                 const Sid::String& target, /*!< The normalized phone number of the target recipient. @n */
    02306                 TARGETSTATUS& status /*!< The send status of the target recipient, for example, TARGET_ANALYZING, TARGET_DELIVERY_PENDING, TARGET_DELIVERY_SUCCESSFUL, TARGET_DELIVERY_FAILED, and so forth. TARGET_UNDEFINED implies that the specified target is not a recipient of this SMS. @n */
    02307         );
    02308
    02309         /** Retrieves the amount of Skype credit necessary to send the SMS to a particular recipient. Defaults to -1 on instantiation and set only when that recipient's status reflects TARGET_ACCEPTABLE. Use Sms::GetPropPrice to retrieve the total cost of this SMS. @n  @n Note that the target price is an integer value. Calculate the actual price (in units specified by P_PRICE_CURRENCY) using P_PRICE_PRECISION as: @n @code @n actualTargetPrice = targetPrice / 10^pricePrecision;  @n @endcode @n  */
    02310         bool GetTargetPrice(
    02311                 const Sid::String& target, /*!< The normalized phone number of the target recipient. @n */
    02312                 uint& price /*!< The price of sending this SMS message to the target recipient. @n */
    02313         );
    02314
    02315         enum SETBODYRESULT {
    02316                 BODY_INVALID = 0              /*!< body not set. message status wrong or invalid, or body not valid utf8 string*/,
    02317                 BODY_TRUNCATED                /*!< body too long. set, but truncated. charsUntilNextChunk contains maxChunks value*/,
    02318                 BODY_OK                       /*!< body was set OK*/,
    02319                 BODY_LASTCHAR_IGNORED         /*!< last unicode char was ignored, as some of the text would be deleted due to conversion*/
    02320         };
    02321
    02322         /** Sets the recipient(s) of this SMS. Note that each invocation replaces the target list and re-calculates all prices - they are not additive! @n  */
    02323         bool SetTargets(
    02324                 const Sid::List_String& numbers, /*!< Normalized phone number(s) of the intended recipient(s). @n */
    02325                 bool& success /*!< Set to true if the target list appears to contain valid, normalized telephone numbers. Note that this check is not very reliable. Actual target validity checking occurs asynchronously in the background, and manifests itself as a series of Sms::P_TARGET_STATUSES property change events. @n */
    02326         );
    02327
    02328         /** -The- method for setting the body text of this SMS. While Conversation::PostSMS does have a body argument, that argument is currently unused. @n  */
    02329         bool SetBody(
    02330                 const Sid::String& text, /*!< Message body text. @n */
    02331                 SETBODYRESULT& result, /*!< Whether the Message body was successfully set and if not, why not. @n */
    02332                 Sid::List_String& chunks, /*!< The Message body as a list of individual chunks. @n */
    02333                 uint& charsUntilNextChunk /*!< Number of available characters until creation of the next chunk becomes necessary. @n */
    02334         );
    02335
    02336         /** Retrieves string list of SMS text chunks in first argument, while the second argument contains the number of available characters until creation of the next chunk becomes necessary. @n  */
    02337         bool GetBodyChunks(
    02338                 Sid::List_String& textChunks, /*!< List of text chunk strings @n */
    02339                 uint& charsUntilNextChunk /*!< Number of available characters until creation of the next chunk becomes necessary. @n */
    02340         );
    02341
    02342         enum CONFIRM_TYPE {
    02343                 ID_SMS = 1                    /*!< Confirm mobile number as SMS sender number*/,
    02344                 ID_MOBILE                     /*!< Confirm mobile number as CLI for SkypeOut calls*/,
    02345                 ID_SKYPEIN                    /*!< unused currently*/
    02346         };
    02347
    02348         /** Sms::P_TYPE property get accessor */
    02349         bool GetPropType(TYPE& type);
    02350
    02351         /** Sms::P_STATUS property get accessor */
    02352         bool GetPropStatus(STATUS& status);
    02353
    02354         /** Sms::P_FAILUREREASON property get accessor */
    02355         bool GetPropFailurereason(FAILUREREASON& failurereason);
    02356
    02357         /** Sms::P_IS_FAILED_UNSEEN property get accessor */
    02358         bool GetPropIsFailedUnseen(bool& is_failed_unseen);
    02359
    02360         /** Sms::P_TIMESTAMP property get accessor */
    02361         bool GetPropTimestamp(uint& timestamp);
    02362
    02363         /** Sms::P_PRICE property get accessor */
    02364         bool GetPropPrice(uint& price);
    02365
    02366         /** Sms::P_PRICE_PRECISION property get accessor */
    02367         bool GetPropPricePrecision(uint& price_precision);
    02368
    02369         /** Sms::P_PRICE_CURRENCY property get accessor */
    02370         bool GetPropPriceCurrency(Sid::String& price_currency);
    02371
    02372         /** Sms::P_REPLY_TO_NUMBER property get accessor */
    02373         bool GetPropReplyToNumber(Sid::String& reply_to_number);
    02374
    02375         /** Sms::P_TARGET_NUMBERS property get accessor */
    02376         bool GetPropTargetNumbers(Sid::String& target_numbers);
    02377
    02378         /** Sms::P_TARGET_STATUSES property get accessor */
    02379         bool GetPropTargetStatuses(Sid::Binary& target_statuses);
    02380
    02381         /** Sms::P_BODY property get accessor */
    02382         bool GetPropBody(Sid::String& body);
    02383
    02384         /** Sms::P_CHATMSG_ID property get accessor */
    02385         bool GetPropChatmsgId(MessageRef& chatmsg_id);
    02386
    02387 };
    02388
    02389
    02390 /*! \class Transfer skype-embedded_2.h "skype-embedded_2.h"
    02391  *  \brief
    02392  *  \nosubgrouping
    02393  *  Transfer in this context refers to transferring (sending/receiving) files among Skype Contacts, not transferring a
    02394  *  call to another Skype or PSTN Contact. This class includes file transfer-specific properties and methods, such as
    02395  *  FILESIZE, BYTESPERSECOND, Pause and Resume. Recipients of these file transfers must explicitly accept (or decline)
    02396  *  any incoming transfer. @brief Transfer instances represent files being sent and received within a Conversation
    02397  *  context. Each Transfer instance represents a single file transfer - if a conversation has multiple remote
    02398  *  participants, a separate Transfer instance must be instantiated for each remote participant (a Transfer instance is
    02399  *  not instantiated for the sender). @n  @n Transfer instances cannot be instantiated directly. Instead, you initiate a
    02400  *  file transfer by invoking Conversation::PostFiles. This instantiates a Message instance of type POSTED_FILES, which
    02401  *  is added to the Conversation for all the participants (including the sender). The Transfer instance is associated
    02402  *  with @n this Message instance, and the Message::P_BODY_XML looks like this: @n  @n @code @n Some text<files
    02403  *  alt=""><file size="2336020" index="0">test.zip</file></files>  @n @endcode @n  @n To put it another way, the object
    02404  *  chain goes like this: @n @code @n Conversation->Message->Transfer  @n @endcode @n  @n The first part of the message
    02405  *  (before the files section) comes from the Conversation::PostFiles body argument. For each file in the message, a
    02406  *  file section is provided with three fields: @li file size in bytes @li index - more or less arbitrary order in which
    02407  *  the transfers should be displayed in the UI @li file name. @n  @n For practical purposes, the Message::P_BODY_XML
    02408  *  property is not all that useful in this context. The Transfer instances, however, contain the state and progress
    02409  *  feedback for your UI. You retrieve these Transfer instances using Message::GetTransfers method. Since the sender can
    02410  *  post multiple files to @n a Conversation using the same Message, Message:GetTransfers retrieves a list of Transfer
    02411  *  instances - one per file per recipient. @n  @n You can determine the direction of particular Transfer instance by
    02412  *  querying Transfer::P_TYPE (INCOMING/OUTGOING).  @n  @n You can implement a progress indicator by monitoring
    02413  *  Transfer::P_BYTESTRANSFERRED. Note that when testing this on your local network, you will most likely catch these
    02414  *  property change events at the beginning and the end of the transfer only - which does not look like too useful.
    02415  *  However, for non-local network transfers where the transfer speeds are in the neighborhood of 200-300 KB per second,
    02416  *  you should consider implementing progress feedback as being mandatory and expect to catch multiple property change
    02417  *  events for all but the smallest files. @n  @n Another property of interest is Transfer::P_STATUS. The normal
    02418  *  transfer status sequence during successful outgoing transfer is this: @li TRANSFER STATUS -> NEW @li TRANSFER STATUS
    02419  *  -> WAITING_FOR_ACCEPT @li TRANSFER STATUS -> CONNECTING @li TRANSFER STATUS -> TRANSFERRING @li TRANSFER STATUS ->
    02420  *  CONNECTING @li TRANSFER STATUS -> COMPLETED @n  @n The list of all terminal Transfer statuses is: @li COMPLETED @li
    02421  *  FAILED @li CANCELLED @li CANCELLED_BY_REMOTE @n  @n In-progress transfers can be canceled with Transfer::Cancel and
    02422  *  paused/resumed with Transfer::Pause and Transfer::Resume. For transfers that complete with a status of FAILED, your
    02423  *  UI should provide feedback based on the value of Transfer::P_FAILUREREASON. @n  @n Incoming transfers, once
    02424  *  accepted, overwrite existing files with the same name. Before accepting an incoming file transfer, @n your UI should
    02425  *  prompt the recipient to: @li accept or decline the file @li if accepted, specify the directory of here to save the
    02426  *  file (with a pre-filled default) @li if accepted and a file having the same name already exists at the specified
    02427  *  destination, your UI should prompt for confirmation to overwrite and provide a way to alter the file name before
    02428  *  accepting it @n  @n Similarly, your UI should verify the existence of outgoing files prior to invoking
    02429  *  Conversation::PostFiles. @n  @n Note that you should provide both Conversation::PostFiles and Transfer::Accept
    02430  *  methods fully-qualified paths. Otherwise, the paths will be assumed to be relative to the path of SkypeKit runtime,
    02431  *  since the methods are actually executed in the runtime context. @n
    02432  */
    02433 class Transfer : public SEObject
    02434 {
    02435         /** \cond INTERNAL */
    02436         friend class Skype;
    02437 protected:
    02438         Transfer(unsigned int oid, SERootObject* root);
    02439         /** \endcond */
    02440 public:
    02441         virtual ~Transfer();
    02442         typedef TransferRef Ref;
    02443         typedef TransferRefs Refs;
    02444         enum { MODULE_ID = 6 };
    02445         TransferRef ref() {
    02446                 return TransferRef(object_id);
    02447         }
    02448
    02449 private:
    02450         String getNamespace() const;
    02451         const PMAP* getPMap() const;
    02452         const EMAP* getEMap() const;
    02453         unsigned int moduleID() const;
    02454         void __clear_cache(void*);
    02455
    02456 public:
    02457         /** Properties of the Transfer class */
    02458         enum PROPERTY {
    02459                 P_TYPE = 80                     /*!< INCOMING / OUTGOING @n , type: TYPE*/,
    02460                 P_PARTNER_HANDLE                /*!< Skype Name of the remote party of the file transfer. If a file is posted in a conversation with more than one participant, Transfer objects are created for each of them - so a transfer is always to one single remote target. @n , type: Sid::String*/,
    02461                 P_PARTNER_DISPNAME              /*!< Display name of the remote participant. @n , type: Sid::String*/,
    02462                 P_STATUS                        /*!< Current state of the transfer @n , type: STATUS*/,
    02463                 P_FAILUREREASON                 /*!< Set whenever P_STATUS transitions to FAILED. @n , type: FAILUREREASON*/,
    02464                 P_STARTTIME                     /*!< UNIX timestamp of when this Transfer instance was instantiated, not when the transfer process actually started (was accepted from receiver side). Do not use this property when calculate the data transfer speed! Instead, monitor changes to P_BYTESPERSECOND. @n , type: uint*/,
    02465                 P_FINISHTIME                    /*!< UNIX timestamp of when this Transfer COMPLETED or FAILED. This property is never set if the receiving side (local or remote) canceled the transfer. @n , type: uint*/,
    02466                 P_FILEPATH                      /*!< The path -and- filename of the file being transfered (typically fully qualified). For the receiver, SkypeKit sets this property upon acceptance of the incoming transfer. If not fully qualified, the path is assumed to be relative to the path of the SkypeKit runtime. @n , type: Sid::String*/,
    02467                 P_FILENAME                      /*!< The filename -only- of the file being transfered. The receiver side can use this property to pre-populate relevant UI components while prompting the user to accept the incoming transfer. @n , type: Sid::String*/,
    02468                 P_FILESIZE                      /*!< The size of the file being transferred in bytes. Depending on the magnitude of this value, your UI might want to display the size in terms of kilobytes or even megabytes. @n , type: Sid::String*/,
    02469                 P_BYTESTRANSFERRED              /*!< The number of bytes already transferred. Calculate the percentage of the file transferred so far as: @n @code @n P_BYTESTRANSFERRED / (P_FILESIZE / 100);  @n @endcode @n  @n Use float variables to avoid problems with files smaller than 100 bytes! @n , type: Sid::String*/,
    02470                 P_BYTESPERSECOND                /*!< Current data transfer speed in bytes per second. Typically, your UI will want to display this value as kilobytes per second (KBps). @n , type: uint*/,
    02471                 P_CHATMSG_GUID                  /*!< The "global ID" of this Transfer's associated Message instance. GUIDs are shared across Skype client instances and across all users that can see this Message. @n , type: Sid::Binary*/,
    02472                 P_CHATMSG_INDEX                 /*!< A more or less arbitrary index for ordering multiple file transfers within the UI. @n , type: uint*/,
    02473                 P_CONVO_ID = 98                 /*!< The "global ID" of this Transfer's associated Conversation (as chained through its associated Message). GUIDs are shared across Skype client instances and across all users that can see this Conversation. @n  @n Note that currently SkypeKit sets this property for INCOMING file transfers only and returns 0 (zero) for all sending side transfers. This is a known bug. @n , type: ConversationRef*/
    02474         };
    02475
    02476         enum TYPE {
    02477                 INCOMING = 1,
    02478                 OUTGOING
    02479         };
    02480
    02481         /** Recognized values for the P_STATUS property. Reflects current state of this Transfer. @n  */
    02482         enum STATUS {
    02483                 NEW = 0                       /*!< The file has either not been posted (sent) (OUTGOING), or not accepted (received) (INCOMING). @n */,
    02484                 CONNECTING                    /*!< A temporary state that transitions either into TRANSFERRING (relayed or direct) or to FAILED. For unknown reasons, outgoing transfers tend go into this state twice - immediately before the actual data transfer starts and immediately after it ends. @n */,
    02485                 WAITING_FOR_ACCEPT            /*!< The files have been posted but the recipient has not yet accepted (or has declined) the transfer. @n */,
    02486                 TRANSFERRING                  /*!< The transfer has been accepted and file data is being sent/received. Periodic updates of P_BYTESTRANSFERRED property should occur. @n */,
    02487                 TRANSFERRING_OVER_RELAY       /*!< The transfer has been accepted and file data is being sent/received but is going over at least one relay. Since relayed transfers tend to be significantly slower than direct transfers, you might want to differentiate the two in your UI and notify the user that relayed transfer typically take significantly longer to finish. @n */,
    02488                 PAUSED                        /*!< The local user (either the sender or a receiver) has paused the transfer. @n */,
    02489                 REMOTELY_PAUSED               /*!< A remote user has paused the transfer. For senders, a receiver has paused the transfer; for receivers, the sender has paused the transfer. @n */,
    02490                 CANCELLED                     /*!< Local side (either sender or receiver) has canceled the transfer. This is a final state of the STATE property. @n */,
    02491                 COMPLETED                     /*!< File transfer has completed. This is a terminal state. @n */,
    02492                 FAILED                        /*!< File transfer has failed. This is a terminal state. UI should provide feedback, based on value of P_FAILUREREASON. @n */,
    02493                 PLACEHOLDER                   /*!< Transfer whose existence has been hinted by corresponding chat message, but which is yet to arrive. @n */,
    02494                 OFFER_FROM_OTHER_INSTANCE     /*!< Outgoing transfer object from another instance of the same account as current local login, running on another system. Hinted through chat message - only implies an offer was made; not necessarily accepted, failed, or completed.  @n */,
    02495                 CANCELLED_BY_REMOTE           /*!< Remote side (either sender or receiver) has canceled the transfer. This is a final state of the STATE property. @n */
    02496         };
    02497
    02498         enum FAILUREREASON {
    02499                 SENDER_NOT_AUTHORISED = 1,
    02500                 REMOTELY_CANCELLED,
    02501                 FAILED_READ,
    02502                 FAILED_REMOTE_READ,
    02503                 FAILED_WRITE,
    02504                 FAILED_REMOTE_WRITE,
    02505                 REMOTE_DOES_NOT_SUPPORT_FT,
    02506                 REMOTE_OFFLINE_FOR_TOO_LONG,
    02507                 TOO_MANY_PARALLEL,
    02508                 PLACEHOLDER_TIMEOUT
    02509         };
    02510
    02511         /** Accepts an incoming file transfer and saves it to specified file on the local file system. If the specified file exists, SkypeKit will silently overwrite it. Your UI should prompting the user for confirmation in this case and provide a means for canceling the file transfer or specifying a different target file. @n  */
    02512         bool Accept(
    02513                 const Sid::Filename& filenameWithPath, /*!< Where on the local file system to save the file being transferred. Note that you should specify the path as being fully-qualified. Otherwise, SkypeKit will be assume it to be relative to the SkypeKit runtime path, since the method is actually executed in the runtime context. @n */
    02514                 bool& success /*!< Set to true if the specified target file was successfully created on the local file system -and- the initial write(s) succeeded. However, the transfer itself can subsequently fail before completion due to its being canceled (either locally or remotely), network failure, local file system space/write issues, and so forth. @n */
    02515         );
    02516
    02517         /** Temporarily pauses an in-progress incoming or outgoing file transfer. For incoming transfers, only this affects the sender and the invoking recipient only. For outgoing transfers, this affects the sender and all recipients. @n  */
    02518         bool Pause(
    02519         );
    02520
    02521         /** Resumes a previously paused file transfer. @n  */
    02522         bool Resume(
    02523         );
    02524
    02525         /** Cancels an in-progress file transfer. Transfer::STATUS will transition to CANCELLED for incoming file transfers and to CANCELLED_BY_REMOTE for outgoing transfers. @n  */
    02526         bool Cancel(
    02527         );
    02528
    02529         /** Transfer::P_TYPE property get accessor */
    02530         bool GetPropType(TYPE& type);
    02531
    02532         /** Transfer::P_PARTNER_HANDLE property get accessor */
    02533         bool GetPropPartnerHandle(Sid::String& partner_handle);
    02534
    02535         /** Transfer::P_PARTNER_DISPNAME property get accessor */
    02536         bool GetPropPartnerDispname(Sid::String& partner_dispname);
    02537
    02538         /** Transfer::P_STATUS property get accessor */
    02539         bool GetPropStatus(STATUS& status);
    02540
    02541         /** Transfer::P_FAILUREREASON property get accessor */
    02542         bool GetPropFailurereason(FAILUREREASON& failurereason);
    02543
    02544         /** Transfer::P_STARTTIME property get accessor */
    02545         bool GetPropStarttime(uint& starttime);
    02546
    02547         /** Transfer::P_FINISHTIME property get accessor */
    02548         bool GetPropFinishtime(uint& finishtime);
    02549
    02550         /** Transfer::P_FILEPATH property get accessor */
    02551         bool GetPropFilepath(Sid::String& filepath);
    02552
    02553         /** Transfer::P_FILENAME property get accessor */
    02554         bool GetPropFilename(Sid::String& filename);
    02555
    02556         /** Transfer::P_FILESIZE property get accessor */
    02557         bool GetPropFilesize(Sid::String& filesize);
    02558
    02559         /** Transfer::P_BYTESTRANSFERRED property get accessor */
    02560         bool GetPropBytestransferred(Sid::String& bytestransferred);
    02561
    02562         /** Transfer::P_BYTESPERSECOND property get accessor */
    02563         bool GetPropBytespersecond(uint& bytespersecond);
    02564
    02565         /** Transfer::P_CHATMSG_GUID property get accessor */
    02566         bool GetPropChatmsgGuid(Sid::Binary& chatmsg_guid);
    02567
    02568         /** Transfer::P_CHATMSG_INDEX property get accessor */
    02569         bool GetPropChatmsgIndex(uint& chatmsg_index);
    02570
    02571         /** Transfer::P_CONVO_ID property get accessor */
    02572         bool GetPropConvoId(ConversationRef& convo_id);
    02573
    02574 };
    02575
    02576
    02577 /*! \class Account skype-embedded_2.h "skype-embedded_2.h"
    02578  *  \brief
    02579  *  \nosubgrouping
    02580  *  Represents a local account. Encapsulates methods for Skype account creation, login and logout as well as account
    02581  *  profile setting properties. NB! Unlike all the other SkypeKit classes, most of the Account class properties are
    02582  *  actually read-write. @brief In fact, there are two sorts of Account's read-write properties: server-side properties
    02583  *  and local properties. Different setter methods need to be used for those two kinds. @n  @n The subset of server-side
    02584  *  properties consists of all the policy properties (everything with _POLICY suffix) that are all of type int and can
    02585  *  be set with SetServersideIntProperty method. There is currently only one server-side string property -
    02586  *  OFFLINE_CALLFORWARD which can be set with SetServersideStrProperty setter. @n  @n The set of writeable account
    02587  *  profile properties (local profile) is as follows; @li P_FULLNAME, @li P_BIRTHDAY, @li P_GENDER, @li P_LANGUAGES, @li
    02588  *  P_COUNTRY, @li P_PROVINCE, @li P_CITY, @li P_PHONE_HOME, @li P_PHONE_OFFICE, @li P_PHONE_MOBILE, @li P_EMAILS, @li
    02589  *  P_HOMEPAGE, @li P_ABOUT, @li P_MOOD_TEXT, @li P_TIMEZONE, @li P_AVATAR_IMAGE, @li P_RICH_MOOD_TEXT @n  @n These can
    02590  *  be set with SetIntProperty, SetStrProperty and SetBinProperty setter methods. Note that there are special methods
    02591  *  for changing account online status (availability) and enabling/disabling auto-login - SetAvailability and
    02592  *  SetSavePwd. @n  @n Note that to set Account properties, you that Account needs to be logged in. Generally,
    02593  *  assumption is that the first thing you do with an Account object after you retrieve it with Skype::GetAccount is
    02594  *  login, with exception of creating a new account. @n  @n The Account class has no default constructor and creating an
    02595  *  Account instance is not the same as creating a Skype account. To create a Skype account: @n  @li obtain an Account
    02596  *  instance by invoking Skype::GetAccount. This automatically sets P_SKYPENAME. @li set any additional profile-related
    02597  *  properties. Skype recommends that you minimally set the following: @li their email address so that they can retrieve
    02598  *  a lost password (P_EMAILS) @li the user's full name (P_FULLNAME) @li at least one phone number (P_PHONE_HOME,
    02599  *  P_PHONE_HOME, P_PHONE_OFFICE) @li invoke Account::Register to actually create the account @n
    02600  */
    02601 class Account : public SEObject
    02602 {
    02603         /** \cond INTERNAL */
    02604         friend class Skype;
    02605 protected:
    02606         Account(unsigned int oid, SERootObject* root);
    02607         /** \endcond */
    02608 public:
    02609         virtual ~Account();
    02610         typedef AccountRef Ref;
    02611         typedef AccountRefs Refs;
    02612         enum { MODULE_ID = 5 };
    02613         AccountRef ref() {
    02614                 return AccountRef(object_id);
    02615         }
    02616
    02617 private:
    02618         String getNamespace() const;
    02619         const PMAP* getPMap() const;
    02620         const EMAP* getEMap() const;
    02621         unsigned int moduleID() const;
    02622         void __clear_cache(void*);
    02623
    02624 public:
    02625         /** Properties of the Account class */
    02626         enum PROPERTY {
    02627                 P_STATUS = 70                   /*!< Account::STATUS, type: STATUS*/,
    02628                 P_PWDCHANGESTATUS               /*!< Account::PWDCHANGESTATUS, type: PWDCHANGESTATUS*/,
    02629                 P_LOGOUTREASON = 73             /*!< This property should only be examined when Account::P_STATUS is LOGGED_OUT or LOGGED_OUT_AND_PWD_SAVED. That is, you should not monitor changes to this property in Account::OnChange callback, other than after already having checked that P_STATUS property has appropriate value. The reason for this is that the LOGOUTREASON does not get reset before the next login attempt. For example: if a user tried to log in with a wrong password, the LOGOUTREASON gets set to INCORRECT_PASSWORD. Now, if the user tries to log in again, and yet again submits an incorrect password, the value of the LOGOUTREASON does not change anymore, because it already is set to INCORRECT_PASSWORD. Consequently, Account::OnChange will not fire in this case. @n , type: LOGOUTREASON*/,
    02630                 P_COMMITSTATUS = 78             /*!< Account::COMMITSTATUS, type: COMMITSTATUS*/,
    02631                 P_SUGGESTED_SKYPENAME = 72      /*!< suggested skypenames, semi-colon separated. present if logoutreason==SKYPENAME_TAKEN, type: Sid::String*/,
    02632                 P_SKYPEOUT_BALANCE_CURRENCY = 74/*!< 'EUR', 'USD', etc., type: Sid::String*/,
    02633                 P_SKYPEOUT_BALANCE              /*!< balance in 'cents', type: uint*/,
    02634                 P_SKYPEOUT_PRECISION = 804      /*!< decimal points in ACCOUNT_SKYPEOUT_BALANCE, type: uint*/,
    02635                 P_SKYPEIN_NUMBERS = 76          /*!< space-separated list of skypein numbers, type: Sid::String*/,
    02636                 P_CBLSYNCSTATUS = 79            /*!< Account::CBLSYNCSTATUS, type: CBLSYNCSTATUS*/,
    02637                 P_OFFLINE_CALLFORWARD = 77      /*!< space-separated list of 'begSecond,endSecond,identity' tokens, type: Sid::String*/,
    02638                 P_CHAT_POLICY = 160             /*!< Server-side account property, use SetServerside*Property() to set, type: CHATPOLICY*/,
    02639                 P_SKYPE_CALL_POLICY             /*!< Server-side account property, use SetServerside*Property() to set, type: SKYPECALLPOLICY*/,
    02640                 P_PSTN_CALL_POLICY              /*!< Server-side account property, use SetServerside*Property() to set, type: PSTNCALLPOLICY*/,
    02641                 P_AVATAR_POLICY                 /*!< Server-side account property, use SetServerside*Property() to set, type: AVATARPOLICY*/,
    02642                 P_BUDDYCOUNT_POLICY             /*!< Server-side account property, use SetServerside*Property() to set, type: BUDDYCOUNTPOLICY*/,
    02643                 P_TIMEZONE_POLICY               /*!< Server-side account property, use SetServerside*Property() to set, type: TIMEZONEPOLICY*/,
    02644                 P_WEBPRESENCE_POLICY            /*!< Server-side account property, use SetServerside*Property() to set, type: WEBPRESENCEPOLICY*/,
    02645                 P_PHONENUMBERS_POLICY = 168     /*!< Server-side account property, use SetServerside*Property() to set, type: PHONENUMBERSPOLICY*/,
    02646                 P_VOICEMAIL_POLICY              /*!< Server-side account property, use SetServerside*Property() to set, type: VOICEMAILPOLICY*/,
    02647                 P_PARTNER_OPTEDOUT = 773        /*!< Alerts: opted out partner id's, space separated, type: Sid::String*/,
    02648                 P_SERVICE_PROVIDER_INFO = 800   /*!< service information if the user is a paid service provider, type: Sid::String*/,
    02649                 P_REGISTRATION_TIMESTAMP        /*!< NB! Unlike your common UNIX timestamps, the registration_timestamp is special, as it counts MINUTES rather than seconds, from Epoch (January 1, 1970) @n , type: uint*/,
    02650                 P_NR_OF_OTHER_INSTANCES         /*!< number of times this user is logged in from other computers, type: uint*/,
    02651                 P_SKYPENAME = 4                 /*!< type: Sid::String*/,
    02652                 P_FULLNAME                      /*!< type: Sid::String*/,
    02653                 P_BIRTHDAY = 7                  /*!< YYYYMMDD, type: uint*/,
    02654                 P_GENDER                        /*!< 1-male, 2-female, type: uint*/,
    02655                 P_LANGUAGES                     /*!< ISO language codes, space-separated, type: Sid::String*/,
    02656                 P_COUNTRY                       /*!< ISO country code, type: Sid::String*/,
    02657                 P_PROVINCE                      /*!< type: Sid::String*/,
    02658                 P_CITY                          /*!< type: Sid::String*/,
    02659                 P_PHONE_HOME                    /*!< NB! string not integer, type: Sid::String*/,
    02660                 P_PHONE_OFFICE                  /*!< type: Sid::String*/,
    02661                 P_PHONE_MOBILE                  /*!< type: Sid::String*/,
    02662                 P_EMAILS                        /*!< This is a string property, that contains space-separated list of email addresses. When surfacing this property in your UI, you will need to take into account that there may be more than one email addresses in this property (i.e. split the value at spaces and display them as list). Similarly, when modifying this property with SetStrProperty method, your editor should allow editing of component email addresses separately and add them all up again, before submitting back to the account. @n , type: Sid::String*/,
    02663                 P_HOMEPAGE                      /*!< type: Sid::String*/,
    02664                 P_ABOUT                         /*!< arbitrary introductory text, type: Sid::String*/,
    02665                 P_PROFILE_TIMESTAMP             /*!< UNIX timestamp of last profile change, type: uint*/,
    02666                 P_MOOD_TEXT = 26                /*!< Personal mood text (visible to authorised users only). Max length 300 bytes. @n , type: Sid::String*/,
    02667                 P_TIMEZONE                      /*!< 24*3600+diff_to_UTC_in_seconds. nb! changes with DST, type: uint*/,
    02668                 P_NROF_AUTHED_BUDDIES           /*!< Count of this user's authorized contacts. @n , type: uint*/,
    02669                 P_AVAILABILITY = 34             /*!< Contact::AVAILABILITY, type: Contact::AVAILABILITY*/,
    02670                 P_AVATAR_IMAGE = 37             /*!< Account avatar picture can be set with Account::SetBinProperty method. The contact avatar picture is limited to max 96x96 pixels and 32000 bytes. If the submitted avatar picture exceeds either of these size limits, it is the responsibility of your client to scale the image down to appropriate size. @n  @n The avatar pictures have to be in JPG format. A SkypeKit client can enable the user to set the Account avatar in other picture formats, in which case the picture should be converted to JPG before submitting it.  @n  @n In any case, the avatar picture should be pre-validated with the Skype::ValidateAvatar method. @n , type: Sid::Binary*/,
    02671                 P_AVATAR_TIMESTAMP = 182        /*!< UNIX timestamp of when current avatar was set, type: uint*/,
    02672                 P_MOOD_TIMESTAMP                /*!< UNIX timestamp of when current mood was set, type: uint*/,
    02673                 P_RICH_MOOD_TEXT = 205          /*!< XML version of CONTACT_MOOD_TEXT. Max length 1000 bytes. @n , type: Sid::String*/
    02674         };
    02675
    02676         enum STATUS {
    02677                 LOGGED_OUT = 1,
    02678                 LOGGED_OUT_AND_PWD_SAVED      /*!< the account is logged out, but password is not needed for re-login*/,
    02679                 CONNECTING_TO_P2P             /*!< connecting to P2P network*/,
    02680                 CONNECTING_TO_SERVER          /*!< connecting to login server*/,
    02681                 LOGGING_IN                    /*!< waiting for response from server*/,
    02682                 INITIALIZING                  /*!< response OK. initialising account-specific lib structures*/,
    02683                 LOGGED_IN                     /*!< alright, we're good to go!*/,
    02684                 LOGGING_OUT                   /*!< Logout() has been called but not processed yet*/
    02685         };
    02686
    02687         bool GetStatusWithProgress(
    02688                 STATUS& status, /*!< Current value of this account's P_STATUS property*/
    02689                 uint& progress /*!< This argument returns 0. @n */
    02690         );
    02691
    02692         /** Recognized values for the P_CBLSYNCSTATUS property. CBL stands for Central Buddy List. In principle, this property and its states can be ignored by most UI developers. However, it can help to optimize UI buildup and behaviour, particularly in case of limited resources (such as mobile devices). @n  @n CBL is used to backup your contact list, contact groups, and profile information, and also used to synchronize this information with other Skype instances of your account (i.e. on another device). CBL sync can occur both during login and during normal operation. Note that CBL synchronization does not take place immediately after an Account property is changed. A delay between the first property change and CBL sync initiation enables the client to accumulate changes and do the synchronization in bulk. @n  @n Clients with limited resources might want to wait for CBL_IN_SYNC status before generating their UI's contact list representation. Otherwise it might be forced to redraw the contact list multiple times, as new updates get retrieved from the server-side. Similarly, applications that modify an account's mood message might want to know when the P_MOOD_TEXT or P_RICH_MOOD_TEXT property is synchronized to the server. Note that this sync is only for CBL and other logged in instances of the same account - other contacts will receive the mood message update directly. @n  */
    02693         enum CBLSYNCSTATUS {
    02694                 CBL_INITIALIZING = 0          /*!< status is not clear (yet)*/,
    02695                 CBL_INITIAL_SYNC_PENDING      /*!< first sync with empty profile*/,
    02696                 CBL_SYNC_PENDING              /*!< Account properties are considered to be out of sync with CBL - attempt at synchronization is imminent. You might wish to wait with updating UI components that display the data that is about to change anyway.*/,
    02697                 CBL_SYNC_IN_PROGRESS          /*!< CBL synchronization is currently taking place.*/,
    02698                 CBL_IN_SYNC                   /*!< Account properties are up-to-date.*/,
    02699                 CBL_SYNC_FAILED               /*!< CBL sync has. Another attempt will be made after several minutes. If a second attempt also fails, subsequent attempts at synchronization will be made at ever increasing intervals.*/,
    02700                 CBL_REMOTE_SYNC_PENDING       /*!< we have received a hint that there is a remote data change in CBL*/
    02701         };
    02702
    02703         /** Recognized values for the Account::P_LOGOUTREASON. Note that this property should only be examined when Account::P_STATUS is LOGGED_OUT or LOGGED_OUT_AND_PWD_SAVED. That is, you should not monitor changes to this property in Account::OnChange callback, other than after already having checked that P_STATUS property has appropriate value. The reason for this is that the LOGOUTREASON does not get reset before the next login attempt. For example: if a user tried to log in with a wrong password, the LOGOUTREASON gets set to INCORRECT_PASSWORD. Now, if the user tries to log in again, and yet again submits an incorrect password, the value of the LOGOUTREASON does not change anymore, because it already is set to INCORRECT_PASSWORD. Consequently, Account::OnChange will not fire in this case. @n  */
    02704         enum LOGOUTREASON {
    02705                 LOGOUT_CALLED = 1             /*!< manual logout (or unknown reason from previous session)*/,
    02706                 HTTPS_PROXY_AUTH_FAILED       /*!< sync errors at login/registration*/,
    02707                 SOCKS_PROXY_AUTH_FAILED       /*!< sync errors at login/registration*/,
    02708                 P2P_CONNECT_FAILED            /*!< sync errors at login/registration*/,
    02709                 SERVER_CONNECT_FAILED         /*!< sync errors at login/registration*/,
    02710                 SERVER_OVERLOADED             /*!< sync errors at login/registration*/,
    02711                 DB_IN_USE                     /*!< sync errors at login/registration*/,
    02712                 INVALID_SKYPENAME             /*!< sync errors at registration*/,
    02713                 INVALID_EMAIL                 /*!< sync errors at registration*/,
    02714                 UNACCEPTABLE_PASSWORD         /*!< sync errors at registration*/,
    02715                 SKYPENAME_TAKEN               /*!< sync errors at registration*/,
    02716                 REJECTED_AS_UNDERAGE          /*!< sync errors at registration*/,
    02717                 NO_SUCH_IDENTITY              /*!< sync errors at login*/,
    02718                 INCORRECT_PASSWORD            /*!< sync errors at login*/,
    02719                 TOO_MANY_LOGIN_ATTEMPTS       /*!< sync errors at login*/,
    02720                 PASSWORD_HAS_CHANGED          /*!< async errors (can happen anytime while logged in)*/,
    02721                 PERIODIC_UIC_UPDATE_FAILED    /*!< async errors (can happen anytime while logged in)*/,
    02722                 DB_DISK_FULL                  /*!< async errors (can happen anytime while logged in)*/,
    02723                 DB_IO_ERROR                   /*!< async errors (can happen anytime while logged in)*/,
    02724                 DB_CORRUPT                    /*!< async errors (can happen anytime while logged in)*/,
    02725                 DB_FAILURE                    /*!< deprecated (superceded by more detailed DB_* errors)*/,
    02726                 INVALID_APP_ID                /*!< platform sdk*/,
    02727                 APP_ID_FAILURE                /*!< platform sdk*/,
    02728                 UNSUPPORTED_VERSION           /*!< forced upgrade/discontinuation*/
    02729         };
    02730
    02731         /** Login an auto-login enabled account (P_STATUS is LOGGED_OUT_AND_PWD_SAVED) and optionally set the availability, for example login in as Contact::DO_NOT_DISTURB. To find out whether there is an auto-login enabled account available, you can use Skype::GetDefaultAccountName to retrieve the skypename of that account. You can then get an Account instance for login by invoking Skype::GetAccount. @n  @n If no accounts with stored login credentials are available (GetDefaultAccountName returns an empty string), then you will have to prompt the user for account name and password and then use LoginWithPassword. Account name field in the UI can be pre-populated with strings retrieved with Skype::GetExistingAccounts @n  */
    02732         bool Login(
    02733                 const Contact::AVAILABILITY setAvailabilityTo = Contact::UNKNOWN /*!< force this account's initial online status to the specified Contact::AVAILABILITY value.*/
    02734         );
    02735
    02736         /**   @n Login in an account by specifying its password. To retrieve an account instance for login, invoke Skype::GetAccount. @n  */
    02737         bool LoginWithPassword(
    02738                 const Sid::String& password, /*!< Password string (plaintext) for this account, which should be pre-validated (Skype::ValidatePassword) @n */
    02739                 const bool savePwd = false, /*!< @li true: Saves the password, ensuring that auto-login is enabled. @li false (default): Does not save the password, and so the user might not be able to effect auto-login until they explicitly invoke Account::SetPasswordSaved(true).*/
    02740                 const bool saveDataLocally = true /*!< For internal use only.*/
    02741         );
    02742
    02743         /** This command can be used to create a new Skype account, based on the Account object. When successful, this command will also log in with the newly created account. If the new account registration was not successful, Account status property will change to LOGGED_OUT. A common reason for registration failures is that the an account with that name already exists. In that case, Account LOGOUT_REASON will be set to SKYPENAME_TAKEN. Also, Account SUGGESTED_SKYPENAME property will be set to a list of similar but still available skypenames that could be used instead. The property will contain up to 5 semicolon-separated alternative skypenames. In if no suggested skypenames were available, then this property will contain an empty string. @n NB! You should pre-validate your P_SKYPENAME value and any email string (Skype::ValidateProfileString) prior to invoking this method. @n  */
    02744         bool Register(
    02745                 const Sid::String& password, /*!< Password string (plaintext) for this account, which should be pre-validated (Skype::ValidatePassword)*/
    02746                 const bool savePwd = false, /*!< @li true: Saves the password and enables auto-login. @li false (default): Does not save the password, and the user needs to be prompted for password on the next login attempt.*/
    02747                 const bool saveDataLocally = true, /*!< For internal use only.*/
    02748                 const Sid::String email = "", /*!< An email address for retrieving lost passwords and receiving news and information from Skype.*/
    02749                 const bool allowSpam = false /*!< enable/disable news and information from Skype being sent to account's e-mail.*/
    02750         );
    02751
    02752         /** Logs out current account. Note that calling this on client application exit is optional. @n  */
    02753         bool Logout(
    02754                 const bool clearSavedPwd = false /*!< @li true: Clears any saved password use with auto-login and so disables auto-login until you explicitly invoke Account::SetPasswordSaved(true). @li false (default): Does not clear any saved password and so does not affect existing auto-login behavior.*/
    02755         );
    02756
    02757         /** Recognized values for the P_PWDCHANGESTATUS property that provides information on whether a password change succeeded or failed, giving detailed failure reason. After successful return from the Change Password method, clients should monitor the P_PWDCHANGESTATUS property changes. @li PWD_CHANGING - consider displaying an "in progress" indicator and continue polling @li PWD_OK - consider displaying an updated indicator and stop polling @li PWD_OK_BUT_CHANGE_SUGGESTED - consider displaying an updated indicator, along with a recommendation to change again to a stronger password. @n  */
    02758         enum PWDCHANGESTATUS {
    02759                 PWD_OK = 0                    /*!< Password change succeeded. @n */,
    02760                 PWD_CHANGING                  /*!< Password change is in progress. @n */,
    02761                 PWD_INVALID_OLD_PASSWORD      /*!< Old password was incorrect. @n */,
    02762                 PWD_SERVER_CONNECT_FAILED     /*!< Failed to verify password because of no connection to server. @n */,
    02763                 PWD_OK_BUT_CHANGE_SUGGESTED   /*!< Password was set but server didn't like it much. @n */,
    02764                 PWD_MUST_DIFFER_FROM_OLD      /*!< New password was exactly the same as old one. @n */,
    02765                 PWD_INVALID_NEW_PWD           /*!< The new password was unacceptable. (too short, too simple, etc.) @n */,
    02766                 PWD_MUST_LOG_IN_TO_CHANGE     /*!< Account was currently not logged in. @n */
    02767         };
    02768
    02769         /** Changes this account's password. Returns false if the change failed. NB! You should pre-validate your password strings (Skype::ValidatePassword) and ensure that they are different prior to invoking this method. @n  */
    02770         bool ChangePassword(
    02771                 const Sid::String& oldPassword, /*!< "Current password string (plaintext) for this account*/
    02772                 const Sid::String& newPassword, /*!< New password string (plaintext) for this account*/
    02773                 const bool savePwd = false /*!< @li true: Saves the new password and enables auto-login. @li false (default): Clears any existing saved password and so the user cannot effect auto-login until they explicitly invoke Account::SetPasswordSaved(true)*/
    02774         );
    02775
    02776         /** save or clear credentials for auto-login whilst already logged in */
    02777         bool SetPasswordSaved(
    02778                 const bool& savePwd
    02779         );
    02780
    02781         /** Setter for integer (and enum) server-side properties. For a list of writeable server-side properties, see the detailed description of the Account class. @n  */
    02782         bool SetServersideIntProperty(
    02783                 const int& propKey,
    02784                 const uint& value
    02785         );
    02786
    02787         /** Setter for String server-side properties. For a list of writeable server-side properties, see the detailed description of the Account class. @n  */
    02788         bool SetServersideStrProperty(
    02789                 const int& propKey,
    02790                 const Sid::String& value
    02791         );
    02792
    02793         /** The list of possible values of Account class COMMITSTATUS property. Note that this property and its values have nothing to do with (automatic) CBL synchronization. Rather, the COMMITSTATUS reflects commit status to account's server side properties initiated with calls to Account class SetServersideIntProperty and Account class SetServersideStrProperty methods. After those methods, your client UI may want to wait until the COMMITSTATUS becomes COMMITTING_TO_SERVER followed by COMMITTED and inform the user if the value becomes COMMIT_FAILED. SetServerside<type>Property methods are used for writing privacy policy related and call forwarding related Account properties to the server. Unlike CBL synchronization, those updates are executed immediately. @n  */
    02794         enum COMMITSTATUS {
    02795                 COMMITTED = 1                 /*!< No pending updates to the server. @n */,
    02796                 COMMITTING_TO_SERVER          /*!< Update to the server in progress. @n */,
    02797                 COMMIT_FAILED                 /*!< Server update has failed. @n */
    02798         };
    02799
    02800         /** Cancels an attempt to commit a server-side P_XXX_POLICY or the P_OFFLINE_CALLFORWARD server-side property. Invoking this cancellation only makes sense whilst the P_COMMITTSTATUS is in COMMITTING_TO_SERVER state. @n  */
    02801         bool CancelServerCommit(
    02802         );
    02803
    02804         /** Recognized values for the P_CHAT_POLICY property that controls whether non-authorized users can initiate text chat with the currently logged in account. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntProperty @n  */
    02805         enum CHATPOLICY {
    02806                 EVERYONE_CAN_ADD = 0          /*!< Unauthorized contacts can initiate text chat. @n */,
    02807                 BUDDIES_OR_AUTHORIZED_CAN_ADD = 2/*!< Only authorized contacts can initiate chat (default policy). @n */
    02808         };
    02809
    02810         /** Recognized values for the P_SKYPECALLPOLICY property that controls acceptance of incoming Skype calls. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntPropertyserver-side. @n  */
    02811         enum SKYPECALLPOLICY {
    02812                 EVERYONE_CAN_CALL = 0         /*!< Skype calls accepted from unauthorized contacts.*/,
    02813                 BUDDIES_OR_AUTHORIZED_CAN_CALL = 2/*!< Skype calls not accepted from unauthorized contacts.*/
    02814         };
    02815
    02816         /** Recognized values for the P_PSTNCALLPOLICY property that controls whether (and from whom) this account accepts incoming PSTN calls. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntProperty @n  */
    02817         enum PSTNCALLPOLICY {
    02818                 ALL_NUMBERS_CAN_CALL = 0      /*!< All incoming PSTN calls are accepted.*/,
    02819                 DISCLOSED_NUMBERS_CAN_CALL    /*!< Only PSTN calls that report caller ID are accepted.*/,
    02820                 BUDDY_NUMBERS_CAN_CALL        /*!< Only calls from PSTN numbers found in local contact list are accepted.*/
    02821         };
    02822
    02823         /** Recognized values for the P_AVATAR_POLICY property that controls whether remote contacts can view local account's avatar image. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntPropertyserver-side. @n Note that setting account's AVATAR_POLICY to BUDDIES_OR_AUTHORIZED_CAN_SEE does not guarantee that remote users will be able to immediately retrieve the avatar picture via corresponding Contact object. Avatar changes propagate between clients only when direct sessions between clients are established. Direct sessions are established during live sessions or whilst online contacts are engaged in chat. @n  */
    02824         enum AVATARPOLICY {
    02825                 BUDDIES_OR_AUTHORIZED_CAN_SEE = 0/*!< Only authorized remote users can see this user's avatar image*/,
    02826                 EVERYONE_CAN_SEE = 2          /*!< Everyone can see this user's avatar image, once the contact/account avatar property has been synchronized during a direct session. The avatar image may also become viewable on some Skype Web-based services.*/
    02827         };
    02828
    02829         /** Recognized values for the P_BUDDYCOUNT_POLICY property that controls whether the number of this user's authorized contacts is visible to other users, either through Account::GetPropNrofAuthedBuddies or Contact::GetPropNrofAuthedBuddies when those instances reference this user. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntProperty, like this: @n account->SetServersideIntProperty(Account::P_BUDDYCOUNT_POLICY, Account::DISCLOSE_TO_AUTHORIZED); @n account->SetServersideIntProperty(Account::P_BUDDYCOUNT_POLICY, Account::DISCLOSE_TO_NOONE ); @n  */
    02830         enum BUDDYCOUNTPOLICY {
    02831                 DISCLOSE_TO_AUTHORIZED = 0    /*!< Authorized remote users can retrieve the number of this user's authorized contacts (Contact::P_NROF_AUTHED_BUDDIES)*/,
    02832                 DISCLOSE_TO_NOONE             /*!< No remote user - regardless their authorization status - can retrieve the number of this user's authorized contacts. Account::GetPropNrofAuthedBuddies and Contact::GetPropNrofAuthedBuddies will always return 0*/
    02833         };
    02834
    02835         /** Recognized values for the P_TIMEZONEPOLICY property that sets the rules for timezone offset so remote clients can determine your local time. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntPropertyserver-side. */
    02836         enum TIMEZONEPOLICY {
    02837                 TZ_AUTOMATIC = 0              /*!< Account's timezone setting is determined automatically. @n */,
    02838                 TZ_MANUAL                     /*!< Account's timezone setting is set manually. @n */,
    02839                 TZ_UNDISCLOSED                /*!< Remote users will have no idea what your local time is. @n */
    02840         };
    02841
    02842         /** Recognized values for the P_WEBPRESENCEPOLICY property that controls whether your online status (presence) can be seen using the "Skype buttons" ( http://www.skype.com/share/buttons/ ) embedded in web pages. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntPropertyserver-side. @n  */
    02843         enum WEBPRESENCEPOLICY {
    02844                 WEBPRESENCE_DISABLED = 0      /*!< Disable displaying online status on web for this account.*/,
    02845                 WEBPRESENCE_ENABLED           /*!< Enable displaying online status on web for this account.*/
    02846         };
    02847
    02848         /** Recognized values for the P_PHONENUMBERSPOLICY property that controls whether unauthorized remote users can see associated phone numbers in their UI (for reference, see the different phone number tabs in Windows desktop Client contact view). Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntProperty @n  */
    02849         enum PHONENUMBERSPOLICY {
    02850                 PHONENUMBERS_VISIBLE_FOR_BUDDIES = 0/*!< Only authorized contacts can see the phone numbers.*/,
    02851                 PHONENUMBERS_VISIBLE_FOR_EVERYONE/*!< Everyone can see the phone numbers.*/
    02852         };
    02853
    02854         /** Recognized values for the P_VOICEMAILPOLICY property that controls acceptance of incoming voicemail messages. Note that since this set of values is associated with a server-side property, you must set that property using Account::SetServersideIntPropertyserver-side. @n  */
    02855         enum VOICEMAILPOLICY {
    02856                 VOICEMAIL_ENABLED = 0         /*!< Incoming voicemails enabled.*/,
    02857                 VOICEMAIL_DISABLED            /*!< Incoming voicemails disabled.*/
    02858         };
    02859
    02860         /** Setter for integer properties. For a list of writeable account profile properties, see the detailed description of the Account class. @n  */
    02861         bool SetIntProperty(
    02862                 const int& propKey,
    02863                 const uint& value
    02864         );
    02865
    02866         /** Setter for String properties. For a list of writeable account profile properties, see the detailed description of the Account class. NB! You should pre-validate your about and mood message strings (Skype::ValidateProfileString) prior to invoking this method. @n  */
    02867         bool SetStrProperty(
    02868                 const int& propKey,
    02869                 const Sid::String& value
    02870         );
    02871
    02872         /** Setter for BLOB properties, such as its avatar image. For a list of writeable account profile properties, see the detailed description of the Account class. NB! You should pre-validate your avatar image (Skype::ValidateAvatar) prior to invoking this method. @n  */
    02873         bool SetBinProperty(
    02874                 const int& propKey,
    02875                 const Sid::Binary& value
    02876         );
    02877
    02878         /** Sets online status of the currently logged in account to one of the values from Contact class AVAILABILITY enumerator. @n  */
    02879         bool SetAvailability(
    02880                 const Contact::AVAILABILITY& availability /*!< only subset of all contact availabilities allowed*/
    02881         );
    02882
    02883         /** Transitions the availability of this account's associated user, who is assumed to be logged in. @n  */
    02884         bool SetStandby(
    02885                 const bool& standby /*!< @li true: Saves the user's current availability, then sets it to CONTACT::AVAILABILITY.OFFLINE @li false: Reconnects the user and restores their previous availability*/
    02886         );
    02887
    02888         /** Account capabability statuses are possible values of Contact class CAPABILITY enumerator, when that enumerator is used in context of account. Compared to Contact class CAPABILITYSTATUS enums, Account class CAPABILITYSTATUS has additional items for subscription expiration warnings. @n  */
    02889         enum CAPABILITYSTATUS {
    02890                 NO_CAPABILITY = 0             /*!< Capability is not supported by the currently logged in SkypeKit client.*/,
    02891                 CAPABILITY_EXISTS             /*!< Capability is supported by the currently logged in SkypeKit client. @n */,
    02892                 FIRST_EXPIRY_WARNING          /*!< Support for this capability ends this month (within 30 days) @n */,
    02893                 SECOND_EXPIRY_WARNING         /*!< Support for this capability ends this week (within 7 days)  @n */,
    02894                 FINAL_EXPIRY_WARNING          /*!< Support for this capability ends today @n */
    02895         };
    02896
    02897         /** Returns state of a given account capability. Takes Contact class CAPABILITY property as input argument and returns its state and expiration timestamp where appropriate. For example (C++ wrapper, with other wrappers the syntax may vary but the idea is the same) MyAccount.GetCapabilityStatus(Contact::CAPABILITY_SKYPEOUT, Cap, T); will return Account::CAPABILITY_EXISTS if local account has SkypeOut enabled. @n  */
    02898         bool GetCapabilityStatus(
    02899                 const Contact::CAPABILITY& capability,
    02900                 CAPABILITYSTATUS& status,
    02901                 uint& expiryTimestamp
    02902         );
    02903
    02904         /** Response is empty when called with an inactive or invalid account */
    02905         bool GetSkypenameHash(
    02906                 Sid::String& skypenameHash
    02907         );
    02908
    02909         /** returns verified-by-Skype e-mail for this account if exists and verifiable */
    02910         bool GetVerifiedEmail(
    02911                 Sid::String& email
    02912         );
    02913
    02914         /** returns verified-by-Skype company for this account if exists and verifiable */
    02915         bool GetVerifiedCompany(
    02916                 Sid::String& company
    02917         );
    02918
    02919         /** Deletes all account data stored locally. Does not remove any account data from the server! @n  */
    02920         bool Delete(
    02921         );
    02922
    02923         /** Account::P_STATUS property get accessor */
    02924         bool GetPropStatus(STATUS& status);
    02925
    02926         /** Account::P_PWDCHANGESTATUS property get accessor */
    02927         bool GetPropPwdchangestatus(PWDCHANGESTATUS& pwdchangestatus);
    02928
    02929         /** Account::P_LOGOUTREASON property get accessor */
    02930         bool GetPropLogoutreason(LOGOUTREASON& logoutreason);
    02931
    02932         /** Account::P_COMMITSTATUS property get accessor */
    02933         bool GetPropCommitstatus(COMMITSTATUS& commitstatus);
    02934
    02935         /** Account::P_SUGGESTED_SKYPENAME property get accessor */
    02936         bool GetPropSuggestedSkypename(Sid::String& suggested_skypename);
    02937
    02938         /** Account::P_SKYPEOUT_BALANCE_CURRENCY property get accessor */
    02939         bool GetPropSkypeoutBalanceCurrency(Sid::String& skypeout_balance_currency);
    02940
    02941         /** Account::P_SKYPEOUT_BALANCE property get accessor */
    02942         bool GetPropSkypeoutBalance(uint& skypeout_balance);
    02943
    02944         /** Account::P_SKYPEOUT_PRECISION property get accessor */
    02945         bool GetPropSkypeoutPrecision(uint& skypeout_precision);
    02946
    02947         /** Account::P_SKYPEIN_NUMBERS property get accessor */
    02948         bool GetPropSkypeinNumbers(Sid::String& skypein_numbers);
    02949
    02950         /** Account::P_CBLSYNCSTATUS property get accessor */
    02951         bool GetPropCblsyncstatus(CBLSYNCSTATUS& cblsyncstatus);
    02952
    02953         /** Account::P_OFFLINE_CALLFORWARD property get accessor */
    02954         bool GetPropOfflineCallforward(Sid::String& offline_callforward);
    02955
    02956         /** Account::P_CHAT_POLICY property get accessor */
    02957         bool GetPropChatPolicy(CHATPOLICY& chat_policy);
    02958
    02959         /** Account::P_SKYPE_CALL_POLICY property get accessor */
    02960         bool GetPropSkypeCallPolicy(SKYPECALLPOLICY& skype_call_policy);
    02961
    02962         /** Account::P_PSTN_CALL_POLICY property get accessor */
    02963         bool GetPropPstnCallPolicy(PSTNCALLPOLICY& pstn_call_policy);
    02964
    02965         /** Account::P_AVATAR_POLICY property get accessor */
    02966         bool GetPropAvatarPolicy(AVATARPOLICY& avatar_policy);
    02967
    02968         /** Account::P_BUDDYCOUNT_POLICY property get accessor */
    02969         bool GetPropBuddycountPolicy(BUDDYCOUNTPOLICY& buddycount_policy);
    02970
    02971         /** Account::P_TIMEZONE_POLICY property get accessor */
    02972         bool GetPropTimezonePolicy(TIMEZONEPOLICY& timezone_policy);
    02973
    02974         /** Account::P_WEBPRESENCE_POLICY property get accessor */
    02975         bool GetPropWebpresencePolicy(WEBPRESENCEPOLICY& webpresence_policy);
    02976
    02977         /** Account::P_PHONENUMBERS_POLICY property get accessor */
    02978         bool GetPropPhonenumbersPolicy(PHONENUMBERSPOLICY& phonenumbers_policy);
    02979
    02980         /** Account::P_VOICEMAIL_POLICY property get accessor */
    02981         bool GetPropVoicemailPolicy(VOICEMAILPOLICY& voicemail_policy);
    02982
    02983         /** Account::P_PARTNER_OPTEDOUT property get accessor */
    02984         bool GetPropPartnerOptedout(Sid::String& partner_optedout);
    02985
    02986         /** Account::P_SERVICE_PROVIDER_INFO property get accessor */
    02987         bool GetPropServiceProviderInfo(Sid::String& service_provider_info);
    02988
    02989         /** Account::P_REGISTRATION_TIMESTAMP property get accessor */
    02990         bool GetPropRegistrationTimestamp(uint& registration_timestamp);
    02991
    02992         /** Account::P_NR_OF_OTHER_INSTANCES property get accessor */
    02993         bool GetPropNrOfOtherInstances(uint& nr_of_other_instances);
    02994
    02995         /** Account::P_SKYPENAME property get accessor */
    02996         bool GetPropSkypename(Sid::String& skypename);
    02997
    02998         /** Account::P_FULLNAME property get accessor */
    02999         bool GetPropFullname(Sid::String& fullname);
    03000
    03001         /** Account::P_BIRTHDAY property get accessor */
    03002         bool GetPropBirthday(uint& birthday);
    03003
    03004         /** Account::P_GENDER property get accessor */
    03005         bool GetPropGender(uint& gender);
    03006
    03007         /** Account::P_LANGUAGES property get accessor */
    03008         bool GetPropLanguages(Sid::String& languages);
    03009
    03010         /** Account::P_COUNTRY property get accessor */
    03011         bool GetPropCountry(Sid::String& country);
    03012
    03013         /** Account::P_PROVINCE property get accessor */
    03014         bool GetPropProvince(Sid::String& province);
    03015
    03016         /** Account::P_CITY property get accessor */
    03017         bool GetPropCity(Sid::String& city);
    03018
    03019         /** Account::P_PHONE_HOME property get accessor */
    03020         bool GetPropPhoneHome(Sid::String& phone_home);
    03021
    03022         /** Account::P_PHONE_OFFICE property get accessor */
    03023         bool GetPropPhoneOffice(Sid::String& phone_office);
    03024
    03025         /** Account::P_PHONE_MOBILE property get accessor */
    03026         bool GetPropPhoneMobile(Sid::String& phone_mobile);
    03027
    03028         /** Account::P_EMAILS property get accessor */
    03029         bool GetPropEmails(Sid::String& emails);
    03030
    03031         /** Account::P_HOMEPAGE property get accessor */
    03032         bool GetPropHomepage(Sid::String& homepage);
    03033
    03034         /** Account::P_ABOUT property get accessor */
    03035         bool GetPropAbout(Sid::String& about);
    03036
    03037         /** Account::P_PROFILE_TIMESTAMP property get accessor */
    03038         bool GetPropProfileTimestamp(uint& profile_timestamp);
    03039
    03040         /** Account::P_MOOD_TEXT property get accessor */
    03041         bool GetPropMoodText(Sid::String& mood_text);
    03042
    03043         /** Account::P_TIMEZONE property get accessor */
    03044         bool GetPropTimezone(uint& timezone);
    03045
    03046         /** Account::P_NROF_AUTHED_BUDDIES property get accessor */
    03047         bool GetPropNrofAuthedBuddies(uint& nrof_authed_buddies);
    03048
    03049         /** Account::P_AVAILABILITY property get accessor */
    03050         bool GetPropAvailability(Contact::AVAILABILITY& availability);
    03051
    03052         /** Account::P_AVATAR_IMAGE property get accessor */
    03053         bool GetPropAvatarImage(Sid::Binary& avatar_image);
    03054
    03055         /** Account::P_AVATAR_TIMESTAMP property get accessor */
    03056         bool GetPropAvatarTimestamp(uint& avatar_timestamp);
    03057
    03058         /** Account::P_MOOD_TIMESTAMP property get accessor */
    03059         bool GetPropMoodTimestamp(uint& mood_timestamp);
    03060
    03061         /** Account::P_RICH_MOOD_TEXT property get accessor */
    03062         bool GetPropRichMoodText(Sid::String& rich_mood_text);
    03063
    03064 };
    03065
    03066
    03067 /*! \class Skype skype-embedded.h "skype-embedded.h"
    03068  *  \brief
    03069  *  \nosubgrouping
    03070  *  The main class that exposes Skype-related functionality to your application. Currently the SDK only supports one
    03071  *  Skype class instance per runtime. Note that most of the Skype class methods will fail until you have successfully
    03072  *  logged in with an account. For more information on constructing a Skype object and the login sequence, see first
    03073  *  tutorial example. @n
    03074  */
    03075 class Skype : public SERootObject
    03076 {
    03077         friend class SEObject;
    03078         friend class ContactGroup;
    03079         friend class Contact;
    03080         friend class ContactSearch;
    03081         friend class Participant;
    03082         friend class Conversation;
    03083         friend class Message;
    03084         friend class Video;
    03085         friend class Voicemail;
    03086         friend class Sms;
    03087         friend class Transfer;
    03088         friend class Account;
    03089         protected:
    03090         virtual ContactGroup * newContactGroup(int oid);
    03091         virtual Contact * newContact(int oid);
    03092         virtual ContactSearch * newContactSearch(int oid);
    03093         virtual Participant * newParticipant(int oid);
    03094         virtual Conversation * newConversation(int oid);
    03095         virtual Message * newMessage(int oid);
    03096         virtual Video * newVideo(int oid);
    03097         virtual Voicemail * newVoicemail(int oid);
    03098         virtual Sms * newSms(int oid);
    03099         virtual Transfer * newTransfer(int oid);
    03100         virtual Account * newAccount(int oid);
    03101
    03102 public:
    03103         Skype(int num_threads = 1);
    03104         virtual ~Skype();
    03105
    03106         bool start();
    03107         const unsigned int moduleID() const;
    03108         String getNamespace() const { return __EA(SKYPE);}
    03109         const PMAP* getPMap() const { return 0;}
    03110         const EMAP* getEMap() const { return 0;}
    03111         static Skype* instance(){ return (Skype*)SERootObject::instance(); }
    03112         Sid::Field* get_property_desc(const uint& modid, const uint& propid);
    03113         SEObject* factory(const uint& modid, const uint& oid);
    03114
    03115         void* prop_factory(const uint& moduleid);
    03116
    03117         Sid::List_uint* prop_cached_list(void* propstruct, const uint& moduleid);
    03118
    03119         Sid::Protocol::Status dispatch_event(Sid::CommandInitiator* thread, Sid::Protocol::ClientInterface* protocol, const uint& modid, const uint& evid);
    03120         bool Start(
    03121                 bool& started
    03122         );
    03123
    03124         /** Setupkey SETUPKEY_DB_STORAGE_QUOTA_KB type:int default value:"0" @n Use this key to limit the size of the main.db file. Value is in KB. Quota are disabled by default. @n  @n <b>NB!</b> This setup key only limits the size of the main database files. It <b>does not include size of sqlite temporary files</b>, such as rollback journals. Sometimes even if this quota is set, the total size of db files on storage can grow more than than the set limit, for short period of time. @n  @n Because of this, as a rule of thumb, you should set this setup key to approximately <b>half</b> of actual available storage space. @n  @n If the storage limit is exceeded (or the database file just runs out of available storage), the currently logged in account will be forcibily logged out, with P_LOGOUT_REASON set to DB_IO_ERROR. @n  @n This setup key is machine-specific and affects all local accounts. @n  */
    03125         #define SETUPKEY_DB_STORAGE_QUOTA_KB "*Lib/DbManager/StorageQuotaKb"
    03126
    03127         /** returns the runtime version as a string */
    03128         bool GetVersionString(
    03129                 Sid::String& version
    03130         );
    03131
    03132         /** Returns the time as used in SkypeKit, in the form of a Unix timestamp (number of seconds since 1.1.1970).                   If the local system time is incorrect my more than one year, the time provided                   by the Skype network will be provided, which is correct. Therefore this function                   can be used to adjust the system time if set incorrectly (e.g. if set to 1.1.1970). */
    03133         bool GetUnixTimestamp(
    03134                 uint& timestamp
    03135         );
    03136
    03137         /** Takes TYPE argument (TYPE comes from ContactGroup class) and returns reference to the corresponding hardwired contact group. For example (C++): skype->GetHardwiredContactGroup(ContactGroup::ONLINE_BUDDIES, GroupRef) would return the list of all contacts that are currently online. @n  */
    03138         bool GetHardwiredContactGroup(
    03139                 const ContactGroup::TYPE& type,
    03140                 ContactGroupRef& contactGroup
    03141         );
    03142
    03143         /** Returns a list of custom contact group references, i.e. all contact groups that are not hardwired. @n  */
    03144         bool GetCustomContactGroups(
    03145                 ContactGroupRefs& groups
    03146         );
    03147
    03148         /** Creates a new empty contact group object and returns a reference to it. The group will then show up in the custom group list that you can get with Skype class GetCustomContactGroups method. Existing contacts can be added to the new group with ContactGroup class AddContact method and a custom name can be given to it with GiveDisplayName method. @n Note that no check is made for existing of displaynames with the same name - if you wish to force uniqueness in custom group names you will have to check that yourself before creating the group. @n  */
    03149         bool CreateCustomContactGroup(
    03150                 ContactGroupRef& group
    03151         );
    03152
    03153         /**
    03154         * @param group eg, new contact group loaded from CBL
    03155         */
    03156         virtual void OnNewCustomContactGroup(
    03157                 const ContactGroupRef& group
    03158         );
    03159
    03160         /** analyzes the identity for contact type */
    03161         bool GetContactType(
    03162                 const Sid::String& identity,
    03163                 Contact::TYPE& type
    03164         );
    03165
    03166         /** Returns a Contact object reference. If a matching contact is not found in the existing contact list, a new Contact object will be created. Note that if you pass in a phone number in the identity argument, the type for the newly created Contact will be automatically set to Contact::PSTN (Contact::SKYPE otherwise). @n  */
    03167         bool GetContact(
    03168                 const Sid::String& identity, /*!< Either skypename or a phone number @n */
    03169                 ContactRef& contact /*!< Returns a contact object. @n */
    03170         );
    03171
    03172         bool FindContactByPstnNumber(
    03173                 const Sid::String& number,
    03174                 bool& found,
    03175                 ContactRef& contact,
    03176                 uint& foundInKey /*!< type is actually PROPKEY*/
    03177         );
    03178
    03179         enum IDENTITYTYPE {
    03180                 UNRECOGNIZED = 0,
    03181                 SKYPE,
    03182                 SKYPE_MYSELF,
    03183                 SKYPE_UNDISCLOSED,
    03184                 PSTN,
    03185                 PSTN_EMERGENCY,
    03186                 PSTN_FREE,
    03187                 PSTN_UNDISCLOSED,
    03188                 CONFERENCE,
    03189                 EXTERNAL
    03190         };
    03191
    03192         /** This takes skypename or a phone number string as argument and returns corresponding identity type (SKYPE, SKYPE_MYSELF, PSTN, etc.) @n  */
    03193         bool GetIdentityType(
    03194                 const Sid::String& identity,
    03195                 IDENTITYTYPE& type
    03196         );
    03197
    03198         enum NORMALIZERESULT {
    03199                 IDENTITY_OK = 0,
    03200                 IDENTITY_EMPTY,
    03201                 IDENTITY_TOO_LONG,
    03202                 IDENTITY_CONTAINS_INVALID_CHAR,
    03203                 PSTN_NUMBER_TOO_SHORT,
    03204                 PSTN_NUMBER_HAS_INVALID_PREFIX/*!< identity looks like pstn number but does not start with +/00/011*/,
    03205                 SKYPENAME_STARTS_WITH_NONALPHA,
    03206                 SKYPENAME_SHORTER_THAN_6_CHARS/*!< returned only when isNewSkypeName*/
    03207         };
    03208
    03209         /** compares two identities to see if they match */
    03210         bool IdentitiesMatch(
    03211                 const Sid::String& identityA,
    03212                 const Sid::String& identityB,
    03213                 bool& result
    03214         );
    03215
    03216         /** This method is deprecated. Use ValidateProfileString method instead. @n  */
    03217         bool NormalizeIdentity(
    03218                 const Sid::String& original,
    03219                 NORMALIZERESULT& result,
    03220                 Sid::String& normalized,
    03221                 const bool isNewSkypeName = false
    03222         );
    03223
    03224         /** NormalizePSTNWithCountry checks if the phone number starts with + if it doesn't, it prefixes the output with +XXX (where XXX is the country code). It also converts letters to numbers based on the standard phone keypad, so that the phone number string 212CALLME1 with country code 372 (Estonia) would be normalized to +3722122255631. If the method cannot normalize the phone number (because it's too long, too short, etc.), it returns an error code in &result. @n  */
    03225         bool NormalizePSTNWithCountry(
    03226                 const Sid::String& original,
    03227                 NORMALIZERESULT& result,
    03228                 Sid::String& normalized,
    03229                 const uint countryPrefix = 0
    03230         );
    03231
    03232         /** This contact has appeared online. display alert */
    03233         virtual void OnContactOnlineAppearance(
    03234                 const ContactRef& contact
    03235         );
    03236
    03237         /** This contact has gone offline. display alert */
    03238         virtual void OnContactGoneOffline(
    03239                 const ContactRef& contact
    03240         );
    03241
    03242         /** list of (min,max) pairs */
    03243         bool GetOptimalAgeRanges(
    03244                 Sid::List_uint& rangeList
    03245         );
    03246
    03247         /** Creates a blank contact search object, in which you can add your custom search terms. For more information how asynchronous contact search works, see ContactSearch class details. @n  */
    03248         bool CreateContactSearch(
    03249                 ContactSearchRef& search /*!< Returns blank ContactSearch object. @n */
    03250         );
    03251
    03252         /** searches skypenames, aliases, fullnames, emails. false if not valid */
    03253         bool CreateBasicContactSearch(
    03254                 const Sid::String& text,
    03255                 ContactSearchRef& search
    03256         );
    03257
    03258         /** searches skypenames and aliases. returns 0 or 1 results. false if not valid */
    03259         bool CreateIdentitySearch(
    03260                 const Sid::String& identity,
    03261                 ContactSearchRef& search
    03262         );
    03263
    03264         /** Creates a new empty conversation object and returns a reference to it. @n  */
    03265         bool CreateConference(
    03266                 ConversationRef& conference
    03267         );
    03268
    03269         /** Returns reference tp conversation object by conversation ID string (equivalent of old chat ID). NB! ID here is that of conversation, rather than skypename of dialog partner. If you want to retrieve a conversation object with any particular person, then Skype class GetConversationByParticipants method is what you are looking for. @n  */
    03270         bool GetConversationByIdentity(
    03271                 const Sid::String& convoIdentity,
    03272                 ConversationRef& conversation
    03273         );
    03274
    03275         /** myself not included */
    03276         bool GetConversationByParticipants(
    03277                 const Sid::List_String& participantIdentities,
    03278                 ConversationRef& conversation,
    03279                 const bool createIfNonExisting = false,
    03280                 const bool ignoreBookmarkedOrNamed = false
    03281         );
    03282
    03283         /** Retrieves a Conversation object by Public Conversation BLOB. Public conversation blobs are globally unique conversation IDs that provide a method for joining conversation without explicitly being added to the conversation by someone already in it. Programmatically, a Conversation BLOB can be retrieved with Conversation::GetJoinBlob method. In Skype desktop clients, the BLOB can be retrieved by typing "/get uri" in a conversation. The conversation can then be joined by people who have somehow received that BLOB. @n  */
    03284         bool GetConversationByBlob(
    03285                 const Sid::String& joinBlob, /*!< The BLOB string. @n */
    03286                 ConversationRef& conversation, /*!< Returns Conversation object if successful. @n */
    03287                 const bool alsoJoin = true /*!< If set to true, automatically joins current user into the Conversation. @n */
    03288         );
    03289
    03290         /** Returns a list of Conversation objects by Conversation::LIST_TYPE filter. @n  */
    03291         bool GetConversationList(
    03292                 ConversationRefs& conversations, /*!< List of conversations matching the filter. @n */
    03293                 const Conversation::LIST_TYPE type = Conversation::ALL_CONVERSATIONS /*!< Filter. @n */
    03294         );
    03295
    03296         /** This event gets fired when a Conversation item is added or removed from the list specified in the type argument. The primary use of this event is to detect creation of new Conversation objects. It can also be used for detecting occurance of live sessions - by monitoring added = true in Conversation::LIVE_CONVERSATIONS. Note that this method is not entirely sufficient for detecting live session termination (added = false and type = Conversation::LIVE_CONVERSATIONS). When the live session goes down, the default behaviour is that the Conversation object remains in the LIVE_CONVERSATIONS list for approximately 10 seconds. When another live session comes up within the same Conversation, the OnConversationListChange event will not fire - because the conversation was already in that list. There are two ways of getting around that. Firstly you can have all the conversations referenced at all times and then monitor Conversation::P_LOCAL_LIVESTATUS property changes, in which case you can pick up incoming live sessions from there. Alternatively, you can remove the delay between live session termination and conversation's removal from the LIVE_CONVERSATIONS list. This delay is controlled by the SETUPKEY_RECENTLY_LIVE_TIMEOUT setup key. To remove the delay, use Skype::SetInt(SETUPKEY_RECENTLY_LIVE_TIMEOUT, 0). Note that this setup key is account-based. You will need to have an account logged in in order to modify its value. @n
    03297         * @param conversation Conversation object that was added or removed to a list specified in the type argument. @n
    03298         * @param type Specifies the list, into which the conversation was added or removed from. @n
    03299         * @param added Specifies whether the conversation was added or removed. For ALL_CONVERSATIONS list, the removed event is only fired when the conversation is actually deleted. @n
    03300         */
    03301         virtual void OnConversationListChange(
    03302                 const ConversationRef& conversation,
    03303                 const Conversation::LIST_TYPE& type,
    03304                 const bool& added
    03305         );
    03306
    03307         /** Retrieves a Message object by the P_GUID property (globally unique ID, same for all the participants of the conversation, in which this message occured). @n  */
    03308         bool GetMessageByGuid(
    03309                 const Sid::Binary& guid, /*!< Globally unique ID of the message. @n */
    03310                 MessageRef& message /*!< Returns a Message object if a match was found. @n */
    03311         );
    03312
    03313         /** Returns all messages of the given type */
    03314         bool GetMessageListByType(
    03315                 const Message::TYPE& type, /*!< Type of messages requested. For POSTED_TEXT or POSTED_EMOTE, returns a list with both types*/
    03316                 const bool& latestPerConvOnly, /*!< Whether to return only the most recent message per conversation*/
    03317                 MessageRefs& messages,
    03318                 const uint fromTimestampInc = 0, /*!< Starting timestamp for reqested range, inclusive*/
    03319                 const uint toTimestampExc = MAX_UINT /*!< Ending timestamp for requested range, exclusive*/
    03320         );
    03321
    03322         /**
    03323         * @param changesInboxTimestamp if changesInboxTimestamp==true is a hint that tray alert should probably be displayed
    03324         * @param supersedesHistoryMessage DEPRECATED, not set anymore
    03325         */
    03326         virtual void OnMessage(
    03327                 const MessageRef& message,
    03328                 const bool& changesInboxTimestamp,
    03329                 const MessageRef& supersedesHistoryMessage,
    03330                 const ConversationRef& conversation
    03331         );
    03332
    03333         /** This method returns a table in form of two string lists of equal length and an uint argument that returns the count of items i both lists. The first list contains video recording device handles and the second list descriptive names of those devices. NB! This method requires videortphost to be running, otherwise it will return empty lists. @n  */
    03334         bool GetAvailableVideoDevices(
    03335                 Sid::List_String& deviceNames,
    03336                 Sid::List_String& devicePaths,
    03337                 uint& count
    03338         );
    03339
    03340         /** Queries whether the given video device has a specific Video::VIDEO_DEVICE_CAPABILITY. Use Skype::GetAvailableVideoDevices method to retrieve sstring lists with available deviceName and devicePath values. @n  */
    03341         bool HasVideoDeviceCapability(
    03342                 const Sid::String& deviceName, /*!< Human readable device name. @n */
    03343                 const Sid::String& devicePath, /*!< Device ID. @n */
    03344                 const Video::VIDEO_DEVICE_CAPABILITY& cap, /*!< Any of the Video::VIDEO_DEVICE_CAPABILITY values. @n */
    03345                 bool& result
    03346         );
    03347
    03348         bool DisplayVideoDeviceTuningDialog(
    03349                 const Sid::String& deviceName,
    03350                 const Sid::String& devicePath
    03351         );
    03352
    03353         /** Warning: Will be deprecated soon */
    03354         bool GetPreviewVideo(
    03355                 const Video::MEDIATYPE& type,
    03356                 VideoRef& video,
    03357                 const Sid::String deviceName = "", /*!< name and path to be used only with media type VIDEO*/
    03358                 const Sid::String devicePath = ""
    03359         );
    03360
    03361         /** Avaible to Video Engines using the Video RTP API */
    03362         bool VideoCommand(
    03363                 const Sid::String& command,
    03364                 Sid::String& response
    03365         );
    03366
    03367         /** This callback gets fired when there are changes in the system video device list (USB webcam gets plugged in or is detached.) @n  */
    03368         virtual void OnAvailableVideoDeviceListChange(
    03369         );
    03370
    03371         /** Event is implemented only in SkypeKit builds. Fired when Skype video library uses software H264 codec for the first time on the particular hardware by particular SkypeKit-based application */
    03372         virtual void OnH264Activated(
    03373         );
    03374
    03375         enum QUALITYTESTTYPE {
    03376                 QTT_AUDIO_IN = 0,
    03377                 QTT_AUDIO_OUT,
    03378                 QTT_VIDEO_OUT,
    03379                 QTT_CPU,
    03380                 QTT_NETWORK,
    03381                 QTT_VIDEO_IN
    03382         };
    03383
    03384         enum QUALITYTESTRESULT {
    03385                 QTR_UNDEFINED = 0,
    03386                 QTR_CRITICAL,
    03387                 QTR_POOR,
    03388                 QTR_AVERAGE,
    03389                 QTR_GOOD,
    03390                 QTR_EXCELLENT
    03391         };
    03392
    03393         bool StartMonitoringQuality(
    03394                 const Sid::String& withUser, /*!< if empty, network test results would reflect status of local node only*/
    03395                 const bool& excludeNetworkTest
    03396         );
    03397
    03398         bool StopMonitoringQuality(
    03399                 const Sid::String& withUser,
    03400                 QUALITYTESTRESULT& result,
    03401                 const bool justStop = false
    03402         );
    03403
    03404         virtual void OnQualityTestResult(
    03405                 const QUALITYTESTTYPE& testType,
    03406                 const QUALITYTESTRESULT& testResult,
    03407                 const Sid::String& withUser,
    03408                 const Sid::String& details,
    03409                 const Sid::String& xmlDetails
    03410         );
    03411
    03412         bool GetGreeting(
    03413                 const Sid::String& skypeName,
    03414                 VoicemailRef& greeting
    03415         );
    03416
    03417         /** Setupkey SETUPKEY_DISABLED_CODECS type:string  @n Space-separated array of disabled codecs @n This setup key is machine-specific and affects all local accounts. @n  */
    03418         #define SETUPKEY_DISABLED_CODECS "*Lib/Audio/DisableCodecs"
    03419
    03420         /** Setupkey SETUPKEY_DISABLE_AEC type:boolean  @n Disables Skype echo canceller @n This setup key is machine-specific and affects all local accounts. @n  */
    03421         #define SETUPKEY_DISABLE_AEC "*Lib/Audio/DisableAEC"
    03422
    03423         /** Setupkey SETUPKEY_DISABLE_NOISE_SUPPRESSOR type:boolean  @n Disables Skype noise suppressor @n This setup key is machine-specific and affects all local accounts. @n  */
    03424         #define SETUPKEY_DISABLE_NOISE_SUPPRESSOR "*Lib/Audio/DisableNS"
    03425
    03426         /** Setupkey SETUPKEY_DISABLE_AGC type:boolean  Disables Skype automatic gain controller @n This setup key is machine-specific and affects all local accounts. @n  */
    03427         #define SETUPKEY_DISABLE_AGC "*Lib/Audio/DisableAGC"
    03428
    03429         /** Setupkey SETUPKEY_DISABLE_DIGITAL_NEAR_END_AGC type:boolean  @n Disables Skype digital near-end gain controller @n This setup key is machine-specific and affects all local accounts. @n  */
    03430         #define SETUPKEY_DISABLE_DIGITAL_NEAR_END_AGC "*Lib/Audio/DisableDigitalNearEndAGC"
    03431
    03432         /** Setupkey SETUPKEY_DISABLE_DIGITAL_FAR_END_AGC type:boolean  @n Disables Skype digital far-end gain controller @n This setup key is machine-specific and affects all local accounts. @n  */
    03433         #define SETUPKEY_DISABLE_DIGITAL_FAR_END_AGC "*Lib/Audio/DisableDigitalFarEndAGC"
    03434
    03435         /** Setupkey SETUPKEY_BEAMFORMER_MIC_SPACING type:string  @n Space-separated array of 1 (in case of 2 microphones) or 2 (in case of 4 microphones) integers. SAL beamforming currently only supports 2 and 4-microphone configurations. The values represent the spacing between microphones (in millimeters). @n In case of 2-microphone setup, Only the first value is used. @n  @n In case of 4-microphone setup, The first value is the distance between inner pair of microphones. The second value is the distance between inner pair of microphones and the outer pair. Like this: @n  @n Let the microphones be on straight line, A B C D. @n Microphones B and C form the inner pair, while A and D form the outer pair. @n The first value in the setup string would be distance between B and C. @n The second value would be distance between A and B (which is the same as distance between C and D). @n  @n With 4-mic setup, you will need to use two channels. The inner pair should go to one channel (left) and the outer pair should go to another (right). @n  @n This setup key is machine-specific and affects all local accounts. @n  */
    03436         #define SETUPKEY_BEAMFORMER_MIC_SPACING "*Lib/Audio/BeamformerMicSpacing"
    03437
    03438         /** Setupkey SETUPKEY_DISABLE_AUDIO_DEVICE_PROBING type:boolean  @n Disables audio devices probing @n This setup key is machine-specific and affects all local accounts. @n  */
    03439         #define SETUPKEY_DISABLE_AUDIO_DEVICE_PROBING "*Lib/QualityMonitor/DisableAudioDeviceProbing"
    03440
    03441         enum PREPARESOUNDRESULT {
    03442                 PREPARESOUND_SUCCESS = 0,
    03443                 PREPARESOUND_MISC_ERROR,
    03444                 PREPARESOUND_FILE_NOT_FOUND,
    03445                 PREPARESOUND_FILE_TOO_BIG,
    03446                 PREPARESOUND_FILE_READ_ERROR,
    03447                 PREPARESOUND_UNSUPPORTED_FILE_FORMAT,
    03448                 PREPARESOUND_PLAYBACK_NOT_SUPPORTED
    03449         };
    03450
    03451         enum AUDIODEVICE_CAPABILITIES {
    03452                 HAS_VIDEO_CAPTURE = 1,
    03453                 HAS_USB_INTERFACE,
    03454                 POSSIBLY_HEADSET = 4,
    03455                 HAS_AUDIO_CAPTURE = 8,
    03456                 HAS_AUDIO_RENDERING = 16,
    03457                 HAS_LOWBANDWIDTH_CAPTURE = 32,
    03458                 IS_WEBCAM = 64,
    03459                 IS_HEADSET = 128,
    03460                 POSSIBLY_WEBCAM = 256,
    03461                 HAS_VIDEO_RENDERING = 2048,
    03462                 HAS_BLUETOOTH_INTERFACE = 4096
    03463         };
    03464
    03465         /** Takes audio data that comes from the sound argument and mixes it into playback or notification device, depending on the value passed in the useCallOutDevice argument. The sound argument contains the audio data in in follwing format: first 4 bytes of the binary contain the sample rate, followed by 16 bit (mono) samples. The soundid argument is an arbitrary ID that you can pass in and then later use as an argument for Skype class PlayStop method. To mix the audio into playback device stream, set useCallOutDevice to true, to mic it into notification stream, set useCallOutDevice to false. @n  */
    03466         bool PlayStart(
    03467                 const uint& soundid,
    03468                 const Sid::Binary& sound,
    03469                 const bool& loop,
    03470                 const bool useCallOutDevice = false
    03471         );
    03472
    03473         bool PlayStartFromFile(
    03474                 const uint& soundid,
    03475                 const Sid::Filename& datafile,
    03476                 const bool& loop,
    03477                 PREPARESOUNDRESULT& result,
    03478                 const bool useCallOutDevice = false
    03479         );
    03480
    03481         /** Stops playback of the soundfile. The argument is the same ID you passed in the Skype class StartPlayback method. @n  */
    03482         bool PlayStop(
    03483                 const uint& soundid
    03484         );
    03485
    03486         bool StartRecordingTest(
    03487                 const bool recordAndPlaybackData = false
    03488         );
    03489
    03490         bool StopRecordingTest(
    03491         );
    03492
    03493         /** This method returns a table in form of three string lists of equal lengths. The first list contains audio output device handles ('hw:0,0', 'hw:0,1', etc.) The second list contains descriptive names of those devices (Ensoniq AudioPCI etc.) The third list contains device product IDs. Note that the values in these lists depend on which audio engine you are running (SAL, PCM, RTP). @n  */
    03494         bool GetAvailableOutputDevices(
    03495                 Sid::List_String& handleList,
    03496                 Sid::List_String& nameList,
    03497                 Sid::List_String& productIdList
    03498         );
    03499
    03500         /** This method returns a table in form of three string lists of equal length. The first list contains audio recording device handles ('hw:0,0', 'hw:0,1', etc.) The second list contains descriptive names of those devices (Ensoniq AudioPCI etc.) The third list contains device product IDs. Note that the values in these lists depend on which audio engine you are running (SAL, PCM, RTP). @n  */
    03501         bool GetAvailableRecordingDevices(
    03502                 Sid::List_String& handleList,
    03503                 Sid::List_String& nameList,
    03504                 Sid::List_String& productIdList
    03505         );
    03506
    03507         /** Sets audio devices given in arguments as active audio devices. This command selects all three devices - microphone, playback and the notification channel. Valid input values for this method come from the first string list you get back from Skype class GetAvailableOutputDevices (handleList). @n  */
    03508         bool SelectSoundDevices(
    03509                 const Sid::String& callInDevice,
    03510                 const Sid::String& callOutDevice,
    03511                 const Sid::String& waveOutDevice
    03512         );
    03513
    03514         /** The uint argument returns AUDIODEVICE_CAPABILITIES (declared in Skype class) @n  */
    03515         bool GetAudioDeviceCapabilities(
    03516                 const Sid::String& deviceHandle,
    03517                 Sid::String& interfaceString,
    03518                 uint& capabilities /*!< bit set of AUDIODEVICE_CAPABILITIES*/
    03519         );
    03520
    03521         /** Returns current audio stream volume for both playback and microphone streams. Useful for displaying visual audio indicators in you UI. See also Skype class OnNrgLevelsChange callback that gets fired each time the these values are changed. @n  */
    03522         bool GetNrgLevels(
    03523                 uint& micLevel,
    03524                 uint& speakerLevel
    03525         );
    03526
    03527         /** NB! This command only works if its implemented in external audiohost (RTP or PCM host). The command can be is used for passing custom commands from client UI to the audio implementation. @n  */
    03528         bool VoiceCommand(
    03529                 const Sid::String& command,
    03530                 Sid::String& response
    03531         );
    03532
    03533         /** Returns value of audio playback volume setting (0..100). @n  */
    03534         bool GetSpeakerVolume(
    03535                 uint& volume
    03536         );
    03537
    03538         /** This method is for setting speaker volume. It will set the level for Skype digital gain control. Skype audio library will not control gain of audio device itself. @n  */
    03539         bool SetSpeakerVolume(
    03540                 const uint& volume
    03541         );
    03542
    03543         /** Returns value of microphone volume setting (0..100). It will return the analog gain of audio device set by Skype AGC. For real-time microphone volume, use GetNrgLevels method or OnNrgLevelsChange callback (both are methods of Skype class). @n  */
    03544         bool GetMicVolume(
    03545                 uint& micVolume
    03546         );
    03547
    03548         /** This method is for setting the microphone volume level. This does not work when Skype AGC (Automatic Gain Control) is enabled, which it is by default. It is currently impossible to disable AGC, so for now this method is here for purpose of future compatibility. @n  */
    03549         bool SetMicVolume(
    03550                 const uint& volume
    03551         );
    03552
    03553         /** Returns true in &muted argument if the currently selected playback device is muted. @n  */
    03554         bool IsSpeakerMuted(
    03555                 bool& muted
    03556         );
    03557
    03558         /** Returns true in &muted argument if the currently selected microphone is muted. @n  */
    03559         bool IsMicrophoneMuted(
    03560                 bool& muted
    03561         );
    03562
    03563         /** Sets currently selected playback device mute status according to argument. @n  */
    03564         bool MuteSpeakers(
    03565                 const bool& mute
    03566         );
    03567
    03568         /** Sets currently selected microphone mute status according to argument. @n  */
    03569         bool MuteMicrophone(
    03570                 const bool& mute
    03571         );
    03572
    03573         /** This callback gets fired when there are changes in the system audio device list (USB headset gets plugged in or is detached.) @n  */
    03574         virtual void OnAvailableDeviceListChange(
    03575         );
    03576
    03577         /** This callback gets fired when the audio strength changes in either playback or recording audio streams. Useful for providing visual indicators of audio activity in your UI. @n  */
    03578         virtual void OnNrgLevelsChange(
    03579         );
    03580
    03581         enum OPERATING_MEDIA {
    03582                 OM_UNKNOWN = 0,
    03583                 OM_FREE,
    03584                 OM_FREE_WIRELESS,
    03585                 OM_3G,
    03586                 OM_4G
    03587         };
    03588
    03589         bool SetOperatingMedia(
    03590                 const OPERATING_MEDIA& media,
    03591                 const uint& maxUplinkBps,
    03592                 const uint& maxDownlinkBps
    03593         );
    03594
    03595         /** creates and sends a CONFIRMATION_CODE_REQUEST message                   this sends a confirmation code to the number provided */
    03596         bool RequestConfirmationCode(
    03597                 const Sms::CONFIRM_TYPE& type,
    03598                 const Sid::String& number,
    03599                 SmsRef& sms
    03600         );
    03601
    03602         /** creates and sends a CONFIRMATION_CODE_SUBMIT message                   this authorizes the number with the server for the purpose given in RequestConfirmationCode */
    03603         bool SubmitConfirmationCode(
    03604                 const Sid::String& number,
    03605                 const Sid::String& code,
    03606                 SmsRef& sms
    03607         );
    03608
    03609         /** creates an OUTGOING/COMPOSING SMS message */
    03610         bool CreateOutgoingSms(
    03611                 SmsRef& sms
    03612         );
    03613
    03614         /** Setupkey SETUPKEY_FT_AUTOACCEPT type:int  @n Controls file transfer auto-accept.  @li 0 - off @li 1 - on @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    03615         #define SETUPKEY_FT_AUTOACCEPT "Lib/FileTransfer/AutoAccept"
    03616
    03617         /** Setupkey SETUPKEY_FT_SAVEPATH type:string  @n Full local path to save incoming file transfers (used for AutoAccept feature) @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    03618         #define SETUPKEY_FT_SAVEPATH "Lib/FileTransfer/SavePath"
    03619
    03620         /** Setupkey SETUPKEY_FT_INCOMING_LIMIT type:uint  @n Number of simultaneous incoming file transfers (per user). Value 0 means no limitation.  @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    03621         #define SETUPKEY_FT_INCOMING_LIMIT "Lib/FileTransfer/IncomingLimit"
    03622
    03623         /** Setupkey SETUPKEY_IDLE_TIME_FOR_AWAY type:int  @n Number of seconds since the last keyboard or mouse activity, after which the online status of currently logged in account should be set to AWAY. See Account::SetAvailability method for more information. @n This is account-specific setup key. It can only be used while an account is logged in. @n  */
    03624         #define SETUPKEY_IDLE_TIME_FOR_AWAY "Lib/Account/IdleTimeForAway"
    03625
    03626         /** Setupkey SETUPKEY_IDLE_TIME_FOR_NA type:int  @n The Contact::AVAILABILITY.NOT_AVAILABLE online status has been deprecated. This setup key is no longer in use. @n  */
    03627         #define SETUPKEY_IDLE_TIME_FOR_NA "Lib/Account/IdleTimeForNA"
    03628
    03629         /** Retrieves an Account object by Skype name (identity). This should normally be one of the first method calls after Skype object initialization. Nearly all the other methods require successful account login in order to work properly. The list of accounts that have been used on the local machine/database can be retrieved with Skype::GetExistingAccounts method. If a matching identity is not found, a new Account object is created. This object can then be used to populate requred fields and then use Account::Register method for new account creation. This method returns false on error. @n  */
    03630         bool GetAccount(
    03631                 const Sid::String& identity, /*!< Account skypename. @n */
    03632                 AccountRef& account /*!< Returns account object if successful. @n */
    03633         );
    03634
    03635         /** Returns a list of possible profiles used before on this machine */
    03636         bool GetExistingAccounts(
    03637                 Sid::List_String& accountNameList
    03638         );
    03639
    03640         /** return most recently used account that has pwd saved. empty string if none */
    03641         bool GetDefaultAccountName(
    03642                 Sid::String& account
    03643         );
    03644
    03645         /** suggest a nice skypename to go with given fullname */
    03646         bool GetSuggestedSkypename(
    03647                 const Sid::String& fullname,
    03648                 Sid::String& suggestedName
    03649         );
    03650
    03651         /** A value of this type can be returned by one of the following methods (of Skype class): ValidateAvatar, ValidateProfileString, ValidatePassword.  @n  */
    03652         enum VALIDATERESULT {
    03653                 NOT_VALIDATED = 0             /*!< Given property could not be validated. The length of the field was within limits and the value is assumed to be Ok. Your client should treat this value as equivalent to VALIDATED_OK. @n */,
    03654                 VALIDATED_OK                  /*!< Avatar or profile string validation succeeded. @n */,
    03655                 TOO_SHORT                     /*!< Password is too short. @n */,
    03656                 TOO_LONG                      /*!< The value exceeds max size limit for the given property. @n */,
    03657                 CONTAINS_INVALID_CHAR         /*!< Value contains illegal characters. @n */,
    03658                 CONTAINS_SPACE                /*!< Value contains whitespace. @n */,
    03659                 SAME_AS_USERNAME              /*!< Password cannot be the same as skypename. @n */,
    03660                 INVALID_FORMAT                /*!< Value has invalid format. @n */,
    03661                 CONTAINS_INVALID_WORD         /*!< Value contains invalid word. @n */,
    03662                 TOO_SIMPLE                    /*!< Password is too simple. @n */,
    03663                 STARTS_WITH_INVALID_CHAR      /*!< Value starts with an invalid character. @n */
    03664         };
    03665
    03666         bool ValidateAvatar(
    03667                 const Sid::Binary& value,
    03668                 VALIDATERESULT& result,
    03669                 int& freeBytesLeft
    03670         );
    03671
    03672         /** This method should be used for validating skypenames before registering new accounts, if the propKey is set to SKYPENAME (Contact class) and forRegistration argument is set to true. If the forRegistration argument is false, only string length check is applied. It is also useful to probe, what the size limits are, for each string property (e.g. 300 characters for moodmessage) @n  */
    03673         bool ValidateProfileString(
    03674                 const int& propKey,
    03675                 const Sid::String& strValue,
    03676                 VALIDATERESULT& result,
    03677                 int& freeBytesLeft,
    03678                 const bool forRegistration = false
    03679         );
    03680
    03681         /** This method is for pre-validating account passwords before account creation or password change. The result will return either VALIDATED_OK or one of many possible reasons the password is unacceptable (too short, too simple, etc.) @n  */
    03682         bool ValidatePassword(
    03683                 const Sid::String& username,
    03684                 const Sid::String& password,
    03685                 VALIDATERESULT& result
    03686         );
    03687
    03688         /** Setupkey SETUPKEY_PORT type:int  @n Suggested port number (lib will *try* to use that) @n This setup key is machine-specific and affects all local accounts. @n  */
    03689         #define SETUPKEY_PORT "*Lib/Connection/Port"
    03690
    03691         /** Setupkey SETUPKEY_HTTPS_PROXY_ENABLE type:int  @n Set to 0 for automatic proxy detect, 1 to use proxy config below @n This setup key is machine-specific and affects all local accounts. @n  */
    03692         #define SETUPKEY_HTTPS_PROXY_ENABLE "*Lib/Connection/HttpsProxy/Enable"
    03693
    03694         /** Setupkey SETUPKEY_HTTPS_PROXY_ADDR type:string  @n name:port of HTTP proxy server @n This setup key is machine-specific and affects all local accounts. @n  */
    03695         #define SETUPKEY_HTTPS_PROXY_ADDR "*Lib/Connection/HttpsProxy/Addr"
    03696
    03697         /** Setupkey SETUPKEY_HTTPS_PROXY_USER type:string  @n HTTPS proxy server username @n This setup key is machine-specific and affects all local accounts. @n  */
    03698         #define SETUPKEY_HTTPS_PROXY_USER "*Lib/Connection/HttpsProxy/User"
    03699
    03700         /** Setupkey SETUPKEY_HTTPS_PROXY_PWD type:string  @n HTTPS proxy server password (base64 encoded) @n This setup key is machine-specific and affects all local accounts. @n  */
    03701         #define SETUPKEY_HTTPS_PROXY_PWD "*Lib/Connection/HttpsProxy/Pwd"
    03702
    03703         /** Setupkey SETUPKEY_SOCKS_PROXY_ENABLE type:int  @n Set to non-zero to enable socks proxy support @n This setup key is machine-specific and affects all local accounts. @n  */
    03704         #define SETUPKEY_SOCKS_PROXY_ENABLE "*Lib/Connection/SocksProxy/Enable"
    03705
    03706         /** Setupkey SETUPKEY_SOCKS_PROXY_ADDR type:string  @n name:port of SOCKS proxy server @n This setup key is machine-specific and affects all local accounts. @n  */
    03707         #define SETUPKEY_SOCKS_PROXY_ADDR "*Lib/Connection/SocksProxy/Addr"
    03708
    03709         /** Setupkey SETUPKEY_SOCKS_PROXY_USER type:string  @n SOCKS proxy server username @n This setup key is machine-specific and affects all local accounts. @n  */
    03710         #define SETUPKEY_SOCKS_PROXY_USER "*Lib/Connection/SocksProxy/User"
    03711
    03712         /** Setupkey SETUPKEY_SOCKS_PROXY_PWD type:string  @n SOCKS proxy server password (base64 encoded) @n This setup key is machine-specific and affects all local accounts. @n  */
    03713         #define SETUPKEY_SOCKS_PROXY_PWD "*Lib/Connection/SocksProxy/Pwd"
    03714
    03715         /** Setupkey SETUPKEY_LOCALADDRESS type:string  @n local interface to listen to @n This setup key is machine-specific and affects all local accounts. @n  */
    03716         #define SETUPKEY_LOCALADDRESS "*Lib/Connection/LocalAddress"
    03717
    03718         /** Setupkey SETUPKEY_DISABLE_PORT80 type:int  @n 1 disables listening of alternative ports (80, 443) @n This setup key is machine-specific and affects all local accounts. @n  */
    03719         #define SETUPKEY_DISABLE_PORT80 "*Lib/Connection/DisablePort80"
    03720
    03721         /** Setupkey SETUPKEY_DISABLE_UDP type:int  @n 1 disables UDP port binding. should be set before connect @n This setup key is machine-specific and affects all local accounts. @n  */
    03722         #define SETUPKEY_DISABLE_UDP "*Lib/Connection/DisableUDP"
    03723
    03724         enum PROXYTYPE {
    03725                 HTTPS_PROXY = 0,
    03726                 SOCKS_PROXY
    03727         };
    03728
    03729         virtual void OnProxyAuthFailure(
    03730                 const PROXYTYPE& type
    03731         );
    03732
    03733         /** port that lib ended up listening. usually equal to SETUPKEY_PORT. 0 if none used (disconnected or binding failed) */
    03734         bool GetUsedPort(
    03735                 uint& port
    03736         );
    03737
    03738         /** This is used for retrieving local setup keys of type string. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03739         bool GetStr(
    03740                 const Sid::String& key,
    03741                 Sid::String& value
    03742         );
    03743
    03744         /** This is used for retrieving local setup keys of type int. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03745         bool GetInt(
    03746                 const Sid::String& key,
    03747                 int& value
    03748         );
    03749
    03750         /** This is used for retrieving local setup keys of type binary. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03751         bool GetBin(
    03752                 const Sid::String& key,
    03753                 Sid::Binary& value
    03754         );
    03755
    03756         /** This is used for setting local setup keys of type string. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03757         bool SetStr(
    03758                 const Sid::String& key,
    03759                 const Sid::String& value
    03760         );
    03761
    03762         /** This is used for setting local setup keys of type int. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03763         bool SetInt(
    03764                 const Sid::String& key,
    03765                 const int& value
    03766         );
    03767
    03768         /** This is used for setting local setup keys of type binary. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03769         bool SetBin(
    03770                 const Sid::String& key,
    03771                 const Sid::Binary& value
    03772         );
    03773
    03774         /** Returns true if the given setup key is defined in local setup. For more information, see Defines section in the skype-embedded_2.h  @n  */
    03775         bool IsDefined(
    03776                 const Sid::String& key,
    03777                 bool& value
    03778         );
    03779
    03780         bool Delete(
    03781                 const Sid::String& key
    03782         );
    03783
    03784         bool GetSubKeys(
    03785                 const Sid::String& key,
    03786                 Sid::List_String& value
    03787         );
    03788
    03789         /** Returns two string lists. First of them will contain list of two-letter language codes (ISO 639-1) The second list contains names of corresponding languages. @n  */
    03790         bool GetISOLanguageInfo(
    03791                 Sid::List_String& languageCodeList,
    03792                 Sid::List_String& languageNameList /*!< assumes UI has set correct language*/
    03793         );
    03794
    03795         /** Returns three string lists and one int array, containing 2-letter country code, country name, dialing prefix and example dial string (not available for all items). This method does currently return 0 for South Georgia and the South Sandwich Islands. @n  */
    03796         bool GetISOCountryInfo(
    03797                 Sid::List_String& countryCodeList,
    03798                 Sid::List_String& countryNameList, /*!< assumes UI has set correct language*/
    03799                 Sid::List_uint& countryPrefixList,
    03800                 Sid::List_String& countryDialExampleList
    03801         );
    03802
    03803         /** Returns 2-letter country code based on PSTN number. The input argument has to be without + in from of it - '37212345678' will return 'ee' while '+37212345678' will return an empty string. @n  */
    03804         bool GetISOCountryCodebyPhoneNo(
    03805                 const Sid::String& number,
    03806                 Sid::String& countryCode
    03807         );
    03808
    03809         /** App2AppCreate method constructs a local instance of an App2App application. App2App applications are not abstracted in the SkypeKit API as a separate class. Rather, they can be created with App2AppCreate, supplying their name as ID, and then connected to remote parties using App2AppConnect method. @n  @n App2App portion of the SkypeKit API enables you to implement arbitrary data exchange protocols between Skype clients. Basically, if you are ever tempted to use conversation chat messages for something other than actual human-readable chat - you should consider using your own custom App2App protocol instead. @n  @n The downside of App2App is that all the participants need to be running a client that supports the same App2App application. Although, it is possible to have one side using a custom SkypeKit client and another side using Skype desktop client - App2App is supported in both, in case of desktop client via Public API - you are still limited to remote side running something that can recognize your protocol and react to connection attempts from your side. @n  @n To establish connection between each other, all participants need to create their local instances of the application (with the same ID, and then connect to each other. More than one App2App applications can be active in a local client at the same time. Also, more than two clients can be connected with the same application. @n  @n Once connection is established, you can choose between two communication methods - datagrams and stream read/write methods. Overall, there are not much principal difference between the two. Datagram packet size is limited to 1500 bytes and stream packet size to 32 KB of payload data. Implementation-wise, datagrams are probably somewhat easier to deal with. @n  */
    03810         bool App2AppCreate(
    03811                 const Sid::String& appname, /*!< Application ID. This ID is used by the rest of the App2App commands to differentiate between applications, should there be more than one app2app applications running on the local system. @n */
    03812                 bool& result /*!< Returns true if the app creation was successful. Returns false when an application with the same name already exists in the local system. @n */
    03813         );
    03814
    03815         /** Disconnects and deletes the App2App application. @n  */
    03816         bool App2AppDelete(
    03817                 const Sid::String& appname, /*!< application ID. @n */
    03818                 bool& result /*!< Returns true if the deletion was successful (application with such ID actually existed) @n */
    03819         );
    03820
    03821         /** The App2AppConnect connect result does not mean the connection was immediately established. It will return Ok even if the remote party was offline. The actual connection will be established when both parties have fired App2AppConnect with the same application name, at eachother. At that point, OnApp2AppStreamListChange event will fire for both local and remote party (with listType argument set to ALL_STREAMS) and you can start exchanging data, using either App2App datagrams or App2AppRead App2AppWrite methods. @n  */
    03822         bool App2AppConnect(
    03823                 const Sid::String& appname, /*!< Application ID. This needs to match with application ID connecting from the remote side. @n */
    03824                 const Sid::String& skypename, /*!< Skype Name of the remote party. @n */
    03825                 bool& result /*!< NB! This argument will return true even if the remote party has not yet connected (or is not even online yet) - it merely indicates that the connect command was successfuly processed in runtime. The actual connection success will be indicated when the OnApp2AppStreamListChange event fires, i.e. when App2App stream will be established between connecting parties. @n */
    03826         );
    03827
    03828         /** Disconnects an App2App stream. This is different from App2AppDelete command in that it enables you to disconnect remote parties selectively - in case there are more than two participants in the App2App stream pool. @n  */
    03829         bool App2AppDisconnect(
    03830                 const Sid::String& appname, /*!< application ID @n */
    03831                 const Sid::String& stream, /*!< stream ID. @n */
    03832                 bool& result /*!< returns true when the stream disconnect was successful. @n */
    03833         );
    03834
    03835         /** Sends a stream packet to the remote party specified in the stream argument. The max size of stream write packet is 32KB. After calling this method, OnApp2AppStreamListChange will fire for both parties. In local ssytem with listType set to SENDING_STREAMS and on remote system with listType set to RECEIVED_STREAMS. This event can be used to read received packets out of the stream. @n  */
    03836         bool App2AppWrite(
    03837                 const Sid::String& appname, /*!< application ID @n */
    03838                 const Sid::String& stream, /*!< stream ID @n */
    03839                 const Sid::Binary& data, /*!< packet payload @n */
    03840                 bool& result /*!< returns true if the call was successful. Note that this does indicate the packet was actually received by remote party. @n */
    03841         );
    03842
    03843         /** Sends a datagram to the remote party specified in the stream argument. The max size of datagram payload is 1500 bytes. @n  */
    03844         bool App2AppDatagram(
    03845                 const Sid::String& appname, /*!< application ID - from App2AppCreate @n */
    03846                 const Sid::String& stream, /*!< stream ID - either from App2AppGetStreamsList or from OnApp2AppStreamListChange*/
    03847                 const Sid::Binary& data, /*!< datagram payload (max 1500 bytes)*/
    03848                 bool& result /*!< returns true on method success. Note that this does mean the remote party has actually received your datagram - that sort of feedback, should you want it, is up to you to implement in your custom protocol.*/
    03849         );
    03850
    03851         /** Reads data from the specified stream. This method should be called from the OnApp2AppStreamListChange event callback, when this callback gets fired with listType argument set to RECEIVED_STREAMS. @n  */
    03852         bool App2AppRead(
    03853                 const Sid::String& appname, /*!< application ID @n */
    03854                 const Sid::String& stream, /*!< stream ID @n */
    03855                 bool& result, /*!< returns true on method success. Note that this does mean the remote party has actually received your packet - that sort of feedback, should you want it, is up to you to implement in your custom protocol. @n */
    03856                 Sid::Binary& data /*!< stream packet payload @n */
    03857         );
    03858
    03859         /** App2AppGetConnectableUsers returns a list of currently online contacts. It does not return a list of contacts who have an app2app application running. There is currently no way of querying whether an application has been launched on the remote side - other than trying to connect to the remote side and waiting for timeout. NB! if you use App2AppGetConnectableUsers immediately after login - then the online presence of your contact list has not yet updated itself - so this method will most likely return either an empty list or a list with echo123 in it. @n  */
    03860         bool App2AppGetConnectableUsers(
    03861                 const Sid::String& appname, /*!< application ID @n */
    03862                 bool& result, /*!< returns true on method success @n */
    03863                 Sid::List_String& users /*!< stringlist with Skype Names of connectable users @n */
    03864         );
    03865
    03866         enum APP2APP_STREAMS {
    03867                 ALL_STREAMS = 0,
    03868                 SENDING_STREAMS,
    03869                 RECEIVED_STREAMS
    03870         };
    03871
    03872         /** Takes application ID and list type filter and returns a stringlist with streamID's that pass the filter. @n  */
    03873         bool App2AppGetStreamsList(
    03874                 const Sid::String& appname, /*!< application ID @n */
    03875                 const APP2APP_STREAMS& listType, /*!< list type filter @n */
    03876                 bool& result, /*!< results true if the method call was successful @n */
    03877                 Sid::List_String& streams, /*!< string list with stream IDs @n */
    03878                 Sid::List_uint& receivedSizes /*!< For RECEIVED_STREAMS, contains the number of bytes in each stream waiting to be read*/
    03879         );
    03880
    03881         /** This event gets fired on incoming app2app datagram. @n
    03882         * @param appname App2app application ID. @n
    03883         * @param stream App2app stream ID - see OnApp2AppStreamListChange event for obtaining stream IDs. @n
    03884         * @param data Datagram payload - limited to 1500 bytes. @n
    03885         */
    03886         virtual void OnApp2AppDatagram(
    03887                 const Sid::String& appname,
    03888                 const Sid::String& stream,
    03889                 const Sid::Binary& data
    03890         );
    03891
    03892         /** In context of datagrams, this event will fire when: @li Connection is established between two app2app applications. That is, when both parties have an app up with the same name and -both- used App2AppConnect In that case, both parties get this event, with listType ALL_STREAMS @li When a datagram is sent, the sender will get this event with listType SENDING_STREAMS Receiver of the datagram will get OnApp2AppDatagram event instead. @li When the remote party drops app2app connection, the local user will get OnApp2AppStreamListChange with listType ALL_STREAMS and streams.size() zero. @n In context of stream reads/writes, this event will fire for both the sender (listType == SENDING_STREAMS)and the receiver (listType == RECEIVED_STREAMS). For receiver side, this is the place to put your reading code - App2AppRead. @n
    03893         * @param appname application ID - the name you supplied in App2AppCreate. @n
    03894         * @param listType application list type (read/write/all) @n
    03895         * @param streams SEStringlist with affected stream IDs. @n
    03896         * @param receivedSizes For RECEIVED_STREAMS, contains the number of bytes in each stream waiting to be read
    03897         */
    03898         virtual void OnApp2AppStreamListChange(
    03899                 const Sid::String& appname,
    03900                 const APP2APP_STREAMS& listType,
    03901                 const Sid::List_String& streams,
    03902                 const Sid::List_uint& receivedSizes
    03903         );
    03904
    03905 };
    03906 #ifdef SE_USE_NAMESPACE
    03907 };
    03908 #endif
    03909
    03910 #endif //compile-guard

All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

(c) Skype Technologies S.A. Confidential/Proprietary

Last updated: Fri Jan 27 2012