NDEF Decoder and Encoder for Python¶

Message Decoder¶

ndef.message_decoder(stream_or_bytes, errors='strict', known_records=Record._known_types)¶

Returns a generator function that decodes NDEF Records from a file-like, byte-oriented stream or a bytes object given by the stream_or_bytes argument. When the errors argument is set to ‘strict’ (the default), the decoder expects a valid NDEF Message with Message Begin and End flags set for the first and last record and decoding of known record types will fail for any format errors. Minor format errors are accepted when errors is set to ‘relax’. With errors set to ‘ignore’ the decoder silently stops when a non-correctable error is encountered. The known_records argument provides the mapping of record type strings to class implementations. It defaults to all global records implemented by ndeflib or additionally registered from user code. It’s main use would probably be to force decoding into only generic records with known_records={}.

Parameters:	stream_or_bytes (byte stream or bytes object) – message data octets errors (str) – error handling strategy, may be ‘strict’, ‘relax’ or ‘ignore’ known_records (dict) – mapping of known record types to implementation classes
Raises:	ndef.DecodeError – for data format errors (unless errors is set to ‘ignore’)

>>> import ndef
>>> octets = bytearray.fromhex('910303414243616263 5903030144454630646566')
>>> decoder = ndef.message_decoder(octets)
>>> next(decoder)
ndef.record.Record('urn:nfc:wkt:ABC', '', bytearray(b'abc'))
>>> next(decoder)
ndef.record.Record('urn:nfc:wkt:DEF', '0', bytearray(b'def'))
>>> next(decoder)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
StopIteration
>>> message = list(ndef.message_decoder(octets))
>>> len(message)
2

Message Encoder¶

ndef.message_encoder(message=None, stream=None)¶

Returns a generator function that encodes ndef.Record objects into an NDEF Message octet sequence. The message argument is either an iterable of records or None, if message is None the records must be sequentially send to the encoder (as for any generator the first send value must be None, specific to the message encoder is that octets are generated for the previous record and a final None value must be send for the last record octets). The stream argument controls the output of the generator function. If stream is None, the generator yields a bytes object for each encoded record. Otherwise, it must be a file-like, byte-oriented stream that receives the encoded octets and the generator yields the number of octets written per record.

Parameters:	message (iterable or None) – sequence of records to encode stream (byte stream or None) – file-like output stream
Raises:	ndef.EncodeError – for invalid record parameter values or types

>>> import ndef
>>> record1 = ndef.Record('urn:nfc:wkt:ABC', '1', b'abc')
>>> record2 = ndef.Record('urn:nfc:wkt:DEF', '2', b'def')
>>> encoder = ndef.message_encoder()
>>> encoder.send(None)
>>> encoder.send(record1)
>>> encoder.send(record2)
b'\x99\x03\x03\x01ABC1abc'
>>> encoder.send(None)
b'Y\x03\x03\x01DEF2def'
>>> message = [record1, record2]
>>> b''.join((ndef.message_encoder(message)))
b'\x99\x03\x03\x01ABC1abcY\x03\x03\x01DEF2def'
>>> list((ndef.message_encoder(message, open('/dev/null', 'wb'))))
[11, 11]

Record Class¶

class ndef.Record(type='', name='', data=b'')¶

This class implements generic decoding and encoding of an NDEF Record and is the base for all specialized record type classes. The NDEF Record Payload Type encoded by the TNF (Type Name Format) and TYPE field is represented by a single type string argument:

Empty (TNF 0)

An Empty record has no TYPE, ID, and PAYLOAD fields. This is set if the type argument is absent, None, or an empty string. Encoding ignores whatever is set as name and data, producing just the short length record b'\x10\x00\x00'.

NFC Forum Well Known Type (TNF 1)

An NFC Forum Well Known Type is a URN (RFC 2141) with namespace identifier (NID) nfc and the namespace specific string (NSS) prefixed with wkt:. When encoding, the type is written as a relative-URI (cf. RFC 3986), omitting the NID and the prefix. For example, the type urn:nfc:wkt:T is encoded as TNF 1, TYPE T.

Media-type as defined in RFC 2046 (TNF 2)

A media-type follows the media-type grammar defined in RFC 2046. Records that carry a payload with an existing, registered media type should use this record type. Note that the record type indicates the type of the payload; it does not refer to a MIME message that contains an entity of the given type. For example, the media type ‘image/jpeg’ indicates that the payload is an image in JPEG format using JFIF encoding as defined by RFC 2046.

Absolute URI as defined in RFC 3986 (TNF 3)

An absolute-URI follows the absolute-URI BNF construct defined by RFC 3986. This type can be used for payloads that are defined by URIs. For example, records that carry a payload with an XML-based message type may use the XML namespace identifier of the root element as the record type, like a SOAP/1.1 message may be http://schemas.xmlsoap.org/soap/envelope/.

