MessageBuilder.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef NFC_NDEF_MESSAGEBUILDER_H_
00018 #define NFC_NDEF_MESSAGEBUILDER_H_
00019 
00020 #include <stdint.h>
00021 
00022 #include "platform/Span.h"
00023 
00024 #include "nfc/ndef/Record.h"
00025 
00026 namespace mbed {
00027 namespace nfc {
00028 namespace ndef {
00029 
00030 /**
00031  * @addtogroup nfc
00032  * @{
00033  */
00034 
00035 /**
00036  * Construct a NDEF Message.
00037  */
00038 class MessageBuilder {
00039 
00040 public:
00041     /**
00042      * Build a record payload.
00043      */
00044     struct PayloadBuilder {
00045         /**
00046          * Return the size of the payload built by this object.
00047          *
00048          * @return The size of the payload.
00049          */
00050         virtual size_t size() const = 0;
00051 
00052         /**
00053          * Build the payload in a buffer that has the required size.
00054          *
00055          * @param buffer The buffer used to construct the payload.
00056          */
00057         virtual void build(const Span<uint8_t>  &buffer) const = 0;
00058 
00059     protected:
00060         /**
00061          * Non virtual destructor.
00062          */
00063         ~PayloadBuilder() { }
00064     };
00065 
00066     /**
00067      * Create a new MessageBuilder that can be used to construct valid NDEF
00068      * messages.
00069      *
00070      * @param buffer The data buffer that will contain the NDEF message.
00071      */
00072     MessageBuilder(const Span<uint8_t>  &buffer);
00073 
00074     /**
00075      * Append a new record to the message being built.
00076      *
00077      * @param type The type of the record to insert.
00078      * @param payload The payload of the record (optional).
00079      * @param is_last_record true if the record to insert is the last record of
00080      * the payload or false otherwise.
00081      *
00082      * @return true if the record has been successfully inserted or false
00083      * otherwise.
00084      *
00085      * @note insertion can fail if the message is already complete or if the
00086      * size remaining in the message buffer is not large enough to makes the
00087      * record inserted fit.
00088      */
00089     bool append_record(
00090         const RecordType &type,
00091         const RecordPayload  &payload = RecordPayload(),
00092         bool is_last_record = false
00093     );
00094 
00095     /**
00096      * Append a new record to the message being built.
00097      *
00098      * @param type The type of the record to insert.
00099      * @param builder The builder of the payload.
00100      * @param is_last_record true if the record to insert is the last record of
00101      * the payload or false otherwise.
00102      *
00103      * @return true if the record has been successfully inserted or false
00104      * otherwise.
00105      *
00106      * @note insertion can fail if the message is already complete or if the
00107      * size remaining in the message buffer is not large enough to makes the
00108      * record inserted fit.
00109      */
00110     bool append_record(
00111         const RecordType &type,
00112         const PayloadBuilder &builder,
00113         bool is_last_record = false
00114     );
00115 
00116     /**
00117      * Append a new record to the message being built.
00118      *
00119      * @param record The record to insert.
00120      * @param builder The builder that will construct the payload.
00121      *
00122      * @return true if the record has been successfully inserted or false otherwise.
00123      *
00124      * @note insertion can fail if the message is already complete or if the
00125      * size remaining in the message buffer is not large enough to makes the
00126      * record inserted fit.
00127      */
00128     bool append_record(
00129         const Record &record,
00130         const PayloadBuilder *builder = NULL
00131     );
00132 
00133     /**
00134      * Compute the size of a record.
00135      *
00136      * @param record The record used to compute the size.
00137      * @param builder The payload builder if any.
00138      *
00139      * @return The size of the payload for the record in input.
00140      */
00141     static size_t compute_record_size(
00142         const Record &record,
00143         const PayloadBuilder *builder = NULL
00144     );
00145 
00146     /**
00147      * Reset the builder state.
00148      */
00149     void reset();
00150 
00151     /**
00152      * Reset the builder state and assign a new buffer to it.
00153      */
00154     void reset(const Span<uint8_t>  &buffer);
00155 
00156     /**
00157      * Return true if the message stored is complete and false otherwise.
00158      *
00159      * @return true if the message is complete or false.
00160      */
00161     bool is_message_complete() const;
00162 
00163     /**
00164      * Return the buffer storing the data if the message is complete or an empty
00165      * buffer if the message is not complete.
00166      *
00167      * @return The message built.
00168      */
00169     Span<const uint8_t>  get_message() const;
00170 
00171 private:
00172     // append fields
00173     void append_header(const Record &record, const PayloadBuilder *);
00174     void append_type_length(const Record &record);
00175     void append_payload_length(const Record &, const PayloadBuilder *);
00176     void append_id_length(const Record &);
00177     void append_type(const Record &);
00178     void append_id(const Record &);
00179     void append_payload(const Record &, const PayloadBuilder *);
00180 
00181     // helpers
00182     static bool is_short_payload(const Record &record, const PayloadBuilder *);
00183     static size_t get_payload_size(const Record &, const PayloadBuilder *);
00184 
00185     // builder state.
00186     Span<uint8_t>  _message_buffer;
00187     size_t _position;
00188     bool _message_started;
00189     bool _message_ended;
00190     bool _in_chunk;
00191 };
00192 
00193 /**
00194  * @}
00195  */
00196 
00197 } // namespace ndef
00198 } // namespace nfc
00199 } // namespace mbed
00200 
00201 #endif /* NFC_NDEF_MESSAGEBUILDER_H_ */