Public Types | Public Member Functions

Message Class Reference

Events in a conversation context are expressed as Messages. It is therefore useful to think of Message objects as events, rather than specifically text chat messages. More...

#include <skype-embedded_2.h>

List of all members.

Public Types

enum  { MODULE_ID = 9 }
enum  PROPERTY {
  P_CONVO_ID = 960,
  P_CONVO_GUID = 120,
  P_AUTHOR = 122,
  P_AUTHOR_DISPLAYNAME,
  P_GUID = 792,
  P_ORIGINALLY_MEANT_FOR = 790,
  P_TIMESTAMP = 121,
  P_TYPE = 961,
  P_SENDING_STATUS,
  P_CONSUMPTION_STATUS = 968,
  P_EDITED_BY = 222,
  P_EDIT_TIMESTAMP,
  P_PARAM_KEY = 963,
  P_PARAM_VALUE,
  P_BODY_XML = 127,
  P_IDENTITIES = 125,
  P_REASON = 966,
  P_LEAVEREASON = 126,
  P_PARTICIPANT_COUNT = 982
}
enum  TYPE {
  SET_METADATA = 2,
  SPAWNED_CONFERENCE = 4,
  ADDED_CONSUMERS = 10,
  ADDED_APPLICANTS,
  RETIRED_OTHERS,
  RETIRED,
  SET_RANK = 21,
  STARTED_LIVESESSION = 30,
  ENDED_LIVESESSION = 39,
  REQUESTED_AUTH = 50,
  GRANTED_AUTH,
  BLOCKED = 53,
  POSTED_TEXT = 61,
  POSTED_EMOTE = 60,
  POSTED_CONTACTS = 63,
  POSTED_SMS,
  POSTED_ALERT,
  POSTED_VOICE_MESSAGE = 67,
  POSTED_FILES,
  POSTED_INVOICE,
  HAS_BIRTHDAY = 110
}
enum  SENDING_STATUS {
  SENDING = 1,
  SENT,
  FAILED_TO_SEND
}
enum  CONSUMPTION_STATUS {
  CONSUMED = 0,
  UNCONSUMED_SUPPRESSED,
  UNCONSUMED_NORMAL,
  UNCONSUMED_ELEVATED
}
enum  SET_METADATA_KEY {
  SET_META_NAME = 3640,
  SET_META_TOPIC = 3644,
  SET_META_GUIDELINES = 3652,
  SET_META_PICTURE = 3658
}
enum  LEAVEREASON {
  USER_INCAPABLE = 2,
  ADDER_MUST_BE_FRIEND,
  ADDER_MUST_BE_AUTHORIZED,
  DECLINE_ADD,
  UNSUBSCRIBE
}
typedef MessageRef Ref
typedef MessageRefs Refs

Public Member Functions

virtual ~Message ()
MessageRef ref ()
bool CanEdit (bool &result)
bool Edit (const Sid::String &newText, const bool isXML=false, const bool undo=false)
bool GetContacts (ContactRefs &contacts)
bool GetTransfers (TransferRefs &transfers)
bool GetVoiceMessage (VoicemailRef &voicemail)
bool GetSMS (SmsRef &sms)
bool DeleteLocally ()
bool GetPropConvoId (ConversationRef &convo_id)
bool GetPropConvoGuid (Sid::String &convo_guid)
bool GetPropAuthor (Sid::String &author)
bool GetPropAuthorDisplayname (Sid::String &author_displayname)
bool GetPropGuid (Sid::Binary &guid)
bool GetPropOriginallyMeantFor (Sid::String &originally_meant_for)
bool GetPropTimestamp (uint &timestamp)
bool GetPropType (Message::TYPE &type)
bool GetPropSendingStatus (Message::SENDING_STATUS &sending_status)
bool GetPropConsumptionStatus (Message::CONSUMPTION_STATUS &consumption_status)
bool GetPropEditedBy (Sid::String &edited_by)
bool GetPropEditTimestamp (uint &edit_timestamp)
bool GetPropParamKey (uint &param_key)
bool GetPropParamValue (uint &param_value)
bool GetPropBodyXml (Sid::String &body_xml)
bool GetPropIdentities (Sid::String &identities)
bool GetPropReason (Sid::String &reason)
bool GetPropLeavereason (LEAVE_REASON &leavereason)
bool GetPropParticipantCount (uint &participant_count)

