Class Transfer
source code
object --+
|
skypekit.Cached --+
|
skypekit.Object --+
|
Transfer
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:
::
Some text<files alt=""><file size="2336020" index="0">test.zip</file></files>
To put it another way, the object chain goes like this:
::
Conversation->Message->Transfer
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:
- file size in bytes
- index - more or less arbitrary order in which the transfers should be displayed in the UI
- file name.
For practical purposes, the Message::P_BODY_XML property is not all that useful in this context. The Transfer instances, however, contain the state and progress feedback for your UI. You retrieve these Transfer instances using Message::GetTransfers method. Since the sender can post multiple files to
a Conversation using the same Message, Message:GetTransfers retrieves a list of Transfer instances - one per file per recipient.
You can determine the direction of particular Transfer instance by querying Transfer::P_TYPE (INCOMING/OUTGOING).
You can implement a progress indicator by monitoring Transfer::P_BYTESTRANSFERRED. Note that when testing this on your local network, you will most likely catch these property change events at the beginning and the end of the transfer only - which does not look like too useful. However, for non-local network transfers where the transfer speeds are in the neighborhood of 200-300 KB per second, you should consider implementing progress feedback as being mandatory and expect to catch multiple property change events for all but the smallest files.
Another property of interest is Transfer::P_STATUS. The normal transfer status sequence during successful outgoing transfer is this:
- TRANSFER STATUS -> NEW
- TRANSFER STATUS -> WAITING_FOR_ACCEPT
- TRANSFER STATUS -> CONNECTING
- TRANSFER STATUS -> TRANSFERRING
- TRANSFER STATUS -> CONNECTING
- TRANSFER STATUS -> COMPLETED
The list of all terminal Transfer statuses is:
- COMPLETED
- FAILED
- CANCELLED
- CANCELLED_BY_REMOTE
In-progress transfers can be canceled with Transfer::Cancel and paused/resumed with Transfer::Pause and Transfer::Resume. For transfers that complete with a status of FAILED, your UI should provide feedback based on the value of Transfer::P_FAILUREREASON.
Incoming transfers, once accepted, overwrite existing files with the same name. Before accepting an incoming file transfer,
your UI should prompt the recipient to:
- accept or decline the file
- if accepted, specify the directory of here to save the file (with a pre-filled default)
- if accepted and a file having the same name already exists at the specified destination, your UI should prompt for confirmation to overwrite and provide a way to alter the file name before accepting it
Similarly, your UI should verify the existence of outgoing files prior to invoking Conversation::PostFiles.
Note that you should provide both Conversation::PostFiles and Transfer::Accept methods fully-qualified paths. Otherwise, the paths will be assumed to be relative to the path of SkypeKit runtime, since the methods are actually executed in the runtime context.
|
|
|
|
|
|
|
|
OnPropertyChange(self,
property_name)
notifies from a property change |
source code
|
|
|
|
Accept(self,
filename_with_path)
Accepts an incoming file transfer and saves it to specified file on
the local file system. |
source code
|
|
|
|
Pause(self)
Temporarily pauses an in-progress incoming or outgoing file transfer. |
source code
|
|
|
|
Resume(self)
Resumes a previously paused file transfer. |
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 = {80: 'type', 81: 'partner_handle', 82: 'partner...
|
|
|
module_id = 6
|
|
|
TYPE = {1: 'INCOMING', 2: 'OUTGOING', 'INCOMING': 1, 'OUTGOING...
INCOMING
|
|
|
STATUS = {0: 'NEW', 1: 'CONNECTING', 2: 'WAITING_FOR_ACCEPT', ...
Recognized values for the P_STATUS property.
|
|
|
FAILUREREASON = {1: 'SENDER_NOT_AUTHORISED', 2: 'REMOTELY_CANC...
SENDER_NOT_AUTHORISED
|
|
|
P_TYPE = 80
|
|
|
P_PARTNER_HANDLE = 81
|
|
|
P_PARTNER_DISPNAME = 82
|
|
|
P_STATUS = 83
|
|
|
P_FAILUREREASON = 84
|
|
|
P_STARTTIME = 85
|
|
|
P_FINISHTIME = 86
|
|
|
P_FILEPATH = 87
|
|
|
P_FILENAME = 88
|
|
|
P_FILESIZE = 89
|
|
|
P_BYTESTRANSFERRED = 90
|
|
|
P_BYTESPERSECOND = 91
|
|
|
P_CHATMSG_GUID = 92
|
|
|
P_CHATMSG_INDEX = 93
|
|
|
P_CONVO_ID = 98
|
|
Inherited from skypekit.Object:
rwlock
|
|
|
type
INCOMING / OUTGOING
|
|
|
partner_handle
Skype Name of the remote party of the file transfer.
|
|
|
partner_dispname
Display name of the remote participant.
|
|
|
status
Current state of the transfer
|
|
|
failurereason
Set whenever P_STATUS transitions to FAILED.
|
|
|
starttime
UNIX timestamp of when this Transfer instance was instantiated, not
when the transfer process actually started (was accepted from
receiver side).
|
|
|
finishtime
UNIX timestamp of when this Transfer COMPLETED or FAILED.
|
|
|
filepath
The path -and- filename of the file being transfered (typically fully
qualified).
|
|
|
filename
The filename -only- of the file being transfered.
|
|
|
filesize
The size of the file being transferred in bytes.
|
|
|
bytestransferred
The number of bytes already transferred.
|
|
|
bytespersecond
Current data transfer speed in bytes per second.
|
|
|
chatmsg_guid
The "global ID" of this Transfer's associated Message
instance.
|
|
|
chatmsg_index
A more or less arbitrary index for ordering multiple file transfers
within the UI.
|
|
|
convo_id
The "global ID" of this Transfer's associated Conversation
(as chained through its associated Message).
|
|
Inherited from object:
__class__
|
__str__(self)
(Informal representation operator)
| source code
|
str(x)
- Overrides:
object.__str__
- (inherited documentation)
|
|
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.
Arguments:
-
filename_with_path - 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.
Return values:
-
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.
|
|
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.
|
|
Cancels an in-progress file transfer. Transfer::STATUS will transition
to CANCELLED for incoming file transfers and to CANCELLED_BY_REMOTE for
outgoing transfers.
|
propid2label
- Value:
{80: 'type',
81: 'partner_handle',
82: 'partner_dispname',
83: 'status',
84: 'failurereason',
85: 'starttime',
86: 'finishtime',
87: 'filepath',
...
|
|
TYPE
- Value:
{1: 'INCOMING', 2: 'OUTGOING', 'INCOMING': 1, 'OUTGOING': 2}
|
|
STATUS
Recognized values for the P_STATUS property. Reflects current state of
this Transfer.
-
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.
- Value:
{0: 'NEW',
1: 'CONNECTING',
2: 'WAITING_FOR_ACCEPT',
3: 'TRANSFERRING',
4: 'TRANSFERRING_OVER_RELAY',
5: 'PAUSED',
6: 'REMOTELY_PAUSED',
7: 'CANCELLED',
...
|
|
FAILUREREASON
-
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
- Value:
{1: 'SENDER_NOT_AUTHORISED',
2: 'REMOTELY_CANCELLED',
3: 'FAILED_READ',
4: 'FAILED_REMOTE_READ',
5: 'FAILED_WRITE',
6: 'FAILED_REMOTE_WRITE',
7: 'REMOTE_DOES_NOT_SUPPORT_FT',
8: 'REMOTE_OFFLINE_FOR_TOO_LONG',
...
|
|
type
INCOMING / OUTGOING
- Get Method:
- _sk_get_type(self)
- INCOMING / OUTGOING
|
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.
- Get Method:
- _sk_get_partner_handle(self)
- Skype Name of the remote party of the file transfer.
|
partner_dispname
Display name of the remote participant.
- Get Method:
- _sk_get_partner_dispname(self)
- Display name of the remote participant.
|
status
Current state of the transfer
- Get Method:
- _sk_get_status(self)
- Current state of the transfer
|
failurereason
Set whenever P_STATUS transitions to FAILED.
- Get Method:
- _sk_get_failurereason(self)
- Set whenever P_STATUS transitions to FAILED.
|
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.
- Get Method:
- _sk_get_starttime(self)
- UNIX timestamp of when this Transfer instance was instantiated, not when
the transfer process actually started (was accepted from receiver side).
|
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.
- Get Method:
- _sk_get_finishtime(self)
- UNIX timestamp of when this Transfer COMPLETED or FAILED.
|
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.
- Get Method:
- _sk_get_filepath(self)
- The path -and- filename of the file being transfered (typically fully
qualified).
|
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.
- Get Method:
- _sk_get_filename(self)
- The filename -only- of the file being transfered.
|
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.
- Get Method:
- _sk_get_filesize(self)
- The size of the file being transferred in bytes.
|
bytestransferred
The number of bytes already transferred. Calculate the percentage of the file transferred so far as:
::
P_BYTESTRANSFERRED / (P_FILESIZE / 100);
Use float variables to avoid problems with files smaller than 100 bytes!
- Get Method:
- _sk_get_bytestransferred(self)
- The number of bytes already transferred.
|
bytespersecond
Current data transfer speed in bytes per second. Typically, your UI
will want to display this value as kilobytes per second (KBps).
- Get Method:
- _sk_get_bytespersecond(self)
- Current data transfer speed in bytes per second.
|
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.
- Get Method:
- _sk_get_chatmsg_guid(self)
- The "global ID" of this Transfer's associated Message instance.
|
chatmsg_index
A more or less arbitrary index for ordering multiple file transfers
within the UI.
- Get Method:
- _sk_get_chatmsg_index(self)
- A more or less arbitrary index for ordering multiple file transfers within
the UI.
|
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.
- Get Method:
- _sk_get_convo_id(self)
- The "global ID" of this Transfer's associated Conversation (as
chained through its associated Message).
|