Receive Transfer Structure

A Receive Transfer structure is returned from getTransfersAsync(). This structure describes a transfer that is being received on a server. This differs from the Transfer structure, which describes a transfer being sent from a server.

The Receive Transfer structure describes a receiving server’s record of transfer while it is in progress. Note that the receiving server will (eventually) remove its record of a transfer when the transfer has finished (the files remain, of course), whereas the sending server will maintain its records of a transfer indefinitely.

admitted

Whether this server is letting the transfer arrive.

False means the server is holding it, and has asked the sender to suspend the transfer. This happens when more transfers are arriving than the server’s --max-concurrent-transfers allows, or when the sending machine is over the server’s incomingMaxConnections limit. The transfer keeps its place and starts again on its own when a place frees up.

Warning

The hold is a request. The server asks the sender to stop, and a sender that does not honour the request keeps sending. Read admitted: False as “we asked the sender to stop”, never as “the transfer has stopped”. The --incoming-rate-limit is different: this server enforces that limit itself.

allocationBps

Always None. The server no longer divides its incoming bandwidth between transfers. The --incoming-rate-limit is one ceiling on the total rate of all arriving transfers.

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.

heldBySender

True if the sending server has queued this transfer and told this server so, and no data has arrived since. A transfer that is still arriving then reports the status waiting. The transfer starts again when the sender gives it a place. A sender older than this feature does not send the notice, so its queued transfers report stalled.

integrity

What the end-to-end integrity check concluded. One of:

  • verified – the sender’s digest arrived and matched. The bytes are identical.

  • verifiedOnDisk – the transfer asked for an on-disk check, and the files read back from storage matched.

  • unverified – the transfer completed, but no digest arrived from the sender.

  • failed – the digest did not match, and the transfer failed.

  • disabled – the check was off for this transfer, or the manifest had no file data.

  • pending – the transfer is still running, or there is no result yet.

  • unknown – the record was saved before this field existed.

lastErrorMsg

The message for the interruption recorded in lastErrorTime. Not reported for a complete transfer.

lastErrorTime

If there has been an interruption to a transfer at the receiving server at any time, this records the timestamp at which the interruption occurred. A value here does not necessarily mean that the transfer has failed; compare status. See Timestamps.

lastRecvTime

A timestamp indicating the last receive activity. See Timestamps.

lastSendTime

A timestamp indicating the last send activity. See Timestamps.

progress

How much of the transfer has arrived, from 0.0 to 1.0.

rate

The current receive rate for this transfer, in kilobits-per-second.

sourceIP

The IP for a source (i.e. the sending).

sourcePort

The port on which the source (i.e. sending) is connected.

status

The status for this transfer. May be one of:

  • receiving

  • stalled – no data has arrived for some time.

  • waiting – the sending server has queued the transfer. See heldBySender.

  • complete

  • error

  • canceled

  • suspended

  • deleted

totalSize

The total size, in bytes, of all files in this transfer.

transferId

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

urgency

How urgent the sending server said this transfer is: one of critical, high, medium, low or idle.

This is the sender’s claim, carried with the transfer, not a setting on this server. It is reported because it decides the order held transfers are released in, so it is the answer to “why is that one waiting while this one arrives”. A sender older than this feature does not send an urgency; its transfers are reported as medium, the default.

Changed in version 3.0.0: (API 47) Added urgency, admitted and allocationBps. The receiving server now limits how many transfers arrive at once, not only how fast each one is allowed to go.