aiocoap.interfaces module

This module provides interface base classes to various aiocoap services, especially with respect to request and response handling.

class aiocoap.interfaces.TransportEndpoint

Bases: object

A MessageEndpoint (renaming pending) is an object that can exchange addressed messages over unreliable transports. Implementations send and receive messages with message type and message ID, and are driven by a Context that deals with retransmission.

Usually, an MessageEndpoint refers to something like a local socket, and send messages to different remote endpoints depending on the message’s addresses. Just as well, a MessageEndpoint can be useful for one single address only, or use various local addresses depending on the remote address.

Next steps: Have it operated not by a Context, but by a RequestResponseEndpoint that is controlled by a thinner Context.

shutdown()

Deactivate the complete transport, usually irrevertably. When the coroutine returns, the object must have made sure that it can be destructed by means of ref-counting or a garbage collector run.

send(message)

Send a given Message object

determine_remote(message)

Return a value suitable for the message’s remote property based on its .opt.uri_host or .unresolved_remote.

May return None, which indicates that the TransportEndpoint can not transport the message (typically because it is of the wrong scheme).

class aiocoap.interfaces.EndpointAddress

Bases: object

An address that is suitable for routing through the application to a remote endpoint.

Depending on the TransportEndpoint implementation used, an EndpointAddress property of a message can mean the message is exchanged “with [2001:db8::2:1]:5683, while my local address was [2001:db8:1::1]:5683” (typical of UDP6), “over the connected <Socket at 0x1234>, whereever that’s connected to” (simple6 or TCP) or “with participant 0x01 of the OSCAP key 0x..., routed over <another EndpointAddress>”.

EndpointAddresses are only concstructed by TransportEndpoint objects, either for incoming messages or when populating a message’s .remote in TransportEndpoint.determine_remote().

There is no requirement that those address are always identical for a given address. However, incoming addresses must be hashable and hash-compare identically to requests from the same context. The “same context”, for the purpose of EndpointAddresses, means that the message must be eligible for request/response, blockwise (de)composition and observations. (For example, in a DTLS context, the hash must change between epochs due to RFC7252 Section 9.1.2).

So far, it is required that hash-identical objects also compare the same. That requirement might go away in future to allow equality to reflect finer details that are not hashed. (The only property that is currently known not to be hashed is the local address in UDP6, because that is unknown in initially sent packages, and thus disregarded for comparison but needed to round-trip through responses.)

hostinfo

The authority component of URIs that this endpoint represents

uri

The base URI for this endpoint (typically scheme plus .hostinfo)

is_multicast

True if the remote address is a multicast address, otherwise false.

is_multicast_locally

True if the local address is a multicast address, otherwise false.

class aiocoap.interfaces.MessageManager

Bases: object

The interface an entity that drives a TransportEndpoint provides towards the TransportEndpoint for callbacks and object acquisition.

dispatch_message(message)

Callback to be invoked with an incoming message

dispatch_error(errno, remote)

Callback to be invoked when the operating system indicated an error condition from a particular remote.

This interface is likely to change soon to something that is not limited to errno-style errors, and might allow transporting additional data.

client_credentials

A CredentialsMap that transports should consult when trying to establish a security context

class aiocoap.interfaces.RequestProvider

Bases: object

request(request_message)

Create and act on a a Request object that will be handled according to the provider’s implementation.

class aiocoap.interfaces.Request

Bases: object

A CoAP request, initiated by sending a message. Typically, this is not instanciated directly, but generated by a RequestProvider.request() method.

response = 'A future that is present from the creation of the object and fullfilled with the response message.'
class aiocoap.interfaces.Resource

Bases: object

Interface that is expected by a protocol.Context to be present on the serversite, which renders all requests to that context.

render(request)

Return a message that can be sent back to the requester.

This does not need to set any low-level message options like remote, token or message type; it does however need to set a response code.

The aiocoap.message.NoResponse sentinel can be returned if the resources wishes to suppress an answer on the request/response layer. (An empty ACK is sent responding to a CON request on message layer nevertheless.)

needs_blockwise_assembly(request)

Indicator to the protocol.Responder about whether it should assemble request blocks to a single request and extract the requested blocks from a complete-resource answer (True), or whether the resource will do that by itself (False).

class aiocoap.interfaces.ObservableResource

Bases: aiocoap.interfaces.Resource

Interface the protocol.ServerObservation uses to negotiate whether an observation can be established based on a request.

This adds only functionality for registering and unregistering observations; the notification contents will be retrieved from the resource using the regular render() method from crafted (fake) requests.

add_observation(request, serverobservation)

Before the incoming request is sent to render(), the add_observation() method is called. If the resource chooses to accept the observation, it has to call the serverobservation.accept(cb) with a callback that will be called when the observation ends. After accepting, the ObservableResource should call serverobservation.trigger() whenever it changes its state; the ServerObservation will then initiate notifications by having the request rendered again.