summaryrefslogtreecommitdiffstats
path: root/dbus/message.h
blob: 38887f8c7bea03aa6a8dfb56310e7523f11e7a41 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
// Copyright (c) 2012 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.

#ifndef DBUS_MESSAGE_H_
#define DBUS_MESSAGE_H_
#pragma once

#include <string>
#include <vector>
#include <dbus/dbus.h>

#include "base/basictypes.h"
#include "dbus/file_descriptor.h"
#include "dbus/object_path.h"

namespace google {
namespace protobuf {

class MessageLite;

}  // namespace protobuf
}  // namespace google


namespace dbus {

class MessageWriter;
class MessageReader;

// DBUS_TYPE_UNIX_FD was added in D-Bus version 1.4
#if defined(DBUS_TYPE_UNIX_FD)
const bool kDBusTypeUnixFdIsSupported = true;
#else
const bool kDBusTypeUnixFdIsSupported = false;
#define DBUS_TYPE_UNIX_FD      ((int) 'h')
#endif

// Message is the base class of D-Bus message types. Client code must use
// sub classes such as MethodCall and Response instead.
//
// The class name Message is very generic, but there should be no problem
// as the class is inside 'dbus' namespace. We chose to name this way, as
// libdbus defines lots of types starting with DBus, such as
// DBusMessage. We should avoid confusion and conflict with these types.
class Message {
 public:
  // The message type used in D-Bus.  Redefined here so client code
  // doesn't need to use raw D-Bus macros. DBUS_MESSAGE_TYPE_INVALID
  // etc. are #define macros. Having an enum type here makes code a bit
  // more type-safe.
  enum MessageType {
    MESSAGE_INVALID = DBUS_MESSAGE_TYPE_INVALID,
    MESSAGE_METHOD_CALL = DBUS_MESSAGE_TYPE_METHOD_CALL,
    MESSAGE_METHOD_RETURN = DBUS_MESSAGE_TYPE_METHOD_RETURN,
    MESSAGE_SIGNAL = DBUS_MESSAGE_TYPE_SIGNAL,
    MESSAGE_ERROR = DBUS_MESSAGE_TYPE_ERROR,
 };

  // The data type used in the D-Bus type system.  See the comment at
  // MessageType for why we are redefining data types here.
  enum DataType {
    INVALID_DATA = DBUS_TYPE_INVALID,
    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,
    UNIX_FD = DBUS_TYPE_UNIX_FD,
  };

  // Returns the type of the message. Returns MESSAGE_INVALID if
  // raw_message_ is NULL.
  MessageType GetMessageType();

  // Returns the type of the message as string like "MESSAGE_METHOD_CALL"
  // for instance.
  std::string GetMessageTypeAsString();

  DBusMessage* raw_message() { return raw_message_; }

  // Sets the destination, the path, the interface, the member, etc.
  bool SetDestination(const std::string& destination);
  bool SetPath(const ObjectPath& path);
  bool SetInterface(const std::string& interface);
  bool SetMember(const std::string& member);
  bool SetErrorName(const std::string& error_name);
  bool SetSender(const std::string& sender);
  void SetSerial(uint32 serial);
  void SetReplySerial(uint32 reply_serial);
  // SetSignature() does not exist as we cannot do it.

  // Gets the destination, the path, the interface, the member, etc.
  // If not set, an empty string is returned.
  std::string GetDestination();
  ObjectPath GetPath();
  std::string GetInterface();
  std::string GetMember();
  std::string GetErrorName();
  std::string GetSender();
  std::string GetSignature();
  // Gets the serial and reply serial numbers. Returns 0 if not set.
  uint32 GetSerial();
  uint32 GetReplySerial();

  // Returns the string representation of this message. Useful for
  // debugging. The output is truncated as needed (ex. strings are truncated
  // if longer than a certain limit defined in the .cc file).
  std::string ToString();

 protected:
  // This class cannot be instantiated. Use sub classes instead.
  Message();
  virtual ~Message();

  // Initializes the message with the given raw message.
  void Init(DBusMessage* raw_message);

 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");
  //
  // The constructor creates the internal raw message.
  MethodCall(const std::string& interface_name,
             const std::string& method_name);

  // Returns a newly created MethodCall from the given raw message of the
  // type DBUS_MESSAGE_TYPE_METHOD_CALL. The caller must delete the
  // returned object. Takes the ownership of |raw_message|.
  static MethodCall* FromRawMessage(DBusMessage* raw_message);

 private:
  // Creates a method call message. The internal raw message is NULL.
  // Only used internally.
  MethodCall();

