inc/FNetNfcTagConnection.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    FNetNfcTagConnection.h
  19  * @brief   This is the header file for the %TagConnection class.
  20  *
  21  * This header file contains the declarations of the %TagConnection class.
  22  */
  23
  24 #ifndef _FNET_NFC_TAG_CONNECTION_H_
  25 #define _FNET_NFC_TAG_CONNECTION_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseResult.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32 class ByteBuffer;
  33 } }
  34
  35 namespace Tizen { namespace Net { namespace Nfc
  36 {
  37
  38 class NfcTag;
  39 class _TagConnectionImpl;
  40 class ITagConnectionListener;
  41
  42 /**
  43  * @class   TagConnection
  44  * @brief   This class represents the connection with an NFC tag. It provides the mechanism to communicate with the NFC
  45  *          tag through ISO14443 or a general Radio Frequency Identification (RFID) manner.
  46  *
  47  * @since   2.0
  48  *
  49  * The %TagConnection class represents the connection with an NFC tag. It provides the mechanism to communicate with
  50  * the NFC tag through ISO14443 or a general Radio Frequency Identification (RFID) manner. @n
  51  * The class has an NfcTag instance that represents the target tag. This class can be inherited by the
  52  * NdefTagConnection class if the target tag supports the NFC Data Exchange Format (NDEF) operations.
  53  *
  54  * For more information on the class features, see
  55  * <a href="../org.tizen.native.appprogramming/html/guide/net/nfc.htm">NFC Guide</a>.
  56  *
  57  * The following example demonstrates how to use the %TagConnection class.
  58  *
  59  * @code
  60  * // MyClass.h
  61  * #include <FNet.h>
  62  *
  63  * class MyClass
  64  *      : public Tizen::Net::Nfc::INfcManagerEventListener
  65  *      , public Tizen::Net::Nfc::INfcTagDiscoveryEventListener
  66  *      , public Tizen::Net::Nfc::ITagConnectionListener
  67  * {
  68  * public:
  69  *      // Method declarations are hidden for the sake of simplicity.
  70  *
  71  * private:
  72  *      Tizen::Net::Nfc::NfcManager*      __pNfcManager;
  73  *      Tizen::Net::Nfc::TagConnection*   __pConnection;
  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  *      , __pConnection(null)
  84  * {
  85  *      __pNfcManager = new NfcManager();
  86  * }
  87  *
  88  * MyClass::~MyClass(void)
  89  * {
  90  *      // Removes the tag discovery event listener for the ISO14443-4 tag type.
  91  *      __pNfcManager->RemoveTagDiscoveryEventListener(*this, NFC_TAG_TYPE_ISO14443_4);
  92  *
  93  *      delete __pNfcManager;
  94  * }
  95  *
  96  * void
  97  * MyClass::SendApduCommandSample(void)
  98  * {
  99  *      // Creates an instance of NfcManager and registers the manager event listener
 100  *      __pNfcManager->Construct(*this);
 101  *
 102  *      // Adds the tag discovery event listener for the ISO14443-4 tag type
 103  *      __pNfcManager->AddTagDiscoveryEventListener(*this, NFC_TAG_TYPE_ISO14443_4);
 104  * }
 105  *
 106  * // This method is invoked when a new ISO14443-4 tag like a Mifare DESFire is detected
 107  * void
 108  * MyClass::OnNfcTagDetectedN(TagConnection* pConnection)
 109  * {
 110  *      // Checks whether the connection supports ISO14443-4,
 111  *      // but the evaluation result of the below code is always true in this example
 112  *      if (pConnection->GetTargetTag()->HasTagType(NFC_TAG_TYPE_ISO14443_4))
 113  *      {
 114  *              __pConnection = pConnection;
 115  *
 116  *              // Registers the tag connection listener
 117  *              __pConnection->SetTagConnectionListener(this);
 118  *
 119  *              Tizen::Base::ByteBuffer command;
 120  *              // Makes an APDU(ISO7816-4) command here
 121  *
 122  *              __pConnection->SendCommand(command);
 123  *      }
 124  * }
 125  *
 126  * // This method is invoked when the target tag is lost
 127  * void
 128  * MyClass::OnNfcTagLost(void)
 129  * {
 130  *      // The acquired TagConnection should be deallocated
 131  *      delete __pConnection;
 132  * }
 133  *
 134  * // This method is invoked when the response of the command is received
 135  * void
 136  * MyClass::OnNfcResponseReceivedN(Tizen::Base::ByteBuffer* pResponse, result r)
 137  * {
 138  *      if (r == E_SUCCESS)
 139  *      {
 140  *              // Uses the response data here
 141  *
 142  *              // Deallocates the response data
 143  *              delete pResponse;
 144  *      }
 145  * }
 146  * @endcode
 147  */
 148 class _OSP_EXPORT_ TagConnection
 149         : public Tizen::Base::Object
 150 {
 151 public:
 152         /**
 153          * Checks whether the connection supports the NDEF message operations.
 154          *
 155          * @since       2.0
 156          *
 157          * @return      @c true if the connection supports the NDEF message operations, @n
 158          *              else @c false
 159          */
 160         virtual bool IsNdefConnection(void) const;
 161
 162         /**
 163          * Gets the target tag object with which this connection is established.
 164          *
 165          * @since       2.0
 166          *
 167          * @return      The tag object
 168          */
 169         const NfcTag* GetTargetTag(void) const;
 170
 171         /**
 172          * Sets a listener for receiving the response of the command sent on this tag connection.
 173          *
 174          * @since       2.0
 175          *
 176          * @return      An error code
 177          * @param[in]   pListener           The listener to add
 178          * @exception   E_SUCCESS           The method is successful.
 179          * @exception   E_SYSTEM            A system error has occurred.
 180          * @remarks     Only one event listener can be registered. If the input parameter is @c null, the listener that is
 181          *              already registered gets unregistered.
 182          */
 183         result SetTagConnectionListener(ITagConnectionListener* pListener);
 184
 185         /**
 186          * Sends the specified command to the target tag.
 187          *
 188          * @since       2.0
 189          *
 190          * @return      An error code
 191          * @param[in]   command             The command to send
 192          * @exception   E_SUCCESS           The method is successful.
 193          * @exception   E_INVALID_ARG       The input @c command is invalid.
 194          * @exception   E_IN_PROGRESS       The previous send request is in progress.
 195          * @exception   E_CONNECTION_BUSY   The connection is busy. Therefore, the method cannot process the send request.
 196          * @exception   E_CONNECTION_FAILED The connection to the tag is closed or it has failed.
 197          * @exception   E_SYSTEM            A system error has occurred.
 198          * @see         ITagConnectionListener::OnNfcResponseReceivedN()
 199          */
 200         result SendCommand(const Tizen::Base::ByteBuffer& command);
 201
 202         /**
 203          * This destructor overrides Tizen::Base::Object::~Object().
 204          *
 205          * @since       2.0
 206          */
 207         virtual ~TagConnection(void);
 208
 209 protected:
 210         //
 211         // This method is for internal use only. Using this method can cause behavioral, security-related,
 212         // and consistency-related issues in the application.
 213         //
 214         // This is the default constructor for this class.
 215         //
 216         // @since       2.0
 217         //
 218         TagConnection(void);
 219
 220         //
 221         // This method is for internal use only. Using this method can cause behavioral, security-related,
 222         // and consistency-related issues in the application.
 223         //
 224         // This method is reserved and may change its name at any time without prior notice.
 225         //
 226         // @since       2.0
 227         //
 228         virtual void TagConnection_Reserved1(void) {}
 229
 230         //
 231         // This method is for internal use only. Using this method can cause behavioral, security-related,
 232         // and consistency-related issues in the application.
 233         //
 234         // This method is reserved and may change its name at any time without prior notice.
 235         //
 236         // @since       2.0
 237         //
 238         virtual void TagConnection_Reserved2(void) {}
 239
 240         //
 241         // This method is for internal use only. Using this method can cause behavioral, security-related,
 242         // and consistency-related issues in the application.
 243         //
 244         // This method is reserved and may change its name at any time without prior notice.
 245         //
 246         // @since       2.0
 247         //
 248         virtual void TagConnection_Reserved3(void) {}
 249
 250 private:
 251         //
 252         // The implementation of this copy constructor is intentionally blank to prohibit copying of objects.
 253         //
 254         TagConnection(const TagConnection& value);
 255
 256         //
 257         // The implementation of this copy assignment operator is intentionally blank to prohibit copying of objects.
 258         //
 259         TagConnection& operator =(const TagConnection& value);
 260
 261 protected:
 262         //
 263         // This variable is for internal use only. Using this variable can cause behavioral,
 264         // security-related, and consistency-related issues in the application.
 265         //
 266         // The point for indicating the implementation object.
 267         //
 268         // @since       2.0
 269         //
 270         _TagConnectionImpl* _pImpl;
 271
 272         friend class _TagConnectionImpl;
 273
 274 }; // TagConnection
 275
 276 } } } // Tizen::Net::Nfc
 277
 278 #endif // _FNET_NFC_TAG_CONNECTION_H_