2
* Copyright © 2012 Canonical Ltd.
4
* This program is free software: you can redistribute it and/or modify it
5
* under the terms of the GNU Lesser General Public License version 3,
6
* as published by the Free Software Foundation.
8
* This program is distributed in the hope that it will be useful,
9
* but WITHOUT ANY WARRANTY; without even the implied warranty of
10
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
* GNU Lesser General Public License for more details.
13
* You should have received a copy of the GNU Lesser General Public License
14
* along with this program. If not, see <http://www.gnu.org/licenses/>.
16
* Authored by: Thomas Voß <thomas.voss@canonical.com>
18
#ifndef CORE_DBUS_MESSAGE_H_
19
#define CORE_DBUS_MESSAGE_H_
21
#include <core/dbus/argument_type.h>
22
#include <core/dbus/visibility.h>
24
#include <core/dbus/types/any.h>
25
#include <core/dbus/types/object_path.h>
26
#include <core/dbus/types/signature.h>
27
#include <core/dbus/types/unix_fd.h>
28
#include <core/dbus/types/variant.h>
30
#include <dbus/dbus.h>
42
template<typename T> struct Codec;
47
* @brief The Message class wraps a raw DBus message
49
class Message : public std::enable_shared_from_this<Message>
52
typedef std::shared_ptr<Message> Ptr;
55
* @brief The Type enum models the type of the message.
59
invalid = DBUS_MESSAGE_TYPE_INVALID, ///< Invalid message type
60
signal = DBUS_MESSAGE_TYPE_SIGNAL, ///< A signal message
61
method_call = DBUS_MESSAGE_TYPE_METHOD_CALL, ///< A method-call message
62
method_return = DBUS_MESSAGE_TYPE_METHOD_RETURN, ///< A method-return message
63
error = DBUS_MESSAGE_TYPE_ERROR ///< An error message.
67
* @brief The Reader class allows type-safe reading of arguments from a message.
74
Reader(const Reader&) = delete;
75
Reader& operator=(const Reader&) = delete;
78
Reader& operator=(Reader&&);
81
* @brief Returns the current type.
84
ArgumentType type() const;
87
* @brief Advances this view into the message.
92
* @brief Reads a byte from the underlying message.
94
std::int8_t pop_byte();
97
* @brief Reads a boolean from the underlying message.
102
* @brief Reads an int16 from the underlying message.
104
std::int16_t pop_int16();
107
* @brief Reads a uint16 from the underlying message.
109
std::uint16_t pop_uint16();
112
* @brief Reads an int32 from the underlying message.
114
std::int32_t pop_int32();
117
* @brief Reads a uint32 from the underlying message.
119
std::uint32_t pop_uint32();
122
* @brief Reads an int64 from the underlying message.
124
std::int64_t pop_int64();
127
* @brief Reads a uint64 from the underlying message.
129
std::uint64_t pop_uint64();
132
* @brief Reads a floating point value from the underlying message.
134
double pop_floating_point();
137
* @brief Reads a string from the underlying message.
139
const char* pop_string();
142
* @brief Reads an object_path from the underlying message.
144
types::ObjectPath pop_object_path();
147
* @brief Reads a signature from the underlying message.
149
types::Signature pop_signature();
152
* @brief Reads a unix fd from the underlying message.
154
types::UnixFd pop_unix_fd();
157
* @brief Prepares reading of an array from the underlying message.
158
* @return A reader pointing to the array.
163
* @brief Prepares reading of a structure from the underlying message.
164
* @return A reader pointing into the structure.
166
Reader pop_structure();
169
* @brief Prepares reading of a variant from the underlying message.
170
* @return A reader pointing into the variant.
172
Reader pop_variant();
175
* @brief Prepares reading of a dict entry from the underlying message.
176
* @return A reader pointing to the array.
178
Reader pop_dict_entry();
181
friend struct Codec<types::Any>;
182
friend class Message;
183
explicit Reader(const std::shared_ptr<Message>& msg);
185
const std::shared_ptr<Message>& access_message();
188
std::unique_ptr<Private> d;
192
* @brief The Writer class allows type-safe serialization of input arguments to a message.
198
Writer(const Writer&) = delete;
199
Writer& operator=(const Writer&) = delete;
202
Writer& operator=(Writer&&);
205
* @brief Writes a byte to the underlying message.
207
void push_byte(std::int8_t value);
210
* @brief Writes a boolean to the underlying message.
212
void push_boolean(bool value);
215
* @brief Writes an int16 to the underlying message.
217
void push_int16(std::int16_t value);
220
* @brief Writes a uint16 to the underlying message.
222
void push_uint16(std::uint16_t value);
225
* @brief Writes an int32 to the underlying message.
227
void push_int32(std::int32_t value);
230
* @brief Writes a uint32 to the underlying message.
232
void push_uint32(std::uint32_t value);
235
* @brief Writes an int64 to the underlying message.
237
void push_int64(std::int64_t value);
240
* @brief Writes a uint64 to the underlying message.
242
void push_uint64(std::uint64_t value);
245
* @brief Writes a floating point value to the underlying message.
247
void push_floating_point(double value);
250
* @brief Writes a string to the underlying message.
252
void push_stringn(const char* value, std::size_t size);
255
* @brief Writes an object_path to the underlying message.
257
void push_object_path(const types::ObjectPath& value);
260
* @brief Writes a signature to the underlying message.
262
void push_signature(const types::Signature& value);
265
* @brief Writes a unix fd to the underlying message.
267
void push_unix_fd(const types::UnixFd& value);
270
* @brief Prepares writing of an array to the underlying message.
271
* @param [in] signature The signature of the contained data type.
273
Writer open_array(const types::Signature& signature);
276
* @brief Finalizes writing of an array to the underlying message.
278
void close_array(Writer writer);
281
* @brief Prepares writing of a structure to the underlying message.
283
Writer open_structure();
286
* @brief Finalizes writing of a structure to the underlying message.
288
void close_structure(Writer writer);
291
* @brief Prepares writing of a variant to the underlying message.
292
* @param [in] signature The signature of the contained data type.
294
Writer open_variant(const types::Signature& signature);
297
* @brief Finalizes writing of a variant to the underlying message.
299
void close_variant(Writer writer);
302
* @brief Prepares writing of a dict entry to the underlying message.
304
Writer open_dict_entry();
307
* @brief Finalizes writing of a dict entry to the underlying message.
309
void close_dict_entry(Writer writer);
312
friend class Message;
313
explicit Writer(const std::shared_ptr<Message>& msg);
316
std::unique_ptr<Private> d;
320
* @brief make_method_call creates an instance of Message with type Type::method_call.
321
* @param destination The name of the remote service to send the message to.
322
* @param path The name of the remote object to send the message to.
323
* @param interface The interface to route the message to.
324
* @param method The actual method that should be invoked
325
* @return An instance of message of type Type::method_call.
326
* @throw std::runtime_error if any of the parameters violates the DBus specification.
328
static std::shared_ptr<Message> make_method_call(
329
const std::string& destination,
330
const types::ObjectPath& path,
331
const std::string& interface,
332
const std::string& method);
335
* @brief make_method_return creates a message instance in response to a raw DBus message of type method-call.
336
* @param msg The message to reply to, must not be null. Must be of type Type::method_call.
337
* @return An instance of message of type Type::method_return.
339
static std::shared_ptr<Message> make_method_return(const Message::Ptr& msg);
342
* @brief make_signal creates a message instance wrapping a signal emission.
343
* @param path The path of the object emitting the signal.
344
* @param interface The interface containing the signal.
345
* @param signal The actual signal name.
346
* @return An instance of message of type Type::signal.
348
static std::shared_ptr<Message> make_signal(
349
const std::string& path,
350
const std::string& interface,
351
const std::string& signal);
354
* @brief make_error creates an error message instance in response to a raw DBus message of type method-call.
355
* @param in_reply_to The message to reply to, must not be null. Must be of type Type::method_call.
356
* @param error_name The name of the error.
357
* @param error_desc Human-readable description of the error.
358
* @return An instance of message of type Type::error.
360
static std::shared_ptr<Message> make_error(
361
const Message::Ptr& in_reply_to,
362
const std::string& error_name,
363
const std::string& error_desc);
366
* @brief from_raw_message creates an instance of message from a raw message.
367
* @param msg The message to wrap.
368
* @return An instance of Message with a type corresponding to the type of the raw message.
370
static std::shared_ptr<Message> from_raw_message(DBusMessage* msg);
375
* @brief Queries the type of the message.
380
* @brief Checks if the message expects a reply, i.e., is of type Type::method_call.
382
bool expects_reply() const;
385
* @brief Queries the path of the object that this message belongs to.
387
types::ObjectPath path() const;
390
* @brief Queries the member name that this message corresponds to.
392
std::string member() const;
395
* @brief Queries the type signature of this message.
397
std::string signature() const;
400
* @brief Queries the interface name that this message corresponds to.
402
std::string interface() const;
405
* @brief Queries the name of the destination that this message should go to.
407
std::string destination() const;
410
* @brief Queries the name of the sender that this message originates from.
412
std::string sender() const;
415
* @brief Extracts error information from the message.
416
* @throw std::runtime_error if not an error message.
421
* @brief Creates a Reader instance to read from this message.
426
* @brief Creates a Writer instance to write to this message.
431
* @brief Extracts the raw DBus message contained within this instance. Use with care.
433
DBusMessage* get() const;
436
friend struct Codec<types::Any>;
437
friend class MessageFactory;
441
bool ref_on_construction = false);
443
std::shared_ptr<Message> clone();
445
std::shared_ptr<DBusMessage> dbus_message;
451
#include "impl/message.h>
453
#endif // CORE_DBUS_MESSAGE_H_
added
removed
src/core/dbus/message_impl.h
