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