• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (c) 2012 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 DBUS_MESSAGE_H_
6 #define DBUS_MESSAGE_H_
7 
8 #include <dbus/dbus.h>
9 #include <stddef.h>
10 #include <stdint.h>
11 
12 #include <memory>
13 #include <string>
14 #include <vector>
15 
16 #include "base/macros.h"
17 #include "dbus/dbus_export.h"
18 #include "dbus/file_descriptor.h"
19 #include "dbus/object_path.h"
20 
21 namespace google {
22 namespace protobuf {
23 
24 class MessageLite;
25 
26 }  // namespace protobuf
27 }  // namespace google
28 
29 
30 namespace dbus {
31 
32 class MessageWriter;
33 class MessageReader;
34 
35 // DBUS_TYPE_UNIX_FD was added in D-Bus version 1.4
36 #if !defined(DBUS_TYPE_UNIX_FD)
37 #define DBUS_TYPE_UNIX_FD      ((int) 'h')
38 #endif
39 
40 // Returns true if Unix FD passing is supported in libdbus.
41 // The check is done runtime rather than compile time as the libdbus
42 // version used at runtime may be different from the one used at compile time.
43 CHROME_DBUS_EXPORT bool IsDBusTypeUnixFdSupported();
44 
45 // Message is the base class of D-Bus message types. Client code must use
46 // sub classes such as MethodCall and Response instead.
47 //
48 // The class name Message is very generic, but there should be no problem
49 // as the class is inside 'dbus' namespace. We chose to name this way, as
50 // libdbus defines lots of types starting with DBus, such as
51 // DBusMessage. We should avoid confusion and conflict with these types.
52 class CHROME_DBUS_EXPORT Message {
53  public:
54   // The message type used in D-Bus.  Redefined here so client code
55   // doesn't need to use raw D-Bus macros. DBUS_MESSAGE_TYPE_INVALID
56   // etc. are #define macros. Having an enum type here makes code a bit
57   // more type-safe.
58   enum MessageType {
59     MESSAGE_INVALID = DBUS_MESSAGE_TYPE_INVALID,
60     MESSAGE_METHOD_CALL = DBUS_MESSAGE_TYPE_METHOD_CALL,
61     MESSAGE_METHOD_RETURN = DBUS_MESSAGE_TYPE_METHOD_RETURN,
62     MESSAGE_SIGNAL = DBUS_MESSAGE_TYPE_SIGNAL,
63     MESSAGE_ERROR = DBUS_MESSAGE_TYPE_ERROR,
64  };
65 
66   // The data type used in the D-Bus type system.  See the comment at
67   // MessageType for why we are redefining data types here.
68   enum DataType {
69     INVALID_DATA = DBUS_TYPE_INVALID,
70     BYTE = DBUS_TYPE_BYTE,
71     BOOL = DBUS_TYPE_BOOLEAN,
72     INT16 = DBUS_TYPE_INT16,
73     UINT16 = DBUS_TYPE_UINT16,
74     INT32 = DBUS_TYPE_INT32,
75     UINT32 = DBUS_TYPE_UINT32,
76     INT64 = DBUS_TYPE_INT64,
77     UINT64 = DBUS_TYPE_UINT64,
78     DOUBLE = DBUS_TYPE_DOUBLE,
79     STRING = DBUS_TYPE_STRING,
80     OBJECT_PATH = DBUS_TYPE_OBJECT_PATH,
81     ARRAY = DBUS_TYPE_ARRAY,
82     STRUCT = DBUS_TYPE_STRUCT,
83     DICT_ENTRY = DBUS_TYPE_DICT_ENTRY,
84     VARIANT = DBUS_TYPE_VARIANT,
85     UNIX_FD = DBUS_TYPE_UNIX_FD,
86   };
87 
88   // Returns the type of the message. Returns MESSAGE_INVALID if
89   // raw_message_ is NULL.
90   MessageType GetMessageType();
91 
92   // Returns the type of the message as string like "MESSAGE_METHOD_CALL"
93   // for instance.
94   std::string GetMessageTypeAsString();
95 
raw_message()96   DBusMessage* raw_message() { return raw_message_; }
97 
98   // Sets the destination, the path, the interface, the member, etc.
99   bool SetDestination(const std::string& destination);
100   bool SetPath(const ObjectPath& path);
101   bool SetInterface(const std::string& interface);
102   bool SetMember(const std::string& member);
103   bool SetErrorName(const std::string& error_name);
104   bool SetSender(const std::string& sender);
105   void SetSerial(uint32_t serial);
106   void SetReplySerial(uint32_t reply_serial);
107   // SetSignature() does not exist as we cannot do it.
108 
109   // Gets the destination, the path, the interface, the member, etc.
110   // If not set, an empty string is returned.
111   std::string GetDestination();
112   ObjectPath GetPath();
113   std::string GetInterface();
114   std::string GetMember();
115   std::string GetErrorName();
116   std::string GetSender();
117   std::string GetSignature();
118   // Gets the serial and reply serial numbers. Returns 0 if not set.
119   uint32_t GetSerial();
120   uint32_t GetReplySerial();
121 
122   // Returns the string representation of this message. Useful for
123   // debugging. The output is truncated as needed (ex. strings are truncated
124   // if longer than a certain limit defined in the .cc file).
125   std::string ToString();
126 
127  protected:
128   // This class cannot be instantiated. Use sub classes instead.
129   Message();
130   virtual ~Message();
131 
132   // Initializes the message with the given raw message.
133   void Init(DBusMessage* raw_message);
134 
135  private:
136   // Helper function used in ToString().
137   std::string ToStringInternal(const std::string& indent,
138                                MessageReader* reader);
139 
140   DBusMessage* raw_message_;
141   DISALLOW_COPY_AND_ASSIGN(Message);
142 };
143 
144 // MessageCall is a type of message used for calling a method via D-Bus.
145 class CHROME_DBUS_EXPORT MethodCall : public Message {
146  public:
147   // Creates a method call message for the specified interface name and
148   // the method name.
149   //
150   // For instance, to call "Get" method of DBUS_INTERFACE_INTROSPECTABLE
151   // interface ("org.freedesktop.DBus.Introspectable"), create a method
152   // call like this:
153   //
154   //   MethodCall method_call(DBUS_INTERFACE_INTROSPECTABLE, "Get");
155   //
156   // The constructor creates the internal raw message.
157   MethodCall(const std::string& interface_name,
158              const std::string& method_name);
159 
160   // Returns a newly created MethodCall from the given raw message of the
161   // type DBUS_MESSAGE_TYPE_METHOD_CALL. The caller must delete the
162   // returned object. Takes the ownership of |raw_message|.
163   static MethodCall* FromRawMessage(DBusMessage* raw_message);
164 
165  private:
166   // Creates a method call message. The internal raw message is NULL.
167   // Only used internally.
168   MethodCall();
169 
170   DISALLOW_COPY_AND_ASSIGN(MethodCall);
171 };
172 
173 // Signal is a type of message used to send a signal.
174 class CHROME_DBUS_EXPORT Signal : public Message {
175  public:
176   // Creates a signal message for the specified interface name and the
177   // method name.
178   //
179   // For instance, to send "PropertiesChanged" signal of
180   // DBUS_INTERFACE_INTROSPECTABLE interface
181   // ("org.freedesktop.DBus.Introspectable"), create a signal like this:
182   //
183   //   Signal signal(DBUS_INTERFACE_INTROSPECTABLE, "PropertiesChanged");
184   //
185   // The constructor creates the internal raw_message_.
186   Signal(const std::string& interface_name,
187          const std::string& method_name);
188 
189   // Returns a newly created SIGNAL from the given raw message of the type
190   // DBUS_MESSAGE_TYPE_SIGNAL. The caller must delete the returned
191   // object. Takes the ownership of |raw_message|.
192   static Signal* FromRawMessage(DBusMessage* raw_message);
193 
194  private:
195   // Creates a signal message. The internal raw message is NULL.
196   // Only used internally.
197   Signal();
198 
199   DISALLOW_COPY_AND_ASSIGN(Signal);
200 };
201 
202 // Response is a type of message used for receiving a response from a
203 // method via D-Bus.
204 class CHROME_DBUS_EXPORT Response : public Message {
205  public:
206   // Returns a newly created Response from the given raw message of the
207   // type DBUS_MESSAGE_TYPE_METHOD_RETURN. Takes the ownership of |raw_message|.
208   static std::unique_ptr<Response> FromRawMessage(DBusMessage* raw_message);
209 
210   // Returns a newly created Response from the given method call.
211   // Used for implementing exported methods. Does NOT take the ownership of
212   // |method_call|.
213   static std::unique_ptr<Response> FromMethodCall(MethodCall* method_call);
214 
215   // Returns a newly created Response with an empty payload.
216   // Useful for testing.
217   static std::unique_ptr<Response> CreateEmpty();
218 
219  protected:
220   // Creates a Response message. The internal raw message is NULL.
221   Response();
222 
223  private:
224   DISALLOW_COPY_AND_ASSIGN(Response);
225 };
226 
227 // ErrorResponse is a type of message used to return an error to the
228 // caller of a method.
229 class CHROME_DBUS_EXPORT ErrorResponse: public Response {
230  public:
231   // Returns a newly created Response from the given raw message of the
232   // type DBUS_MESSAGE_TYPE_METHOD_RETURN. Takes the ownership of |raw_message|.
233   static std::unique_ptr<ErrorResponse> FromRawMessage(
234       DBusMessage* raw_message);
235 
236   // Returns a newly created ErrorResponse from the given method call, the
237   // error name, and the error message.  The error name looks like
238   // "org.freedesktop.DBus.Error.Failed". Used for returning an error to a
239   // failed method call. Does NOT take the ownership of |method_call|.
240   static std::unique_ptr<ErrorResponse> FromMethodCall(
241       MethodCall* method_call,
242       const std::string& error_name,
243       const std::string& error_message);
244 
245  private:
246   // Creates an ErrorResponse message. The internal raw message is NULL.
247   ErrorResponse();
248 
249   DISALLOW_COPY_AND_ASSIGN(ErrorResponse);
250 };
251 
252 // MessageWriter is used to write outgoing messages for calling methods
253 // and sending signals.
254 //
255 // The main design goal of MessageReader and MessageWriter classes is to
256 // provide a type safe API. In the past, there was a Chrome OS blocker
257 // bug, that took days to fix, that would have been prevented if the API
258 // was type-safe.
259 //
260 // For instance, instead of doing something like:
261 //
262 //   // We shouldn't add '&' to str here, but it compiles with '&' added.
263 //   dbus_g_proxy_call(..., G_TYPE_STRING, str, G_TYPE_INVALID, ...)
264 //
265 // We want to do something like:
266 //
267 //   writer.AppendString(str);
268 //
269 class CHROME_DBUS_EXPORT MessageWriter {
270  public:
271   // Data added with Append* will be written to |message|, which may be NULL
272   // to create a sub-writer for passing to OpenArray, etc.
273   explicit MessageWriter(Message* message);
274   ~MessageWriter();
275 
276   // Appends a byte to the message.
277   void AppendByte(uint8_t value);
278   void AppendBool(bool value);
279   void AppendInt16(int16_t value);
280   void AppendUint16(uint16_t value);
281   void AppendInt32(int32_t value);
282   void AppendUint32(uint32_t value);
283   void AppendInt64(int64_t value);
284   void AppendUint64(uint64_t value);
285   void AppendDouble(double value);
286   void AppendString(const std::string& value);
287   void AppendObjectPath(const ObjectPath& value);
288   void AppendFileDescriptor(const FileDescriptor& value);
289 
290   // Opens an array. The array contents can be added to the array with
291   // |sub_writer|. The client code must close the array with
292   // CloseContainer(), once all contents are added.
293   //
294   // |signature| parameter is used to supply the D-Bus type signature of
295   // the array contents. For instance, if you want an array of strings,
296   // then you pass "s" as the signature.
297   //
298   // See the spec for details about the type signatures.
299   // http://dbus.freedesktop.org/doc/dbus-specification.html
300   // #message-protocol-signatures
301   //
302   void OpenArray(const std::string& signature, MessageWriter* sub_writer);
303   // Do the same for a variant.
304   void OpenVariant(const std::string& signature, MessageWriter* sub_writer);
305   // Do the same for Struct and dict entry. They don't need the signature.
306   void OpenStruct(MessageWriter* sub_writer);
307   void OpenDictEntry(MessageWriter* sub_writer);
308 
309   // Close the container for a array/variant/struct/dict entry.
310   void CloseContainer(MessageWriter* sub_writer);
311 
312   // Appends the array of bytes. Arrays of bytes are often used for
313   // exchanging binary blobs hence it's worth having a specialized
314   // function.
315   void AppendArrayOfBytes(const uint8_t* values, size_t length);
316 
317   // Appends the array of doubles. Used for audio mixer matrix doubles.
318   void AppendArrayOfDoubles(const double* values, size_t length);
319 
320   // Appends the array of strings. Arrays of strings are often used for
321   // exchanging lists of names hence it's worth having a specialized
322   // function.
323   void AppendArrayOfStrings(const std::vector<std::string>& strings);
324 
325   // Appends the array of object paths. Arrays of object paths are often
326   // used when exchanging object paths, hence it's worth having a
327   // specialized function.
328   void AppendArrayOfObjectPaths(const std::vector<ObjectPath>& object_paths);
329 
330   // Appends the protocol buffer as an array of bytes. The buffer is serialized
331   // into an array of bytes before communication, since protocol buffers are not
332   // a native dbus type. On the receiving size the array of bytes needs to be
333   // read and deserialized into a protocol buffer of the correct type. There are
334   // methods in MessageReader to assist in this.  Return true on succes and fail
335   // when serialization is not successful.
336   bool AppendProtoAsArrayOfBytes(const google::protobuf::MessageLite& protobuf);
337 
338   // Appends the byte wrapped in a variant data container. Variants are
339   // widely used in D-Bus services so it's worth having a specialized
340   // function. For instance, The third parameter of
341   // "org.freedesktop.DBus.Properties.Set" is a variant.
342   void AppendVariantOfByte(uint8_t value);
343   void AppendVariantOfBool(bool value);
344   void AppendVariantOfInt16(int16_t value);
345   void AppendVariantOfUint16(uint16_t value);
346   void AppendVariantOfInt32(int32_t value);
347   void AppendVariantOfUint32(uint32_t value);
348   void AppendVariantOfInt64(int64_t value);
349   void AppendVariantOfUint64(uint64_t value);
350   void AppendVariantOfDouble(double value);
351   void AppendVariantOfString(const std::string& value);
352   void AppendVariantOfObjectPath(const ObjectPath& value);
353 
354  private:
355   // Helper function used to implement AppendByte etc.
356   void AppendBasic(int dbus_type, const void* value);
357 
358   // Helper function used to implement AppendVariantOfByte() etc.
359   void AppendVariantOfBasic(int dbus_type, const void* value);
360 
361   Message* message_;
362   DBusMessageIter raw_message_iter_;
363   bool container_is_open_;
364 
365   DISALLOW_COPY_AND_ASSIGN(MessageWriter);
366 };
367 
368 // MessageReader is used to read incoming messages such as responses for
369 // method calls.
370 //
371 // MessageReader manages an internal iterator to read data. All functions
372 // starting with Pop advance the iterator on success.
373 class CHROME_DBUS_EXPORT MessageReader {
374  public:
375   // The data will be read from the given |message|, which may be NULL to
376   // create a sub-reader for passing to PopArray, etc.
377   explicit MessageReader(Message* message);
378   ~MessageReader();
379 
380   // Returns true if the reader has more data to read. The function is
381   // used to iterate contents in a container like:
382   //
383   //   while (reader.HasMoreData())
384   //     reader.PopString(&value);
385   bool HasMoreData();
386 
387   // Gets the byte at the current iterator position.
388   // Returns true and advances the iterator on success.
389   // Returns false if the data type is not a byte.
390   bool PopByte(uint8_t* value);
391   bool PopBool(bool* value);
392   bool PopInt16(int16_t* value);
393   bool PopUint16(uint16_t* value);
394   bool PopInt32(int32_t* value);
395   bool PopUint32(uint32_t* value);
396   bool PopInt64(int64_t* value);
397   bool PopUint64(uint64_t* value);
398   bool PopDouble(double* value);
399   bool PopString(std::string* value);
400   bool PopObjectPath(ObjectPath* value);
401   bool PopFileDescriptor(FileDescriptor* value);
402 
403   // Sets up the given message reader to read an array at the current
404   // iterator position.
405   // Returns true and advances the iterator on success.
406   // Returns false if the data type is not an array
407   bool PopArray(MessageReader* sub_reader);
408   bool PopStruct(MessageReader* sub_reader);
409   bool PopDictEntry(MessageReader* sub_reader);
410   bool PopVariant(MessageReader* sub_reader);
411 
412   // Gets the array of bytes at the current iterator position.
413   // Returns true and advances the iterator on success.
414   //
415   // Arrays of bytes are often used for exchanging binary blobs hence it's
416   // worth having a specialized function.
417   //
418   // Ownership of the memory pointed to by |bytes| remains with the
419   // MessageReader; |bytes| must be copied if the contents will be referenced
420   // after the MessageReader is destroyed.
421   bool PopArrayOfBytes(const uint8_t** bytes, size_t* length);
422 
423   // Gets the array of doubles at the current iterator position.
424   bool PopArrayOfDoubles(const double** doubles, size_t* length);
425 
426   // Gets the array of strings at the current iterator position. |strings| is
427   // cleared before being modified. Returns true and advances the iterator on
428   // success.
429   //
430   // Arrays of strings are often used to communicate with D-Bus
431   // services like KWallet, hence it's worth having a specialized
432   // function.
433   bool PopArrayOfStrings(std::vector<std::string>* strings);
434 
435   // Gets the array of object paths at the current iterator position.
436   // |object_paths| is cleared before being modified. Returns true and advances
437   // the iterator on success.
438   //
439   // Arrays of object paths are often used to communicate with D-Bus
440   // services like NetworkManager, hence it's worth having a specialized
441   // function.
442   bool PopArrayOfObjectPaths(std::vector<ObjectPath>* object_paths);
443 
444   // Gets the array of bytes at the current iterator position. It then parses
445   // this binary blob into the protocol buffer supplied.
446   // Returns true and advances the iterator on success. On failure returns false
447   // and emits an error message on the source of the failure. The two most
448   // common errors come from the iterator not currently being at a byte array or
449   // the wrong type of protocol buffer is passed in and the parse fails.
450   bool PopArrayOfBytesAsProto(google::protobuf::MessageLite* protobuf);
451 
452   // Gets the byte from the variant data container at the current iterator
453   // position.
454   // Returns true and advances the iterator on success.
455   //
456   // Variants are widely used in D-Bus services so it's worth having a
457   // specialized function. For instance, The return value type of
458   // "org.freedesktop.DBus.Properties.Get" is a variant.
459   bool PopVariantOfByte(uint8_t* value);
460   bool PopVariantOfBool(bool* value);
461   bool PopVariantOfInt16(int16_t* value);
462   bool PopVariantOfUint16(uint16_t* value);
463   bool PopVariantOfInt32(int32_t* value);
464   bool PopVariantOfUint32(uint32_t* value);
465   bool PopVariantOfInt64(int64_t* value);
466   bool PopVariantOfUint64(uint64_t* value);
467   bool PopVariantOfDouble(double* value);
468   bool PopVariantOfString(std::string* value);
469   bool PopVariantOfObjectPath(ObjectPath* value);
470 
471   // Get the data type of the value at the current iterator
472   // position. INVALID_DATA will be returned if the iterator points to the
473   // end of the message.
474   Message::DataType GetDataType();
475 
476   // Get the DBus signature of the value at the current iterator position.
477   // An empty string will be returned if the iterator points to the end of
478   // the message.
479   std::string GetDataSignature();
480 
481  private:
482   // Returns true if the data type at the current iterator position
483   // matches the given D-Bus type, such as DBUS_TYPE_BYTE.
484   bool CheckDataType(int dbus_type);
485 
486   // Helper function used to implement PopByte() etc.
487   bool PopBasic(int dbus_type, void *value);
488 
489   // Helper function used to implement PopArray() etc.
490   bool PopContainer(int dbus_type, MessageReader* sub_reader);
491 
492   // Helper function used to implement PopVariantOfByte() etc.
493   bool PopVariantOfBasic(int dbus_type, void* value);
494 
495   Message* message_;
496   DBusMessageIter raw_message_iter_;
497 
498   DISALLOW_COPY_AND_ASSIGN(MessageReader);
499 };
500 
501 }  // namespace dbus
502 
503 #endif  // DBUS_MESSAGE_H_
504