Public Types | Public Member Functions

# Voicemail Class Reference

Wrapper class that includes voicemail-specific methods and properties. More...

`#include <skype-embedded_2.h>`

List of all members.

## Public Types
enum | { MODULE_ID = 7 }
enum | PROPERTY { P_TYPE = 100, P_PARTNER_HANDLE, P_PARTNER_DISPNAME, P_STATUS, P_FAILUREREASON, P_SUBJECT, P_TIMESTAMP, P_DURATION, P_ALLOWED_DURATION, P_PLAYBACK_PROGRESS, P_CONVO_ID = 830, P_CHATMSG_GUID }
enum | TYPE { INCOMING = 1, DEFAULT_GREETING = 4, CUSTOM_GREETING = 2, OUTGOING }
enum | STATUS { NOTDOWNLOADED = 1, DOWNLOADING, UNPLAYED, BUFFERING, PLAYING, PLAYED, BLANK, RECORDING, RECORDED, UPLOADING, UPLOADED, DELETING, FAILED, DELETING_FAILED, CHECKING, CANCELLED }
enum | FAILUREREASON { MISC_ERROR = 1, CONNECT_ERROR, NO_VOICEMAIL_CAPABILITY, NO_SUCH_VOICEMAIL, FILE_READ_ERROR, FILE_WRITE_ERROR, RECORDING_ERROR, PLAYBACK_ERROR, NO_PERMISSION, RECEIVER_DISABLED_VOICEMAIL, SENDER_NOT_AUTHORIZED, SENDER_BLOCKED }
typedef VoicemailRef | Ref
typedef VoicemailRefs | Refs
## Public Member Functions
virtual | ~Voicemail ()
VoicemailRef | ref ()
bool | StartRecording ()
bool | StopRecording ()
bool | StartPlayback ()
bool | StopPlayback ()
bool | Delete ()
bool | Cancel ()
bool | CheckPermission (bool &result)
bool | GetPropType (TYPE &type)
bool | GetPropPartnerHandle (Sid::String &partner_handle)
bool | GetPropPartnerDispname (Sid::String &partner_dispname)
bool | GetPropStatus (STATUS &status)
bool | GetPropFailurereason (FAILUREREASON &failurereason)
bool | GetPropSubject (Sid::String &subject)
bool | GetPropTimestamp (uint &timestamp)
bool | GetPropDuration (uint &duration)
bool | GetPropAllowedDuration (uint &allowed_duration)
bool | GetPropPlaybackProgress (uint &playback_progress)
bool | GetPropConvoId (ConversationRef &convo_id)
bool | GetPropChatmsgGuid (Sid::Binary &chatmsg_guid)

## Detailed Description

Wrapper class that includes voicemail-specific methods and properties.

In the Skype Conversation API, Voicemail is actually something of a misnomer for what would be more accurately called Voice Message.
The traditional Voicemail use case involves recording a voice message when an incoming call does not get answered in a pre-determined amount of time. In the Skype Conversation API, voicemail does not depend on a call going unanswered - you can post a voice message asynchronously into any dialog conversation at any time.
In fact, a high-level action flow directing unanswered incoming live sessions to voicemail is not something provided by the Conversation API - implementation of this use case is largely up to your UI.
The fact that your UI must retrieve incoming Voicemails by monitoring changes to a Conversation instance's Messages illustrates this conceptual difference between traditional voicemail and voice messages. The message type Message::POSTED_VOICE_MESSAGE indicates that a Message instance should be handled as a voice message instead of by displaying its body text in the Conversation UI. Message::GetVoiceMessage enables you to retrieve the associated Voicemail instance; Voicemail::StartPlayback enables you to listen to the message audio.
To put it another way, the object chain goes like this:

     @n
      Contact->Conversation->Message->Voicemail  @n

There are three basic types of Voicemail objects:

- INCOMING - received voice messages that can be retrieved from Message objects;
- OUTGOING - outbound voice messages that can be created with Conversation::StartVoiceMessage;
- GREETING - voice messages that represent auto-answer greetings, either recorded by the user (CUSTOM_GREETING) or included as part of SkypeKit (DEFAULT_GREETING). This is the audio that gets played back to sender of the voice message before he can start recording his voice message.
  Before trying to send out a voicemail, you should ensure that target Contact has the capability to receive them. Use Contact::GetCapabilityStatus to check for Contact::CAPABILITY_CAN_BE_SENT_VM.
  Recording and Sending a Voice Message
  The first step is to obtain a dialog Conversation with the target Contact. In that conversation, you can initiate the outgoing voice message with Conversation::StartVoiceMessage
  Note that this call does not return an actual Voicemail object. To catch when an object gets created, you will need to check Conversation::P_ACTIVE_VM_ID property updates.
  After invoking Conversation::StartVoiceMessage, SkypeKit instantiates a Voicemail instance for the target Contact's greeting (with type CUSTOM_GREETING or DEFAULT_GREETING). At this point, the Conversation::P_ACTIVE_VM_ID property update fires, newVM contains a reference to the greeting, and playback of the greeting for the sender starts automatically.
  Once the greeting playback finishes, SkypeKit instantiates a second Voicemail instance for the outgoing voice message. At this point, the Conversation::P_ACTIVE_VM_ID property update fires again, newVM now contains a reference to the outgoing message, and recording starts automatically. If you want to include notification and/or error handling for whether this message was sent successfully, you should make a copy of newVM now.
  Once the user finishes (or abandons) recording of their message, they want to either send the message or to cancel it. To send the message, use Conversation::PostVoiceMessage; to cancel the message, use Conversation::LeaveLiveSession.
  Both of these actions results in the Conversation::P_ACTIVE_VM_ID property update firing for a third time, setting the value to NULL. However, the Voicemail object will actually continue its existence past this point. Saving a reference to the message's Voicemail object when you start recording it enables you to keep receiving Voicemail property updates. This in turn enables your UI to check whether voice message send succeeded or failed.
  The relevant terminal state Voicemail::P_STATUS property values are:
- Voicemail::CANCELLED - recording and/or sending of this message was cancelled
- Voicemail::UPLOADED - message sent
- Voicemail::FAILED - message could not be sent
  Receiving and Playing Back a Voice Message
  On the remote side, the Voicemail appears as a Message object of type Message::POSTED_VOICE_MESSAGE. The message's author property contains the Skype Name of the Voicemail originator, and its BodyXml property contains the message length and title text in following format:

       @n
        <voicemail alt="Sent voicemail to people in this conversation."><message length="5" ></message></voicemail>  @n

  Receiver side UI can then retrieve the Voicemail object from the message with Message::GetVoiceMessage and
  start local playback with Message::StartPlayback.

Examples:

  tutorial_14.cpp.

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

## Member Typedef Documentation

typedef VoicemailRef Voicemail::Ref

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

typedef VoicemailRefs Voicemail::Refs

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

## Member Enumeration Documentation

anonymous enum

Enumerator:

  MODULE_ID |

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

enum Voicemail::FAILUREREASON

Enumerator:

  MISC_ERROR |
  CONNECT_ERROR |
  NO_VOICEMAIL_CAPABILITY |
  NO_SUCH_VOICEMAIL |
  FILE_READ_ERROR |
  FILE_WRITE_ERROR |
  RECORDING_ERROR |
  PLAYBACK_ERROR |
  NO_PERMISSION |
  RECEIVER_DISABLED_VOICEMAIL | receiver turned off voicemail
  SENDER_NOT_AUTHORIZED | receiver has not authorized you and privacy is not set to anyone
  SENDER_BLOCKED | receiver blocked sender

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

enum Voicemail::PROPERTY

Properties of the Voicemail class

