com.skype.api
Class Transfer

java.lang.Object
  extended by com.skype.api.SkypeObject
      extended by com.skype.api.Transfer

public class Transfer
extends SkypeObject

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:

@code
Some texttest.zip


To put it another way, the object chain goes like this:
@code
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.


Nested Class Summary
static class Transfer.FAILUREREASON
           
static class Transfer.PROPERTY
          Properties of the Transfer class
static class Transfer.STATUS
          Recognized values for the P_STATUS property.
static interface Transfer.TransferListener
           
static class Transfer.TYPE
           
 
Field Summary
 
Fields inherited from class com.skype.api.SkypeObject
mObjectId, mPropCache, skype
 
Constructor Summary
Transfer(int oid, Skype skype)
           
 
Method Summary
 boolean Accept(java.lang.String filenameWithPath)
          Accepts an incoming file transfer and saves it to specified file on the local file system.
 void Cancel()
          Cancels an in-progress file transfer.
 byte[] GetBinProperty(Transfer.PROPERTY prop)
           
 boolean GetBooleanProperty(Transfer.PROPERTY prop)
           
 int GetIntProperty(Transfer.PROPERTY prop)
           
 java.lang.Object GetPropertyAsEnum(int propid)
           
 java.lang.String GetStrProperty(Transfer.PROPERTY prop)
           
static int moduleID()
           
 void Pause()
          Temporarily pauses an in-progress incoming or outgoing file transfer.
 void Resume()
          Resumes a previously paused file transfer.
 
Methods inherited from class com.skype.api.SkypeObject
close, getOid
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Transfer

public Transfer(int oid,
                Skype skype)
Method Detail

moduleID

public static final int moduleID()

GetPropertyAsEnum

public java.lang.Object GetPropertyAsEnum(int propid)
Specified by:
GetPropertyAsEnum in class SkypeObject

GetStrProperty

public java.lang.String GetStrProperty(Transfer.PROPERTY prop)

GetIntProperty

public int GetIntProperty(Transfer.PROPERTY prop)

GetBooleanProperty

public boolean GetBooleanProperty(Transfer.PROPERTY prop)

GetBinProperty

public byte[] GetBinProperty(Transfer.PROPERTY prop)

Accept

public boolean Accept(java.lang.String filenameWithPath)
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.
Returns:
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.

Pause

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


Resume

public void Resume()
Resumes a previously paused file transfer.


Cancel

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



Copyright © 2010, 2011 Skype Technologies. All Rights Reserved.