Detailed Description

Events in a conversation context are expressed as Messages. It is therefore useful to think of Message objects as events, rather than specifically text chat messages.



Message member functions all return a Boolean indicating the success (true) or failure (false) of processing the request itself (transport, runtime availability, and so forth) - not the success or failure of its associated functionality. For example, Message::Edit returns true if it was able to make a determination, and its result parameter reflects whether this Message can be edited. Similarly, Message::Edit returns false if it was unable to make a determination, and the value of its result parameter is undefined.

Message member functions that are specific to a Message TYPE return false if this Message is not of that type. For example, Message::GetVoiceMessage will return false if this Message's type is not POSTED_VOICE_MESSAGE.

The actual meaning of a Message can be determined by its P_TYPE property. The meanings of most other Message properties depend on the value of P_TYPE. For example, let's take P_BODY_XML property.

Following messages have a text entered by the user as a body. It may contain emoticons, URLs, etc.

Definition at line 1618 of file skype-embedded_2.h.


Member Typedef Documentation

Definition at line 1627 of file skype-embedded_2.h.

Definition at line 1628 of file skype-embedded_2.h.


Member Enumeration Documentation

anonymous enum
Enumerator:
MODULE_ID 

Definition at line 1629 of file skype-embedded_2.h.

Indicates if a message has been consumed (meaning read) or not

Enumerator:
CONSUMED 

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.

UNCONSUMED_SUPPRESSED 

Do not notify the user that they have this unread message

UNCONSUMED_NORMAL 

Notify the user that they have this unread message

UNCONSUMED_ELEVATED 

This message consumption state is marked as DEPRECATED

Definition at line 1697 of file skype-embedded_2.h.

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.

Enumerator:
USER_INCAPABLE 

User cannot chat (user is currently logged in with a client that has chat disabled - see Contact::CAPABILITY.CAPABILITY_TEXT)

ADDER_MUST_BE_FRIEND 

Attempt to add local user to a conversation by an unknown contact

ADDER_MUST_BE_AUTHORIZED 

Attempt to add local user to a conversation by an unauthorized contact

DECLINE_ADD 

Local user declined an "invitation" to join a chat

UNSUBSCRIBE 

User decided to end participation in an on-going multi-chat

Definition at line 1713 of file skype-embedded_2.h.

Properties of the Message class

Enumerator:
P_CONVO_ID 

DB ID of corresponding conversation, type: ConversationRef

P_CONVO_GUID 

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.
, type: Sid::String

P_AUTHOR 

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).
, type: Sid::String

P_AUTHOR_DISPLAYNAME 

displayname of the sender at the time of posting, type: Sid::String

P_GUID 

Unlike the message id, the GUID is the same on all instances and for all participants.
, type: Sid::Binary

P_ORIGINALLY_MEANT_FOR 

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.
, type: Sid::String

P_TIMESTAMP 

UNIX timestamp (sent time, adjusted for local clock), type: uint

P_TYPE 

type: Message::TYPE

P_SENDING_STATUS 

type: Message::SENDING_STATUS

P_CONSUMPTION_STATUS 

type: Message::CONSUMPTION_STATUS

P_EDITED_BY 

Identity of the author that last edited this message. NULL if message has not been edited
, type: Sid::String

P_EDIT_TIMESTAMP 

UNIX timestamp of last edit, type: uint

P_PARAM_KEY 

Message type-specific parameter. See Message::SET_METADATA_KEY for more information.
, type: uint

P_PARAM_VALUE 

Message type-specific parameter
, type: uint

P_BODY_XML 

Message type-specific parameter
, type: Sid::String

P_IDENTITIES 

