inc/FNetNfcNdefMessage.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 /**
  18  * @file    FNetNfcNdefMessage.h
  19  * @brief   This is the header file for the %NdefMessage class.
  20  *
  21  * This header file contains the declarations of the %NdefMessage class.
  22  */
  23
  24 #ifndef _FNET_NFC_NDEF_MESSAGE_H_
  25 #define _FNET_NFC_NDEF_MESSAGE_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseResult.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32 class ByteBuffer;
  33 class String;
  34 } }
  35
  36 namespace Tizen { namespace Net { namespace Nfc
  37 {
  38
  39 class _NdefMessageImpl;
  40 class NdefRecord;
  41
  42 /**
  43  * @class   NdefMessage
  44  * @brief   This class represents an NDEF message.
  45  *
  46  * @since   2.0
  47  *
  48  * The %NdefMessage class represents an NDEF message. An NDEF message is composed of 1 or more NDEF records. Therefore,
  49  * this class has NdefRecord instances and provides the operations to manipulate the list of those instances. These
  50  * operations are very similar to those of the Tizen::Base::Collection::IList class.
  51  *
  52  * If a new NDEF record is inserted, the uniqueness of its payload identifier is checked. This class also provides
  53  * methods which convert %NdefMessage to Tizen::Base::ByteBuffer and vice versa.
  54  *
  55  * For more information on the class features, see
  56  * <a href="../org.tizen.native.appprogramming/html/guide/net/nfc.htm">NFC Guide</a>.
  57  */
  58 class _OSP_EXPORT_ NdefMessage
  59         : public Tizen::Base::Object
  60 {
  61 public:
  62         /**
  63          * This is the default constructor for this class.
  64          *
  65          * @since       2.0
  66          */
  67         NdefMessage(void);
  68
  69         /**
  70          * Copying of objects using this copy assignment operator is allowed.
  71          *
  72          * @since       2.0
  73          *
  74          * @param[in]   value               An instance of %NdefMessage
  75          * @remarks     This performs a deep copy.
  76          */
  77         NdefMessage(const NdefMessage& value);
  78
  79         /**
  80          * This destructor overrides Tizen::Base::Object::~Object().
  81          *
  82          * @since       2.0
  83          */
  84         virtual ~NdefMessage(void);
  85
  86         /**
  87          * Compares the calling instance with the specified instance.
  88          *
  89          * @since       2.0
  90          *
  91          * @return      @c true if the specified instance of Tizen::Base::Object is equal to the calling %NdefMessage
  92          *              instance, @n
  93          *              else @c false
  94          * @param[in]   obj                    The object to compare
  95          * @remark      Two NdefMessage instances are equal only if they contain the same %NdefRecord instances in the
  96          *              same order.
  97          */
  98         virtual bool Equals(const Tizen::Base::Object& obj) const;
  99
 100         /**
 101          * Gets the hash value of the current instance.
 102          *
 103          * @since       2.0
 104          *
 105          * @return      The hash value of the current instance
 106          */
 107         virtual int GetHashCode(void) const;
 108
 109         /**
 110          * Gets the number of NDEF records in this NDEF message.
 111          *
 112          * @since       2.0
 113          *
 114          * @return      The number of NDEF records
 115          */
 116         int GetRecordsCount(void) const;
 117
 118         /**
 119          * Searches for an NdefRecord object in this class. @n
 120          * Gets the index of the NdefRecord object if the record is present.
 121          *
 122          * @since       2.0
 123          *
 124          * @exception   E_SUCCESS           The method is successful.
 125          * @exception   E_OBJ_NOT_FOUND     The specified record is not found.
 126          * @remarks     This method verifies the equality of its pointers, but does not check the content of the specified
 127          *              record.
 128          */
 129         result IndexOf(const NdefRecord& record, int& index) const;
 130
 131         /**
 132          * Gets the NdefRecord object from the specified location.
 133          *
 134          * @since       2.0
 135          *
 136          * @return      The requested NdefRecord object, @n
 137          *              else @c null if the index is not valid
 138          * @param[in]   index               The index of the NDEF record to get
 139          * @exception   E_SUCCESS           The method is successful.
 140          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 141          *                                  The specified @c index parameter is either greater than or equal to the number
 142          *                                  of elements or less than @c 0.
 143          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 144          */
 145         NdefRecord* GetRecordAt(int index) const;
 146
 147         /**
 148          * Gets the NdefRecord object with the specified payload identifier.
 149          *
 150          * @since       2.0
 151          *
 152          * @return      The requested NdefRecord object, @n
 153          *              else @c null if no record matches
 154          * @param[in]   payloadId           The payload identifier of the NDEF record to get
 155          * @exception   E_SUCCESS           The method is successful.
 156          * @exception   E_OBJ_NOT_FOUND     The specified @c id is not found in any of the NDEF records.
 157          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 158          */
 159         NdefRecord* GetRecord(const Tizen::Base::String& payloadId) const;
 160
 161         /**
 162          * Appends the specified NDEF record at the end of the last record in the NDEF message.
 163          *
 164          * @since       2.0
 165          *
 166          * @return      An error code
 167          * @param[in]   record              The NDEF record to append
 168          * @exception   E_SUCCESS           The method is successful.
 169          * @exception   E_INVALID_ARG       The specified NDEF record is invalid. @n
 170          *                                  For example, the record has the same payload identifier as the other records in
 171          *                                  this NDEF message.
 172          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 173          * @remarks     This method performs a shallow copy. It adds just the pointer, not the NdefRecord instance.
 174          */
 175         result AppendRecord(const NdefRecord& record);
 176
 177         /**
 178          * Inserts the specified NDEF record in the NDEF message at the specified location.
 179          *
 180          * @since       2.0
 181          *
 182          * @return      An error code
 183          * @param[in]   record              The NDEF record to insert
 184          * @param[in]   index               The index at which the NDEF record must be inserted
 185          * @exception   E_SUCCESS           The method is successful.
 186          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 187          *                                  The specified @c index is greater than the number of elements or less than
 188          *                                  @c 0.
 189          * @exception   E_INVALID_ARG       The specified NDEF record is invalid. @n
 190          *                                  For example, the record has the same payload identifier as the other records in
 191          *                                  this NDEF message.
 192          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 193          * @remarks
 194          *              - The NDEF records that appear after the insertion point move downwards to accommodate the inserted
 195          *                NDEF record.
 196          *              - This method performs a shallow copy. It adds just the pointer, not the NdefRecord instance.
 197          */
 198         result InsertRecordAt(const NdefRecord& record, int index);
 199
 200         /**
 201          * Replaces the NDEF record from the specified location with the specified NDEF record.
 202          *
 203          * @since       2.0
 204          *
 205          * @return      An error code
 206          * @param[in]   record              The NDEF record to set
 207          * @param[in]   index               The index at which the NDEF record is set
 208          * @param[in]   deallocate          Set to @c true to deallocate the replaced record, @n
 209          *                                  else @c false
 210          * @exception   E_SUCCESS           The method is successful.
 211          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 212          *                                  The specified @c index is either equal to or greater than the number of
 213          *                                  elements or less than @c 0.
 214          * @exception   E_INVALID_ARG       The specified NDEF record is invalid. @n
 215          *                                  For example, the record has the same payload identifier as the other records in
 216          *                                  this NDEF message.
 217          * @remarks     This method performs a shallow copy. It adds just the pointer, not the NdefRecord instance.
 218          */
 219         result SetRecordAt(const NdefRecord& record, int index, bool deallocate = false);
 220
 221         /**
 222          * Removes the NDEF record from a specified location.
 223          *
 224          * @since       2.0
 225          *
 226          * @return      An error code
 227          * @param[in]   index               The index from where the NDEF record is removed
 228          * @param[in]   deallocate          Set to @c true to deallocate the record, @n
 229          *                                  else @c false
 230          * @exception   E_SUCCESS           The method is successful.
 231          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 232          *                                  The specified @c index is either equal to or greater than the number of
 233          *                                  elements or less than @c 0.
 234          * @remarks     The NDEF records that appear after the deletion point move upwards to occupy the vacated spot.
 235          */
 236         result RemoveRecordAt(int index, bool deallocate = false);
 237
 238         /**
 239          * Removes all the records in the NDEF message. @n
 240          * If the specified @c deallocate parameter is set to @c true, it deallocates all the NdefRecord instances in the
 241          * message.
 242          *
 243          * @since       2.0
 244          *
 245          * @param[in]   deallocate          Set to @c true to deallocate the record, @n
 246          *                                  else @c false
 247          */
 248         void RemoveAllRecords(bool deallocate = false);
 249
 250         /**
 251          * Converts the entire NDEF message with all the NDEF records into a byte sequence as per the NDEF specification.
 252          *
 253          * @since       2.0
 254          *
 255          * @return      The NDEF message as a Tizen::Base::ByteBuffer, @n
 256          *              else @c null if the conversion fails
 257          * @exception   E_SUCCESS           The method is successful.
 258          * @exception   E_INVALID_DATA      The specified NDEF message does not contain any NDEF records.
 259          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 260          * @exception   E_SYSTEM            A system error has occurred.
 261          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 262          */
 263         Tizen::Base::ByteBuffer* ToByteBufferN(void) const;
 264
 265         /**
 266          * Gets a new instance of the NDEF message from the specified Tizen::Base::ByteBuffer.
 267          *
 268          * @since       2.0
 269          *
 270          * @return      The instance of the created NDEF message, @n
 271          *              else @c null if the conversion fails
 272          * @param[in]   buffer              An NDEF message as a byte sequence
 273          * @exception   E_SUCCESS           The method is successful.
 274          * @exception   E_INVALID_FORMAT    The specified @c buffer cannot be formulated to the NDEF message.
 275          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 276          * @exception   E_SYSTEM            A system error has occurred.
 277          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 278          */
 279         static NdefMessage* GetInstanceN(const Tizen::Base::ByteBuffer& buffer);
 280
 281         /**
 282          * Assigns the value of the specified instance to the current instance of %NdefMessage.
 283          *
 284          * @since       2.0
 285          *
 286          * @return      A reference to the %NdefMessage instance
 287          * @param[in]   rhs                     A reference to the %NdefMessage instance to copy
 288          */
 289         NdefMessage& operator =(const NdefMessage& rhs);
 290
 291 private:
 292         _NdefMessageImpl* __pImpl;
 293
 294         friend class _NdefMessageImpl;
 295
 296 }; // NdefMessage
 297
 298 } } } // Tizen::Net::Nfc
 299
 300 #endif // _FNET_NFC_NDEF_MESSAGE_H_