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

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:

• 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.

Instance Variables	_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.
	boxReceiver	an 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