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