Public Types | Public Member Functions

Transfer Class Reference

Transfer in this context refers to transferring (sending/receiving) files among Skype Contacts, not transferring a call to another Skype or PSTN Contact. This class includes file transfer-specific properties and methods, such as FILESIZE, BYTESPERSECOND, Pause and Resume. Recipients of these file transfers must explicitly accept (or decline) any incoming transfer. More...

#include <skype-embedded_2.h>

List of all members.

Public Types

enum  { MODULE_ID = 6 }
enum  PROPERTY {
  P_TYPE = 80,
  P_PARTNER_HANDLE,
  P_PARTNER_DISPNAME,
  P_STATUS,
  P_FAILUREREASON,
  P_STARTTIME,
  P_FINISHTIME,
  P_FILEPATH,
  P_FILENAME,
  P_FILESIZE,
  P_BYTESTRANSFERRED,
  P_BYTESPERSECOND,
  P_CHATMSG_GUID,
  P_CHATMSG_INDEX,
  P_CONVO_ID = 98
}
enum  TYPE {
  INCOMING = 1,
  OUTGOING
}
enum  STATUS {
  NEW = 0,
  CONNECTING,
  WAITING_FOR_ACCEPT,
  TRANSFERRING,
  TRANSFERRING_OVER_RELAY,
  PAUSED,
  REMOTELY_PAUSED,
  CANCELLED,
  COMPLETED,
  FAILED,
  PLACEHOLDER,
  OFFER_FROM_OTHER_INSTANCE,
  CANCELLED_BY_REMOTE
}
enum  FAILUREREASON {
  SENDER_NOT_AUTHORISED = 1,
  REMOTELY_CANCELLED,
  FAILED_READ,
  FAILED_REMOTE_READ,
  FAILED_WRITE,
  FAILED_REMOTE_WRITE,
  REMOTE_DOES_NOT_SUPPORT_FT,
  REMOTE_OFFLINE_FOR_TOO_LONG,
  TOO_MANY_PARALLEL,
  PLACEHOLDER_TIMEOUT
}
typedef TransferRef Ref
typedef TransferRefs Refs

Public Member Functions

virtual ~Transfer ()
TransferRef ref ()
bool Accept (const Sid::Filename &filenameWithPath, bool &success)
bool Pause ()
bool Resume ()
bool Cancel ()
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 GetPropStarttime (uint &starttime)
bool GetPropFinishtime (uint &finishtime)
bool GetPropFilepath (Sid::String &filepath)
bool GetPropFilename (Sid::String &filename)
bool GetPropFilesize (Sid::String &filesize)
bool GetPropBytestransferred (Sid::String &bytestransferred)
bool GetPropBytespersecond (uint &bytespersecond)
bool GetPropChatmsgGuid (Sid::Binary &chatmsg_guid)
bool GetPropChatmsgIndex (uint &chatmsg_index)
bool GetPropConvoId (ConversationRef &convo_id)

Detailed Description

Transfer in this context refers to transferring (sending/receiving) files among Skype Contacts, not transferring a call to another Skype or PSTN Contact. This class includes file transfer-specific properties and methods, such as FILESIZE, BYTESPERSECOND, Pause and Resume. Recipients of these file transfers must explicitly accept (or decline) any incoming transfer.

Transfer instances represent files being sent and received within a Conversation context. Each Transfer instance represents a single file transfer - if a conversation has multiple remote participants, a separate Transfer instance must be instantiated for each remote participant (a Transfer instance is not instantiated for the sender).

Transfer instances cannot be instantiated directly. Instead, you initiate a file transfer by invoking Conversation::PostFiles. This instantiates a Message instance of type POSTED_FILES, which is added to the Conversation for all the participants (including the sender). The Transfer instance is associated with
this Message instance, and the Message::P_BODY_XML looks like this:

 @n Some text<files
  alt=""><file size="2336020" index="0">test.zip</file></files>  @n 



To put it another way, the object chain goes like this:

 @n Conversation->Message->Transfer  @n 



The first part of the message (before the files section) comes from the Conversation::PostFiles body argument. For each file in the message, a file section is provided with three fields:

Examples:

tutorial_16.cpp.

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


Member Typedef Documentation

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

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


Member Enumeration Documentation

anonymous enum
Enumerator:
MODULE_ID 

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

Enumerator:
SENDER_NOT_AUTHORISED 
REMOTELY_CANCELLED 
FAILED_READ 
FAILED_REMOTE_READ 
FAILED_WRITE 
FAILED_REMOTE_WRITE 
REMOTE_DOES_NOT_SUPPORT_FT 
REMOTE_OFFLINE_FOR_TOO_LONG 
TOO_MANY_PARALLEL 
PLACEHOLDER_TIMEOUT 

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

Properties of the Transfer class

Enumerator:
P_TYPE 

