twisted.protocols.amp.BinaryBoxProtocol(StatefulStringProtocol, Int16StringReceiver, _DescriptorExchanger)
class documentationtwisted.protocols.amp
View Source
(View In Hierarchy)
Known subclasses: twisted.protocols.amp.AMP
Implements interfaces: twisted.protocols.amp.IBoxSender
A protocol for receiving AmpBox
es -
key/value pairs - via length-prefixed strings. A box is composed of:
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
.
Instance Variable | boxReceiver | an IBoxReceiver
provider, whose IBoxReceiver.ampBoxReceived
method will be invoked for each AmpBox that is
received. |
Method | __init__ | Undocumented |
Method | sendBox | Send a amp.Box to my peer. |
Method | makeConnection | Notify boxReceiver
that it is about to receive boxes from this protocol by invoking IBoxReceiver.startReceivingBoxes . |
Method | dataReceived | Either parse incoming data as AmpBox es or relay
it to our nested protocol. |
Method | connectionLost | The connection was lost; notify any nested protocol. |
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 | lengthLimitExceeded | The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported. |
Method | unhandledError | The buck stops here. This error was completely unhandled, time to terminate the connection. |
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. |
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 | _lockForSwitch | No summary |
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. |
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 | _getPeerCertificate | Undocumented |
Method | _defaultStartTLSResponder | The default TLS responder doesn't specify any certificate or anything. |
Inherited from StatefulStringProtocol:
Instance Variable | state | Current state of the protocol. Defaults to 'init' . (type: str ) |
Method | stringReceived | Choose a protocol phase function and call it. |
Inherited from IntNStringReceiver (via Int16StringReceiver):
Instance Variable | structFormat | format used for struct packing/unpacking. Define it in subclass. (type: str ) |
Instance Variable | prefixLength | length of the prefix, in bytes. Define it in subclass, using
struct.calcsize(structFormat) (type: int ) |
Method | stringReceived | Override this for notification when each complete string is received. |
Method | sendString | Send a prefixed string to the other end of the connection. |
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. (type: bytes ) |
Instance Variable | _compatibilityOffset | the offset within _unprocessed to the next message to be
parsed. (used to generate the recvd attribute) (type: int ) |
Inherited from Protocol (via Int16StringReceiver, IntNStringReceiver):
Method | logPrefix | Return a prefix matching the class name, to identify log messages related to this protocol instance. |
Inherited from BaseProtocol (via Int16StringReceiver, IntNStringReceiver, Protocol):
Method | connectionMade | Called when a connection is made. |
Inherited from _PauseableMixin (via Int16StringReceiver, IntNStringReceiver):
Method | pauseProducing | Undocumented |
Method | resumeProducing | Undocumented |
Method | stopProducing | Undocumented |
Inherited from _DescriptorExchanger:
Method | fileDescriptorReceived | Collect received file descriptors to be claimed later by Descriptor . |
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. (type: dict ) |
Instance Variable | _sendingDescriptorCounter | A no-argument callable which returns the ordinals, starting from 0. This
is used to construct values for _sendFileDescriptor . |
Instance Variable | _receivingDescriptorCounter | A no-argument callable which returns the ordinals, starting from 0. This
is used to construct values for fileDescriptorReceived . |
Method | _sendFileDescriptor | Assign and return the next ordinal to the given descriptor after sending the descriptor over this protocol's transport. |
IBoxReceiver
provider, whose IBoxReceiver.ampBoxReceived
method will be invoked for each AmpBox
that is
received.
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. |
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. |
Notify boxReceiver
that it is about to receive boxes from this protocol by invoking IBoxReceiver.startReceivingBoxes
.
Either parse incoming data as AmpBox
es or relay
it to our nested protocol.
The connection was lost; notify any nested protocol.
String received in the 'key' state. If the key is empty, a complete box has been received.
The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.
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.
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.
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
.
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. |
The buck stops here. This error was completely unhandled, time to terminate the connection.
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.