Enumerator:

  P_TYPE | type: TYPE
  P_PARTNER_HANDLE | registered username of the other party, type: Sid::String
  P_PARTNER_DISPNAME | user's display name of the other party, type: Sid::String
  P_STATUS | type: STATUS
  P_FAILUREREASON | type: FAILUREREASON
  P_SUBJECT | DEPRECATED: subject line, type: Sid::String
  P_TIMESTAMP | timestamp of creation, type: uint
  P_DURATION | duration in seconds, type: uint
  P_ALLOWED_DURATION | max allowed duration in seconds, type: uint
  P_PLAYBACK_PROGRESS | VM playback progress in seconds, type: uint
  P_CONVO_ID | CONVERSATION_ID of corresponding conversation, type: ConversationRef
  P_CHATMSG_GUID | GUID of the message that the VM is tied to, type: Sid::Binary

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

enum Voicemail::STATUS

Enumerator:

  NOTDOWNLOADED |
  DOWNLOADING |
  UNPLAYED |
  BUFFERING |
  PLAYING |
  PLAYED |
  BLANK |
  RECORDING |
  RECORDED |
  UPLOADING |
  UPLOADED |
  DELETING |
  FAILED |
  DELETING_FAILED |
  CHECKING |
  CANCELLED |

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

enum Voicemail::TYPE

Enumerator:

  INCOMING |
  DEFAULT_GREETING |
  CUSTOM_GREETING |
  OUTGOING |

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

## Constructor & Destructor Documentation

Voicemail::~Voicemail | ( |  | ) | `[virtual]`

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

## Member Function Documentation

bool Voicemail::Cancel | ( |  | ) |

Canceling recording of your own auto-answer greeting message. To stop recording of and cancel an outgoing Voicemail, use Conversation::LeaveLiveSession.

bool Voicemail::CheckPermission | ( | bool & | result | ) |

check if we can send voicemail (unauth,blocked,no priv etc cases). only OUTGOING

bool Voicemail::Delete | ( |  | ) |

first from server, and then the local copy

bool Voicemail::GetPropAllowedDuration | ( | uint & | allowed_duration | ) |

Voicemail::P_ALLOWED_DURATION property get accessor

bool Voicemail::GetPropChatmsgGuid | ( | Sid::Binary & | chatmsg_guid | ) |

Voicemail::P_CHATMSG_GUID property get accessor

bool Voicemail::GetPropConvoId | ( | ConversationRef & | convo_id | ) |

Voicemail::P_CONVO_ID property get accessor

bool Voicemail::GetPropDuration | ( | uint & | duration | ) |

Voicemail::P_DURATION property get accessor

bool Voicemail::GetPropFailurereason | ( | FAILUREREASON & | failurereason | ) |

Voicemail::P_FAILUREREASON property get accessor

bool Voicemail::GetPropPartnerDispname | ( | Sid::String & | partner_dispname | ) |

Voicemail::P_PARTNER_DISPNAME property get accessor

bool Voicemail::GetPropPartnerHandle | ( | Sid::String & | partner_handle | ) |

Voicemail::P_PARTNER_HANDLE property get accessor

bool Voicemail::GetPropPlaybackProgress | ( | uint & | playback_progress | ) |

Voicemail::P_PLAYBACK_PROGRESS property get accessor

bool Voicemail::GetPropStatus | ( | STATUS & | status | ) |

Voicemail::P_STATUS property get accessor

bool Voicemail::GetPropSubject | ( | Sid::String & | subject | ) |

Voicemail::P_SUBJECT property get accessor

bool Voicemail::GetPropTimestamp | ( | uint & | timestamp | ) |

Voicemail::P_TIMESTAMP property get accessor

bool Voicemail::GetPropType | ( | TYPE & | type | ) |

Voicemail::P_TYPE property get accessor

VoicemailRef Voicemail::ref | ( |  | ) | `[inline]`

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

bool Voicemail::StartPlayback | ( |  | ) |

Initiates playback of a voice message

bool Voicemail::StartRecording | ( |  | ) |

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.

bool Voicemail::StopPlayback | ( |  | ) |

Terminates playback of a voice message

bool Voicemail::StopRecording | ( |  | ) |

Stop recording of your own auto-answer greeting message only. To stop recording of and send an outgoing Voicemail, use Conversation::PostVoiceMessage.

The documentation for this class was generated from the following files:

- skype-embedded_2.h
- skype-embedded_2.cpp

All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

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

Last updated: Fri Jan 27 2012