|
| 1 | +### NDEF API |
| 2 | + |
| 3 | +Mbed OS provide this API to construct and parse NDEF messages, which is the common data format exchange for NFC messages. |
| 4 | + |
| 5 | +An NDEF message is a collection of separate NDEF records. Each of these records is defined by a type, such as URI, Mime and Text, that identifies a payload and what the record contains. |
| 6 | + |
| 7 | +#### Parsing |
| 8 | + |
| 9 | +The class `mbed::nfc::ndef::MessageParser` parses a buffer of data in input and produces parsing events that are forwarded to its delegate. To help you, we offer a more integrated parser (`mbed::nfc::ndef::common::SimpleMessageParser`) that parses well known NFC types records, such as Text, URI or Mime records, and produces usable objects out of the box. |
| 10 | + |
| 11 | +``` |
| 12 | +#include "nfc/ndef/common/SimpleMessageParser.h" |
| 13 | +
|
| 14 | +using mbed::nfc::ndef::Record; |
| 15 | +using mbed::nfc::ndef::RecordType; |
| 16 | +using mbed::nfc::ndef::RecordID; |
| 17 | +using mbed::nfc::ndef::MessageParser; |
| 18 | +using mbed::nfc::ndef::common::Text; |
| 19 | +using mbed::nfc::ndef::common::URI; |
| 20 | +using mbed::nfc::ndef::common::Mime; |
| 21 | +
|
| 22 | +using mbed::nfc::ndef::common::SimpleMessageParser; |
| 23 | +
|
| 24 | +void parse_ndef_message(const Span<const uint8_t> &buffer) { |
| 25 | + SimpleMessageParser parser; |
| 26 | + struct : SimpleMessageParser::Delegate { |
| 27 | + virtual void on_parsing_started() { |
| 28 | + printf("parsing started\r\n"); |
| 29 | + } |
| 30 | +
|
| 31 | + virtual void on_text_parsed(const Text &text, const RecordID &) { |
| 32 | + printf("Text record parsed.\r\n"); |
| 33 | + printf( |
| 34 | + "\tlanguage: %.*s\r\n", |
| 35 | + text.get_language_code().size(), text.get_language_code().data() |
| 36 | + ); |
| 37 | + printf("\ttext: %.*s\r\n", text.get_text().size(), text.get_text().data()); |
| 38 | + } |
| 39 | +
|
| 40 | + virtual void on_uri_parsed(const URI &uri, const RecordID &) { |
| 41 | + printf("URI parsed.\r\n"); |
| 42 | + printf("\tid: %d\r\n", uri.get_id()); |
| 43 | + printf("\tvalue: %.*s\r\n", uri.get_uri_field().size(), uri.get_uri_field().data()); |
| 44 | + } |
| 45 | +
|
| 46 | + virtual void on_mime_parsed(const Mime &mime, const RecordID &) { |
| 47 | + printf("Mime object parsed.\r\n"); |
| 48 | + printf("\ttype: %.*s\r\n", mime.get_mime_type().size(), mime.get_mime_type().data()); |
| 49 | + printf("\tcontent size: %d\r\n", mime.get_mime_content().size()); |
| 50 | + } |
| 51 | +
|
| 52 | + virtual void on_unknown_record_parsed(const Record &record) { |
| 53 | + printf("Unknown record parsed.\r\n"); |
| 54 | + printf( |
| 55 | + "\ttype: %d, type_value: %.*s\r\n", |
| 56 | + record.type.tnf, record.type.value.size(), record.type.value.data() |
| 57 | + ); |
| 58 | + printf( |
| 59 | + "\tpayload size: %d, payload: %.*s\r\n", |
| 60 | + record.payload.size(), record.payload.size(), record.payload.data() |
| 61 | + ); |
| 62 | + } |
| 63 | +
|
| 64 | + virtual void on_parsing_terminated() { |
| 65 | + printf("parsing terminated\r\n"); |
| 66 | + } |
| 67 | +
|
| 68 | + virtual void on_parsing_error(MessageParser::error_t error) { |
| 69 | + printf("Parsing error: %d\r\n", error); |
| 70 | + } |
| 71 | + } delegate; |
| 72 | +
|
| 73 | + parser.set_delegate(&delegate); |
| 74 | + parser.parse(buffer); |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +An application can extend capabilities of `SimpleMessageParser` by adding new record parsers (`mbed::nfc::ndef::RecordParser`) at runtime. |
| 79 | + |
| 80 | +[](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1nfc_1_1ndef_1_1_message_parser.html) |
| 81 | + |
| 82 | +[](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1nfc_1_1ndef_1_1common_1_1_simple_message_parser.html) |
| 83 | + |
| 84 | +#### Construction |
| 85 | + |
| 86 | +The class `mbed::nfc::ndef::MessageBuilder` builds an NDEF message into a user-provided buffer. `URI`, `Text` and `Mime` types can be serialized in the builder with the help of the member function `append_as_record`. |
| 87 | + |
| 88 | +``` |
| 89 | +#include "nfc/ndef/MessageBuilder.h" |
| 90 | +
|
| 91 | +using mbed::nfc::ndef::MessageBuilder; |
| 92 | +using mbed::nfc::ndef::common::Text; |
| 93 | +using mbed::nfc::ndef::common::URI; |
| 94 | +
|
| 95 | +size_t build_ndef_message(const Span<uint8_t> &buffer) { |
| 96 | + MessageBuilder builder(buffer); |
| 97 | +
|
| 98 | + URI uri(URI::HTTPS_WWW, span_from_cstr("mbed.com")); |
| 99 | + Text text(Text::UTF8, span_from_cstr("en-US"), span_from_cstr("Mbed website")); |
| 100 | +
|
| 101 | + uri.append_as_record(builder); |
| 102 | + text.append_as_record(builder, /* last record */ true); |
| 103 | +
|
| 104 | + return builder.get_message().size(); |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +[](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1nfc_1_1ndef_1_1_message_builder.html) |
0 commit comments