twisted.protocols.amp.BoxDispatcher : API documentation

Known subclasses: twisted.protocols.amp.AMP

Implements interfaces: twisted.protocols.amp.IBoxReceiver

A BoxDispatcher dispatches '_ask', '_answer', and '_error' AmpBoxes, both incoming and outgoing, to their appropriate destinations.

Outgoing commands are converted into Deferreds and outgoing boxes, and associated tracking state to fire those Deferred when '_answer' boxes come back. Incoming '_answer' and '_error' boxes are converted into callbacks and errbacks on those Deferreds, respectively.

Incoming '_ask' boxes are converted into method calls on a supplied method locator.

Instance Variable	locator	an object with a `locateResponder` method that locates a responder function that takes a Box and returns a result (either a Box or a Deferred which fires one).
Instance Variable	boxSender	an object which can send boxes, via the `_sendBox` method, such as an `AMP` instance. (type: `IBoxSender`)
Method	__init__	Undocumented
Method	startReceivingBoxes	The given boxSender is going to start calling boxReceived on this `BoxDispatcher`.
Method	stopReceivingBoxes	No further boxes will be received here. Terminate all currently oustanding command deferreds with the given reason.
Method	failAllOutgoing	Call the errback on all outstanding requests awaiting responses.
Method	callRemoteString	This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.
Method	callRemote	This is the primary high-level API for sending messages via AMP. Invoke it with a command and appropriate arguments to send a message to this connection's peer.
Method	unhandledError	This is a terminal callback called after application code has had a chance to quash any errors.
Method	ampBoxReceived	An AmpBox was received, representing a command, or an answer to a previously issued command (either successful or erroneous). Respond to it according to its contents.
Method	dispatchCommand	A box with a _command key was received.
Instance Variable	_outstandingRequests	a dictionary mapping request IDs to `Deferred`s which were returned for those requests.
Method	_nextTag	Generate protocol-local serial numbers for _ask keys.
Method	_sendBoxCommand	Send a command across the wire with the given `amp.Box`.
Method	_answerReceived	An AMP box was received that answered a command previously sent with `callRemote`.
Method	_errorReceived	An AMP box was received that answered a command previously sent with `callRemote`, with an error.
Method	_commandReceived
Method	_safeEmit	Emit a box, ignoring `ProtocolSwitched` and `ConnectionLost` errors which cannot be usefully handled.

The given boxSender is going to start calling boxReceived on this BoxDispatcher.

Parameters boxSender The IBoxSender to send command responses to.

No further boxes will be received here. Terminate all currently oustanding command deferreds with the given reason.

Call the errback on all outstanding requests awaiting responses.

Parameters reason the Failure instance to pass to those errbacks.

Generate protocol-local serial numbers for _ask keys.

Returns a string that has not yet been used on this connection.

Send a command across the wire with the given amp.Box.

Mutate the given box to give it any additional keys (_command, _ask) required for the command and request/response machinery, then send it.

If requiresAnswer is True, returns a Deferred which fires when a response is received. The Deferred is fired with an amp.Box on success, or with an amp.RemoteAmpError if an error is received.

If the Deferred fails and the error is not handled by the caller of this method, the failure will be logged and the connection dropped.

Parameters	command	a str, the name of the command to issue.
	box	an AmpBox with the arguments for the command.
	requiresAnswer	a boolean. Defaults to True. If True, return a Deferred which will fire when the other side responds to this command. If False, return None and do not ask the other side for acknowledgement.
Returns	a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.
Raises	ProtocolSwitched	if the protocol has been switched.

This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.

Parameters	command	a str naming the command.
	kw	arguments to the amp box.
	requiresAnswer	a boolean. Defaults to True. If True, return a Deferred which will fire when the other side responds to this command. If False, return None and do not ask the other side for acknowledgement.
Returns	a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.

This is the primary high-level API for sending messages via AMP. Invoke it with a command and appropriate arguments to send a message to this connection's peer.

Parameters	commandType	a subclass of Command. (type: `type`)
	a	Positional (special) parameters taken by the command. Positional parameters will typically not be sent over the wire. The only command included with AMP which uses positional parameters is `ProtocolSwitchCommand`, which takes the protocol that will be switched to as its first argument.
	kw	Keyword arguments taken by the command. These are the arguments declared in the command's 'arguments' attribute. They will be encoded and sent to the peer as arguments for the `commandType`.
Returns	If `commandType` has a `requiresAnswer` attribute set to `False`, then return `None`. Otherwise, return a `Deferred` which fires with a dictionary of objects representing the result of this call. Additionally, this `Deferred` may fail with an exception representing a connection failure, with `UnknownRemoteError` if the other end of the connection fails for an unknown reason, or with any error specified as a key in `commandType`'s `errors` dictionary.

This is a terminal callback called after application code has had a chance to quash any errors.

An AMP box was received that answered a command previously sent with callRemote.

Parameters box an AmpBox with a value for its ANSWER key.

An AMP box was received that answered a command previously sent with callRemote, with an error.

Parameters box an AmpBox with a value for its ERROR, ERROR_CODE, and ERROR_DESCRIPTION keys.

Parameters box an AmpBox with a value for its COMMAND and ASK keys.

An AmpBox was received, representing a command, or an answer to a previously issued command (either successful or erroneous). Respond to it according to its contents.

Parameters	box	an AmpBox
Raises	NoEmptyBoxes	when a box is received that does not contain an '_answer', '_command' / '_ask', or '_error' key; i.e. one which does not fit into the command / response protocol defined by AMP.

Emit a box, ignoring ProtocolSwitched and ConnectionLost errors which cannot be usefully handled.

A box with a _command key was received.

Dispatch it to a local handler call it.

Parameters	proto	an AMP instance.
	box	an AmpBox to be dispatched.

t.p.a.BoxDispatcher : class documentation