bus: implement bus_path_{en,de}code_unique()

Whenever we provide a bus API that allows clients to create and manage
server-side objects, we need to provide a unique name for these objects.
There are two ways to provide them:
  1) Let the server choose a name and return it as method reply.
  2) Let the client pass its name of choice in the method arguments.

The first method is the easiest one to implement. However, it suffers from
a race condition: If a client creates an object asynchronously, it cannot
destroy that object until it received the method reply. It cannot know the
name of the new object, thus, it cannot destroy it. Furthermore, this
method enforces a round-trip. If the client _depends_ on the method call
to succeed (eg., it would close() the connection if it failed), the client
usually has no reason to wait for the method reply. Instead, the client
can immediately schedule further method calls on the newly created object
(in case the API guarantees in-order method-call handling).

The second method fixes both problems: The client passes an object name
with the method-call. The server uses it to create the object. Therefore,
the client can schedule object destruction even if the object-creation
hasn't finished, yet (again, requiring in-order method-call handling).
Furthermore, the client can schedule further method calls on the newly
created object, before the constructor returned.

There're two problems to solve, though:
  1) Object names are usually defined via dbus object paths, which are
     usually globally namespaced. Therefore, multiple clients must be able
     to choose unique object names without interference.
  2) If multiple libraries share the same bus connection, they must be
     able to choose unique object names without interference.

The first problem is solved easily by prefixing a name with the
unique-bus-name of a connection. The server side must enforce this and
reject any other name.
The second problem is solved by providing unique suffixes from within
sd-bus. As long as sd-bus always returns a fresh new ID, if requested,
multiple libraries will never interfere. This implementation re-uses
bus->cookie as ID generator, which already provides unique IDs for each
bus connection.

This patch introduces two new helpers:
  bus_path_encode_unique(sd_bus *bus,
                         const char *prefix,
                         const char *sender_id,
                         const char *external_id,
                         char **ret_path);
    This creates a new object-path via the template
    '/prefix/sender_id/external_id'. That is, it appends two new labels to
    the given prefix. If 'sender_id' is NULL, it will use
    bus->unique_name, if 'external_id' is NULL, it will allocate a fresh,
    unique cookie from bus->cookie.

  bus_path_decode_unique(const char *path,
                         const char *prefix,
                         char **ret_sender,
                         char **ret_external);
    This reverses what bus_path_encode_unique() did. It parses 'path' from
    the template '/prefix/sender/external' and returns both suffix-labels
    in 'ret_sender' and 'ret_external'. In case the template does not
    match, 0 is returned and both output arguments are set to NULL.
    Otherwise, 1 is returned and the output arguments contain the decoded
    labels.

Note: Client-side allocated IDs are inspired by the Wayland protocol
      (which itself was inspired by X11). Wayland uses those IDs heavily
      to avoid round-trips. Clients can create server-side objects and
      send method calls without any round-trip and waiting for any object
      IDs to be returned. But unlike Wayland, DBus uses gobally namespaced
      object names. Therefore, we have to add the extra step by adding the
      unique-name of the bus connection.

0 files changed, 0 insertions, 0 deletions