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
~~~~~~~~~~

DBus 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`.

In most cases, DBus types have an obvious corresponding type in Python. However,
a few types require further explanation:

* DBus *ARRAY* are Python lists, except for arrays of *DICT_ENTRY*, which are
  dicts.
* DBus *STRUCT* are Python tuples.
* DBus *VARIANT* are 2-tuples ``(signature, data)``. E.g. to put a string into
  a variant field, you would pass the data ``("s", "my string")``.
* Jeepney does not (yet) support sending or receiving file descriptors.