Message type-specific parameter. Depending of Message type, this property contains:

  • STARTED_LIVESESSION - list of participants in the cal;
  • ENDED_LIVESESSION - list of participants in the call;
  • POSTED_SMS - list of recipients of the message;
  • SPAWNED_CONFERENCE - the list of identities that were added;
  • ADDED_CONSUMERS - the list of identities that were added;
  • RETIRED_OTHERS - the skypename of the participant who was kicked;
  • SET_RANK - the skypename of the participant whose rank was changed;
  • 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;
  • GRANTED_AUTH - the skypename of the user we granted authorization;
  • BLOCKED - the skypename of the user who was blocked;
  • HAS_BIRTHDAY - skypename of current logged in user.
    , type: Sid::String
P_REASON 

Message type-specific parameter. Possible values for STARTED/ENDED_LIVESESSION (only set for dialogs):

  • no_answer
  • manual
  • busy
  • connection_dropped
  • no_skypeout_subscription;
  • insufficient_funds
  • internet_connection_lost
  • skypeout_account_blocked
  • pstn_could_not_connect_to_skype_proxy
  • pstn_invalid_number
  • pstn_number_forbidden
  • pstn_call_timed_out
  • pstn_busy
  • pstn_call_terminated
  • pstn_network_error
  • number_unavailable
  • pstn_call_rejected
  • pstn_misc_error
  • internal_error
  • unable_to_connect
  • connection_dropped
  • recording_failed
  • playback_error
  • legacy_error
  • blocked_by_privacy_settings
  • error
  • transfer_failed
  • transfer_insufficient_funds
  • blocked_by_us
  • emergency_call_denied

    This information is now available as an enum in LEAVEREASON
    , type: Sid::String
P_LEAVEREASON 

Leave reason for message of the RETIRED type, and STARTED/ENDED_LIVESESSION. Use for STARTED/ENDED_LIVESESSION is to provide simpler, enum based handling and deprecates the reason property (only set for dialogs), type: LEAVE_REASON

P_PARTICIPANT_COUNT 

Number of people who received this message (including local user)
, type: uint

Definition at line 1643 of file skype-embedded_2.h.

Enumerator:
SENDING 

Message has not been delivered to at least one of the participants

SENT 

Message has been delivered to at least one other participant

FAILED_TO_SEND 

Message could not be delivered (for SMS this reflects the actual SMS, not the chat message)

Definition at line 1690 of file skype-embedded_2.h.

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.
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.

Enumerator:
SET_META_NAME 

Notification message that conversation name has changed.

SET_META_TOPIC 

Notification message that conversation topic has changed.

SET_META_GUIDELINES 

Notification message that conversation guidelines have changed.

SET_META_PICTURE 

Notification message that conversation picture has changed.

Definition at line 1705 of file skype-embedded_2.h.

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.

Enumerator:
SET_METADATA 

Conference metadata were changed

SPAWNED_CONFERENCE 

A conference was spawned from this dialog

ADDED_CONSUMERS 

Some users were added to the conference

ADDED_APPLICANTS 

Some users are applying to be added to the conference

RETIRED_OTHERS 

User was kicked from the conference

RETIRED 

User left the conference

SET_RANK 

Changed the rank of a user in the Conversation (multichat administration)

STARTED_LIVESESSION 

A live session started

ENDED_LIVESESSION 

A live session ended

REQUESTED_AUTH 

User requested authorization

GRANTED_AUTH 

User was granted authorization. Notification message that user is now an authorized contact (of the local user).

BLOCKED 

User was blocked

POSTED_TEXT 

A text message

POSTED_EMOTE 

An emote ('John Doe is laughing', cf /me chat command)

POSTED_CONTACTS 

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

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.

POSTED_ALERT 

Deprecated, never sent

POSTED_VOICE_MESSAGE 

A voicemail

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

POSTED_INVOICE 

Currently unused.

HAS_BIRTHDAY 

The message represents a Contact birthday notification.

Definition at line 1666 of file skype-embedded_2.h.


Constructor & Destructor Documentation

