
.. _structure-connection:

:index:`Connection Structure`
------------------------------

A Connection structure is returned from :meth:`~jetstream.sendinterface.SendInterface.getConnection` and :meth:`~jetstream.sendinterface.SendInterface.getConnections`.

.. glossary::
   :sorted:

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

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

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

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

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

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

   :index:`encryptionEnabled <pair: Connection 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: Connection 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: Connection 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: Connection Structure; lastError>`
      The last critical error that occurred when connecting to the remote server. ``None`` if there are currently no errors.

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

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

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

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

   :index:`rateControlMethod <pair: Connection Structure; rateControlMethod>`
      Sets the algorithm used by the rate controller.

   :index:`rateControllerActive <pair: Connection Structure; rateControllerActive>`
      If ``True``, the JetStream Rate Controller is used to dynamically adjust the transfer rates for optimal performance.

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

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

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

   :index:`sendRate <pair: Connection Structure; sendRate>`
      The configured send rate for this server, in kilobits-per-second.

   :index:`sendRateAverage <pair: Connection 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:`sendRateAverageWindow <pair: Connection Structure; sendRateAverageWindow>`
      The send rate measured within a "window" of time, in kilobits-per-second. This shows the performance "right now".

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

   :index:`sendRateMin <pair: Connection Structure; sendRateMin>`
      The minimum send rate allowed for this server. The Rate Controller will maintain the send rate at or above this value.

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

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

   :index:`snapshotTime <pair: Connection 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.


.. versionchanged:: 1.7.0 Added connection structure.

