twisted.protocols.amp.BinaryBoxProtocol(StatefulStringProtocol, Int16StringReceiver, _DescriptorExchanger)class documentation
twisted.protocols.ampView Source (View In Hierarchy)
A protocol for receiving
AmpBoxes - 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
|Method||sendBox||Send a amp.Box to my peer.|
|Method||dataReceived||Either parse incoming data as
|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||_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
|Method||_startTLS||Used by TLSBox to initiate the SSL handshake.|
|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
|Method||stringReceived||Choose a protocol phase function and call it.|
Inherited from 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.|
|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
|Instance Variable||_compatibilityOffset||the offset within
|Method||logPrefix||Return a prefix matching the class name, to identify log messages related to this protocol instance.|
|Method||connectionMade||Called when a connection is made.|
Inherited from _DescriptorExchanger:
|Method||fileDescriptorReceived||Collect received file descriptors to be claimed later by
|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
|Instance Variable||_sendingDescriptorCounter||A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for
|Instance Variable||_receivingDescriptorCounter||A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for
|Method||_sendFileDescriptor||Assign and return the next ordinal to the given descriptor after sending the descriptor over this protocol's transport.|
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 |
Send a amp.Box to my peer.
Note: transport.write is never called outside of this method.
|Raises||ProtocolSwitched||if the protocol has previously been switched.|
|ConnectionLost||if the connection has previously been lost.|
Either parse incoming data as
AmpBoxes or relay it to our nested protocol.
String received in the 'init' state.
String received in the 'key' state. If the key is empty, a complete box has been received.
String received in the 'value' state.
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
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.