# ``twisted`.`protocols`.`amp`.`BinaryBoxProtocol``

class documentation

`class BinaryBoxProtocol(StatefulStringProtocol, Int16StringReceiver, _DescriptorExchanger): (source)`

Known subclasses: `twisted.protocols.amp.AMP`

Implements interfaces: `twisted.protocols.amp.IBoxSender`

View In Hierarchy

A protocol for receiving `AmpBox`es - key/value pairs - via length-prefixed strings. A box is composed of:

- any number of key-value pairs, described by:
  - a 2-byte network-endian packed key length (of which the first byte must be null, and the second must be non-null: i.e. the value of the length must be 1-255)
  - a key, comprised of that many bytes
  - a 2-byte network-endian unsigned value length (up to the maximum of 65535)
  - a value, comprised of that many bytes
- 2 null bytes

In other words, an even number of strings prefixed with packed unsigned 16-bit integers, and then a 0-length string to indicate the end of the box.

This protocol also implements 2 extra private bits of functionality related to the byte boundaries between messages; it can start TLS between two given boxes or switch to an entirely different protocol. However, due to some tricky elements of the implementation, the public interface to this functionality is `ProtocolSwitchCommand` and `StartTLS`.

Method | `__init__` | Undocumented
Method | `connectionLost` | The connection was lost; notify any nested protocol.
Method | `dataReceived` | Either parse incoming data as `AmpBox`es or relay it to our nested protocol.
Method | `lengthLimitExceeded` | The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.
Method | `makeConnection` | Notify `boxReceiver` that it is about to receive boxes from this protocol by invoking `IBoxReceiver.startReceivingBoxes`.
Method | `proto_init` | String received in the 'init' state.
Method | `proto_key` | String received in the 'key' state. If the key is empty, a complete box has been received.
Method | `proto_value` | String received in the 'value' state.
Method | `sendBox` | Send a amp.Box to my peer.
Method | `unhandledError` | The buck stops here. This error was completely unhandled, time to terminate the connection.
Class Variable | `noPeerCertificate` | Undocumented
Instance Variable | `boxReceiver` | an `IBoxReceiver` provider, whose `IBoxReceiver.ampBoxReceived` method will be invoked for each `AmpBox` that is received.
Instance Variable | `hostCertificate` | Undocumented
Instance Variable | `innerProtocol` | Undocumented
Instance Variable | `innerProtocolClientFactory` | Undocumented
Instance Variable | `MAX_LENGTH` | Undocumented
Instance Variable | `recvd` | Undocumented
Instance Variable | `transport` | Undocumented
Property | `peerCertificate` | Undocumented
Method | `_defaultStartTLSResponder` | The default TLS responder doesn't specify any certificate or anything.
Method | `_lockForSwitch` | No summary
Method | `_prepareTLS` | Used by StartTLSCommand to put us into the state where we don't actually send things that get sent, instead we buffer them. see `_sendBoxCommand`.
Method | `_startTLS` | Used by TLSBox to initiate the SSL handshake.
Method | `_switchTo` | Switch this BinaryBoxProtocol's transport to a new protocol. You need to do this 'simultaneously' on both ends of a connection; the easiest way to do this is to use a subclass of ProtocolSwitchCommand.
Method | `_unlockFromSwitch` | Unlock this locked binary protocol so that further boxes may be sent again. This is used after an attempt to switch protocols has failed for some reason.
Constant | `_MAX_KEY_LENGTH` | Undocumented
Constant | `_MAX_VALUE_LENGTH` | Undocumented
Instance Variable | `_currentBox` | Undocumented
Instance Variable | `_currentKey` | Undocumented
Instance Variable | `_justStartedTLS` | Undocumented
Instance Variable | `_keyLengthLimitExceeded` | A flag which is only true when the connection is being closed because a key length prefix which was longer than allowed by the protocol was received.
Instance Variable | `_locked` | Undocumented
Instance Variable | `_startingTLSBuffer` | Undocumented

Inherited from `StatefulStringProtocol`:

Method | `stringReceived` | Choose a protocol phase function and call it.
Instance Variable | `state` | Current state of the protocol. Defaults to `'init'`.

Inherited from `Int16StringReceiver`:

Class Variable | `prefixLength` | Undocumented
Class Variable | `structFormat` | Undocumented

Inherited from `IntNStringReceiver` (via `Int16StringReceiver`):

Method | `sendString` | Send a prefixed string to the other end of the connection.
Method | `stringReceived` | Override this for notification when each complete string is received.
Instance Variable | `_compatibilityOffset` | the offset within `_unprocessed` to the next message to be parsed. (used to generate the recvd attribute)
Instance Variable | `_unprocessed` | bytes received, but not yet broken up into messages / sent to stringReceived. _compatibilityOffset must be updated when this value is updated so that the `recvd` attribute can be generated correctly.

Inherited from `Protocol` (via `Int16StringReceiver`, `IntNStringReceiver`):

Method | `logPrefix` | Return a prefix matching the class name, to identify log messages related to this protocol instance.
Class Variable | `factory` | Undocumented

Inherited from `BaseProtocol` (via `Int16StringReceiver`, `IntNStringReceiver`, `Protocol`):

Method | `connectionMade` | Called when a connection is made.
Instance Variable | `connected` | Undocumented

Inherited from `_PauseableMixin` (via `Int16StringReceiver`, `IntNStringReceiver`):

Method | `pauseProducing` | Undocumented
Method | `resumeProducing` | Undocumented
Method | `stopProducing` | Undocumented
Instance Variable | `paused` | Undocumented

Inherited from `_DescriptorExchanger`:

Method | `fileDescriptorReceived` | Collect received file descriptors to be claimed later by `Descriptor`.
Method | `_sendFileDescriptor` | Assign and return the next ordinal to the given descriptor after sending the descriptor over this protocol's transport.
Instance Variable | `_descriptors` | Temporary storage for all file descriptors received. Values in this dictionary are the file descriptors (as integers). Keys in this dictionary are ordinals giving the order in which each descriptor was received. The ordering information is used to allow `Descriptor` to determine which is the correct descriptor for any particular usage of that argument type.
Instance Variable | `_getDescriptor` | Undocumented
Instance Variable | `_receivingDescriptorCounter` | A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for `fileDescriptorReceived`.
Instance Variable | `_sendingDescriptorCounter` | A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for `_sendFileDescriptor`.

def __init__(self, boxReceiver): (source)
overrides `twisted.protocols.amp._DescriptorExchanger.__init__`
overridden in `twisted.protocols.amp.AMP`

Undocumented

def connectionLost(self, reason): (source)
from `twisted.internet.interfaces.IProtocol`
overrides `twisted.internet.protocol.Protocol.connectionLost`
overridden in `twisted.protocols.amp.AMP`
The connection was lost; notify any nested protocol.
def dataReceived(self, data): (source)
from `twisted.internet.interfaces.IProtocol`
overrides `twisted.protocols.basic.IntNStringReceiver.dataReceived`
Either parse incoming data as `AmpBox`es or relay it to our nested protocol.
def lengthLimitExceeded(self, length): (source)
overrides `twisted.protocols.basic.IntNStringReceiver.lengthLimitExceeded`
The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.
def makeConnection(self, transport): (source)
from `twisted.internet.interfaces.IProtocol`
overrides `twisted.internet.protocol.BaseProtocol.makeConnection`
overridden in `twisted.protocols.amp.AMP`
Notify `boxReceiver` that it is about to receive boxes from this protocol by invoking `IBoxReceiver.startReceivingBoxes`.
def proto_init(self, string): (source)
String received in the 'init' state.
def proto_key(self, string): (source)
String received in the 'key' state. If the key is empty, a complete box has been received.
def proto_value(self, string): (source)
String received in the 'value' state.
def sendBox(self, box): (source)
from `twisted.protocols.amp.IBoxSender`

Send a amp.Box to my peer.

Note: transport.write is never called outside of this method.

Parameters
box | an AmpBox.
Raises
`ProtocolSwitched` | if the protocol has previously been switched.
`ConnectionLost` | if the connection has previously been lost.

def unhandledError(self, failure): (source)
from `twisted.protocols.amp.IBoxSender`
The buck stops here. This error was completely unhandled, time to terminate the connection.
noPeerCertificate: `bool` = (source)

Undocumented

boxReceiver = (source)
an `IBoxReceiver` provider, whose `IBoxReceiver.ampBoxReceived` method will be invoked for each `AmpBox` that is received.
hostCertificate = (source)

Undocumented

innerProtocol = (source)

Undocumented

innerProtocolClientFactory = (source)

Undocumented

MAX_LENGTH = (source)
overrides `twisted.protocols.basic.IntNStringReceiver.MAX_LENGTH`

Undocumented

recvd: `str` = (source)
overrides `twisted.protocols.basic.IntNStringReceiver.recvd`

Undocumented

transport = (source)
overrides `twisted.internet.protocol.BaseProtocol.transport`
overridden in `twisted.protocols.amp.AMP`

Undocumented

@property
peerCertificate = (source)

Undocumented

def _defaultStartTLSResponder(self): (source)

The default TLS responder doesn't specify any certificate or anything.

From a security perspective, it's little better than a plain-text connection - but it is still a *bit* better, so it's included for convenience.

You probably want to override this by providing your own StartTLS.responder.

def _lockForSwitch(self): (source)
Lock this binary protocol so that no further boxes may be sent. This is used when sending a request to switch underlying protocols. You probably want to subclass ProtocolSwitchCommand rather than calling this directly.
def _prepareTLS(self, certificate, verifyAuthorities): (source)
Used by StartTLSCommand to put us into the state where we don't actually send things that get sent, instead we buffer them. see `_sendBoxCommand`.
def _startTLS(self, certificate, verifyAuthorities): (source)
Used by TLSBox to initiate the SSL handshake.

Parameters
certificate | a `twisted.internet.ssl.PrivateCertificate` for use locally.
verifyAuthorities | `twisted.internet.ssl.Certificate` instances representing certificate authorities which will verify our peer.

def _switchTo(self, newProto, clientFactory=None): (source)
Switch this BinaryBoxProtocol's transport to a new protocol. You need to do this 'simultaneously' on both ends of a connection; the easiest way to do this is to use a subclass of ProtocolSwitchCommand.

Parameters
newProto | the new protocol instance to switch to.
clientFactory | the ClientFactory to send the `twisted.internet.protocol.ClientFactory.clientConnectionLost` notification to.

def _unlockFromSwitch(self): (source)
Unlock this locked binary protocol so that further boxes may be sent again. This is used after an attempt to switch protocols has failed for some reason.
_MAX_KEY_LENGTH: `int` = (source)

Undocumented

Value

    255

_MAX_VALUE_LENGTH: `int` = (source)

Undocumented

Value

    65535

_currentBox = (source)

Undocumented

_currentKey = (source)

Undocumented

_justStartedTLS: `bool` = (source)

Undocumented

_keyLengthLimitExceeded: `bool` = (source)
A flag which is only true when the connection is being closed because a key length prefix which was longer than allowed by the protocol was received.
_locked: `bool` = (source)

Undocumented

_startingTLSBuffer = (source)

Undocumented