Connection-Related Classes

• coapy.connection.Message
• coapy.connection.TransmissionRecord
• coapy.connection.ReceptionRecord
• coapy.connection.EndPoint

class coapy.connection.EndPoint(address_family=2, socket_type=2, socket_proto=17)

Bases: object

process(timeout_ms)

Process network activity related to CoAP messages on this end-point.

This method is responsible for transmitting (and re-transmitting) outgoing messages, and for receiving incoming messages. It will block until the timeout is reached, or an incoming message is received.

Incoming messages that are transaction responses are, if possible, associated with the transmission record to which they pertain. A ReceptionRecord is returned. The infrastructure does not automatically acknowledge any incoming message; this is an application responsibility.

Parameter:timeout_ms – The maximum time, in milliseconds, that this method should block. A value of None indicates no limit: the method will block forever if no activity occurs. Returns:rx_record or None Return type:ReceptionRecord

register(sfd)

Register the given socket as a potential source of incoming messages.

The primary socket is automatically registered. This method can be used to associate additional sockets, such as multicast ones, with this end-point.

Note:Regardless of the socket on which a message is received, any response will be transmitted from socket.

send(message, remote)

Transmit a message to the remote.

The message should have a code of either Message.CON or Message.NON; acknowledgements and resets should be generated through the ReceptionRecord methods.

The TransmissionRecord associated with the transmission is returned.

Note:Invoking this does not actually transmit the message: it merely records it and queues it for transmission on the next invocation of process().

socket

Return a reference to the primary socket associated with the end-point.

If this end-point is expected to receive REST requests, the socket should be bound to a known port so that clients can identify the server.

class coapy.connection.Message(transaction_type=0, code=0, payload='', **kw)

Bases: object

Represent the components of a CoAP message.

• transaction_type
• code
• options
• payload

The transaction ID is not recorded in the message instance. Rather, it is recorded in a TransmissionRecord or ReceptionRecord.

Create a Message instance.

As a convenience, message options can be created from keyword parameters if the keywords are present in OptionKeywords.

Parameters:

• transaction_type – One of CON, NON, ACK, RST. The message transaction type cannot be modified after creation.
• code – The integral code identifying the method of a request message, or the disposition in a response message.
• payload – An optional payload for the message. If not provided, the message will have no payload unless subsequently assigned.

ACK

The message transaction type indicating acknowledgement of a confirmable message. Note that such a message may also include a response payload that pertains to the acknowledged message.

CON

The message transaction type indicating a confirmable message (one that requires an acknowledgement).

NON

The message transaction type indicating a non-confirmable message (one that does not evoke an acknowledgement).

OptionKeywords

A map from Python identifiers to option classes.

These identifiers can be provided as keyword parameters to the Message.__init__() method; the corresponding option class will be invoked with the parameter value to create an option that is associated with the message.

RST

The message transaction type indicating that a received confirmable message could not be processed due to insufficient context.

addOption(opt)

Add a new option instance.

If the option can appear multiple times, this method is intended to add the new value to the existing ones.

Warning:Currently multi-valued options are not supported and this is equivalent to replaceOption().

build_uri(explicit=False)

code

The integral request method code or response code of the message.

classmethod decode(packed)

Create a Message instance from a payload.

This method decodes the payload, and returns a pair (xid, message) where xid is the transaction ID extracted from the encoded message, and message is an instance of Message initialized to the decoded components of the data.

Parameter:payload – A sequence of octets comprising a complete CoAP packet Return type:(int, Message)

deleteOption(opt)

Remove the option from the message.

Parameter:opt – An option, specified as an option instance, an option class, or the type code of an option.

findOption(opt)

Locate the given option within the message.

Returns None if no matching option can be found.

Parameter:opt – An option, specified as an option instance, an option class, or the type code of an option.

options

A tuple containing the options associated with the message.

The options are sorted in increasing value of option type.

payload

The payload of the message as a str.

If this is not an empty string, there should be a corresponding coapy.options.ContentType option present that defines its format (if the default value of text/plain is not appropriate).

replaceOption(opt)

Add a new option instance.

If the option is already present in message, its previous value is replaced by the new one.

transaction_type

Return the transaction type (one of CON, NON, ACK, RST).

Note:The transaction type is assigned when the message is created, and cannot be changed thereafter.

version

The CoAP protocol version.

class coapy.connection.ReceptionRecord(end_point, packed, remote)

Bases: object

Material related to a received CoAP message.

• message
• remote
• transaction_id
• pertains_to
• end_point

ack(response_msg=None)

end_point

The EndPoint that received the message.

has_responded

message

The Message received.

pertains_to

The TransmissionRecord to which the received message was interpreted as a response.

The value will be None if the message transaction type is neither Message.ACK nor Message.RST, or if the receiving EndPoint could not identify the relevant message (e.g., it had already been expired from the transmission cache).

remote

The socket address from which the message was received.

reset()

transaction_id

The transaction ID of the received message.

class coapy.connection.TransmissionRecord(end_point, message, remote)

Bases: object

Material related to a transmitted CoAP message.

• message
• remote
• transaction_id
• end_point
• packed

Parameters:

• end_point – The EndPoint responsible for transmitting the message.
• message – An instance of Message from which the transmission content will be calculated
• remote – A Python socket address identifying the destination of the transmission.

end_point

The EndPoint that transmitted the message.

is_unacknowledged

Return True iff this was a confirmable transaction for which the last transmission response wait has elapsed without receipt of a response.

last_event_time

The time.time() at which the last event related to the transmission occured.

Transmission events are:

• transmission or retranmission of the message
• receipt of a response to the message

message

A reference to the Message from which the transmission derived.

Note:The content of the message may have been changed by application code subsequent to its transmission.

next_event_time

Get the time.time() value at which the next event associated with this transmission is due.

Predictable transmission events are:

• the time at which the message should be retransmitted
• the time by which a response to the message should be received

Returns None if there are no events associated with the transmission.

packed

The octet sequence representing the message.

remote

The Python socket address to which the transmission was sent.

response

The ReceptionRecord for the first message that was interpreted as a response to this message.

response_type

• Message.NON if the message does not require a response
• Message.ACK if the message has been acknowledged. If the acknowledgement carried a response message, it is available in response.
• Message.RST if the message received could not process the message.
• None if the message is confirmable and neither an Message.ACK nor Message.RST has been received.

responses

A set containing all ReceptionRecords that pertain to this transmission.

transaction_id

The transmission ID encoded in the packed message.

transmission_time

The time.time() at which the message was first transmitted.

transmissions_left

Return the number of (re-)transmissions yet to occur.

A positive value requires that next_event_time not be None.

coapy.connection.is_multicast(address)

Return True iff address is a multicast address.

This function is used to eliminate retransmissions for confirmable messages sent to multicast addresses.

Parameter:address – A socket address as supported by the Python socket functions: i.e. a pair (host, port) for IPv4 addresses and a tuple (host, port, flowinfo, scopeid) for IPv6. The host may be either a host name or an IP address in the textual notation appropriate to the address family.