inc/FNetNfcNdefTagConnection.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    FNetNfcNdefTagConnection.h
  19  * @brief   This is the header file for the %NdefTagConnection class.
  20  *
  21  * This header file contains the declarations of the %NdefTagConnection class.
  22  */
  23
  24 #ifndef _FNET_NFC_NDEF_TAG_CONNECTION_H_
  25 #define _FNET_NFC_NDEF_TAG_CONNECTION_H_
  26
  27 #include <FBaseResult.h>
  28 #include <FNetNfcTagConnection.h>
  29
  30 namespace Tizen { namespace Net { namespace Nfc
  31 {
  32
  33 class _NdefTagConnectionImpl;
  34 class NdefMessage;
  35 class INdefTagConnectionListener;
  36
  37 /**
  38  * @class    NdefTagConnection
  39  * @brief    This class represents the connection with an NFC tag that has the NDEF data.
  40  *
  41  * @since    2.0
  42  *
  43  * The %NdefTagConnection class provides the mechanism to communicate with the tag that has NFC Data Exchange Format
  44  * (NDEF) data and supports the NDEF message operations. @n
  45  * This class can be derived from the TagConnection class. Use the IsNdefConnection() method to check the availability
  46  * of the derivation. @n
  47  * Use the Read() and Write() methods to read and write the NDEF data. After the completion of the read and write
  48  * operations, the response is received by the INdefTagConnectionListener::OnNdefReadCompletedN() and
  49  * INdefTagConnectionListener::OnNdefWriteCompleted() event handlers, respectively.
  50  *
  51  * For more information on the class features, see
  52  * <a href="../org.tizen.native.appprogramming/html/guide/net/nfc.htm">NFC Guide</a>.
  53  *
  54  * The following example demonstrates how to use the %NdefTagConnection class.
  55  * @code
  56  * // MyClass.h
  57  * #include <FNet.h>
  58  *
  59  * class MyClass
  60  *      : public Tizen::Net::Nfc::INfcManagerEventListener
  61  *      , public Tizen::Net::Nfc::INfcTagDiscoveryEventListener
  62  *      , public Tizen::Net::Nfc::INdefTagConnectionListener
  63  * {
  64  * public:
  65  *      void WriteNdefMessageSample(void);
  66  *      virtual void OnNfcTagDetectedN(Tizen::Net::Nfc::TagConnection* pConnection);
  67  *      virtual void OnNfcTagLost(void);
  68  *      virtual void OnNdefWriteCompleted(result r);
  69  *      // Other methods are hidden for the sake of simplicity.
  70  *
  71  * private:
  72  *      Tizen::Net::Nfc::NfcManager*            __pNfcManager;
  73  *      Tizen::Net::Nfc::NdefTagConnection*     __pNdefConnection;
  74  * };
  75  *
  76  * // MyClass.cpp
  77  * #include "MyClass.h"
  78  *
  79  * using namespace Tizen::Net::Nfc;
  80  *
  81  * MyClass::MyClass(void)
  82  *      : __pNfcManager(null)
  83  *      , __pNdefConnection(null)
  84  * {
  85  *      __pNfcManager = new NfcManager();
  86  * }
  87  *
  88  * MyClass::~MyClass(void)
  89  * {
  90  *      // Removes the tag discovery event listener for all the NDEF tag types
  91  *      __pNfcManager->RemoveTagDiscoveryEventListener(*this, NFC_TAG_TYPE_ALL_NDEF_COMPATIBLE);
  92  *
  93  *      delete __pNfcManager;
  94  * }
  95  *
  96  * void
  97  * MyClass::WriteNdefMessageSample(void)
  98  * {
  99  *      // Creates NfcManager instance and registers the manager event listener
 100  *      __pNfcManager->Construct(*this);
 101  *
 102  *      // Adds the tag discovery event listener for all the NDEF tag types
 103  *      __pNfcManager->AddTagDiscoveryEventListener(*this, NFC_TAG_TYPE_ALL_NDEF_COMPATIBLE);
 104  * }
 105  *
 106  * // This method is invoked when a new NDEF tag is detected
 107  * void
 108  * MyClass::OnNfcTagDetectedN(TagConnection* pConnection)
 109  * {
 110  *      // Checks whether the connection supports NDEF operations,
 111  *      // but the evaluation result of the below code is always true in this example
 112  *      if (pConnection->IsNdefConnection())
 113  *      {
 114  *              __pNdefConnection = dynamic_cast<NdefTagConnection*>(pConnection);
 115  *
 116  *              // Registers the NDEF tag connection listener
 117  *              __pNdefConnection->SetNdefTagConnectionListener(this);
 118  *
 119  *              NdefMessage message;
 120  *              // Fills up the NdefMessage object here
 121  *
 122  *              __pNdefConnection->Write(message);
 123  *      }
 124  * }
 125  *
 126  * // This method is invoked when the target tag is lost
 127  * void
 128  * MyClass::OnNfcTagLost(void)
 129  * {
 130  *      // The acquired NdefTagConnection should be deallocated
 131  *      delete __pNdefConnection;
 132  * }
 133  *
 134  * // This method is invoked when the write request is completed
 135  * void
 136  * MyClass::OnNdefWriteCompleted(result r)
 137  * {
 138  *      if (r == E_SUCCESS)
 139  *      {
 140  *              // Writing NdefMessage is successful
 141  *      }
 142  * }
 143  * @endcode
 144  */
 145 class _OSP_EXPORT_ NdefTagConnection
 146         : public TagConnection
 147 {
 148 public:
 149         /**
 150          * Checks whether the connection supports the NDEF message operations.
 151          *
 152          * @since       2.0
 153          *
 154          * @return      @c true if the connection supports the NDEF message operations, @n
 155          *              else @c false
 156          */
 157         virtual bool IsNdefConnection(void) const;
 158
 159         /**
 160          * Sets a listener for receiving the result of reading or writing on this NDEF tag connection.
 161          *
 162          * @since       2.0
 163          *
 164          * @return      An error code
 165          * @param[in]   pListener           The listener to add
 166          * @exception   E_SUCCESS           The method is successful.
 167          * @exception   E_SYSTEM            A system error has occurred.
 168          * @remarks     At the most, one event listener can be registered. If the input parameter is @c null, the listener
 169          *              that is currently registered gets unregistered.
 170          */
 171         result SetNdefTagConnectionListener(INdefTagConnectionListener* pListener);
 172
 173         /**
 174          * Reads the NDEF data from the NDEF tag.
 175          *
 176          * @since       2.0
 177          *
 178          * @return      An error code
 179          * @exception   E_SUCCESS           The method is successful.
 180          * @exception   E_IN_PROGRESS       The read process is in progress.
 181          * @exception   E_CONNECTION_BUSY   The connection is busy. Therefore, the method cannot process the read request.
 182          * @exception   E_CONNECTION_FAILED The connection to the tag is closed or it has failed.
 183          * @exception   E_SYSTEM            A system error has occurred.
 184          * @see         INdefTagConnectionListener::OnNdefReadCompletedN()
 185          */
 186         result Read(void);
 187
 188         /**
 189          * Writes the NDEF data to the NDEF tag.
 190          *
 191          * @since       2.0
 192          *
 193          * @return      An error code
 194          * @param[in]   message             The NDEF message to write to the target
 195          * @exception   E_SUCCESS           The method is successful.
 196          * @exception   E_INVALID_ARG       The input @c message is invalid. @n
 197          *                                  For example, it does not contain any NDEF records.
 198          * @exception   E_IN_PROGRESS       The write process is in progress.
 199          * @exception   E_CONNECTION_BUSY   The connection is busy. Therefore, the method cannot process the write request.
 200          * @exception   E_CONNECTION_FAILED The connection to the tag is closed or it has failed.
 201          * @exception   E_SYSTEM            A system error has occurred.
 202          * @see         INdefTagConnectionListener::OnNdefWriteCompleted()
 203          */
 204         result Write(const NdefMessage& message);
 205
 206         /**
 207          * This destructor overrides Tizen::Base::Object::~Object().
 208          *
 209          * @since       2.0
 210          */
 211         virtual ~NdefTagConnection(void);
 212
 213 private:
 214         //
 215         // This default constructor is intentionally declared as private so that only the platform can create an instance.
 216         //
 217         NdefTagConnection(void);
 218
 219         //
 220         // The implementation of this copy constructor is intentionally blank to prohibit copying of objects.
 221         //
 222         NdefTagConnection(const NdefTagConnection& value);
 223
 224         //
 225         // The implementation of this copy assignment operator is intentionally blank to prohibit copying of objects.
 226         //
 227         NdefTagConnection& operator =(const NdefTagConnection& value);
 228
 229 private:
 230         _NdefTagConnectionImpl* __pNdefImpl;
 231
 232         friend class _TagConnectionImpl;
 233         friend class _NdefTagConnectionImpl;
 234
 235 }; // NdefTagConnection
 236
 237 } } } // Tizen::Net::Nfc
 238
 239 #endif // _FNET_NFC_NDEF_TAG_CONNECTION_H_