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

All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

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

Last updated: Fri Mar 16 2012