Message::~Message (  )  [virtual]

Definition at line 760 of file skype-embedded_2.cpp.


Member Function Documentation

bool Message::CanEdit ( bool &  result  ) 

For Message types having a body, determines whether that body is editable by the user.

bool Message::DeleteLocally (  ) 

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.

bool Message::Edit ( const Sid::String &  newText,
const bool  isXML = false,
const bool  undo = false 
)

For Message types that include a body and are editable:

  • alters BODY_XML of the message object
  • sets EDITED_BY and EDIT_TIMESTAMP properties
  • propagates the changes to remote users.
Parameters:
newText New value of the message BODY_XML property.
isXML 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.
undo Reverts the message body to the original version. newText parameter is ignored when this is set
bool Message::GetContacts ( ContactRefs contacts  ) 

For messages of type POSTED_CONTACTS, parses the body XML and formats the data as a list of Contact instances.

bool Message::GetPropAuthor ( Sid::String &  author  ) 

Message::P_AUTHOR property get accessor

bool Message::GetPropAuthorDisplayname ( Sid::String &  author_displayname  ) 

Message::P_AUTHOR_DISPLAYNAME property get accessor

bool Message::GetPropBodyXml ( Sid::String &  body_xml  ) 

Message::P_BODY_XML property get accessor

bool Message::GetPropConsumptionStatus ( Message::CONSUMPTION_STATUS consumption_status  ) 

Message::P_CONSUMPTION_STATUS property get accessor

bool Message::GetPropConvoGuid ( Sid::String &  convo_guid  ) 

Message::P_CONVO_GUID property get accessor

bool Message::GetPropConvoId ( ConversationRef convo_id  ) 

Message::P_CONVO_ID property get accessor

bool Message::GetPropEditedBy ( Sid::String &  edited_by  ) 

Message::P_EDITED_BY property get accessor

bool Message::GetPropEditTimestamp ( uint &  edit_timestamp  ) 

Message::P_EDIT_TIMESTAMP property get accessor

bool Message::GetPropGuid ( Sid::Binary &  guid  ) 

Message::P_GUID property get accessor

bool Message::GetPropIdentities ( Sid::String &  identities  ) 

Message::P_IDENTITIES property get accessor

bool Message::GetPropLeavereason ( LEAVE_REASON leavereason  ) 

Message::P_LEAVEREASON property get accessor

bool Message::GetPropOriginallyMeantFor ( Sid::String &  originally_meant_for  ) 

Message::P_ORIGINALLY_MEANT_FOR property get accessor

bool Message::GetPropParamKey ( uint &  param_key  ) 

Message::P_PARAM_KEY property get accessor

bool Message::GetPropParamValue ( uint &  param_value  ) 

Message::P_PARAM_VALUE property get accessor

bool Message::GetPropParticipantCount ( uint &  participant_count  ) 

Message::P_PARTICIPANT_COUNT property get accessor

bool Message::GetPropReason ( Sid::String &  reason  ) 

Message::P_REASON property get accessor

bool Message::GetPropSendingStatus ( Message::SENDING_STATUS sending_status  ) 

Message::P_SENDING_STATUS property get accessor

bool Message::GetPropTimestamp ( uint &  timestamp  ) 

Message::P_TIMESTAMP property get accessor

bool Message::GetPropType ( Message::TYPE type  ) 

Message::P_TYPE property get accessor

bool Message::GetSMS ( SmsRef sms  ) 

For messages of type POSTED_SMS, parses the body XML and creates an SMS instances

bool Message::GetTransfers ( TransferRefs transfers  ) 

For messages of type POSTED_FILES, parses the body XML and creates a list of Transfer instances.

bool Message::GetVoiceMessage ( VoicemailRef voicemail  ) 

For messages of type POSTED_VOICE_MESSAGE, parses the body XML and creates a Voicemail instance.

MessageRef Message::ref (  )  [inline]

Definition at line 1630 of file skype-embedded_2.h.


The documentation for this class was generated from the following files:
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

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

Last updated: Fri Jan 27 2012