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, this class
  49  * has NdefRecord instances and provides the operations to manipulate the list of those instances. These operations are
  50  * 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 %Object is equal to the calling %NdefMessage instance, @n
  92          *              else @c false
  93          * @param[in]   obj                    The object to compare
  94          * @remark      Two %NdefMessage instances are equal only if they contain the same %NdefRecord instances in the
  95          *              same order.
  96          */
  97         virtual bool Equals(const Tizen::Base::Object& obj) const;
  98
  99         /**
 100          * Gets the hash value of the current instance.
 101          *
 102          * @since       2.0
 103          *
 104          * @return      The hash value of the current instance
 105          */
 106         virtual int GetHashCode(void) const;
 107
 108         /**
 109          * Gets the number of NDEF records in this NDEF message.
 110          *
 111          * @since       2.0
 112          *
 113          * @return      The number of NDEF records
 114          */
 115         int GetRecordsCount(void) const;
 116
 117         /**
 118          * Searches for an NdefRecord object in this class. @n
 119          * Gets the index of the NdefRecord object if the record is present.
 120          *
 121          * @since       2.0
 122          *
 123          * @exception   E_SUCCESS           The method is successful.
 124          * @exception   E_OBJ_NOT_FOUND     The specified record is not found.
 125          * @remarks     This method verifies the equality of its pointers, but does not check the content of the specified
 126          *              record.
 127          */
 128         result IndexOf(const NdefRecord& record, int& index) const;
 129
 130         /**
 131          * Gets the NdefRecord object from the specified location.
 132          *
 133          * @since       2.0
 134          *
 135          * @return      The requested NdefRecord object, @n
 136          *              else @c null if the index is not valid
 137          * @param[in]   index               The index of the NDEF record to get
 138          * @exception   E_SUCCESS           The method is successful.
 139          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 140          *                                  The specified @c index parameter is either greater than or equal to the number
 141          *                                  of elements or less than @c 0.
 142          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 143          */
 144         NdefRecord* GetRecordAt(int index) const;
 145
 146         /**
 147          * Gets the NdefRecord object with the specified payload identifier.
 148          *
 149          * @since       2.0
 150          *
 151          * @return      The requested NdefRecord object, @n
 152          *              else @c null if no record matches
 153          * @param[in]   payloadId           The payload identifier of the NDEF record to get
 154          * @exception   E_SUCCESS           The method is successful.
 155          * @exception   E_OBJ_NOT_FOUND     The specified @c id is not found in any of the NDEF records.
 156          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 157          */
 158         NdefRecord* GetRecord(const Tizen::Base::String& payloadId) const;
 159
 160         /**
 161          * Appends the specified NDEF record at the end of the last record in the NDEF message.
 162          *
 163          * @since       2.0
 164          *
 165          * @return      An error code
 166          * @param[in]   record              The NDEF record to be appended
 167          * @exception   E_SUCCESS           The method is successful.
 168          * @exception   E_INVALID_ARG       The specified NDEF record is invalid. @n
 169          *                                  For example, the record has the same payload identifier as the other records in
 170          *                                  this NDEF message.
 171          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 172          * @remarks     This method performs a shallow copy. It adds just the pointer, not the NdefRecord instance.
 173          */
 174         result AppendRecord(const NdefRecord& record);
 175
 176         /**
 177          * Inserts the specified NDEF record in the NDEF message at the specified location.
 178          *
 179          * @since       2.0
 180          *
 181          * @return      An error code
 182          * @param[in]   record              The NDEF record to be inserted
 183          * @param[in]   index               The index at which the NDEF record must be inserted
 184          * @exception   E_SUCCESS           The method is successful.
 185          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 186          *                                  The specified @c index is greater than the number of elements or less than
 187          *                                  @c 0.
 188          * @exception   E_INVALID_ARG       The specified NDEF record is invalid. @n
 189          *                                  For example, the record has the same payload identifier as the other records in
 190          *                                  this NDEF message.
 191          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 192          * @remarks     The NDEF records that appear after the insertion point move downwards to accommodate the inserted
 193          *              NDEF record.
 194          *              This method performs a shallow copy. It adds just the pointer, not the NdefRecord instance.
 195          */
 196         result InsertRecordAt(const NdefRecord& record, int index);
 197
 198         /**
 199          * Replaces the NDEF record from the specified location with the specified NDEF record.
 200          *
 201          * @since       2.0
 202          *
 203          * @return      An error code
 204          * @param[in]   record              The NDEF record to be set
 205          * @param[in]   index               The index at which the NDEF record is to be set
 206          * @param[in]   deallocate          Set to @c true to deallocate the replaced record, @n
 207          *                                  else @c false
 208          * @exception   E_SUCCESS           The method is successful.
 209          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 210          *                                  The specified @c index is either equal to or greater than the number of
 211          *                                  elements or less than @c 0.
 212          * @exception   E_INVALID_ARG       The specified NDEF record is invalid. @n
 213          *                                  For example, the record has the same payload identifier as the other records in
 214          *                                  this NDEF message.
 215          * @remarks     This method performs a shallow copy. It adds just the pointer, not the NdefRecord instance.
 216          */
 217         result SetRecordAt(const NdefRecord& record, int index, bool deallocate = false);
 218
 219         /**
 220          * Removes the NDEF record from a specified location.
 221          *
 222          * @since       2.0
 223          *
 224          * @return      An error code
 225          * @param[in]   index               The index from where the NDEF record is removed
 226          * @param[in]   deallocate          Set to @c true to deallocate the record, @n
 227          *                                  else @c false
 228          * @exception   E_SUCCESS           The method is successful.
 229          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the record list. @n
 230          *                                  The specified @c index is either equal to or greater than the number of
 231          *                                  elements or less than @c 0.
 232          * @remarks     The NDEF records that appear after the deletion point move upwards to occupy the vacated spot.
 233          */
 234         result RemoveRecordAt(int index, bool deallocate = false);
 235
 236         /**
 237          * Removes all the records in the NDEF message. @n
 238          * If the specified @c deallocate parameter is set to @c true, it deallocates all the NdefRecord instances in the
 239          * message.
 240          *
 241          * @since       2.0
 242          *
 243          * @param[in]   deallocate          Set to @c true to deallocate the record, @n
 244          *                                  else @c false
 245          */
 246         void RemoveAllRecords(bool deallocate = false);
 247
 248         /**
 249          * Converts the entire NDEF message with all the NDEF records into a byte sequence as per the NDEF specification.
 250          *
 251          * @since       2.0
 252          *
 253          * @return      The NDEF message as a ByteBuffer, @n
 254          *              else @c null if the conversion fails
 255          * @exception   E_SUCCESS           The method is successful.
 256          * @exception   E_INVALID_DATA      The specified NDEF message does not contain any NDEF records.
 257          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 258          * @exception   E_SYSTEM            A system error has occurred.
 259          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 260          */
 261         Tizen::Base::ByteBuffer* ToByteBufferN(void) const;
 262
 263         /**
 264          * Gets a new instance of the NDEF message from the specified ByteBuffer.
 265          *
 266          * @since       2.0
 267          *
 268          * @return      The instance of the created NDEF message, @n
 269          *              else @c null if the conversion fails
 270          * @param[in]   buffer              An NDEF message as a byte sequence
 271          * @exception   E_SUCCESS           The method is successful.
 272          * @exception   E_INVALID_FORMAT    The specified @c buffer cannot be formulated to the NDEF message.
 273          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 274          * @exception   E_SYSTEM            A system error has occurred.
 275          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 276          */
 277         static NdefMessage* GetInstanceN(const Tizen::Base::ByteBuffer& buffer);
 278
 279         /**
 280          * Copying of objects using this copy assignment operator is allowed.
 281          *
 282          * @since       2.0
 283          *
 284          * @return      A reference to the %NdefMessage instance
 285          * @param[in]   rhs                     A reference to the %NdefMessage instance to copy
 286          */
 287         NdefMessage& operator =(const NdefMessage& rhs);
 288
 289 private:
 290         _NdefMessageImpl* __pImpl;
 291
 292         friend class _NdefMessageImpl;
 293
 294 }; // NdefMessage
 295
 296 } } } // Tizen::Net::Nfc
 297
 298 #endif // _FNET_NFC_NDEF_MESSAGE_H_