chromeos/dbus/nfc_record_client.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROMEOS_DBUS_NFC_RECORD_CLIENT_H_
   6 #define CHROMEOS_DBUS_NFC_RECORD_CLIENT_H_
   7
   8 #include <string>
   9
  10 #include "chromeos/chromeos_export.h"
  11 #include "chromeos/dbus/dbus_client.h"
  12 #include "chromeos/dbus/nfc_property_set.h"
  13 #include "dbus/object_path.h"
  14 #include "dbus/object_proxy.h"
  15 #include "dbus/property.h"
  16
  17 namespace chromeos {
  18
  19 class NfcDeviceClient;
  20 class NfcTagClient;
  21
  22 // NfcRecordClient is used to communicate with objects representing NDEF
  23 // records that are stored in remote NFC tags and devices.
  24 class CHROMEOS_EXPORT NfcRecordClient : public DBusClient {
  25  public:
  26   // Structure of properties associated with an NFC record.
  27   struct Properties : public NfcPropertySet {
  28     // The NDEF record type.  Possible values are "SmartPoster", "Text", "URI",
  29     // "HandoverRequest", "HandoverSelect", "HandoverCarrier". Read-only.
  30     dbus::Property<std::string> type;
  31
  32     // The character encoding. Possible values are "UTF-8" or "UTF-16".
  33     // This property is only valid for Text and SmartPoster's title records.
  34     // Read-only.
  35     dbus::Property<std::string> encoding;
  36
  37     // The ISO/IANA language code (For example "en" or "jp"). This property is
  38     // only valid for Text and SmartPoster's title records.
  39     dbus::Property<std::string> language;
  40
  41     // The human readable representation of a text or title record.
  42     // This property is only valid for Text and SmartPoster's title records.
  43     // Read-only.
  44     dbus::Property<std::string> representation;
  45
  46     // The record URI (for example https://nfc-forum.org). This is the complete
  47     // URI, including the scheme and the resource. This property is only valid
  48     // for SmartPoster's URI type records.
  49     // Read-only.
  50     dbus::Property<std::string> uri;
  51
  52     // The URI object MIME type. This is a description of the MIME type of the
  53     // object the URI points at. This is not a mandatory field and is only
  54     // valid for SmartPosters carrying a URI record.
  55     // Read-only.
  56     dbus::Property<std::string> mime_type;
  57
  58     // The URI object size. This is the size of the object the URI points at.
  59     // It should be used by applications to decide if they can afford to fetch
  60     // the object or not. This is not a mandatory field and is only valid for
  61     // Smart Posters carrying a URI record.
  62     // Read-only.
  63     dbus::Property<uint32> size;
  64
  65     // The suggested course of action. This one is only valid for Smart Posters
  66     // and is a suggestion only. It can be ignored, and the possible values are
  67     // "Do" (for example launch the browser), "Save" (for example save the URI
  68     // in the bookmarks folder), or "Edit" (for example open the URI in an URI
  69     // editor for the user to modify it).
  70     dbus::Property<std::string> action;
  71
  72     Properties(dbus::ObjectProxy* object_proxy,
  73                const PropertyChangedCallback& callback);
  74     virtual ~Properties();
  75   };
  76
  77   // Interface for observing changes from a remote NFC NDEF record.
  78   class Observer {
  79    public:
  80     virtual ~Observer() {}
  81
  82     // Called when a remote NFC record with the object path |object_path| is
  83     // added to the set of known records.
  84     virtual void RecordAdded(const dbus::ObjectPath& object_path) {}
  85
  86     // Called when a remote NFC record with the object path |object_path| is
  87     // removed from the set of known records.
  88     virtual void RecordRemoved(const dbus::ObjectPath& object_path) {}
  89
  90     // Called when the record property with the name |property_name| on record
  91     // with object path |object_path| has acquired a new value.
  92     virtual void RecordPropertyChanged(const dbus::ObjectPath& object_path,
  93                                        const std::string& property_name) {}
  94
  95     // Called when all properties for the record with object path |object_path|
  96     // have been received. This method will be called after
  97     // Observer::RecordPropertyChanged has been called for all properties that
  98     // were received through the initial property fetch that is done when the
  99     // object proxy is first created or after a call to
 100     // dbus::PropertySet::GetAll Observers can use this method to be notified
 101     // when all existing properties of a record are available for use.
 102     virtual void RecordPropertiesReceived(
 103         const dbus::ObjectPath& object_path) {}
 104   };
 105
 106   virtual ~NfcRecordClient();
 107
 108   // Adds and removes observers for events on all remote NFC records. Check the
 109   // |object_path| parameter of observer methods to determine which record is
 110   // issuing the event.
 111   virtual void AddObserver(Observer* observer) = 0;
 112   virtual void RemoveObserver(Observer* observer) = 0;
 113
 114   // Returns the list of record object paths associated with the given device
 115   // identified by the D-Bus object path |device_path|.
 116   virtual std::vector<dbus::ObjectPath> GetRecordsForDevice(
 117       const dbus::ObjectPath& device_path) = 0;
 118
 119   // Returns the list of record object paths associated with the given tag
 120   // identified by the D-Bus object path |tag_path|.
 121   virtual std::vector<dbus::ObjectPath> GetRecordsForTag(
 122       const dbus::ObjectPath& tag_path) = 0;
 123
 124   // Obtain the properties for the NFC record with object path |object_path|;
 125   // any values should be copied if needed.
 126   virtual Properties* GetProperties(const dbus::ObjectPath& object_path) = 0;
 127
 128   // Creates the instance.
 129   static NfcRecordClient* Create(NfcDeviceClient* device_client,
 130                                  NfcTagClient* tag_client);
 131
 132  protected:
 133   friend class NfcClientTest;
 134
 135   NfcRecordClient();
 136
 137  private:
 138   DISALLOW_COPY_AND_ASSIGN(NfcRecordClient);
 139 };
 140
 141 }  // namespace chromeos
 142
 143 #endif  // CHROMEOS_DBUS_NFC_RECORD_CLIENT_H_