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 /** @addtogroup nfc
00031  * @{
00032  */
00033 
00034 /**
00035  * Construct a NDEF Message.
00036  */
00037 class MessageBuilder {
00038 
00039 public:
00040     /**
00041      * Build a record payload.
00042      */
00043     struct PayloadBuilder {
00044         /**
00045          * Return the size of the payload built by this object.
00046          *
00047          * @return The size of the payload.
00048          */
00049         virtual size_t size() const = 0;
00050 
00051         /**
00052          * Build the payload in a buffer that has the required size.
00053          *
00054          * @param buffer The buffer used to construct the payload.
00055          */
00056         virtual void build(const Span<uint8_t>  &buffer) const = 0;
00057 
00058     protected:
00059         /**
00060          * Non virtual destructor.
00061          */
00062         ~PayloadBuilder() { }
00063     };
00064 
00065     /**
00066      * Create a new MessageBuilder that can be used to construct valid NDEF
00067      * messages.
00068      *
00069      * @param buffer The data buffer that will contain the NDEF message.
00070      */
00071     MessageBuilder(const Span<uint8_t>  &buffer);
00072 
00073     /**
00074      * Append a new record to the message being built.
00075      *
00076      * @param type The type of the record to insert.
00077      * @param payload The payload of the record (optional).
00078      * @param is_last_record true if the record to insert is the last record of
00079      * the payload or false otherwise.
00080      *
00081      * @return true if the record has been successfully inserted or false
00082      * otherwise.
00083      *
00084      * @note insertion can fail if the message is already complete or if the
00085      * size remaining in the message buffer is not large enough to makes the
00086      * record inserted fit.
00087      */
00088     bool append_record(
00089         const RecordType &type,
00090         const RecordPayload  &payload = RecordPayload(),
00091         bool is_last_record = false
00092     );
00093 
00094     /**
00095      * Append a new record to the message being built.
00096      *
00097      * @param type The type of the record to insert.
00098      * @param builder The builder of the payload.
00099      * @param is_last_record true if the record to insert is the last record of
00100      * the payload or false otherwise.
00101      *
00102      * @return true if the record has been successfully inserted or false
00103      * otherwise.
00104      *
00105      * @note insertion can fail if the message is already complete or if the
00106      * size remaining in the message buffer is not large enough to makes the
00107      * record inserted fit.
00108      */
00109     bool append_record(
00110         const RecordType &type,
00111         const PayloadBuilder &builder,
00112         bool is_last_record = false
00113     );
00114 
00115     /**
00116      * Append a new record to the message being built.
00117      *
00118      * @param record The record to insert.
00119      * @param builder The builder that will construct the payload.
00120      *
00121      * @return true if the record has been successfully inserted or false otherwise.
00122      *
00123      * @note insertion can fail if the message is already complete or if the
00124      * size remaining in the message buffer is not large enough to makes the
00125      * record inserted fit.
00126      */
00127     bool append_record(
00128         const Record &record,
00129         const PayloadBuilder *builder = NULL
00130     );
00131 
00132     /**
00133      * Compute the size of a record.
00134      *
00135      * @param record The record used to compute the size.
00136      * @param builder The payload builder if any.
00137      *
00138      * @return The size of the payload for the record in input.
00139      */
00140     static size_t compute_record_size(
00141         const Record &record,
00142         const PayloadBuilder *builder = NULL
00143     );
00144 
00145     /**
00146      * Reset the builder state.
00147      */
00148     void reset();
00149 
00150     /**
00151      * Reset the builder state and assign a new buffer to it.
00152      */
00153     void reset(const Span<uint8_t>  &buffer);
00154 
00155     /**
00156      * Return true if the message stored is complete and false otherwise.
00157      *
00158      * @return true if the message is complete or false.
00159      */
00160     bool is_message_complete() const;
00161 
00162     /**
00163      * Return the buffer storing the data if the message is complete or an empty
00164      * buffer if the message is not complete.
00165      *
00166      * @return The message built.
00167      */
00168     Span<const uint8_t>  get_message() const;
00169 
00170 private:
00171     // append fields
00172     void append_header(const Record &record, const PayloadBuilder *);
00173     void append_type_length(const Record &record);
00174     void append_payload_length(const Record &, const PayloadBuilder *);
00175     void append_id_length(const Record &);
00176     void append_type(const Record &);
00177     void append_id(const Record &);
00178     void append_payload(const Record &, const PayloadBuilder *);
00179 
00180     // helpers
00181     static bool is_short_payload(const Record &record, const PayloadBuilder *);
00182     static size_t get_payload_size(const Record &, const PayloadBuilder *);
00183 
00184     // builder state.
00185     Span<uint8_t>  _message_buffer;
00186     size_t _position;
00187     bool _message_started;
00188     bool _message_ended;
00189     bool _in_chunk;
00190 };
00191 /** @}*/
00192 } // namespace ndef
00193 } // namespace nfc
00194 } // namespace mbed
00195 
00196 #endif /* NFC_NDEF_MESSAGEBUILDER_H_ */