Transfer Structure

A Transfer structure is returned from createTransfer(), getTransfer() and getTransfers().

blocksAcked

The number of processed blocks that have received an ACK response. Effectively, blocks which have been confirmed as received by the remote server.

blockSize

The block size, in bytes, used for transfers. Currently 256.

blocksRetransmitted

The total number of blocks that have been transmitted, presumed lost in transit (i.e. packet loss).

blocksSent

The total number of blocks sent for a transfer.

bytesRecv

The total number of bytes received for a transfer.

bytesSent

The total number of bytes sent for a transfer.

checkpointFrequencySeconds

How frequently to take a checkpoint, in seconds. A checkpoint is a guarantee that files have been written to storage. If the receiver of a transfer is terminated and subsequently resumed, the transfer can safely continue from its last checkpoint. If checkpoints are disabled, this is None.

destinationId

A destination ID. Destination IDs are returned from createDestination, and used in other methods to refer to a specific destination.

destinationPath

The directory that will be created as the parent for all files in the transfer. The manifest paths are respected, and added below this destination path.

endTime

The timestamp at which a transfer ended. See Timestamps.

errorMessage

If unsuccessful, this contains a description of the error that occurred. See status.

manifestId

A manifest ID. Manifest IDs are returned from createManifest(), and used in other methods to refer to a specific manifest.

owner

The owner of this transfer. A transfer may be monitored or modified only by its owner, or by a superuser.

ownerToken

The owner of this transfer, if this transfer was created by a token. A transfer is only visible to its token, owner, or a superuser.

ownerTokenSession

The token session of this token that created this transfer.

packetsRecv

The total number of packets received for a transfer.

packetsSent

The total number of packets sent for a transfer.

priority

The priority of the transfer. Transfers with a lower priority value (e.g. 100) are (generally) transmitted before transfers with a higher value (e.g. 120). If not specified, a transfer will be assigned a default priority of 100.

priorityLane

The priority lane of the transfer. Destinations maintain a list of priority lanes that each utilize a given percentage of the total sending bandwidth.

processing

If True, the JetStream server is still processing this item. Use the getTransfer() or waitForTransfer() method to monitor its progress.

queueTime

A timestamp indicating when a transfer was added to the queue. See Timestamps.

requestTime

A timestamp indicating when a transfer was requested. See Timestamps.

sendRateMax

The maximum send rate of this transfer in kilobits per second. Will be None if no maximum rate is set for this transfer.

snapshotTime

A timestamp indicating when the information was recorded. JetStream captures a snapshot of its state once per second. See Timestamps.

startTime

A timestamp indicating when a transfer was started. See Timestamps.

status

The status may be one of the following values:

pending

The transfer has been queued, but data has not been transmitted yet.

sending

Data is actively being transferred.

suspended

The transfer was suspended. Use resumeTransfer() to resume transmitting.

resuming

The transfer is being resumed, but data is not being transmitted yet (the transfer is waiting in the queue).

complete

The transfer has been completed successfully.

error

The transfer failed. The errorMessage field will contain a description of the error.

totalBlocks

The total number of blocks in a transfer.

totalBytes

The total number of bytes in a transfer.

transferDataSendRate

Rate, in kilobits per second, that file data is being sent. This value can be directly compared to transferThroughputRate.

transferFileReadRate

Rate, in kilobits per second, that file data is being read from disk.

transferId

A transfer ID. Transfer IDs are returned from createTransfer(), and used in other methods to refer to a specific transfer.

transferNetSendRate

Raw socket send rate, in kilobits per second.

transferSendRate

Rate, in kilobits per second, that data is being sent, including protocol overhead such as encryption. This value can be compared to the expected link speed.

transferThroughputRate

Rate, in kilobits per second, of file data being received and confirmed as received by the remote server. This value can be directly compared to transferDataSendRate.

userData

Key-value map of user attached metadata. Use updateObjectUserData() and deleteObjectUserData() to manipulate object user data.

Note

For each transfer, the system time is recorded in requestTime. The other times are internally calculated as durations since requestTime, so differences between reported times for a particular transfer will always be accurate.

Times may not compare accurately against your system’s time, the JetStream sender’s current system time, or the times reported for different transfers, since any system can change its system time. A common source of time changes is NTP correcting clock drift.

Changed in version 1.4.3: Added transferSendRate, transferDataSendRate, transferThroughputRate keys.

Changed in version 1.5.1: Added transferFileReadRate, and transferNetSendRate keys.

Changed in version 1.6.1: Added sendRateMax, and priorityLane keys.

Changed in version 1.9.0: Added owner key.

Changed in version 2.4.0: Added ownerToken, ownerTokenSession keys.