Class Message
source code
object --+
|
skypekit.Cached --+
|
skypekit.Object --+
|
Message
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.
- POSTED_TEXT
- POSTED_EMOTE
- SET_METADATA
- REQUESTED_AUTH
Following messages have a custom XML format for the body (see the specific section on these message types for details):
- POSTED_CONTACTS
- POSTED_VOICE_MESSAGE
- POSTED_FILES
- POSTED_SMS
- STARTED_LIVESESSION and ENDED_LIVESESSION (same format)
Following messages do not use the body property:
- SPAWNED_CONFERENCE
- ADDED_CONSUMERS
- ADDED_APPLICANTS
- RETIRED_OTHERS
- RETIRED
- SET_RANK
- HAS_BIRTHDAY
- GRANTED_AUTH
- BLOCKED
Messages such as POSTED_TEXT use a small subset of a HTML-like markup to control the visual representation of the text. This markup is used by POSTED_TEXT and POSTED_EMOTE, but also for the conversation topic (CONVERSATION_META_TOPIC property and the body of the SET_METADATA message) and for authorization requests.
Having chat messages in XML format means that all formatting is indicated by XML tags. This includes emoticons and URls. The big advantage is that it makes the parsing of the message by the UI much easier. The UI does not need to do emoticons or URL detection, this is already done and it only needs to look for the XML tags.
For text messages, it is possible for the UI to simply ignore (meaning strip) the XML and the message will be understandable fine, it will only have lost some formatting.
But it is obviously nicer to display at least the most commonly used tags.
To strip the XML:
- if they have the alt="sometext" attribute set, return sometext as the output of that tag and ignore the rest of tag and all nested sub tags
- if no alt="" attribute set, use tag content as output - <sometag>hereissomething</sometag> is output as hereissomething
- if no alt="" and no tag content, ignore the tag altogether (return nothing)
Skype for Windows supports displaying many XML tags, but only a sub-set is regularly used and should be supported by the UI for a good experience. These are the ones described here.
Animated emoticons
Emoticons are encoded with the "ss" tag. The element content is the plain text representation. It has a "type" attribute indicating the emoticons canonical name. Example:
::
Hi <ss type="smile">:-)</ss>
Flag emoticons
Flag emoticons are little flags. They are encoded with the "flag" tag. The element contents is the plain text representation and it has a "country" attribute which is a 2-letter ISO-3166 country code. The user can enter a flag using "(flag:XX)", where XX is a valid ISO country code. Example:
::
I am in <flag country="cc">CC</flag>
Links
If the library detects a URL, it will encode it using the html "a" tag, with the "href" attribute indicating the URL. The plain text representation is what the user originally typed. Example:
::
I am in <a href="http://wwww.skype.com">www.skype.com</a>
Alert matches
When a conversation is configured to display only alerts if specific words are present in the message (see "/alertson [text to match]" command), if a message matches the alert, it will be marked with the <alertmatch> tag. This allows the UI to highlight the word matching. Example:
::
Maybe <alertmatch>Vincent</alertmatch> knows the answer
Bold, italic, etc
Skype for Windows also supports displaying bold and italic text, using the "b" and "i" tags.
Encoding messages
When sending a chat message via PostText(), there is the possibility to indicate if the library should do the XML encoding, or if the message has already been encoded. Usually, the UI can let library do the encoding. This is the case when the message does not contain any specific formatting. It may contain emoticons or URls, which will be detected by the library encoder and converted into XML tags.
If the message has some more complex encoding, such as a quote or some bold text, it is up to the UI to encode the message.
|
|
|
|
|
|
|
|
OnPropertyChange(self,
property_name)
notifies from a property change |
source code
|
|
|
|
CanEdit(self)
For Message types having a body, determines whether that body is
editable by the user. |
source code
|
|
|
|
Edit(self,
new_text,
is_xml=False)
For Message types that include a body and are editable: |
source code
|
|
|
|
GetContacts(self)
For messages of type POSTED_CONTACTS, parses the body XML and formats
the data as a list of Contact instances. |
source code
|
|
|
|
GetTransfers(self)
For messages of type POSTED_FILES, parses the body XML and creates a
list of Transfer instances. |
source code
|
|
|
|
GetVoiceMessage(self)
For messages of type POSTED_VOICE_MESSAGE, parses the body XML and
creates a Voicemail instance. |
source code
|
|
|
|
GetSMS(self)
For messages of type POSTED_SMS, parses the body XML and creates an
SMS instances |
source code
|
|
|
|
|
|
Inherited from skypekit.Object:
multiget
Inherited from skypekit.Cached:
__copy__
Inherited from object:
__delattr__,
__format__,
__getattribute__,
__hash__,
__init__,
__reduce__,
__reduce_ex__,
__repr__,
__setattr__,
__sizeof__,
__subclasshook__
|
|
|
event_handlers = {}
|
|
|
propid2label = {120: 'convo_guid', 121: 'timestamp', 122: 'aut...
|
|
|
module_id = 9
|
|
|
TYPE = {2: 'SET_METADATA', 4: 'SPAWNED_CONFERENCE', 10: 'ADDED...
The P_TYPE property determines the actual meaning of the Message
object.
|
|
|
SENDING_STATUS = {1: 'SENDING', 2: 'SENT', 3: 'FAILED_TO_SEND'...
SENDING - Message has not been delivered to at least one of the
participants
|
|
|
CONSUMPTION_STATUS = {0: 'CONSUMED', 1: 'UNCONSUMED_SUPPRESSED...
Indicates if a message has been consumed (meaning read) or not
|
|
|
SET_METADATA_KEY = {3640: 'SET_META_NAME', 3644: 'SET_META_TOP...
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.
|
|
|
LEAVEREASON = {2: 'USER_INCAPABLE', 3: 'ADDER_MUST_BE_FRIEND',...
Indicates the reason a user could not join or left a Conversation.
|
|
|
P_CONVO_ID = 960
|
|
|
P_CONVO_GUID = 120
|
|
|
P_AUTHOR = 122
|
|
|
P_AUTHOR_DISPLAYNAME = 123
|
|
|
P_GUID = 792
|
|
|
P_ORIGINALLY_MEANT_FOR = 790
|
|
|
P_TIMESTAMP = 121
|
|
|
P_TYPE = 961
|
|
|
P_SENDING_STATUS = 962
|
|
|
P_CONSUMPTION_STATUS = 968
|
|
|
P_EDITED_BY = 222
|
|
|
P_EDIT_TIMESTAMP = 223
|
|
|
P_PARAM_KEY = 963
|
|
|
P_PARAM_VALUE = 964
|
|
|
P_BODY_XML = 127
|
|
|
P_IDENTITIES = 125
|
|
|
P_REASON = 966
|
|
|
P_LEAVEREASON = 126
|
|
|
P_PARTICIPANT_COUNT = 982
|
|
Inherited from skypekit.Object:
rwlock
|
__str__(self)
(Informal representation operator)
| source code
|
str(x)
- Overrides:
object.__str__
- (inherited documentation)
|
|
For Message types having a body, determines whether that body is
editable by the user.
Return values:
|
|
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.
Arguments:
-
new_text - New value of the message BODY_XML property.
-
is_xml - 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.
|
|
For messages of type POSTED_CONTACTS, parses the body XML and formats
the data as a list of Contact instances.
Return values:
|
|
For messages of type POSTED_FILES, parses the body XML and creates a
list of Transfer instances.
Return values:
|
|
For messages of type POSTED_VOICE_MESSAGE, parses the body XML and
creates a Voicemail instance.
Return values:
|
|
For messages of type POSTED_SMS, parses the body XML and creates an
SMS instances
Return values:
|
|
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.
|
propid2label
- Value:
{120: 'convo_guid',
121: 'timestamp',
122: 'author',
123: 'author_displayname',
125: 'identities',
126: 'leavereason',
127: 'body_xml',
222: 'edited_by',
...
|
|
TYPE
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.
-
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.
- Value:
{2: 'SET_METADATA',
4: 'SPAWNED_CONFERENCE',
10: 'ADDED_CONSUMERS',
11: 'ADDED_APPLICANTS',
12: 'RETIRED_OTHERS',
13: 'RETIRED',
21: 'SET_RANK',
30: 'STARTED_LIVESESSION',
...
|
|
SENDING_STATUS
-
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)
- Value:
{1: 'SENDING',
2: 'SENT',
3: 'FAILED_TO_SEND',
'FAILED_TO_SEND': 3,
'SENDING': 1,
'SENT': 2}
|
|
CONSUMPTION_STATUS
Indicates if a message has been consumed (meaning read) or not
-
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
- Value:
{0: 'CONSUMED',
1: 'UNCONSUMED_SUPPRESSED',
2: 'UNCONSUMED_NORMAL',
3: 'UNCONSUMED_ELEVATED',
'CONSUMED': 0,
'UNCONSUMED_ELEVATED': 3,
'UNCONSUMED_NORMAL': 2,
'UNCONSUMED_SUPPRESSED': 1}
|
|
SET_METADATA_KEY
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.
-
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.
- Value:
{3640: 'SET_META_NAME',
3644: 'SET_META_TOPIC',
3652: 'SET_META_GUIDELINES',
3658: 'SET_META_PICTURE',
'SET_META_GUIDELINES': 3652,
'SET_META_NAME': 3640,
'SET_META_PICTURE': 3658,
'SET_META_TOPIC': 3644}
|
|
LEAVEREASON
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.
-
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
- Value:
{2: 'USER_INCAPABLE',
3: 'ADDER_MUST_BE_FRIEND',
4: 'ADDER_MUST_BE_AUTHORIZED',
5: 'DECLINE_ADD',
6: 'UNSUBSCRIBE',
'ADDER_MUST_BE_AUTHORIZED': 4,
'ADDER_MUST_BE_FRIEND': 3,
'DECLINE_ADD': 5,
...
|
|
convo_id
DB ID of corresponding conversation
- Get Method:
- _sk_get_convo_id(self)
- DB ID of corresponding conversation
|
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.
- Get Method:
- _sk_get_convo_guid(self)
- GUID of the Conversation.
|
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).
- Get Method:
- _sk_get_author(self)
- Identity of the sender.
|
author_displayname
displayname of the sender at the time of posting
- Get Method:
- _sk_get_author_displayname(self)
- displayname of the sender at the time of posting
|
guid
Unlike the message id, the GUID is the same on all instances and for
all participants.
- Get Method:
- _sk_get_guid(self)
- Unlike the message id, the GUID is the same on all instances and for all
participants.
|
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.
- Get Method:
- _sk_get_originally_meant_for(self)
- This property gets set when a conference is spawned from dialog
Conversation.
|
timestamp
UNIX timestamp (sent time, adjusted for local clock)
- Get Method:
- _sk_get_timestamp(self)
- UNIX timestamp (sent time, adjusted for local clock)
|
edited_by
Identity of the author that last edited this message. NULL if message
has not been edited
- Get Method:
- _sk_get_edited_by(self)
- Identity of the author that last edited this message.
|
edit_timestamp
UNIX timestamp of last edit
- Get Method:
- _sk_get_edit_timestamp(self)
- UNIX timestamp of last edit
|
param_key
Message type-specific parameter. See Message::SET_METADATA_KEY for
more information.
- Get Method:
- _sk_get_param_key(self)
- Message type-specific parameter.
|
param_value
Message type-specific parameter
- Get Method:
- _sk_get_param_value(self)
- Message type-specific parameter
|
body_xml
Message type-specific parameter
- Get Method:
- _sk_get_body_xml(self)
- Message type-specific parameter
|
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.
- Get Method:
- _sk_get_identities(self)
- Message type-specific parameter.
|
reason
Message type-specific parameter. Possible values for
STARTED/ENDED_LIVESESSION (only set for dialogs):
- Get Method:
- _sk_get_reason(self)
- Message type-specific parameter.
|
leavereason
leave reason for message of the RETIRED type
- Get Method:
- _sk_get_leavereason(self)
- leave reason for message of the RETIRED type
|
participant_count
Number of people who received this message (including local user)
- Get Method:
- _sk_get_participant_count(self)
- Number of people who received this message (including local user)
|