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
17namespace chromeos {
18
19class NfcDeviceClient;
20class NfcTagClient;
21
22// NfcRecordClient is used to communicate with objects representing NDEF
23// records that are stored in remote NFC tags and devices.
24class 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_
144