  DISALLOW_COPY_AND_ASSIGN(MethodCall);
};

// Signal is a type of message used to send a signal.
class Signal : public Message {
 public:
  // Creates a signal message for the specified interface name and the
  // method name.
  //
  // For instance, to send "PropertiesChanged" signal of
  // DBUS_INTERFACE_INTROSPECTABLE interface
  // ("org.freedesktop.DBus.Introspectable"), create a signal like this:
  //
  //   Signal signal(DBUS_INTERFACE_INTROSPECTABLE, "PropertiesChanged");
  //
  // The constructor creates the internal raw_message_.
  Signal(const std::string& interface_name,
         const std::string& method_name);

  // Returns a newly created SIGNAL from the given raw message of the type
  // DBUS_MESSAGE_TYPE_SIGNAL. The caller must delete the returned
  // object. Takes the ownership of |raw_message|.
  static Signal* FromRawMessage(DBusMessage* raw_message);

 private:
  // Creates a signal message. The internal raw message is NULL.
  // Only used internally.
  Signal();

  DISALLOW_COPY_AND_ASSIGN(Signal);
};

// Response is a type of message used for receiving a response from a
// method via D-Bus.
class Response : public Message {
 public:
  // Returns a newly created Response from the given raw message of the
  // type DBUS_MESSAGE_TYPE_METHOD_RETURN. The caller must delete the
  // returned object. Takes the ownership of |raw_message|.
  static Response* FromRawMessage(DBusMessage* raw_message);

  // Returns a newly created Response from the given method call. The
  // caller must delete the returned object. Used for implementing
  // exported methods.
  static Response* FromMethodCall(MethodCall* method_call);

  // Returns a newly created Response with an empty payload. The caller
  // must delete the returned object. Useful for testing.
  static Response* CreateEmpty();

 protected:
  // Creates a Response message. The internal raw message is NULL.
  Response();

 private:
  DISALLOW_COPY_AND_ASSIGN(Response);
};

// ErrorResponse is a type of message used to return an error to the
// caller of a method.
class ErrorResponse: public Response {
 public:
  // Returns a newly created Response from the given raw message of the
  // type DBUS_MESSAGE_TYPE_METHOD_RETURN. The caller must delete the
  // returned object. Takes the ownership of |raw_message|.
  static ErrorResponse* FromRawMessage(DBusMessage* raw_message);

  // Returns a newly created ErrorResponse from the given method call, the
  // error name, and the error message.  The error name looks like
  // "org.freedesktop.DBus.Error.Failed". Used for returning an error to a
  // failed method call.
  static ErrorResponse* FromMethodCall(MethodCall* method_call,
                                       const std::string& error_name,
                                       const std::string& error_message);

 private:
  // Creates an ErrorResponse message. The internal raw message is NULL.
  ErrorResponse();

  DISALLOW_COPY_AND_ASSIGN(ErrorResponse);
};

// MessageWriter is used to write outgoing messages for calling methods
// and sending signals.
//
// The main design goal of MessageReader and MessageWriter classes is to
// provide a type safe API. In the past, there was a Chrome OS blocker
// bug, that took days to fix, that would have been prevented if the API
// was type-safe.
//
// For instance, instead of doing something like:
//
//   // We shouldn't add '&' to str here, but it compiles with '&' added.
//   dbus_g_proxy_call(..., G_TYPE_STRING, str, G_TYPE_INVALID, ...)
//
// We want to do something like:
//
//   writer.AppendString(str);
//
class MessageWriter {
 public:
  // Data added with Append* will be written to |message|, which may be NULL
  // to create a sub-writer for passing to OpenArray, etc.
  explicit MessageWriter(Message* message);
  ~MessageWriter();

  // Appends a byte to the message.
  void AppendByte(uint8 value);
  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 ObjectPath& value);
  void AppendFileDescriptor(const FileDescriptor& value);

  // Opens an array. The array contents can be added to the array with
  // |sub_writer|. The client code must close the array with
  // CloseContainer(), once all contents are added.
  //
  // |signature| parameter is used to supply the D-Bus type signature of
  // the array contents. For instance, if you want an array of strings,
  // 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);
  // Do the same for a variant.
  void OpenVariant(const std::string& signature, MessageWriter* sub_writer);
  // Do the same for Struct and dict entry. They don't need the signature.
  void OpenStruct(MessageWriter* sub_writer);
  void OpenDictEntry(MessageWriter* sub_writer);

  // Close the container for a array/variant/struct/dict entry.
  void CloseContainer(MessageWriter* sub_writer);

  // Appends the array of bytes. Arrays of bytes are often used for
  // exchanging binary blobs hence it's worth having a specialized
  // function.
  void AppendArrayOfBytes(const uint8* values, size_t length);

