inc/FNetNfcNdefPushManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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    FNetNfcNdefPushManager.h
  19  * @brief   This is the header file for the %NdefPushManager class.
  20  *
  21  * This header file contains the declarations of the %NdefPushManager class.
  22  */
  23 #ifndef _FNET_NFC_NDEF_PUSH_MANAGER_H_
  24 #define _FNET_NFC_NDEF_PUSH_MANAGER_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FBaseResult.h>
  28 #include <FAppTypes.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32 class String;
  33 } }
  34
  35 namespace Tizen { namespace Base { namespace Collection
  36 {
  37 class IMap;
  38 }
  39 } }
  40
  41 namespace Tizen { namespace Net { namespace Nfc
  42 {
  43
  44 class INdefPushManagerListener;
  45 class NdefMessage;
  46 class _NdefPushManagerImpl;
  47
  48 /**
  49  * @class    NdefPushManager
  50  * @brief    This is the class for pushing an NDEF message to a device.
  51  *
  52  * @since    2.0
  53  *
  54  * @final    This class is not intended for extension.
  55  *
  56  * The %NdefPushManager class is the class for pushing an NDEF message to a device.
  57  *
  58  * For more information on the class features, see
  59  * <a href="../org.tizen.native.appprogramming/html/guide/net/nfc.htm">NFC Guide</a>.
  60  *
  61  */
  62 class _OSP_EXPORT_ NdefPushManager
  63         : public Tizen::Base::Object
  64 {
  65 public:
  66         /**
  67          * This is the default constructor for this class.
  68          *
  69          * @since       2.0
  70          */
  71         NdefPushManager(void);
  72
  73         /**
  74          * This destructor overrides Object::~Object().
  75          *
  76          * @since       2.0
  77          */
  78         ~NdefPushManager(void);
  79
  80         /**
  81          * Sets a listener for receiving the result of pushing an NDEF message.
  82          *
  83          * @since       2.0
  84          * @privlevel   public
  85          * @privilege   %http://tizen.org/privilege/nfc.p2p
  86          * @feature     %http://tizen.org/feature/network.nfc
  87          *
  88          * @return      An error code
  89          * @param[in]   pListener               An instance of %INdefPushManagerListener. @n
  90          *                                      If it is null, it will reset the listener.
  91          * @exception   E_SUCCESS               The method is successful.
  92          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  93          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
  94          *                                      For more information, see
  95          *                                      <a href=”../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm”>
  96          *                                      Application Filtering</a>.
  97          * @exception   E_OPERATION_FAILED      The operation has failed.
  98          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
  99          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
 100          *              methods.
 101          */
 102         result SetNdefPushManagerListener(INdefPushManagerListener* pListener);
 103
 104         /**
 105          * Pushes the NDEF message.
 106          *
 107          * @since       2.0
 108          * @privlevel   public
 109          * @privilege   %http://tizen.org/privilege/nfc.p2p
 110          * @feature     %http://tizen.org/feature/network.nfc
 111          *
 112          * @return      An error code
 113          * @param[in]   message                 The NDEF message to send
 114          * @exception   E_SUCCESS               The method is successful.
 115          * @exception   E_DEVICE_BUSY           The device is processing preceding job.
 116          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 117          * @exception   E_INVALID_STATE         This instance is in an invalid state. @n
 118          *                                      For example, the NFC feature is not activated or a peer device is not
 119          *                                      attached.
 120          * @exception   E_INVALID_ARG           The input @c message is invalid. @n
 121          *                                      For example, it does not contain any NDEF records.
 122          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 123          *                                      For more information, see
 124          *                                      <a href=”../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm”>
 125          *                                      Application Filtering</a>.
 126          * @exception   E_OPERATION_FAILED      The operation has failed.
 127          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 128          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
 129          *              methods.
 130          */
 131         result Push(const NdefMessage& message);
 132
 133         /**
 134          * Activates the Reserved Push feature that sends the preselected NDEF message to the connected NFC peer device on
 135          * behalf of the application.
 136          *
 137          * @since       2.1
 138          * @privlevel   platform
 139          * @privilege   %http://tizen.org/privilege/nfcmanager
 140          * @feature     %http://tizen.org/feature/network.nfc and %http://tizen.org/feature/network.nfc.reserved_push @n
 141          *              Both the features are required.
 142          *
 143          * @return      An error code
 144          * @exception   E_SUCCESS               The method is successful.
 145          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 146          *                                      operation. @n
 147          *                                      For example, Reserved Push is already activated.
 148          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 149          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 150          *                                      For more information, see
 151          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 152          *                                      Application Filtering</a>.
 153          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 154          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/nfc_reserved_push.htm">
 155          *              The NFC Reserved Push guide</a>
 156          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
 157          *              methods.
 158          */
 159         result ActivateReservedPush(void);
 160
 161         /**
 162          * Deactivates the Reserved Push feature that sends the preselected NDEF message to the connected NFC peer device on
 163          * behalf of the application.
 164          *
 165          * @since       2.1
 166          * @privlevel   platform
 167          * @privilege   %http://tizen.org/privilege/nfcmanager
 168          * @feature     %http://tizen.org/feature/network.nfc and %http://tizen.org/feature/network.nfc.reserved_push @n
 169          *              Both the features are required.
 170          *
 171          * @return      An error code
 172          * @exception   E_SUCCESS               The method is successful.
 173          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 174          *                                      operation. @n
 175          *                                      For example, Reserved Push is already deactivated.
 176          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 177          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 178          *                                      For more information, see
 179          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 180          *                                      Application Filtering</a>.
 181          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 182          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/nfc_reserved_push.htm">
 183          *              The NFC Reserved Push guide</a>
 184          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
 185          *              methods.
 186          */
 187         result DeactivateReservedPush(void);
 188
 189         /**
 190          * Checks whether the Reserved Push feature is activated.
 191          *
 192          * @since       2.1
 193          *
 194          * @return      @c true if Reserved Push is activated, @n
 195          *              else @c false
 196          */
 197         bool IsReservedPushActivated(void) const;
 198
 199         /**
 200          * Gets information of all the Reserved Push candidates. @n Each element of the result Tizen::Base::Collection::IMap consists of the package ID
 201          * of the application that registered the NDEF message and the description about the registered NDEF message.
 202          *
 203          * @since       2.1
 204          *
 205          * @return      An IMapT containing the pairs of package ID and message description if successful, @n
 206          *              else @c null
 207          * @remarks     The key of the returned Tizen::Base::Collection::IMap should be casted to Tizen::App::PackageId pointer and the value should
 208          *              be casted to Tizen::Base::String pointer.
 209          */
 210         Tizen::Base::Collection::IMap* GetReservedPushCandidatesN(void) const;
 211
 212         /**
 213          * Picks out an NDEF message among all the Reserved Push candidates by the application ID. @n The selected NDEF message is
 214          * pushed when a peer device is detected.
 215          *
 216          * @since       2.1
 217          * @privlevel   platform
 218          * @privilege   %http://tizen.org/privilege/nfcmanager
 219          * @feature     %http://tizen.org/feature/network.nfc and %http://tizen.org/feature/network.nfc.reserved_push @n
 220          *              Both the features are required.
 221          *
 222          * @return      An error code
 223          * @param[in]   packageId               The package ID of the application that registered the NDEF message to push
 224          * @exception   E_SUCCESS               The method is successful.
 225          * @exception   E_OBJ_NOT_FOUND         The specified @c packageId is not found in the Reserved Push candidate list.
 226          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 227          *                                      For more information, see
 228          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 229          *                                      Application Filtering</a>.
 230          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 231          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 232          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/nfc_reserved_push.htm">
 233          *              The NFC Reserved Push guide</a>
 234          * @remarks
 235          *              - The only one message can be selected to push. So the previously selected message will be replaced
 236          *                by the new one.
 237          *              - Before calling this method, check whether the feature is supported by
 238          *                %Tizen::System::SystemInfo::GetValue() methods.
 239          */
 240         result PickReservedPushMessage(const Tizen::App::PackageId& packageId);
 241
 242         /**
 243          * Gets the owner application ID of the picked NDEF message among all the Reserved Push candidates.
 244          *
 245          * @since       2.1
 246          * @feature     %http://tizen.org/feature/network.nfc and %http://tizen.org/feature/network.nfc.reserved_push @n
 247          *              Both the features are required.
 248          *
 249          * @return      The package ID of the application which is the owner of the picked Reserved Push message @n
 250          *              else an empty string if an error occurs
 251          * @exception   E_SUCCESS               The method is successful.
 252          * @exception   E_OBJ_NOT_FOUND         There is no element in the Reserved Push candidate list.
 253          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 254          *                                      For more information, see
 255          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 256          *                                      Application Filtering</a>.
 257          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 258          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/nfc_reserved_push.htm">
 259          *              The NFC Reserved Push guide</a>
 260          * @remarks
 261          *              - The specific error code can be accessed using the GetLastResult() method.
 262          *              - Before calling this method, check whether the feature is supported by
 263          *                %Tizen::System::SystemInfo::GetValue() methods.
 264          */
 265         Tizen::App::PackageId GetPickedReservedPushMessage(void) const;
 266
 267         /**
 268          * Registers an NDEF message as a Reserved Push candidate. @n
 269          * If the message is picked out among the candidates, it is pushed to the detected peer device when the home screen
 270          * or the main menu is on top of the screen in the local device.
 271          *
 272          * @since       2.0
 273          * @privlevel   public
 274          * @privilege   %http://tizen.org/privilege/nfc.p2p
 275          * @feature     %http://tizen.org/feature/network.nfc and %http://tizen.org/feature/network.nfc.reserved_push @n
 276          *              Both the features are required.
 277          *
 278          * @return      An error code
 279          * @param[in]   message                 The NDEF message to register
 280          * @param[in]   description             The description for the NDEF message to register @n
 281          *                                      This description can be used in Reserved Push UI, for example, UI for
 282          *                                      getting user consent to send the registered message.
 283          * @exception   E_SUCCESS               The method is successful.
 284          * @exception   E_INVALID_ARG           The input @c message is invalid. @n
 285          *                                      For example, it does not contain any NDEF records.
 286          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 287          *                                      For more information, see
 288          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 289          *                                      Application Filtering</a>.
 290          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 291          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 292          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/nfc_reserved_push.htm">
 293          *              The NFC Reserved Push guide</a>
 294          * @remarks
 295          *              - An application can register only one NDEF message. So the previously registered message will be
 296          *                replaced by the new one.
 297          *              - The registered NDEF message is pushed only if it is selected by the user through the Setting
 298          *                application.
 299          *              - Before calling this method, check whether the feature is supported by
 300          *                %Tizen::System::SystemInfo::GetValue() methods.
 301          */
 302         static result RegisterNdefPushMessage(const NdefMessage& message, const Tizen::Base::String& description);
 303
 304         /**
 305          * Unregisters an NDEF message from the Reserved Push candidates.
 306          *
 307          * @since       2.0
 308          * @privlevel   public
 309          * @privilege   %http://tizen.org/privilege/nfc.p2p
 310          * @feature     %http://tizen.org/feature/network.nfc and %http://tizen.org/feature/network.nfc.reserved_push @n
 311          *              Both the features are required.
 312          *
 313          * @return      An error code
 314          * @exception   E_SUCCESS               The method is successful.
 315          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
 316          *                                      For more information, see
 317          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 318          *                                      Application Filtering</a>.
 319          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 320          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 321          * @see         <a href="../org.tizen.native.appprogramming/html/guide/net/nfc_reserved_push.htm">
 322          *              The NFC Reserved Push guide</a>
 323          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
 324          *              methods.
 325          */
 326         static result UnregisterNdefPushMessage(void);
 327
 328 private:
 329         //
 330         // The implementation of this copy constructor is intentionally blank to prohibit copying of objects.
 331         //
 332         NdefPushManager(const NdefPushManager& value);
 333
 334         //
 335         // The implementation of this copy assignment operator is intentionally blank to prohibit copying of objects.
 336         //
 337         NdefPushManager& operator =(const NdefPushManager& value);
 338
 339 private:
 340         _NdefPushManagerImpl* __pImpl;
 341
 342         friend class _NdefPushManagerImpl;
 343 }; // NdefPushManager
 344
 345 } } } // Tizen::Net::Nfc
 346
 347 #endif // _FNET_NFC_NDEF_PUSH_MANAGER_H_