
.. _structure-transfer:

:index:`Transfer Structure`
---------------------------

A Transfer structure is returned from :meth:`~jetstream.sendinterface.SendInterface.createTransfer`, :meth:`~jetstream.sendinterface.SendInterface.getTransfer` and :meth:`~jetstream.sendinterface.SendInterface.getTransfers`.

.. glossary::
   :sorted:

   :index:`blockSize <pair: Transfer Structure; blockSize>`
      The block size, in bytes, used for transfers. Currently 256.

   :index:`blocksAcked <pair: Transfer Structure; blocksAcked>`
      The number of processed blocks that have received an ACK response. Effectively, blocks which have been confirmed as received by the remote server.

   :index:`blocksRetransmitted <pair: Transfer Structure; blocksRetransmitted>`
      The total number of blocks that have been transmitted, presumed lost in transit (i.e. packet loss).

   :index:`blocksSent <pair: Transfer Structure; blocksSent>`
      The total number of blocks sent for a transfer.

   :index:`bytesRecv <pair: Transfer Structure; bytesRecv>`
      The total number of bytes received for a transfer.

   :index:`bytesSent <pair: Transfer Structure; bytesSent>`
      The total number of bytes sent for a transfer.

   :index:`checkpointFrequencySeconds <pair: Transfer Structure; 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``.

   :index:`destinationId <pair: Transfer Structure; destinationId>`
      A destination ID. Destination IDs are returned from createDestination, and used in other methods to refer to a specific destination.

   :index:`destinationPath <pair: Transfer Structure; 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.

   :index:`endTime <pair: Transfer Structure; endTime>`
      The timestamp at which a transfer ended. See :doc:`/api/timestamps`.

   :index:`errorMessage <pair: Transfer Structure; errorMessage>`
      If unsuccessful, this contains a description of the error that occurred. See ``status``.

   :index:`manifestId <pair: Transfer Structure; manifestId>`
      A manifest ID. Manifest IDs are returned from :meth:`~jetstream.sendinterface.SendInterface.createManifest`, and used in other methods to refer to a specific manifest.

   :index:`owner <pair: Transfer Structure; owner>`
      The owner of this transfer. A transfer may be monitored or modified only by its owner, or by a superuser.

   :index:`ownerToken <pair: Transfer Structure; 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.

   :index:`ownerTokenSession <pair: Transfer Structure; ownerTokenSession>`
      The token session of this token that created this transfer.

   :index:`packetsRecv <pair: Transfer Structure; packetsRecv>`
      The total number of packets received for a transfer.

   :index:`packetsSent <pair: Transfer Structure; packetsSent>`
      The total number of packets sent for a transfer.

   :index:`priority <pair: Transfer Structure; 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.

   :index:`priorityLane <pair: Transfer Structure; 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.

   :index:`processing <pair: Transfer Structure; processing>`
      If ``True``, the JetStream server is still processing this item. Use the :meth:`~jetstream.sendinterface.SendInterface.getTransfer()` or :meth:`~jetstream.sendinterface.SendInterface.waitForTransfer()` method to monitor its progress.

   :index:`queueTime <pair: Transfer Structure; queueTime>`
      A timestamp indicating when a transfer was added to the queue. See :doc:`/api/timestamps`.

   :index:`requestTime <pair: Transfer Structure; requestTime>`
      A timestamp indicating when a transfer was requested. See :doc:`/api/timestamps`.

   :index:`sendRateMax <pair: Transfer Structure; sendRateMax>`
      The maximum send rate of this transfer in kilobits per second. Will be ``None`` if no maximum rate is set for this transfer.

   :index:`snapshotTime <pair: Transfer Structure; snapshotTime>`
      A timestamp indicating when the information was recorded. JetStream captures a snapshot of its state once per second. See :doc:`/api/timestamps`.

   :index:`startTime <pair: Transfer Structure; startTime>`
      A timestamp indicating when a transfer was started. See :doc:`/api/timestamps`.

   :index:`status <pair: Transfer Structure; status>`
      The status may be one of the following values:

      :index:`pending <triple: Transfer Structure; status; pending>`
         The transfer has been queued, but data has not been transmitted yet.

      :index:`sending <triple: Transfer Structure; status; sending>`
         Data is actively being transferred.

      :index:`suspended <triple: Transfer Structure; status; suspended>`
         The transfer was suspended. Use :meth:`~jetstream.sendinterface.SendInterface.resumeTransfer` to resume transmitting.

      :index:`resuming <triple: Transfer Structure; status; resuming>`
         The transfer is being resumed, but data is not being transmitted yet (the transfer is waiting in the queue).

      :index:`complete <triple: Transfer Structure; status; complete>`
         The transfer has been completed successfully.

      :index:`error <triple: Transfer Structure; status; error>`
         The transfer failed. The ``errorMessage`` field will contain a description of the error.

   :index:`totalBlocks <pair: Transfer Structure; totalBlocks>`
      The total number of blocks in a transfer.

   :index:`totalBytes <pair: Transfer Structure; totalBytes>`
      The total number of bytes in a transfer.

   :index:`transferDataSendRate <pair: Transfer Structure; transferDataSendRate>`
      Rate, in kilobits per second, that file data is being sent. This value can be directly compared to ``transferThroughputRate``.

   :index:`transferFileReadRate <pair: Transfer Structure; transferFileReadRate>`
      Rate, in kilobits per second, that file data is being read from disk. 

   :index:`transferId <pair: Transfer Structure; transferId>`
      A transfer ID. Transfer IDs are returned from :meth:`~jetstream.sendinterface.SendInterface.createTransfer`, and used in other methods to refer to a specific transfer.

   :index:`transferNetSendRate <pair: Transfer Structure; transferNetSendRate>`
      Raw socket send rate, in kilobits per second.

   :index:`transferSendRate <pair: Transfer Structure; 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.

   :index:`transferThroughputRate <pair: Transfer Structure; 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``.

   :index:`userData <pair: Destination Structure; userData>`
      Key-value map of user attached metadata. Use :meth:`~jetstream.sendinterface.SendInterface.updateObjectUserData` and :meth:`~jetstream.sendinterface.SendInterface.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.


.. versionchanged:: 1.4.3 Added `transferSendRate`, `transferDataSendRate`, `transferThroughputRate` keys.
.. versionchanged:: 1.5.1 Added `transferFileReadRate`, and `transferNetSendRate` keys.
.. versionchanged:: 1.6.1 Added `sendRateMax`, and `priorityLane` keys.
.. versionchanged:: 1.9.0 Added `owner` key.
.. versionchanged:: 2.4.0 Added `ownerToken`, `ownerTokenSession` keys.