INCOMING / OUTGOING
, type: TYPE

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

P_PARTNER_DISPNAME 

Display name of the remote participant.
, type: Sid::String

P_STATUS 

Current state of the transfer
, type: STATUS

P_FAILUREREASON 

Set whenever P_STATUS transitions to FAILED.
, type: FAILUREREASON

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

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

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

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

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

P_BYTESTRANSFERRED 

The number of bytes already transferred. Calculate the percentage of the file transferred so far as:

 @n P_BYTESTRANSFERRED / (P_FILESIZE / 100);  @n 



Use float variables to avoid problems with files smaller than 100 bytes!
, type: Sid::String

P_BYTESPERSECOND 

Current data transfer speed in bytes per second. Typically, your UI will want to display this value as kilobytes per second (KBps).
, type: uint

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

P_CHATMSG_INDEX 

A more or less arbitrary index for ordering multiple file transfers within the UI.
, type: uint

P_CONVO_ID 

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.

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

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

Recognized values for the P_STATUS property. Reflects current state of this Transfer.

Enumerator:
NEW 

The file has either not been posted (sent) (OUTGOING), or not accepted (received) (INCOMING).

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.

WAITING_FOR_ACCEPT 

The files have been posted but the recipient has not yet accepted (or has declined) the transfer.

TRANSFERRING 

The transfer has been accepted and file data is being sent/received. Periodic updates of P_BYTESTRANSFERRED property should occur.

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.

PAUSED 

The local user (either the sender or a receiver) has paused the transfer.

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.

CANCELLED 

Local side (either sender or receiver) has canceled the transfer. This is a final state of the STATE property.

COMPLETED 

File transfer has completed. This is a terminal state.

FAILED 

File transfer has failed. This is a terminal state. UI should provide feedback, based on value of P_FAILUREREASON.

PLACEHOLDER 

Transfer whose existence has been hinted by corresponding chat message, but which is yet to arrive.

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.

CANCELLED_BY_REMOTE 

Remote side (either sender or receiver) has canceled the transfer. This is a final state of the STATE property.

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

Enumerator:
INCOMING 
OUTGOING 

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


Constructor & Destructor Documentation

Transfer::~Transfer (  )  [virtual]

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


Member Function Documentation

bool Transfer::Accept ( const Sid::Filename &  filenameWithPath,
bool &  success 
)

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.

Parameters:
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.
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.
bool Transfer::Cancel (  ) 

Cancels an in-progress file transfer. Transfer::STATUS will transition to CANCELLED for incoming file transfers and to CANCELLED_BY_REMOTE for outgoing transfers.

bool Transfer::GetPropBytespersecond ( uint &  bytespersecond  ) 

Transfer::P_BYTESPERSECOND property get accessor

bool Transfer::GetPropBytestransferred ( Sid::String &  bytestransferred  ) 

Transfer::P_BYTESTRANSFERRED property get accessor

bool Transfer::GetPropChatmsgGuid ( Sid::Binary &  chatmsg_guid  ) 

Transfer::P_CHATMSG_GUID property get accessor

bool Transfer::GetPropChatmsgIndex ( uint &  chatmsg_index  ) 

Transfer::P_CHATMSG_INDEX property get accessor

bool Transfer::GetPropConvoId ( ConversationRef convo_id  ) 

Transfer::P_CONVO_ID property get accessor

bool Transfer::GetPropFailurereason ( FAILUREREASON failurereason  ) 

Transfer::P_FAILUREREASON property get accessor

bool Transfer::GetPropFilename ( Sid::String &  filename  ) 

Transfer::P_FILENAME property get accessor

bool Transfer::GetPropFilepath ( Sid::String &  filepath  ) 

Transfer::P_FILEPATH property get accessor

bool Transfer::GetPropFilesize ( Sid::String &  filesize  ) 

Transfer::P_FILESIZE property get accessor

bool Transfer::GetPropFinishtime ( uint &  finishtime  ) 

Transfer::P_FINISHTIME property get accessor

bool Transfer::GetPropPartnerDispname ( Sid::String &  partner_dispname  ) 

Transfer::P_PARTNER_DISPNAME property get accessor

bool Transfer::GetPropPartnerHandle ( Sid::String &  partner_handle  ) 

Transfer::P_PARTNER_HANDLE property get accessor

bool Transfer::GetPropStarttime ( uint &  starttime  ) 

Transfer::P_STARTTIME property get accessor

bool Transfer::GetPropStatus ( STATUS status  ) 

Transfer::P_STATUS property get accessor

bool Transfer::GetPropType ( TYPE type  ) 

Transfer::P_TYPE property get accessor

bool Transfer::Pause (  ) 

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.

TransferRef Transfer::ref (  )  [inline]

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

bool Transfer::Resume (  ) 

Resumes a previously paused file transfer.


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 Mar 16 2012