NFC Forum External Type (TNF 4)

An NFC Forum External Type is a URN (RFC 2141) with namespace identifier (NID) nfc and the namespace specific string (NSS) prefixed with ext:. When encoding, the type is written as a relative-URI (cf. RFC 3986), omitting the NID and the prefix. For example, the type urn:nfc:ext:nfcpy.org:T will be encoded as TNF 4, TYPE nfcpy.org:T.

Unknown (TNF 5)

The Unknown record type indicates that the type of the payload is unknown, similar to the application/octet-stream media type. It is set with the type argument unknown and encoded with an empty TYPE field.

Unchanged (TNF 6)

The Unchanged record type is used for all except the first record in a chunked payload. It is set with the type argument unchanged and encoded with an empty TYPE field.

The type argument sets the final value of the type attribute, which provides the value only for reading. The name and data argument set the initial values of the name and data attributes. They can both be changed later.

Parameters:	type (str) – final value for the type attribute name (str) – initial value for the see name attribute data (bytes) – initial value for the data attribute

type¶

The record type is a read-only text string set either by decoding or through initialization.

name¶

The record name is a text string that corresponds to the NDEF Record ID field. The maximum capacity is 255 8-bit characters, converted in and out as latin-1.

data¶

The record data is a bytearray with the sequence of octets that correspond to the NDEF Record PAYLOAD field. The attribute itself is readonly but the bytearray content can be changed. Note that for derived record classes this becomes a read-only bytes object with the content encoded from the record’s attributes.

MAX_PAYLOAD_SIZE¶

This is a class data attribute that restricts the decodable and encodable maximum NDEF Record PAYLOAD size from the theoretical value of up to 4GB to 1MB. If needed, a different value can be assigned to the record class: ndef.Record.MAX_PAYLOAD_SIZE = 100*1024

classmethod register_type(record_class)¶

Register a derived record class as a known type for decoding. This creates an entry for the record_class type string to be decoded as a record_class instance. Beyond internal use this is needed for adding private records.

Record with no Payload¶

