Uploading for backup...

net/dbus/dbus.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+//
+// D-Bus library for Chrome.
+
+#ifndef NET_DBUS_DBUS_H_
+#define NET_DBUS_DBUS_H_
+#pragma once
+
+#include <string>
+#include <vector>
+#include <dbus/dbus.h>
+
+#include "base/callback.h"
+#include "base/memory/ref_counted.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/tracked_objects.h"
+
+class MessageLoop;
+
+namespace net {
+namespace dbus {
+
+class ObjectProxy;
+
+// Bus is used to establish a connection with D-Bus, and create object
+// proxies.
+class Bus {
+ public:
+  // Specifies the bus type. SESSION is used to communicate with per-user
+  // services like GNOME applications. SYSTEM is used to communicate with
+  // system-wide services like NetworkManager.
+  enum BusType {
+    SESSION = DBUS_BUS_SESSION,
+    SYSTEM  = DBUS_BUS_SYSTEM,
+  };
+
+  // Specifies the connection type. PRIVATE should usually be used unless
+  // you are sure that SHARED is safe for you. PRIVATE gives you a private
+  // connection, that won't be shared with other Bus objects. SHARED gives
+  // you a connection shared among other Bus objects, which is unsafe if
+  // the connection is shared with multiple threads.
+  enum ConnectionType {
+    PRIVATE,
+    SHARED,
+  };
+
+  // Options used to create a Bus object.
+  struct Options {
+    Options() : bus_type(SESSION), connection_type(PRIVATE) {}
+
+    BusType bus_type;
+    ConnectionType connection_type;
+    // May add other options like timeout.
+  };
+
+  // Creates a Bus object. The actual connection will be established when
+  // Init() is called.
+  Bus(const Options& options);
+  virtual ~Bus();
+
+  // Gets the object proxy for the given service name and the object path.
+  // |service_name| looks like "org.freedesktop.NetworkManager", and
+  // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
+  //
+  // This method never returns NULL. The caller should delete the object.
+  virtual ObjectProxy* GetObjectProxy(const std::string& service_name,
+                                      const std::string& object_path);
+
+ private:
+  class IOThread;
+
+  friend class ObjectProxy;
+  DBusConnection* connection() { return connection_; }
+
+  // Initializes the bus by establishing a connection with the D-Bus.
+  // Returns true on success.
+  //
+  // This is a bit tricky but we off calling this function until when we
+  // first send a message to the D-Bus, as connecting to D-Bus is
+  // expensive(actually a blocking call), and we don't want to do this
+  // when the Bus object is created (that can be in the UI thread).
+  bool Init();
+
+  // ...
+  bool InitForAsync();
+
+  // ...
+  virtual void StartIOThreadIfNeeded();
+
+  // ...
+  virtual void PostTask(const tracked_objects::Location& from_here,
+                        const base::Closure& task);
+
+  static dbus_bool_t OnAddWatch(DBusWatch* watch, void* data);
+  static void OnRemoveWatch(DBusWatch* watch, void* data);
+  static void OnToggleWatch(DBusWatch* watch, void* data);
+
+  const BusType bus_type_;
+  const ConnectionType connection_type_;
+  DBusConnection* connection_;
+  // The thread is used for asynchronous method calls, and shared by the
+  // object proxies created from the bus.
+  scoped_ptr<IOThread> io_thread_;
+
+  DISALLOW_COPY_AND_ASSIGN(Bus);
+};
+
+class MethodCall;
+class Response;
+
+// ObjectProxy is used to communicate with remote objects, such as calling
+// methods and sending signals.
+class ObjectProxy {
+ public:
+  virtual ~ObjectProxy();
+  // Used for CallMethodAsync().
+  typedef base::Callback<void(Response*)> ResponseCallback;
+
+  // Synchronously calls the method of the remote object. This is a
+  // blocking call hence shouldn't be called from the UI thread.
+  virtual bool CallMethodSync(MethodCall* method_call,
+                              Response* response);
+
+  // Asynchronously calls the method of the remote object. |callback| will
+  // be called in message loop of the same thread that calls this
+  // function. If the method call is successful, a valid Response object
+  // will be passed to the callback, and the callback needs to delete it.
+  // If the method call is unsuccessful, NULL will be passed to the callback.
+  //
+  // This is not a blocking call (this function just posts a task to the
+  // message loop in another thread), hence it's safe to be called from
+  // the UI thread.
+  virtual void CallMethodAsync(MethodCall* method_call,
+                               ResponseCallback callback);
+
+  const std::string& service_name() const { return service_name_; }
+  const std::string& object_path() const { return object_path_; }
+
+ private:
+  // Starts the async method call.
+  void StartAsyncMethodCall(void* request_message,
+                            MessageLoop* origin_loop,
+                            ResponseCallback response_callback);
+
+  // Runs the response callback with the given response object.
+  static void RunResponseCallback(ResponseCallback response_callback,
+                                  Response* response);
+
+  // ...
+  struct OnPendingCallIsCompleteData {
+    OnPendingCallIsCompleteData(MessageLoop* in_origin_loop,
+                                ResponseCallback in_response_callback);
+    MessageLoop* origin_loop;
+    ResponseCallback response_callback;
+  };
+
+  // ...
+  static void OnPendingCallIsComplete(DBusPendingCall* pending_call,
+                                      void* user_data);
+
+  friend class Bus;
+
+  // The object proxy can only be created by Bus.
+  ObjectProxy(Bus* bus,
+              const std::string& service_name,
+              const std::string& object_path);
+
+  Bus* bus_;
+  std::string service_name_;
+  std::string object_path_;
+
+  DISALLOW_COPY_AND_ASSIGN(ObjectProxy);
+};
+
+class MessageWriter;
+class MessageReader;
+
+// Message is the base class of D-Bus message types. Client code should
+// usually use sub classes such as MethodCall and Response instead.
+class Message {
+ public:
+  // The data type used in the D-Bus message system.
+  // Redefined here so clients don't need to use raw D-Bus macros.
+  enum Type {
+    BYTE = DBUS_TYPE_BYTE,
+    BOOL = DBUS_TYPE_BOOLEAN,
+    INT16 = DBUS_TYPE_INT16,
+    UINT16 = DBUS_TYPE_UINT16,
+    INT32 = DBUS_TYPE_INT32,
+    UINT32 = DBUS_TYPE_UINT32,
+    INT64 = DBUS_TYPE_INT64,
+    UINT64 = DBUS_TYPE_UINT64,
+    DOUBLE = DBUS_TYPE_DOUBLE,
+    STRING = DBUS_TYPE_STRING,
+    OBJECT_PATH = DBUS_TYPE_OBJECT_PATH,
+    ARRAY = DBUS_TYPE_ARRAY,
+    STRUCT = DBUS_TYPE_STRUCT,
+    DICT_ENTRY = DBUS_TYPE_DICT_ENTRY,
+    VARIANT = DBUS_TYPE_VARIANT,
+  };
+
+  // Creates a Message. The internal raw message is NULL until it's set
+  // from outside by reset_raw_message().
+  Message();
+  virtual ~Message();
+
+  DBusMessage* raw_message() { return raw_message_; }
+  // Takes the ownership of raw_message.
+  void reset_raw_message(DBusMessage* raw_message);
+
+  // Returns the string representation of this message for debugging.
+  std::string ToString();
+
+ private:
+  // Helper function used in ToString().
+  std::string ToStringInternal(const std::string& indent,
+                               MessageReader* reader);
+
+  DBusMessage* raw_message_;
+  DISALLOW_COPY_AND_ASSIGN(Message);
+};
+
+// MessageCall is a type of message used for calling a method via D-Bus.
+class MethodCall : public Message {
+ public:
+  // Creates a method call message for the specified interface name and
+  // the method name.
+  //
+  // For instance, to call "Get" method of DBUS_INTERFACE_INTROSPECTABLE
+  // interface ("org.freedesktop.DBus.Introspectable"), create a method
+  // call like this:
+  //
+  //   MethodCall method_call(DBUS_INTERFACE_INTROSPECTABLE, "Get");
+  //
+  MethodCall(const std::string& interface_name,
+             const std::string& method_name);
+
+ private:
+  friend class ObjectProxy;
+
+  // Sets the service name. This will be handled by the object proxy.
+  void SetServiceName(const std::string& service_name);
+  // Sets the object path. This will be handled by the object proxy.
+  void SetObjectPath(const std::string& object_path);
+
+  DISALLOW_COPY_AND_ASSIGN(MethodCall);
+};
+
+// Response is a type of message used for receiving a response from a
+// method via D-Bus.
+class Response : public Message {
+ public:
+  Response();
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(Response);
+};
+
+// MessageWriter is used to create outgoing messages for calling methods
+// and sending signals.
+class MessageWriter {
+ public:
+  // The data will be written into the given message.
+  MessageWriter(Message* message);
+  ~MessageWriter();
+
+  // Appends a byte to the message.
+  void AppendByte(uint8 value);
+  // The following functions do the same for other basic types.
+  void AppendBool(bool value);
+  void AppendInt16(int16 value);
+  void AppendUint16(uint16 value);
+  void AppendInt32(int32 value);
+  void AppendUint32(uint32 value);
+  void AppendInt64(int64 value);
+  void AppendUint64(uint64 value);
+  void AppendDouble(double value);
+  void AppendString(const std::string& value);
+  void AppendObjectPath(const std::string& value);
+
+  // Ideally, client shouldn't need to supply the signature string, but
+  // the underlying D-Bus system requires us to supply this before
+  // appending contents to array and variant. For instance, if you want an
+  // array of strings, or a variant of a string, then you pass "s" as the
+  // signature.
+  //
+  // See the spec for details about the type signatures.
+  // http://dbus.freedesktop.org/doc/dbus-specification.html
+  // #message-protocol-signatures
+  //
+  void OpenArray(const std::string& signature, MessageWriter* sub_writer);
+  void OpenVariant(const std::string& signature, MessageWriter* sub_writer);
+  // Struct and dict entry don't need the type signature.
+  void OpenStruct(MessageWriter* sub_writer);
+  void OpenDictEntry(MessageWriter* sub_writer);
+  // ...
+  void CloseContainer(MessageWriter* sub_writer);
+
+ private:
+  Message* message_;
+  DBusMessageIter raw_message_iter_;
+
+  DISALLOW_COPY_AND_ASSIGN(MessageWriter);
+};
+
+// MessageReader is used to read incoming messages such as responses for
+// method calls.
+//
+// MessageReader manages an internal iterator to read data. All functions
+// starting with Pop advance the iterator on success.
+class MessageReader {
+ public:
+  // The data will be read from the given message.
+  MessageReader(Message* message);
+  ~MessageReader();
+
+  // Returns true if the reader has more data to read. The function is
+  // used to iterate contents in a container like:
+  //
+  //   while (reader.HasMore())
+  //     reader.PopString(&value);
+  bool HasMore();
+
+  // Gets the byte at the current iterator position. On success, advances
+  // the iterator and returns true. It's an error if the actual data type
+  // is not a byte, so false will be returned in this case.
+  bool PopByte(uint8* value);
+  // The following functions do the same for other basic types.
+  bool PopBool(bool* value);
+  bool PopInt16(int16* value);
+  bool PopUint16(uint16* value);
+  bool PopInt32(int32* value);
+  bool PopUint32(uint32* value);
+  bool PopInt64(int64* value);
+  bool PopUint64(uint64* value);
+  bool PopDouble(double* value);
+  bool PopString(std::string* value);
+  bool PopObjectPath(std::string* value);
+
+  // Sets up the given message reader to read an array at the current
+  // iterator position. On success, advances the iterator and returns
+  // true. It's an error if the actual data type is not an array, so false
+  // will be returned in this case.
+  bool PopArray(MessageReader* sub_reader);
+  // The following functions do the same for other container types.
+  bool PopStruct(MessageReader* sub_reader);
+  bool PopDictEntry(MessageReader* sub_reader);
+  bool PopVariant(MessageReader* sub_reader);
+
+  // Gets the array of bytes at the current iterator positio. On success,
+  // advances the iterator and returns true. Arrays of bytes are often
+  // used for exchanging binary blobs hence it's worth having a
+  // specialized function.
+  bool PopArrayOfBytes(std::vector<uint8>* bytes);
+
+  // Gets the array of object paths at the current iterator positio. On
+  // success, advances the iterator and returns true. Arrays of object
+  // paths are often used to communicate with D-Bus services like
+  // NetworkManager, hence it's worth having a specialized function.
+  bool PopArrayOfObjectPaths(std::vector<std::string>* object_paths);
+
+  // Gets the byte from the variant data container at the current iterator
+  // position. On success, returns true and advances the
+  // iterator. Variants are widely used in D-Bus services so it's worth
+  // having a specialized function. For instance, The return value type of
+  // "org.freedesktop.DBus.Introspectable.Get" is a variant.
+  bool PopVariantOfByte(uint8* value);
+  // The following functions do the same for other basic types.
+  bool PopVariantOfBool(bool* value);
+  bool PopVariantOfInt16(int16* value);
+  bool PopVariantOfUint16(uint16* value);
+  bool PopVariantOfInt32(int32* value);
+  bool PopVariantOfUint32(uint32* value);
+  bool PopVariantOfInt64(int64* value);
+  bool PopVariantOfUint64(uint64* value);
+  bool PopVariantOfDouble(double* value);
+  bool PopVariantOfString(std::string* value);
+  bool PopVariantOfObjectPath(std::string* value);
+
+  // Get the type of the value at the current iterator position. INVALID
+  // will be returned if the iterator points to the end of the message.
+  Message::Type GetType();
+
+ private:
+  // Returns true if the data type at the current iterator position
+  // matches the given D-Bus type, such as DBUS_TYPE_BYTE.
+  bool CheckType(int dbus_type);
+
+  // Helper function used to implement PopByte() etc.
+  bool PopBasic(int dbus_type, void *value);
+
+  // Helper function used to implement PopArray() etc.
+  bool PopContainer(int dbus_type, MessageReader* sub_reader);
+
+  // Helper function used to implement PopVariantOfByte() etc.
+  bool PopVariantOfBasic(int dbus_type, void* value);
+
+  Message* message_;
+  DBusMessageIter raw_message_iter_;
+
+  DISALLOW_COPY_AND_ASSIGN(MessageReader);
+};
+
+}  // namespace dbus
+}  // namespace net
+
+#endif  // NET_DBUS_DBUS_H_