1 // Copyright 2012 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef DBUS_MESSAGE_H_
6 #define DBUS_MESSAGE_H_
16 #include "base/files/scoped_file.h"
17 #include "base/memory/raw_ptr.h"
18 #include "base/strings/string_piece.h"
19 #include "dbus/dbus_export.h"
20 #include "dbus/object_path.h"
27 } // namespace protobuf
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')
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();
45 // Message is the base class of D-Bus message types. Client code must use
46 // sub classes such as MethodCall and Response instead.
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 {
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
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,
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.
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,
88 Message(const Message&) = delete;
89 Message& operator=(const Message&) = delete;
91 // Returns the type of the message. Returns MESSAGE_INVALID if
92 // raw_message_ is NULL.
93 MessageType GetMessageType();
95 // Returns the type of the message as string like "MESSAGE_METHOD_CALL"
97 std::string GetMessageTypeAsString();
99 DBusMessage* raw_message() { return raw_message_; }
101 // Sets the destination, the path, the interface, the member, etc.
102 bool SetDestination(const std::string& destination);
103 bool SetPath(const ObjectPath& path);
104 bool SetInterface(const std::string& interface);
105 bool SetMember(const std::string& member);
106 bool SetErrorName(const std::string& error_name);
107 bool SetSender(const std::string& sender);
108 void SetSerial(uint32_t serial);
109 void SetReplySerial(uint32_t reply_serial);
110 // SetSignature() does not exist as we cannot do it.
112 // Gets the destination, the path, the interface, the member, etc.
113 // If not set, an empty string is returned.
114 std::string GetDestination();
115 ObjectPath GetPath();
116 std::string GetInterface();
117 std::string GetMember();
118 std::string GetErrorName();
119 std::string GetSender();
120 std::string GetSignature();
121 // Gets the serial and reply serial numbers. Returns 0 if not set.
122 uint32_t GetSerial();
123 uint32_t GetReplySerial();
125 // Returns the string representation of this message. Useful for
126 // debugging. The output is truncated as needed (ex. strings are truncated
127 // if longer than a certain limit defined in the .cc file).
128 std::string ToString();
131 // This class cannot be instantiated. Use sub classes instead.
135 // Initializes the message with the given raw message.
136 void Init(DBusMessage* raw_message);
139 // Helper function used in ToString().
140 std::string ToStringInternal(const std::string& indent,
141 MessageReader* reader);
143 raw_ptr<DBusMessage, AcrossTasksDanglingUntriaged> raw_message_;
146 // MessageCall is a type of message used for calling a method via D-Bus.
147 class CHROME_DBUS_EXPORT MethodCall : public Message {
149 // Creates a method call message for the specified interface name and
152 // For instance, to call "Get" method of DBUS_INTERFACE_INTROSPECTABLE
153 // interface ("org.freedesktop.DBus.Introspectable"), create a method
156 // MethodCall method_call(DBUS_INTERFACE_INTROSPECTABLE, "Get");
158 // The constructor creates the internal raw message.
159 MethodCall(const std::string& interface_name, const std::string& method_name);
161 MethodCall(const MethodCall&) = delete;
162 MethodCall& operator=(const MethodCall&) = delete;
164 // Returns a newly created MethodCall from the given raw message of the
165 // type DBUS_MESSAGE_TYPE_METHOD_CALL. Takes the ownership of |raw_message|.
166 static std::unique_ptr<MethodCall> FromRawMessage(DBusMessage* raw_message);
169 // Creates a method call message. The internal raw message is NULL.
170 // Only used internally.
174 // Signal is a type of message used to send a signal.
175 class CHROME_DBUS_EXPORT Signal : public Message {
177 // Creates a signal message for the specified interface name and the
180 // For instance, to send "PropertiesChanged" signal of
181 // DBUS_INTERFACE_INTROSPECTABLE interface
182 // ("org.freedesktop.DBus.Introspectable"), create a signal like this:
184 // Signal signal(DBUS_INTERFACE_INTROSPECTABLE, "PropertiesChanged");
186 // The constructor creates the internal raw_message_.
187 Signal(const std::string& interface_name, const std::string& method_name);
189 Signal(const Signal&) = delete;
190 Signal& operator=(const Signal&) = delete;
192 // Returns a newly created SIGNAL from the given raw message of the type
193 // DBUS_MESSAGE_TYPE_SIGNAL. Takes the ownership of |raw_message|.
194 static std::unique_ptr<Signal> FromRawMessage(DBusMessage* raw_message);
197 // Creates a signal message. The internal raw message is NULL.
198 // Only used internally.
202 // Response is a type of message used for receiving a response from a
204 class CHROME_DBUS_EXPORT Response : public Message {
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);
210 // Returns a newly created Response from the given method call.
211 // Used for implementing exported methods. Does NOT take the ownership of
213 static std::unique_ptr<Response> FromMethodCall(MethodCall* method_call);
215 // Returns a newly created Response with an empty payload.
216 // Useful for testing.
217 static std::unique_ptr<Response> CreateEmpty();
219 Response(const Response&) = delete;
220 Response& operator=(const Response&) = delete;
223 // Creates a Response message. The internal raw message is NULL.
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 {
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);
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);
245 ErrorResponse(const ErrorResponse&) = delete;
246 ErrorResponse& operator=(const ErrorResponse&) = delete;
249 // Creates an ErrorResponse message. The internal raw message is NULL.
253 // MessageWriter is used to write outgoing messages for calling methods
254 // and sending signals.
256 // The main design goal of MessageReader and MessageWriter classes is to
257 // provide a type safe API. In the past, there was a Chrome OS blocker
258 // bug, that took days to fix, that would have been prevented if the API
261 // For instance, instead of doing something like:
263 // // We shouldn't add '&' to str here, but it compiles with '&' added.
264 // dbus_g_proxy_call(..., G_TYPE_STRING, str, G_TYPE_INVALID, ...)
266 // We want to do something like:
268 // writer.AppendString(str);
270 class CHROME_DBUS_EXPORT MessageWriter {
272 // Data added with Append* will be written to |message|, which may be NULL
273 // to create a sub-writer for passing to OpenArray, etc.
274 explicit MessageWriter(Message* message);
276 MessageWriter(const MessageWriter&) = delete;
277 MessageWriter& operator=(const MessageWriter&) = delete;
281 // Appends a byte to the message.
282 void AppendByte(uint8_t value);
283 void AppendBool(bool value);
284 void AppendInt16(int16_t value);
285 void AppendUint16(uint16_t value);
286 void AppendInt32(int32_t value);
287 void AppendUint32(uint32_t value);
288 void AppendInt64(int64_t value);
289 void AppendUint64(uint64_t value);
290 void AppendDouble(double value);
291 void AppendString(base::StringPiece value);
292 void AppendObjectPath(const ObjectPath& value);
294 // Appends a file descriptor to the message.
295 // The FD will be duplicated so you still have to close the original FD.
296 void AppendFileDescriptor(int value);
298 // Opens an array. The array contents can be added to the array with
299 // |sub_writer|. The client code must close the array with
300 // CloseContainer(), once all contents are added.
302 // |signature| parameter is used to supply the D-Bus type signature of
303 // the array contents. For instance, if you want an array of strings,
304 // then you pass "s" as the signature.
306 // See the spec for details about the type signatures.
307 // http://dbus.freedesktop.org/doc/dbus-specification.html
308 // #message-protocol-signatures
310 void OpenArray(const std::string& signature, MessageWriter* sub_writer);
311 // Do the same for a variant.
312 void OpenVariant(const std::string& signature, MessageWriter* sub_writer);
313 // Do the same for Struct and dict entry. They don't need the signature.
314 void OpenStruct(MessageWriter* sub_writer);
315 void OpenDictEntry(MessageWriter* sub_writer);
317 // Close the container for a array/variant/struct/dict entry.
318 void CloseContainer(MessageWriter* sub_writer);
320 // Appends the array of bytes. Arrays of bytes are often used for
321 // exchanging binary blobs hence it's worth having a specialized
323 void AppendArrayOfBytes(const uint8_t* values, size_t length);
325 // Appends array of int32_ts.
326 void AppendArrayOfInt32s(const int32_t* values, size_t length);
328 // Appends array of uint32_ts.
329 void AppendArrayOfUint32s(const uint32_t* values, size_t length);
331 // Appends the array of doubles. Used for audio mixer matrix doubles.
332 void AppendArrayOfDoubles(const double* values, size_t length);
334 // Appends the array of strings. Arrays of strings are often used for
335 // exchanging lists of names hence it's worth having a specialized
337 void AppendArrayOfStrings(const std::vector<std::string>& strings);
339 // Appends the array of object paths. Arrays of object paths are often
340 // used when exchanging object paths, hence it's worth having a
341 // specialized function.
342 void AppendArrayOfObjectPaths(const std::vector<ObjectPath>& object_paths);
344 // Appends the protocol buffer as an array of bytes. The buffer is serialized
345 // into an array of bytes before communication, since protocol buffers are not
346 // a native dbus type. On the receiving size the array of bytes needs to be
347 // read and deserialized into a protocol buffer of the correct type. There are
348 // methods in MessageReader to assist in this. Return true on success and
349 // false when serialization fails.
350 bool AppendProtoAsArrayOfBytes(const google::protobuf::MessageLite& protobuf);
352 // Appends the byte wrapped in a variant data container. Variants are
353 // widely used in D-Bus services so it's worth having a specialized
354 // function. For instance, The third parameter of
355 // "org.freedesktop.DBus.Properties.Set" is a variant.
356 void AppendVariantOfByte(uint8_t value);
357 void AppendVariantOfBool(bool value);
358 void AppendVariantOfInt16(int16_t value);
359 void AppendVariantOfUint16(uint16_t value);
360 void AppendVariantOfInt32(int32_t value);
361 void AppendVariantOfUint32(uint32_t value);
362 void AppendVariantOfInt64(int64_t value);
363 void AppendVariantOfUint64(uint64_t value);
364 void AppendVariantOfDouble(double value);
365 void AppendVariantOfString(const std::string& value);
366 void AppendVariantOfObjectPath(const ObjectPath& value);
369 // Helper function used to implement AppendByte etc.
370 void AppendBasic(int dbus_type, const void* value);
372 // Helper function used to implement AppendVariantOfByte() etc.
373 void AppendVariantOfBasic(int dbus_type, const void* value);
375 raw_ptr<Message, AcrossTasksDanglingUntriaged> message_;
376 DBusMessageIter raw_message_iter_;
377 bool container_is_open_;
380 // MessageReader is used to read incoming messages such as responses for
383 // MessageReader manages an internal iterator to read data. All functions
384 // starting with Pop advance the iterator on success.
385 class CHROME_DBUS_EXPORT MessageReader {
387 // The data will be read from the given |message|, which may be NULL to
388 // create a sub-reader for passing to PopArray, etc.
389 explicit MessageReader(Message* message);
391 MessageReader(const MessageReader&) = delete;
392 MessageReader& operator=(const MessageReader&) = delete;
396 // Returns true if the reader has more data to read. The function is
397 // used to iterate contents in a container like:
399 // while (reader.HasMoreData())
400 // reader.PopString(&value);
403 // Gets the byte at the current iterator position.
404 // Returns true and advances the iterator on success.
405 // Returns false if the data type is not a byte.
406 bool PopByte(uint8_t* value);
407 bool PopBool(bool* value);
408 bool PopInt16(int16_t* value);
409 bool PopUint16(uint16_t* value);
410 bool PopInt32(int32_t* value);
411 bool PopUint32(uint32_t* value);
412 bool PopInt64(int64_t* value);
413 bool PopUint64(uint64_t* value);
414 bool PopDouble(double* value);
415 bool PopString(std::string* value);
416 bool PopObjectPath(ObjectPath* value);
417 bool PopFileDescriptor(base::ScopedFD* value);
419 // Sets up the given message reader to read an array at the current
420 // iterator position.
421 // Returns true and advances the iterator on success.
422 // Returns false if the data type is not an array
423 bool PopArray(MessageReader* sub_reader);
424 bool PopStruct(MessageReader* sub_reader);
425 bool PopDictEntry(MessageReader* sub_reader);
426 bool PopVariant(MessageReader* sub_reader);
428 // Gets the array of bytes at the current iterator position.
429 // Returns true and advances the iterator on success.
431 // Arrays of bytes are often used for exchanging binary blobs hence it's
432 // worth having a specialized function.
434 // Ownership of the memory pointed to by |bytes| remains with the
435 // MessageReader; |bytes| must be copied if the contents will be referenced
436 // after the MessageReader is destroyed.
437 bool PopArrayOfBytes(const uint8_t** bytes, size_t* length);
439 // Gets the array of int32_ts at the current iterator position.
440 bool PopArrayOfInt32s(const int32_t** signed_ints, size_t* length);
442 // Gets the array of uint32_ts at the current iterator position.
443 bool PopArrayOfUint32s(const uint32_t** unsigned_ints, size_t* length);
445 // Gets the array of doubles at the current iterator position.
446 bool PopArrayOfDoubles(const double** doubles, size_t* length);
448 // Gets the array of strings at the current iterator position. |strings| is
449 // cleared before being modified. Returns true and advances the iterator on
452 // Arrays of strings are often used to communicate with D-Bus
453 // services like KWallet, hence it's worth having a specialized
455 bool PopArrayOfStrings(std::vector<std::string>* strings);
457 // Gets the array of object paths at the current iterator position.
458 // |object_paths| is cleared before being modified. Returns true and advances
459 // the iterator on success.
461 // Arrays of object paths are often used to communicate with D-Bus
462 // services like NetworkManager, hence it's worth having a specialized
464 bool PopArrayOfObjectPaths(std::vector<ObjectPath>* object_paths);
466 // Gets the array of bytes at the current iterator position. It then parses
467 // this binary blob into the protocol buffer supplied.
468 // Returns true and advances the iterator on success. On failure returns false
469 // and emits an error message on the source of the failure. The two most
470 // common errors come from the iterator not currently being at a byte array or
471 // the wrong type of protocol buffer is passed in and the parse fails.
472 bool PopArrayOfBytesAsProto(google::protobuf::MessageLite* protobuf);
474 // Gets the byte from the variant data container at the current iterator
476 // Returns true and advances the iterator on success.
478 // Variants are widely used in D-Bus services so it's worth having a
479 // specialized function. For instance, The return value type of
480 // "org.freedesktop.DBus.Properties.Get" is a variant.
481 bool PopVariantOfByte(uint8_t* value);
482 bool PopVariantOfBool(bool* value);
483 bool PopVariantOfInt16(int16_t* value);
484 bool PopVariantOfUint16(uint16_t* value);
485 bool PopVariantOfInt32(int32_t* value);
486 bool PopVariantOfUint32(uint32_t* value);
487 bool PopVariantOfInt64(int64_t* value);
488 bool PopVariantOfUint64(uint64_t* value);
489 bool PopVariantOfDouble(double* value);
490 bool PopVariantOfString(std::string* value);
491 bool PopVariantOfObjectPath(ObjectPath* value);
493 // Get the data type of the value at the current iterator
494 // position. INVALID_DATA will be returned if the iterator points to the
495 // end of the message.
496 Message::DataType GetDataType();
498 // Get the DBus signature of the value at the current iterator position.
499 // An empty string will be returned if the iterator points to the end of
501 std::string GetDataSignature();
504 // Returns true if the data type at the current iterator position
505 // matches the given D-Bus type, such as DBUS_TYPE_BYTE.
506 bool CheckDataType(int dbus_type);
508 // Helper function used to implement PopByte() etc.
509 bool PopBasic(int dbus_type, void* value);
511 // Helper function used to implement PopArray() etc.
512 bool PopContainer(int dbus_type, MessageReader* sub_reader);
514 // Helper function used to implement PopVariantOfByte() etc.
515 bool PopVariantOfBasic(int dbus_type, void* value);
517 raw_ptr<Message, AcrossTasksDanglingUntriaged> message_;
518 DBusMessageIter raw_message_iter_;
523 #endif // DBUS_MESSAGE_H_