inc/FNetNfcNfcManager.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    FNetNfcNfcManager.h
  19  * @brief   This is the header file for the %NfcManager class.
  20  *
  21  * This header file contains the declarations of the %NfcManager class.
  22  */
  23 #ifndef _FNET_NFC_NFC_MANAGER_H_
  24 #define _FNET_NFC_NFC_MANAGER_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FBaseResult.h>
  28 #include <FNetNfcNfcTypes.h>
  29
  30 namespace Tizen { namespace Net { namespace Nfc
  31 {
  32
  33 class INfcManagerEventListener;
  34 class INfcTransactionEventListener;
  35 class INfcTagDiscoveryEventListener;
  36 class INdefMessageDiscoveryEventListener;
  37 class INfcDeviceDiscoveryEventListener;
  38 class NdefMessage;
  39 class NdefRecordType;
  40 class TagConnection;
  41 class _NfcManagerImpl;
  42
  43 /**
  44  * @class    NfcManager
  45  * @brief    This is the manager class for the NFC features.
  46  *
  47  * @since    2.0
  48  *
  49  * The %NfcManager class is the manager class for NFC features that includes the methods for enabling and disabling the NFC feature of
  50  * the device and the mechanism for establishing a connection with the detected tag. It is also used to detect the NFC
  51  * tags and NDEF messages. @n
  52  * There are two ways to get the TagConnection instance established with the detected tag. @n
  53  * @li Use the INfcTagDiscoveryEventListener::OnNfcTagDetectedN() method that is invoked immediately when the target
  54  *     tag is detected.
  55  * @li Invoke the GetCurrentTagConnectionN() method after the tag is detected.
  56  *
  57  * If the target tag is lost, the INfcTagDiscoveryEventListener::OnNfcTagLost() method is called and the old
  58  * TagConnection instance becomes invalid. Therefore, the operations performed by the TagConnection class are not
  59  * processed anymore. Moreover, the TagConnection instance cannot be used again even if the same tags are detected
  60  * again by the device.
  61  *
  62  * For more information on the class features, see
  63  * <a href="../org.tizen.native.appprogramming/html/guide/net/nfc.htm">NFC Guide</a>.
  64  *
  65  * The following example demonstrates how to use the %NfcManager class.
  66  *
  67  * @code
  68  * // MyClass.h
  69  * #include <FNet.h>
  70  *
  71  * class MyClass
  72  *      : public Tizen::Net::Nfc::INfcManagerEventListener
  73  *      , public Tizen::Net::Nfc::INfcTagDiscoveryEventListener
  74  *      , public Tizen::Net::Nfc::INdefMessageDiscoveryEventListener
  75  * {
  76  * public:
  77  *      // The method declarations are hidden for the sake of simplicity
  78  *
  79  * private:
  80  *      Tizen::Net::Nfc::NfcManager*      __pNfcManager;
  81  *      Tizen::Net::Nfc::TagConnection*   __pConnection;
  82  * };
  83  *
  84  * // MyClass.cpp
  85  * #include "MyClass.h"
  86  *
  87  * using namespace Tizen::Net::Nfc;
  88  *
  89  * MyClass::MyClass(void)
  90  *      : __pNfcManager(null)
  91  *      , __pConnection(null)
  92  * {
  93  *      __pNfcManager = new NfcManager();
  94  * }
  95  *
  96  * MyClass::~MyClass(void)
  97  * {
  98  *      // Removes the tag discovery event listener for all the NFC tag types
  99  *      __pNfcManager->RemoveTagDiscoveryEventListener(*this, NFC_TAG_TYPE_ALL);
 100  *      // Removes the NDEF message discovery event listener for all the TNF types
 101  *      __pNfcManager->RemoveNdefMessageDiscoveryEventListener(*this, NdefRecordType(NDEF_TNF_ALL));
 102  *
 103  *      delete __pNfcManager;
 104  * }
 105  *
 106  * void
 107  * MyClass::DiscoverySample(void)
 108  * {
 109  *      // Creates the NfcManager instance and registers the manager event listener
 110  *      __pNfcManager->Construct(*this);
 111  *
 112  *      if (__pNfcManager->IsTagConnected())
 113  *      {
 114  *              // This is the way to get the connection already established with the detected tag
 115  *              __pConnection = __pNfcManager->GetCurrentTagConnectionN();
 116  *
 117  *              // Performs connection operations here
 118  *      }
 119  *
 120  *      // Adds the tag discovery event listener for all the NFC tag types
 121  *      // This is the method to establish the connection with tags that are detected hereafter
 122  *      __pNfcManager->AddTagDiscoveryEventListener(*this, NFC_TAG_TYPE_ALL);
 123  *
 124  *      // Adds the NDEF message discovery event listener for all the TNF types
 125  *      // This is the method to get NDEF messages that are detected hereafter
 126  *      __pNfcManager->AddNdefMessageDiscoveryEventListener(*this, NdefRecordType(NDEF_TNF_ALL));
 127  * }
 128  *
 129  * // This method is invoked when a new tag is detected
 130  * void
 131  * MyClass::OnNfcTagDetectedN(TagConnection* pConnection)
 132  * {
 133  *      __pConnection = pConnection;
 134  *
 135  *      // Performs connection operations here
 136  * }
 137  *
 138  * // This method is invoked when the target tag is lost
 139  * void
 140  * MyClass::OnNfcTagLost(void)
 141  * {
 142  *      // The acquired TagConnection should be deallocated
 143  *      delete __pConnection;
 144  * }
 145  *
 146  * // This method is invoked when a new NDEF message is detected
 147  * void
 148  * MyClass::OnNdefMessageDetectedN(NdefMessage* pMessage)
 149  * {
 150  *      // Manipulates the received message here
 151  *
 152  *      // Deallocates the received NdefMessage
 153  *      pMessage->RemoveAllRecords(true);
 154  *      delete pMessage;
 155  * }
 156  * @endcode
 157  */
 158 class _OSP_EXPORT_ NfcManager
 159         : public Tizen::Base::Object
 160 {
 161 public:
 162         /**
 163          * The object is not fully constructed after this constructor is called. @n
 164          * For full construction, the Construct() method must be called right after calling this constructor.
 165          *
 166          * @since       2.0
 167          *
 168          * @remarks     After creating an instance of this class, the Construct() method must be called explicitly to
 169          *              initialize this instance.
 170          * @see         Construct()
 171          */
 172         NfcManager(void);
 173
 174         /**
 175          * This destructor overrides Tizen::Base::Object::~Object().
 176          *
 177          * @since       2.0
 178          */
 179         virtual ~NfcManager(void);
 180
 181         /**
 182          * Initializes this instance of %NfcManager with the specified listener.
 183          *
 184          * @since       2.0
 185          *
 186          * @return      An error code
 187          * @param[in]   listener                The %INfcManagerEventListener instance to be added
 188          * @exception   E_SUCCESS               The method is successful.
 189          * @exception   E_UNSUPPORTED_OPERATION The device does not support the NFC feature.
 190          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 191          * @exception   E_SYSTEM                A system error has occurred.
 192          */
 193         result Construct(INfcManagerEventListener& listener);
 194
 195         /**
 196          * Activates the NFC feature of the device.
 197          *
 198          * @since       2.0
 199          * @privlevel   public
 200          * @privilege   %http://tizen.org/privilege/nfc.admin
 201          *
 202          * @return      An error code
 203          * @exception   E_SUCCESS               The method is successful.
 204          * @exception   E_IN_PROGRESS           The activation process is in progress.
 205          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 206          *                                      operation. @n
 207          *                                      For example, the NFC feature is already activated.
 208          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 209          * @exception   E_SYSTEM                A system error has occurred.
 210          * @see         INfcManagerEventListener::OnNfcActivated()
 211          */
 212         result Activate(void);
 213
 214         /**
 215          * Deactivates the NFC feature of the device.
 216          *
 217          * @since       2.0
 218          * @privlevel   public
 219          * @privilege   %http://tizen.org/privilege/nfc.admin
 220          *
 221          * @return      An error code
 222          * @exception   E_SUCCESS               The method is successful.
 223          * @exception   E_IN_PROGRESS           The deactivation process is in progress.
 224          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 225          *                                      operation. @n
 226          *                                      For example, the NFC feature is already deactivated.
 227          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 228          * @exception   E_SYSTEM                A system error has occurred.
 229          * @see         INfcManagerEventListener::OnNfcDeactivated()
 230          */
 231         result Deactivate(void);
 232
 233         /**
 234          * Checks whether the NFC feature is activated.
 235          *
 236          * @since       2.0
 237          *
 238          * @return      @c true if the NFC feature is activated, @n
 239          *              else @c false
 240          */
 241         bool IsActivated(void) const;
 242
 243         /**
 244          * Checks whether the NFC tag is currently connected with the device.
 245          *
 246          * @since       2.0
 247          *
 248          * @return      @c true if the NFC tag is currently connected, @n
 249          *              else @c false
 250          */
 251         bool IsTagConnected(void) const;
 252
 253         /**
 254          * Gets the tag connection with the currently detected tag.
 255          *
 256          * @since       2.0
 257          * @privlevel   public
 258          * @privilege   %http://tizen.org/privilege/nfc.tag
 259          *
 260          * @return      The tag connection with the currently detected tag, @n
 261          *              else @c null if no tag is connected or if the connection fails
 262          * @exception   E_SUCCESS               The method is successful.
 263          * @exception   E_INVALID_STATE         This instance is in an invalid state. @n
 264          *                                      For example, this instance has not been constructed as yet or the NFC
 265          *                                      feature is not activated.
 266          * @exception   E_CONNECTION_FAILED     The connection to the tag is closed or has failed.
 267          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 268          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 269          * @exception   E_SYSTEM                A system error has occurred.
 270          * @remarks     The NdefTagConnection class can inherit the TagConnection class if the currently detected tag
 271          *              supports the NDEF operations. To check whether the TagConnection class is inherited, use the
 272          *              TagConnection::IsNdefConnection() method.
 273          *              The specific error code can be accessed using the GetLastResult() method.
 274          */
 275         TagConnection* GetCurrentTagConnectionN(void) const;
 276
 277         /**
 278          * Adds the specified %INfcTagDiscoveryEventListener instance for the tag events with the specified tag type.
 279          *
 280          * @since       2.0
 281          * @privlevel   public
 282          * @privilege   %http://tizen.org/privilege/nfc.tag
 283          *
 284          * @return      An error code
 285          * @param[in]   listener                The listener to be added
 286          * @param[in]   type                    The tag type for which the listener is added
 287          * @exception   E_SUCCESS               The method is successful.
 288          * @exception   E_OBJ_ALREADY_EXIST     The listener with the specified type is already added.
 289          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 290          * @exception   E_SYSTEM                A system error has occurred.
 291          * @remarks     This method can be invoked several times with different Tizen::Net::Nfc::NfcTagType values for the
 292          *              same listener instance. In this case, the listener is called if the specified type of the target
 293          *              tag matches with any one of the registered type.
 294          */
 295         result AddTagDiscoveryEventListener(INfcTagDiscoveryEventListener& listener, NfcTagType type);
 296
 297         /**
 298          * Removes the specified %INfcTagDiscoveryEventListener instance. @n
 299          * The removed listener cannot listen to the events that are fired.
 300          *
 301          * @since       2.0
 302          * @privlevel   public
 303          * @privilege   %http://tizen.org/privilege/nfc.tag
 304          *
 305          * @return      An error code
 306          * @param[in]   listener                The listener to be removed
 307          * @param[in]   type                    The tag type for which the listener is removed
 308          * @exception   E_SUCCESS               The method is successful.
 309          * @exception   E_OBJ_NOT_FOUND         The listener with the specified type is not found.
 310          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 311          * @exception   E_SYSTEM                A system error has occurred.
 312          */
 313         result RemoveTagDiscoveryEventListener(INfcTagDiscoveryEventListener& listener, NfcTagType type);
 314
 315         /**
 316          * Adds the specified %INdefMessageDiscoveryEventListener instance for the events related to an NDEF message that
 317          * includes the NDEF record with the specified type.
 318          *
 319          * @since       2.0
 320          * @privlevel   public
 321          * @privilege   %http://tizen.org/privilege/nfc.common
 322          *
 323          * @return      An error code
 324          * @param[in]   listener                The listener to be added
 325          * @param[in]   type                    The type of the NDEF record for which the listener is added
 326          * @exception   E_SUCCESS               The method is successful.
 327          * @exception   E_INVALID_ARG           The specified @c type is invalid. @n
 328          *                                      For example, the name of the record type is an empty string if the name
 329          *                                      format is NDEF_TNF_WELL_KNOWN, NDEF_TNF_MIME_MEDIA, NDEF_TNF_ABSOLUTE_URI,
 330          *                                      or NDEF_TNF_EXTERNAL.
 331          * @exception   E_OBJ_ALREADY_EXIST     The listener with the specified type is already added.
 332          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 333          * @exception   E_SYSTEM                A system error has occurred.
 334          * @remarks     This method can be invoked several times with different NdefRecordType values for the same listener
 335          *              instance. In this case, the listener is called if the record type in the detected NDEF records
 336          *              matches with one of the registered types.
 337          *              In case of the MIME %Media type as Type Name Format (TNF), asterisks can be used in the type name
 338          *              for wildcard matching, such as @htmlonly "image&#47;*" @endhtmlonly.
 339          */
 340         result AddNdefMessageDiscoveryEventListener(INdefMessageDiscoveryEventListener& listener, const NdefRecordType& type);
 341
 342         /**
 343          * Removes the specified %INdefMessageDiscoveryEventListener instance. @n
 344          * The removed listener cannot listen to the events that are fired.
 345          *
 346          * @since       2.0
 347          * @privlevel   public
 348          * @privilege   %http://tizen.org/privilege/nfc.common
 349          *
 350          * @return      An error code
 351          * @param[in]   listener                The listener to be removed
 352          * @param[in]   type                    The type of the NDEF record for which the listener is removed
 353          * @exception   E_SUCCESS               The method is successful.
 354          * @exception   E_INVALID_ARG           The specified @c type is invalid. @n
 355          *                                      For example, the name of the record type is an empty string if the name
 356          *                                      format is NDEF_TNF_WELL_KNOWN, NDEF_TNF_MIME_MEDIA, NDEF_TNF_ABSOLUTE_URI,
 357          *                                      or NDEF_TNF_EXTERNAL.
 358          * @exception   E_OBJ_NOT_FOUND         The listener with the specified type is not found.
 359          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 360          * @exception   E_SYSTEM                A system error has occurred.
 361          */
 362         result RemoveNdefMessageDiscoveryEventListener(INdefMessageDiscoveryEventListener& listener, const NdefRecordType& type);
 363
 364         /**
 365          * Adds the specified %INfcDeviceDiscoveryEventListener instance for the device discovery events.
 366          *
 367          * @since       2.0
 368          * @privlevel   public
 369          * @privilege   %http://tizen.org/privilege/nfc.p2p
 370          *
 371          * @return      An error code
 372          * @param[in]   listener                The listener to be added
 373          * @exception   E_SUCCESS               The method is successful.
 374          * @exception   E_OBJ_ALREADY_EXIST     The listener was already added.
 375          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 376          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 377          * @exception   E_SYSTEM                A system error has occurred.
 378          */
 379         result AddDeviceDiscoveryEventListener(INfcDeviceDiscoveryEventListener& listener);
 380
 381         /**
 382          * Removes the specified %INfcDeviceDiscoveryEventListener instance. @n
 383          * The removed listener cannot listen to the events that are fired.
 384          *
 385          * @since       2.0
 386          * @privlevel   public
 387          * @privilege   %http://tizen.org/privilege/nfc.p2p
 388          *
 389          * @return      An error code
 390          * @param[in]   listener                The listener to be removed
 391          * @exception   E_SUCCESS               The method is successful.
 392          * @exception   E_OBJ_NOT_FOUND         The listener was not found.
 393          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 394          * @exception   E_SYSTEM                A system error has occurred.
 395          */
 396         result RemoveDeviceDiscoveryEventListener(INfcDeviceDiscoveryEventListener& listener);
 397
 398         /**
 399          * Checks whether peer device has been detected.
 400          *
 401          * @since       2.0
 402          *
 403          * @return      @c true if peer device has been detected, @n
 404          *              else @c false
 405          */
 406         bool IsDeviceDetected(void) const;
 407
 408
 409         /**
 410          * Gets the NDEF message cached when the tag is detected.
 411          *
 412          * @since       2.0
 413          * @privlevel   public
 414          * @privilege   %http://tizen.org/privilege/nfc.common
 415          *
 416          * @return      The cached %NdefMessage instance, @n
 417          *              else @c null if the method is not successful
 418          * @exception   E_SUCCESS               The method is successful.
 419          * @exception   E_UNSUPPORTED_OPERATION The device does not support the NFC feature..
 420          * @exception   E_ILLEGAL_ACCESS        This operation is not allowed because the application is not launched by
 421          *                                      Conditional %App Launch.
 422          * @exception   E_INVALID_FORMAT        The cached data cannot be converted to the NDEF message.
 423          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 424          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 425          * @exception   E_SYSTEM                A system error has occurred.
 426          * @remarks     This method is available only to the application that is launched by Conditional %App Launch until
 427          *              the application is terminated or another tag is detected.
 428          *              The input NdefMessage instance should be deleted by the application after it is used, even outside
 429          *              this method. The NdefMessage::RemoveAllRecords() method should be called with @c true as the input
 430          *              value immediately before the NdefMessage instance is deleted.
 431          *              The specific error code can be accessed using the GetLastResult() method.
 432          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/conditional_nfc_app_launch.htm">
 433          *              The Conditional NFC App Launch guide</a>
 434          * @see         Tizen::App::AppManager::RegisterAppLaunch
 435          */
 436         static NdefMessage* GetCachedNdefMessageN(void);
 437
 438         /**
 439          * Enables or disables the Conditional NFC %App Launch pop-up. @n
 440          * The pop-up includes all kinds of UI components that the system raises about NFC as well as a pop-up for
 441          * selecting the launching application when a tag is detected.
 442          *
 443          * @since       2.0
 444          * @privlevel   public
 445          * @privilege   %http://tizen.org/privilege/nfc.common
 446          *
 447          * @return      An error code
 448          * @param[in]   enable                  Set to @c true to enable the Conditional NFC %App Launch pop-up, @n
 449          *                                      else @c false
 450          * @exception   E_SUCCESS               The method is successful.
 451          * @exception   E_UNSUPPORTED_OPERATION The device does not support the NFC feature.
 452          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 453          * @exception   E_SYSTEM                A system error has occurred.
 454          * @remarks     Note that this method is used to enable or disable the launch pop-up when the application is in the
 455          *              foreground. Although the application disables the launch pop-up by invoking this method, it is
 456          *              automatically enabled when the application goes to the background. The launch pop-up is enabled by
 457          *              default.
 458          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/conditional_nfc_app_launch.htm">
 459          *              The Conditional NFC App Launch guide</a>
 460          */
 461         static result SetLaunchPopupEnabled(bool enable);
 462
 463 private:
 464         //
 465         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying
 466         // of objects.
 467         //
 468         NfcManager(const NfcManager& value);
 469
 470         //
 471         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit
 472         // copying of objects.
 473         //
 474         NfcManager& operator =(const NfcManager& value);
 475
 476 private:
 477         _NfcManagerImpl* __pImpl;
 478
 479         friend class _NfcManagerImpl;
 480 }; // NfcManager
 481
 482 } } } // Tizen::Net::Nfc
 483
 484 #endif // _FNET_NFC_NFC_MANAGER_H_