This is the most simple yet fully functional record class. It inherits from the abstract class ndef.record.GlobalRecord (which is actually just an abstract version of Record to make sure the dervied class implements the payload decode and encode methods. The record type string is set via the _type class attribute. The _encode_payload method must return the bytes for the NDEF Record PAYLOAD field, usually encoded from other record attributes but here it’s just empty. The _decode_payload classmethod receives the NDEF Record PAYLOAD field the bytes type octets and returns a record object populated with the decoded PAYLOAD data, again nothing for the record with no payload. The _decode_min_payload_length and _decode_max_payload_length class attributes (put at the end of the class definition only to align with the explanation) inform the record decoder about the minmum required and maximum acceptable PAYLOAD size, thus the octets argument will never have less or more data. If a class does not set those values, the default min value is 0 and the default max value is Record.MAX_PAYLOAD_SIZE.

import ndef

class ExampleRecordWithNoPayload(ndef.record.GlobalRecord):
    """An NDEF Record with no payload."""

    _type = 'urn:nfc:ext:nfcpy.org:x-empty'

    def _encode_payload(self):
        # This record does not have any payload to encode.
        return b''

    @classmethod
    def _decode_payload(cls, octets, errors):
        # This record does not have any payload to decode.
        return cls()

    _decode_min_payload_length = 0
    _decode_max_payload_length = 0

ndef.Record.register_type(ExampleRecordWithNoPayload)

record = ExampleRecordWithNoPayload()
octets = b''.join(ndef.message_encoder([record]))
print("encoded: {}".format(octets))

message = list(ndef.message_decoder(octets))
print("decoded: {}".format(message[0]))

encoded: b'\xd4\x11\x00nfcpy.org:x-empty'
decoded: NDEF Example Record With No Payload ID '' PAYLOAD 0 byte

Example Temperature Record¶

This record carries an unsigned 32-bit integer timestamp that is the seconds since 1.1.1970 (and will overflow on February 7, 2106 !) and a signed 16-bit integer with a temperature. The payload is thus a fixed structure with exactly 6 octets for which the inherited _decode_struct and _encode_struct methods are perfectly suited. They are quite the same as using struct.unpack_from and struct.pack but return a single value directly and not as a (value, ) tuple.

This example also shows how the __format__ method is used to provide an arguments and a data view for the str() and repr() functions.

import ndef
import time

class ExampleTemperatureRecord(ndef.record.GlobalRecord):
    """An NDEF Record that carries a temperature and a timestamp."""

    _type = 'urn:nfc:ext:nfcpy.org:x-temp'

    def __init__(self, timestamp, temperature):
        self._time = timestamp
        self._temp = temperature

    def __format__(self, format_spec):
        if format_spec == 'args':
            # Return the init args for repr() but w/o class name and brackets
            return "{r._time}, {r._temp}".format(r=self)
        if format_spec == 'data':
            # Return a nicely formatted content string for str()
            data_str = time.strftime('%d.%m.%Y', time.gmtime(self._time))
            time_str = time.strftime('%H:%M:%S', time.gmtime(self._time))
            return "{}°C on {} at {}".format(self._temp, data_str, time_str)
        return super(ExampleTemperatureRecord, self).__format__(format_spec)

    def _encode_payload(self):
        return self._encode_struct('>Lh', self._time, self._temp)

    @classmethod
    def _decode_payload(cls, octets, errors):
        timestamp, temperature = cls._decode_struct('>Lh', octets)
        return cls(timestamp, temperature)

    # Make sure that _decode_payload gets only called with 6 octets
    _decode_min_payload_length = 6
    _decode_max_payload_length = 6

ndef.Record.register_type(ExampleTemperatureRecord)

record = ExampleTemperatureRecord(1468410873, 25)
octets = b''.join(ndef.message_encoder([record]))
print("encoded: {}".format(octets))

message = list(ndef.message_decoder(octets))
print("decoded: {}".format(message[0]))

encoded: b'\xd4\x10\x06nfcpy.org:x-tempW\x86+\xf9\x00\x19'
decoded: NDEF Example Temperature Record ID '' 25°C on 13.07.2016 at 11:54:33

Type Length Value Record¶

This record class demonstrates how _decode_struct and _encode_struct can be used for typical Type-Length-Value constructs. The notion ‘BB+’ is a slight extension of the struct module’s format string syntax and means to decode or encode a 1 byte Type field, a 1 byte Length field and Length number of octets as Value. The _decode_struct method then returns just the Type and Value. The _encode_struct needs only the Type and Value arguments and takes the Length from Value. Another format string syntax extension, but not not used in the example, is a trailing ‘*’ character. That just means that all remaining octets are returned as bytes.

This example also demonstrates how decode and encode error exceptions are generated with the _decode_error and _encode_error methods. These methods return an instance of ndef.DecodeError and ndef.EncodeError with the fully qualified class name followed by the expanded format string. Two similar methods, _type_error and _value_error may be used whenever a TypeError or ValueError shall be reported with the full classname in its error string. They do also check if the first word in the format string matches a data attribute name, and if, the string is joined with a ‘.’ to the classname.

The _decode_payload method also shows the use of the errors argument. With ‘strict’ interpretation of errors the payload is expected to have the Type 1 TLV encoded in first place (although not a recommended design for TLV loops). The errors argument may also say ‘relax’ and then the order won’t matter.

import ndef

class ExampleTypeLengthValueRecord(ndef.record.GlobalRecord):
    """An NDEF Record with carries a temperature and a timestamp."""

    _type = 'urn:nfc:ext:nfcpy.org:x-tlvs'

    def __init__(self, *args):
        # We expect each argument to be a tuple of (Type, Value) where Type
        # is int and Value is bytes. So *args* will be a tuple of tuples.
        self._tlvs = args

    def _encode_payload(self):
        if sum([t for t, v in self._tlvs if t == 1]) != 1:
            raise self._encode_error("exactly one Type 1 TLV is required")
        tlv_octets = []
        for t, v in self._tlvs:
            tlv_octets.append(self._encode_struct('>BB+', t, v))
        return b''.join(tlv_octets)

    @classmethod
    def _decode_payload(cls, octets, errors):
        tlvs = []
        offset = 0
        while offset < len(octets):
            t, v = cls._decode_struct('>BB+', octets, offset)
            offset = offset + 2 + len(v)
            tlvs.append((t, v))
        if sum([t for t, v in tlvs if t == 1]) != 1:
            raise cls._encode_error("missing the mandatory Type 1 TLV")
        if errors == 'strict' and len(tlvs) > 0 and tlvs[0][0] != 1:
            errstr = 'first TLV must be Type 1, not Type {}'
            raise cls._encode_error(errstr, tlvs[0][0])
        return cls(*tlvs)

    # We need at least the 2 octets Type, Length for the first TLV.
    _decode_min_payload_length = 2

ndef.Record.register_type(ExampleTypeLengthValueRecord)

record = ExampleTypeLengthValueRecord((1, b'abc'), (5, b'xyz'))
octets = b''.join(ndef.message_encoder([record]))
print("encoded: {}".format(octets))

message = list(ndef.message_decoder(octets))
print("decoded: {}".format(message[0]))

encoded: b'\xd4\x10\nnfcpy.org:x-tlvs\x01\x03abc\x05\x03xyz'
decoded: NDEF Example Type Length Value Record ID '' PAYLOAD 10 byte '0103616263050378797a'