Making and parsing messages
===========================

The core of Jeepney is code to build, serialise and deserialise D-Bus messages.

.. currentmodule:: jeepney

Making messages
---------------

D-Bus has four message types. Three, *method call*, *method return* and *error*,
are used in a request-reply pattern. The fourth, *signal*, is a broadcast
message with no reply.

- *Method call* messages are most conveniently made with a message generator
  class, which can be :doc:`autogenerated <bindgen>`. One layer down from this
  is :func:`new_method_call`, which takes a :class:`DBusAddress` object.
- *Method return* and *error* messages are made with
  :func:`new_method_return` and :func:`new_error`, passing the method call
  message which they are replying to.
- *signal* messages are made with :func:`new_signal`, which takes a
  :class:`DBusAddress` representing the sender.

All of these return a :class:`Message` object. :meth:`Message.serialise`
converts it to bytes, but none of these core methods ever send a message.
See the :doc:`integration layer <integrate>` for that.

Signatures
~~~~~~~~~~

D-Bus is strongly typed, and every message has a *signature* describing the body
data. These are strings using characters such as ``i`` for a signed 32-bit
integer. See the `DBus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#type-system>`_
for the full list.

Jeepney does not try to guess or discover the signature when you build a
message: your code must explicitly specify a signature for every message.
However, Jeepney can help you write this code: see :doc:`bindgen`.

D-Bus types are converted to and from native Python objects as follows:

* All the D-Bus integer types are represented as Python :class:`int`,
  including *BYTE* when it's not in an array.
* *BOOLEAN* is :class:`bool`.
* *DOUBLE* is :class:`float`.
* *STRING*, *OBJECT_PATH* and *SIGNATURE* are all :class:`str`.
* *ARRAY* is :class:`list`, except that an array of *BYTE* is a
  :class:`bytes` object, and an array of *DICT_ENTRY* is a :class:`dict`.
* *STRUCT* is :class:`tuple`.
* *VARIANT* is a 2-tuple ``(signature, data)``. E.g. to put a string into
  a variant field, you would pass the data ``("s", "my string")``.
* *UNIX_FD* are converted from objects with a ``.fileno()`` method
  or plain integers, and converted to :class:`.FileDescriptor` objects. See
  :ref:`send_recv_fds` for more details.

