
.. _structure-destination:

:index:`Destination Structure`
------------------------------

A Destination structure is returned from :meth:`~jetstream.sendinterface.SendInterface.createDestination`, :meth:`~jetstream.sendinterface.SendInterface.getDestination` and :meth:`~jetstream.sendinterface.SendInterface.getDestinations`.

.. glossary::
   :sorted:

   :index:`connectionId <pair: Destination Structure; connectionId>`
      A connection ID. Connection IDs are returned from :meth:`~jetstream.send.getConnection`, and used to refer to a specific connection.

   :index:`destinationAddress <pair: Destination Structure; destinationAddress>`
      The address (host name) for a destination.

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

   :index:`destinationIP <pair: Destination Structure; destinationIP>`
      The IP for a destination.

   :index:`destinationPort <pair: Destination Structure; destinationPort>`
      The UDP receiver port for a destination.

   :index:`destinationPublicKey <pair: Destination Structure; destinationPublicKey>`
      The public key for this destination. This public key must be specified for encrypted transfers to this server.

   :index:`encryptedConnectionState <pair: Destination Structure; encryptedConnectionState>`
      Describes the state of the encryption negotiation, if using an encrypted connection. May be one of:

      - :index:`disconnected <triple: Destination Structure; encryptedConnectionState; disconnected>`
      - :index:`negotiating <triple: Destination Structure; encryptedConnectionState; negotiating>`
      - :index:`connected <triple: Destination Structure; encryptedConnectionState; connected>`

   :index:`encryptionEnabled <pair: Destination Structure; encryptionEnabled>`
      ``True`` if the server has encryption enabled. If encryption is enabled, transfers can only be initiated to a server which also has encryption enabled.

   :index:`lastDestinationServerId <pair: Destination Structure; lastDestinationServerId>`
      The server instance ID that most recently acknowledged a transmission to a destination. This value may be ``None`` if no communication has yet been established.

   :index:`lastDestinationServerUid <pair: Destination Structure; lastDestinationServerUid>`
      The persistent server ID that most recently acknowledged a transmission to a destination. This value may be ``None`` if no communication has yet been established.

   :index:`lastError <pair: Destination Structure; lastError>`
      The last critical error that occurred when connecting to the remote server. ``None`` if there are currently no errors.

   :index:`lastErrorMessage <pair: Destination Structure; lastErrorMessage>`
      Error message associated with ``lastError``.

   :index:`lastRecvTime <pair: Destination Structure; lastRecvTime>`
      A timestamp indicating the last receive activity. See :doc:`/api/timestamps`.

   :index:`lastSendTime <pair: Destination Structure; lastSendTime>`
      A timestamp indicating the last send activity. See :doc:`/api/timestamps`.

   :index:`numTransfersQueued <pair: Destination Structure; numTransfersQueued>`
      The number of transfers waiting in a destination's queue.

   :index:`owner <pair: Destination Structure; owner>`
      The owner of this destination. A destination is only visible to its owner, or a superuser.

   :index:`ownerToken <pair: Destination Structure; ownerToken>`
      The owner of this destination, if this destination was created by a token. A destination is only visible to its token, owner, or a superuser.

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

   :index:`permittedDestinationPublicKey <pair: Destination Structure; permittedDestinationPublicKey>`
      The key used to authorize the remote server. If the remote server's public key doens't match this key, the connection will not succeed.

   :index:`priorityLanes <pair: Destination Structure; priorityLanes>`
      A mapping of the priority lanes. Each lane has a name and a proportion of the total sending bandwidth.

   :index:`relayIP <pair: Destination Structure; relayIP>`
      The IP for the relay server, if using a relay. Will be ``None`` if not using a relay.

   :index:`relayPort <pair: Destination Structure; relayPort>`
      The port for the relay server, if using a relay. Will be ``None`` if not using a relay.

   :index:`roundTripTimeMs <pair: Destination Structure; roundTripTimeMs>`
      The 'ping time' between the sender and receiver in milliseconds.

   :index:`sendRateAverage <pair: Destination Structure; sendRateAverage>`
      The average send rate for a transfer, in kilobits-per-second. This rate represents a "slice" of time, per "send rate average window".

   :index:`sendRateMax <pair: Destination Structure; sendRateMax>`
      The maximum send rate allowed for this server. The Rate Controller will not allow the send rate to exceed this value.

   :index:`senderIP <pair: Destination Structure; senderIP>`
      The IP for the sender connection.

   :index:`senderPort <pair: Destination Structure; senderPort>`
      The port for the sender connection.

   :index:`snapshotTime <pair: Destination 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:`socketSendBufferSize <pair: Destination Structure; socketSendBufferSize>`
      The size of the buffer allocated for sending data.

   :index:`socketRecvBufferSize <pair: Destination Structure; socketRecvBufferSize>`
      The size of the buffer allocated for receiving data.

   :index:`transferDefaults <pair: Destination Structure; transferDefaults>`
      :ref:`structure-destination-transfer-defaults`

   :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.


.. versionchanged:: 1.6.1 Added `priorityLanes` keys.
.. versionchanged:: 1.7.0 Added `lastError`, `lastErrorMessage`, `owner`, `permittedDestinationPublicKey`, and `userData` keys. Removed `encryptionMismatch`, `rateControlActive`, `rateControlMethod`, `sendRate`, `sendRateMin`, `sendRateAverageWindow`, and `versionMismatch` keys.
.. versionchanged:: 2.4.0 Added `ownerToken`, `ownerTokenSession` keys.


.. _structure-destination-transfer-defaults:

:index:`Destination Transfer Defaults Structure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Destination Transfer Defaults structure is returned as part of the :ref:`structure-destination`.

.. glossary::
   :sorted:

   :index:`checkpointFrequencySeconds <pair: Destination Transfer Defaults Structure; checkpointFrequencySeconds>`
      The default value for the ``checkpointFrequencySeconds`` parameter of :meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

   :index:`overwriteMode <pair: Destination Transfer Defaults Structure; overwriteMode>`
      The default value for the ``overwriteMode`` parameter of :meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

   :index:`priority <pair: Destination Transfer Defaults Structure; priority>`
      The default value for the ``priority`` parameter of :meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

   :index:`priorityLane <pair: Destination Transfer Defaults Structure; priorityLane>`
      The default value for the ``priorityLane`` parameter of :meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

   :index:`sendRateMax <pair: Destination Transfer Defaults Structure; sendRateMax>`
      The default value for the ``sendRateMax`` parameter of :meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

   :index:`transferFlags <pair: Destination Transfer Defaults Structure; transferFlags>`
      The default value for the ``transferFlags`` parameter of :meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

.. versionchanged:: 1.6.1 Added `sendRateMax`, and `priorityLane` keys.
.. versionchanged:: 1.7.0 Added `overwriteMode` keys.