  // Appends the array of strings. Arrays of strings are often used for
  // exchanging lists of names hence it's worth having a specialized
  // function.
  void AppendArrayOfStrings(const std::vector<std::string>& strings);

  // Appends the array of object paths. Arrays of object paths are often
  // used when exchanging object paths, hence it's worth having a
  // specialized function.
  void AppendArrayOfObjectPaths(const std::vector<ObjectPath>& object_paths);

  // Appends the protocol buffer as an array of bytes. The buffer is serialized
  // into an array of bytes before communication, since protocol buffers are not
  // a native dbus type. On the receiving size the array of bytes needs to be
  // read and deserialized into a protocol buffer of the correct type. There are
  // methods in MessageReader to assist in this.  Return true on succes and fail
  // when serialization is not successful.
  bool AppendProtoAsArrayOfBytes(const google::protobuf::MessageLite& protobuf);

  // Appends the byte wrapped in a variant data container. Variants are
  // widely used in D-Bus services so it's worth having a specialized
  // function. For instance, The third parameter of
  // "org.freedesktop.DBus.Properties.Set" is a variant.
  void AppendVariantOfByte(uint8 value);
  void AppendVariantOfBool(bool value);
  void AppendVariantOfInt16(int16 value);
  void AppendVariantOfUint16(uint16 value);
  void AppendVariantOfInt32(int32 value);
  void AppendVariantOfUint32(uint32 value);
  void AppendVariantOfInt64(int64 value);
  void AppendVariantOfUint64(uint64 value);
  void AppendVariantOfDouble(double value);
  void AppendVariantOfString(const std::string& value);
  void AppendVariantOfObjectPath(const ObjectPath& value);

 private:
  // Helper function used to implement AppendByte etc.
  void AppendBasic(int dbus_type, const void* value);

  // Helper function used to implement AppendVariantOfByte() etc.
  void AppendVariantOfBasic(int dbus_type, const void* value);

  Message* message_;
  DBusMessageIter raw_message_iter_;
  bool container_is_open_;

  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|, which may be NULL to
  // create a sub-reader for passing to PopArray, etc.
  explicit 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.HasMoreData())
  //     reader.PopString(&value);
  bool HasMoreData();

  // Gets the byte at the current iterator position.
  // Returns true and advances the iterator on success.
  // Returns false if the data type is not a byte.
  bool PopByte(uint8* value);
  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(ObjectPath* value);
  bool PopFileDescriptor(FileDescriptor* value);

  // Sets up the given message reader to read an array at the current
  // iterator position.
  // Returns true and advances the iterator on success.
  // Returns false if the data type is not an array
  bool PopArray(MessageReader* sub_reader);
  bool PopStruct(MessageReader* sub_reader);
  bool PopDictEntry(MessageReader* sub_reader);
  bool PopVariant(MessageReader* sub_reader);

  // Gets the array of bytes at the current iterator position.
  // Returns true and advances the iterator on success.
  //
  // Arrays of bytes are often used for exchanging binary blobs hence it's
  // worth having a specialized function.
  //
  // |bytes| must be copied if the contents will be referenced after the
  // MessageReader is destroyed.
  bool PopArrayOfBytes(uint8** bytes, size_t* length);

  // Gets the array of strings at the current iterator position.
  // Returns true and advances the iterator on success.
  //
  // Arrays of strings are often used to communicate with D-Bus
  // services like KWallet, hence it's worth having a specialized
  // function.
  bool PopArrayOfStrings(std::vector<std::string>* strings);

  // Gets the array of object paths at the current iterator position.
  // Returns true and advances the iterator on success.
  //
  // 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<ObjectPath>* object_paths);

  // Gets the array of bytes at the current iterator position. It then parses
  // this binary blob into the protocol buffer supplied.
  // Returns true and advances the iterator on success. On failure returns false
  // and emits an error message on the source of the failure. The two most
  // common errors come from the iterator not currently being at a byte array or
  // the wrong type of protocol buffer is passed in and the parse fails.
  bool PopArrayOfBytesAsProto(google::protobuf::MessageLite* protobuf);

  // Gets the byte from the variant data container at the current iterator
  // position.
  // Returns true and advances the iterator on success.
  //
  // 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.Properties.Get" is a variant.
  bool PopVariantOfByte(uint8* value);
  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(ObjectPath* value);

  // Get the data type of the value at the current iterator
  // position. INVALID_DATA will be returned if the iterator points to the
  // end of the message.
  Message::DataType GetDataType();

 private:
  // Returns true if the data type at the current iterator position
  // matches the given D-Bus type, such as DBUS_TYPE_BYTE.
  bool CheckDataType(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

#endif  // DBUS_MESSAGE_H_