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
  50  * NFC feature of the device and the mechanism for establishing a connection with the detected tag. It is also used to
  51  * detect the NFC 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 @c listener.
 183          *
 184          * @since       2.0
 185          * @feature     %http://tizen.org/feature/network.nfc
 186          *
 187          * @return      An error code
 188          * @param[in]   listener                The INfcManagerEventListener instance to add
 189          * @exception   E_SUCCESS               The method is successful.
 190          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 191          *                                      For more information, see
 192          *                                      <a href=”../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm”>
 193          *                                      Application Filtering</a>.
 194          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 195          * @exception   E_SYSTEM                A system error has occurred.
 196          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
 197          *              methods.
 198          */
 199         result Construct(INfcManagerEventListener& listener);
 200
 201         /**
 202          * Activates the NFC feature of the device.
 203          *
 204          * @since       2.0
 205          * @privlevel   public
 206          * @privilege   %http://tizen.org/privilege/nfc.admin
 207          *
 208          * @return      An error code
 209          * @exception   E_SUCCESS               The method is successful.
 210          * @exception   E_IN_PROGRESS           The activation process is in progress.
 211          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 212          *                                      operation. @n
 213          *                                      For example, the NFC feature is already activated.
 214          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 215          * @exception   E_SYSTEM                A system error has occurred.
 216          * @see         INfcManagerEventListener::OnNfcActivated()
 217          */
 218         result Activate(void);
 219
 220         /**
 221          * Deactivates the NFC feature of the device.
 222          *
 223          * @since       2.0
 224          * @privlevel   public
 225          * @privilege   %http://tizen.org/privilege/nfc.admin
 226          *
 227          * @return      An error code
 228          * @exception   E_SUCCESS               The method is successful.
 229          * @exception   E_IN_PROGRESS           The deactivation process is in progress.
 230          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 231          *                                      operation. @n
 232          *                                      For example, the NFC feature is already deactivated.
 233          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 234          * @exception   E_SYSTEM                A system error has occurred.
 235          * @see         INfcManagerEventListener::OnNfcDeactivated()
 236          */
 237         result Deactivate(void);
 238
 239         /**
 240          * Checks whether the NFC feature is activated.
 241          *
 242          * @since       2.0
 243          *
 244          * @return      @c true if the NFC feature is activated, @n
 245          *              else @c false
 246          */
 247         bool IsActivated(void) const;
 248
 249         /**
 250          * Checks whether the NFC tag is currently connected with the device.
 251          *
 252          * @since       2.0
 253          *
 254          * @return      @c true if the NFC tag is currently connected, @n
 255          *              else @c false
 256          */
 257         bool IsTagConnected(void) const;
 258
 259         /**
 260          * Gets the tag connection with the currently detected tag.
 261          *
 262          * @since       2.0
 263          * @privlevel   public
 264          * @privilege   %http://tizen.org/privilege/nfc.tag
 265          *
 266          * @return      The tag connection with the currently detected tag, @n
 267          *              else @c null if no tag is connected or if the connection fails
 268          * @exception   E_SUCCESS               The method is successful.
 269          * @exception   E_INVALID_STATE         This instance is in an invalid state. @n
 270          *                                      For example, this instance has not been constructed as yet or the NFC
 271          *                                      feature is not activated.
 272          * @exception   E_CONNECTION_FAILED     The connection to the tag is closed or has failed.
 273          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 274          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 275          * @exception   E_SYSTEM                A system error has occurred.
 276          * @remarks
 277          *              - The NdefTagConnection class can inherit the TagConnection class if the currently detected tag
 278          *                supports the NDEF operations. To check whether the %TagConnection class is inherited, use the
 279          *                TagConnection::IsNdefConnection() method.
 280          *              - The specific error code can be accessed using the GetLastResult() method.
 281          */
 282         TagConnection* GetCurrentTagConnectionN(void) const;
 283
 284         /**
 285          * Adds the specified %INfcTagDiscoveryEventListener instance for the tag events with the specified tag type.
 286          *
 287          * @since       2.0
 288          * @privlevel   public
 289          * @privilege   %http://tizen.org/privilege/nfc.tag
 290          *
 291          * @return      An error code
 292          * @param[in]   listener                The listener to add
 293          * @param[in]   type                    The tag type for which the listener is added
 294          * @exception   E_SUCCESS               The method is successful.
 295          * @exception   E_OBJ_ALREADY_EXIST     The listener with the specified type is already added.
 296          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 297          * @exception   E_SYSTEM                A system error has occurred.
 298          * @remarks     This method can be invoked several times with different Tizen::Net::Nfc::NfcTagType values for the
 299          *              same listener instance. In this case, the listener is called if the specified type of the target
 300          *              tag matches with any one of the registered type.
 301          */
 302         result AddTagDiscoveryEventListener(INfcTagDiscoveryEventListener& listener, NfcTagType type);
 303
 304         /**
 305          * Removes the specified %INfcTagDiscoveryEventListener instance. @n
 306          * The removed listener cannot listen to the events that are fired.
 307          *
 308          * @since       2.0
 309          * @privlevel   public
 310          * @privilege   %http://tizen.org/privilege/nfc.tag
 311          *
 312          * @return      An error code
 313          * @param[in]   listener                The listener to remove
 314          * @param[in]   type                    The tag type for which the listener is removed
 315          * @exception   E_SUCCESS               The method is successful.
 316          * @exception   E_OBJ_NOT_FOUND         The listener with the specified type is not found.
 317          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 318          * @exception   E_SYSTEM                A system error has occurred.
 319          */
 320         result RemoveTagDiscoveryEventListener(INfcTagDiscoveryEventListener& listener, NfcTagType type);
 321
 322         /**
 323          * Adds the specified %INdefMessageDiscoveryEventListener instance for the events related to an NDEF message that
 324          * includes the NDEF record with the specified type.
 325          *
 326          * @since       2.0
 327          * @privlevel   public
 328          * @privilege   %http://tizen.org/privilege/nfc.common
 329          *
 330          * @return      An error code
 331          * @param[in]   listener                The listener to add
 332          * @param[in]   type                    The type of the NDEF record for which the listener is added
 333          * @exception   E_SUCCESS               The method is successful.
 334          * @exception   E_INVALID_ARG           The specified @c type is invalid. @n
 335          *                                      For example, the name of the record type is an empty string if the name
 336          *                                      format is NDEF_TNF_WELL_KNOWN, NDEF_TNF_MIME_MEDIA, NDEF_TNF_ABSOLUTE_URI,
 337          *                                      or NDEF_TNF_EXTERNAL.
 338          * @exception   E_OBJ_ALREADY_EXIST     The listener with the specified type is already added.
 339          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 340          * @exception   E_SYSTEM                A system error has occurred.
 341          * @remarks     - This method can be invoked several times with different NdefRecordType values for the same
 342          *                listener instance. In this case, the listener is called if the record type in the detected NDEF
 343          *                records matches with one of the registered types.
 344          *              - In case of the MIME %Media type as Type Name Format (TNF), asterisks can be used in the type name
 345          *                for wildcard matching, such as @htmlonly "image&#47;*" @endhtmlonly.
 346          */
 347         result AddNdefMessageDiscoveryEventListener(INdefMessageDiscoveryEventListener& listener, const NdefRecordType& type);
 348
 349         /**
 350          * Removes the specified %INdefMessageDiscoveryEventListener instance. @n
 351          * The removed listener cannot listen to the events that are fired.
 352          *
 353          * @since       2.0
 354          * @privlevel   public
 355          * @privilege   %http://tizen.org/privilege/nfc.common
 356          *
 357          * @return      An error code
 358          * @param[in]   listener                The listener to remove
 359          * @param[in]   type                    The type of the NDEF record for which the listener is removed
 360          * @exception   E_SUCCESS               The method is successful.
 361          * @exception   E_INVALID_ARG           The specified @c type is invalid. @n
 362          *                                      For example, the name of the record type is an empty string if the name
 363          *                                      format is NDEF_TNF_WELL_KNOWN, NDEF_TNF_MIME_MEDIA, NDEF_TNF_ABSOLUTE_URI,
 364          *                                      or NDEF_TNF_EXTERNAL.
 365          * @exception   E_OBJ_NOT_FOUND         The listener with the specified type is not found.
 366          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 367          * @exception   E_SYSTEM                A system error has occurred.
 368          */
 369         result RemoveNdefMessageDiscoveryEventListener(INdefMessageDiscoveryEventListener& listener, const NdefRecordType& type);
 370
 371         /**
 372          * Adds the specified %INfcDeviceDiscoveryEventListener instance for the device discovery events.
 373          *
 374          * @since       2.0
 375          * @privlevel   public
 376          * @privilege   %http://tizen.org/privilege/nfc.p2p
 377          *
 378          * @return      An error code
 379          * @param[in]   listener                The listener to add
 380          * @exception   E_SUCCESS               The method is successful.
 381          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
 382          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 383          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 384          * @exception   E_SYSTEM                A system error has occurred.
 385          */
 386         result AddDeviceDiscoveryEventListener(INfcDeviceDiscoveryEventListener& listener);
 387
 388         /**
 389          * Removes the specified %INfcDeviceDiscoveryEventListener instance. @n
 390          * The removed listener cannot listen to the events that are fired.
 391          *
 392          * @since       2.0
 393          * @privlevel   public
 394          * @privilege   %http://tizen.org/privilege/nfc.p2p
 395          *
 396          * @return      An error code
 397          * @param[in]   listener                The listener to remove
 398          * @exception   E_SUCCESS               The method is successful.
 399          * @exception   E_OBJ_NOT_FOUND         The listener is not found.
 400          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 401          * @exception   E_SYSTEM                A system error has occurred.
 402          */
 403         result RemoveDeviceDiscoveryEventListener(INfcDeviceDiscoveryEventListener& listener);
 404
 405         /**
 406          * Checks whether peer device has been detected.
 407          *
 408          * @since       2.0
 409          *
 410          * @return      @c true if peer device has been detected, @n
 411          *              else @c false
 412          */
 413         bool IsDeviceDetected(void) const;
 414
 415
 416         /**
 417          * Gets the NDEF message cached when the tag is detected.
 418          *
 419          * @since       2.0
 420          * @privlevel   public
 421          * @privilege   %http://tizen.org/privilege/nfc.common
 422          * @feature     %http://tizen.org/feature/network.nfc
 423          *
 424          * @return      The cached %NdefMessage instance, @n
 425          *              else @c null if the method is not successful
 426          * @exception   E_SUCCESS               The method is successful.
 427          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 428          *                                      For more information, see
 429          *                                      <a href=”../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm”>
 430          *                                      Application Filtering</a>.
 431          * @exception   E_ILLEGAL_ACCESS        This operation is not allowed because the application is not launched by
 432          *                                      Conditional %App Launch.
 433          * @exception   E_INVALID_FORMAT        The cached data cannot be converted to the NDEF message.
 434          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 435          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 436          * @exception   E_SYSTEM                A system error has occurred.
 437          * @remarks
 438          *              - This method is available only to the application that is launched by Conditional %App Launch
 439          *                until the application is terminated or another tag is detected.
 440          *              - The input NdefMessage instance should be deleted by the application after it is used, even
 441          *                outside this method. The NdefMessage::RemoveAllRecords() method should be called with @c true as
 442          *                the input value immediately before the NdefMessage instance is deleted.
 443          *              - The specific error code can be accessed using the GetLastResult() method.
 444          *              - Before calling this method, check whether the feature is supported by
 445          *                %Tizen::System::SystemInfo::GetValue() methods.
 446          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/conditional_nfc_app_launch.htm">
 447          *              The Conditional NFC App Launch guide</a>
 448          * @see         Tizen::App::AppManager::RegisterAppLaunch
 449          */
 450         static NdefMessage* GetCachedNdefMessageN(void);
 451
 452         /**
 453          * Enables or disables the Conditional NFC %App Launch pop-up. @n
 454          * The pop-up includes all kinds of UI components that the system raises about NFC as well as a pop-up for
 455          * selecting the launching application when a tag is detected.
 456          *
 457          * @since       2.0
 458          * @privlevel   public
 459          * @privilege   %http://tizen.org/privilege/nfc.common
 460          * @feature     %http://tizen.org/feature/network.nfc
 461          *
 462          * @return      An error code
 463          * @param[in]   enable                  Set to @c true to enable the Conditional NFC %App Launch pop-up, @n
 464          *                                      else @c false
 465          * @exception   E_SUCCESS               The method is successful.
 466          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 467          *                                      For more information, see
 468          *                                      <a href=”../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm”>
 469          *                                      Application Filtering</a>.
 470          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 471          * @exception   E_SYSTEM                A system error has occurred.
 472          * @remarks     - Note that this method is used to enable or disable the launch pop-up when the application is in
 473          *                the foreground. Although the application disables the launch pop-up by invoking this method, it
 474          *                is automatically enabled when the application goes to the background. The launch pop-up is
 475          *                enabled by default.
 476          *              - Before calling this method, check whether the feature is supported by
 477          *                %Tizen::System::SystemInfo::GetValue() methods.
 478          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/conditional_nfc_app_launch.htm">
 479          *              The Conditional NFC App Launch guide</a>
 480          */
 481         static result SetLaunchPopupEnabled(bool enable);
 482
 483 private:
 484         //
 485         // The implementation of this copy constructor is intentionally blank to prohibit copying of objects.
 486         //
 487         NfcManager(const NfcManager& value);
 488
 489         //
 490         // The implementation of this copy assignment operator is intentionally blank to prohibit copying of objects.
 491         //
 492         NfcManager& operator =(const NfcManager& value);
 493
 494 private:
 495         _NfcManagerImpl* __pImpl;
 496
 497         friend class _NfcManagerImpl;
 498 }; // NfcManager
 499
 500 } } } // Tizen::Net::Nfc
 501
 502 #endif // _FNET_NFC_NFC_MANAGER_H_