t.p.a.BinaryBoxProtocol(StatefulStringProtocol, Int16StringReceiver) : class documentation

Part of twisted.protocols.amp View Source View In Hierarchy

Known subclasses: twisted.protocols.amp.AMP

Implements interfaces: twisted.protocols.amp.IBoxSender

A protocol for receving Boxes - 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 Variables_keyLengthLimitExceededA 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.
boxReceiveran IBoxReceiver provider, whose ampBoxReceived method will be invoked for each Box 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 startReceivingBoxes.
Method dataReceived Either parse incoming data as AmpBoxes 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.
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 _sendBox.
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:

Method stringReceived Choose a protocol phase function and call it.

Inherited from IntNStringReceiver (via Int16StringReceiver):

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.

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
def __init__(self, boxReceiver): (source)
Undocumented
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.
ParametersnewProtothe new protocol instance to switch to.
clientFactorythe ClientFactory to send the clientConnectionLost notification to.
def sendBox(self, box): (source)

Send a amp.Box to my peer.

Note: transport.write is never called outside of this method.
Parametersboxan AmpBox.
RaisesProtocolSwitchedif the protocol has previously been switched.
ConnectionLostif the connection has previously been lost.
def makeConnection(self, transport): (source)
Notify boxReceiver that it is about to receive boxes from this protocol by invoking startReceivingBoxes.
def dataReceived(self, data): (source)
Either parse incoming data as AmpBoxes or relay it to our nested protocol.
def connectionLost(self, reason): (source)
The connection was lost; notify any nested protocol.
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 lengthLimitExceeded(self, length): (source)
The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.
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 _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.
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 _sendBox.
def _startTLS(self, certificate, verifyAuthorities): (source)
Used by TLSBox to initiate the SSL handshake.
Parameterscertificatea twisted.internet.ssl.PrivateCertificate for use locally.
verifyAuthoritiestwisted.internet.ssl.Certificate instances representing certificate authorities which will verify our peer.
def _getPeerCertificate(self): (source)
Undocumented
def unhandledError(self, failure): (source)
The buck stops here. This error was completely unhandled, time to terminate the connection.
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.
API Documentation for Twisted, generated by pydoctor at 2011-10-27 16:27:37.