</entry>
</row>
+ <row>
+ <entry>org.freedesktop.DBus.Containers1.Instance</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ The container instance object path of the server through
+ which this connection is connected, as returned by
+ <literal>AddServer</literal>. Omitted from the
+ dictionary if this connection is not via a container's
+ server.
+ </entry>
+ </row>
+
+ <row>
+ <entry>org.freedesktop.DBus.Containers1.Type</entry>
+ <entry>STRING</entry>
+ <entry>
+ The container technology that created the container
+ instance, as passed to <literal>AddServer</literal>.
+ Omitted from the dictionary if this connection is not
+ via a container's server. For example, a typical value
+ for a Flatpak application would be
+ <literal>org.flatpak</literal>.
+ </entry>
+ </row>
+
+ <row>
+ <entry>org.freedesktop.DBus.Containers1.Name</entry>
+ <entry>STRING</entry>
+ <entry>
+ The contained app name for the container instance,
+ as passed to <literal>AddServer</literal>. Omitted
+ from the dictionary if this connection is not via a
+ container's server. For example, a typical value for
+ a Flatpak application would be
+ <literal>org.gnome.Weather</literal>.
+ </entry>
+ </row>
+
</tbody>
</tgroup>
</informaltable>
</para>
</sect3>
+ <sect3 id="bus-messages-containers1-add-server">
+ <title><literal>org.freedesktop.DBus.Containers1.AddServer</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ AddServer (in STRING container_type,
+ in STRING container_name,
+ in DICT<STRING,VARIANT> metadata,
+ in DICT<STRING,VARIANT> named_arguments,
+ out OBJECT_PATH container_instance,
+ out ARRAY<BYTE> socket_path,
+ out STRING connectable_address)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>
+ Reversed domain name identifying a container manager
+ or container technology, such as
+ <literal>org.flatpak</literal> or
+ <literal>io.snapcraft</literal>. It must follow the
+ same syntactic rules as a
+ <link linkend="message-protocol-names-interface">D-Bus
+ interface name</link>.
+ </entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>STRING</entry>
+ <entry>
+ Some unique identifier for an application or
+ container, whose meaning is defined by the
+ maintainers of the container type. If the container
+ type does not have a concept of identifying or
+ naming its applications or containers by a string,
+ using the empty string here is suggested.
+ </entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>DICT<STRING,VARIANT></entry>
+ <entry>
+ Metadata describing the application or container, with the
+ keys and values defined by the maintainers of the container
+ type.
+ </entry>
+ </row>
+ <row>
+ <entry>3</entry>
+ <entry>DICT<STRING,VARIANT></entry>
+ <entry>
+ Additional arguments that extend this method.
+ The only named arguments that are allowed are the ones
+ listed in the
+ <literal>org.freedesktop.DBus.Containers1.SupportedArguments</literal>
+ property. All other named arguments are an error.
+ </entry>
+ </row>
+ <row>
+ <entry>4</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ An opaque object path identifying the new container
+ instance.
+ </entry>
+ </row>
+ <row>
+ <entry>5</entry>
+ <entry>ARRAY<BYTE></entry>
+ <entry>
+ The absolute filesystem path of the resulting
+ <literal>AF_UNIX</literal> socket, followed by a single
+ zero (nul) byte, for example
+ <literal>/run/user/1000/dbus-12345vwxyz\x00</literal>
+ where \x00 represents the terminating zero byte.
+ </entry>
+ </row>
+ <row>
+ <entry>6</entry>
+ <entry>STRING</entry>
+ <entry>
+ A connectable D-Bus address, for example
+ <literal>unix:path=/run/user/1000/dbus-12345vwxyz</literal>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Set up a new server socket for use in an application container.
+ Clients can connect to that socket, and the result will be as
+ though they had connected to the message bus, with a few differences.
+ The intention is that a container manager will call this method
+ to get a new server socket, bind-mount the server socket
+ into a location that is accessible by the confined (sandboxed)
+ application, and ensure that the normal message bus socket is
+ <emphasis>not</emphasis> accessible by the confined application.
+ </para>
+
+ <para>
+ Each call to this method creates a new
+ <firstterm>container instance</firstterm>, identified by an object
+ path. Even if the specified container type and name are the
+ same as for a pre-existing container instance, each call
+ creates a new server with a new unique object path, because
+ the new container instance might represent a different
+ version of the confined application with different
+ characteristics and restrictions. The message bus may provide
+ an object at the given object path, but is not required to
+ do so.
+ </para>
+
+ <para>
+ Metadata from the first three arguments is stored by the message
+ bus, but not interpreted; software that interacts with the
+ container manager can use this metadata.
+ <!-- TODO: Clarify how the trust model works here. See
+ <https://bugs.freedesktop.org/show_bug.cgi?id=100344#c15>-->
+ The method call may fail with the error
+ <literal>org.freedesktop.DBus.Error.LimitsExceeded</literal>
+ if the caller provides more metadata than the message bus
+ is willing to store.
+ </para>
+
+ <para>
+ The last argument (the <firstterm>named arguments</firstterm>)
+ will be used in future versions of this specification to modify
+ the behaviour of this method call; all keys in this dictionary not
+ containing <literal>.</literal> are reserved by this specification
+ for this purpose. It can also contain implementation-specific
+ arguments for a particular message bus implementation, which
+ should start with a reversed domain name in the same way as
+ interface names. For example, GLib's gdbus-daemon might use
+ <literal>org.gtk.GDBus.SomeArgument</literal> if it used this
+ extension point.
+ </para>
+
+ <para>
+ In the most basic form of a call to this method, the new server
+ socket is an <literal>AF_UNIX</literal> socket at a path chosen
+ by the message bus and returned from the method. Future versions
+ of this specification are likely to provide a way for the
+ message bus implementation to receive a socket from the caller
+ and arrange for it to listen for connections, using the named
+ arguments dictionary.
+ </para>
+
+ <para>
+ Connections to the new server socket are said to be
+ <firstterm>confined</firstterm>. The message bus may prevent
+ confined connections from calling certain security-sensitive methods,
+ and may apply lower limits to these connections. However, container
+ managers and services must not rely on confined connections having
+ any particular filtering applied to them by the message bus.
+ </para>
+
+ <para>
+ In the most basic form of a call to this method, the server
+ socket will cease to listen for new connections (in the same
+ way as if <literal>StopListening</literal> had been called
+ successfully) when the caller of this method disconnects from
+ the bus. Any confined connections that are already active are
+ unaffected. Future versions of this specification are likely
+ to provide a way for the caller to alter this behaviour by
+ specifying named arguments.
+ </para>
+
+ <para>
+ The container instance object path remains valid for as
+ long as one or more confined connection via the same server
+ socket remain open, or there is a way for the server socket
+ to produce new connections in future (in other words,
+ either it is preparing to listen for new connections, or
+ it is currently listening for new connections). When the
+ container instance has ceased to listen for new connections
+ and no longer has any confined connections, the object path
+ becomes invalid, and API calls that specify it will fail with
+ the <literal>org.freedesktop.DBus.Error.NotContainer</literal>
+ error.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-containers1-stop-instance">
+ <title><literal>org.freedesktop.DBus.Containers1.StopInstance</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ StopInstance (in OBJECT_PATH container_instance)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ The opaque object path that was returned from the
+ <literal>AddServer</literal> method, identifying a
+ container instance.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Terminate the container instance. The server will stop
+ listening for new connections, and any existing connections to
+ that server will be disconnected. When all connections have
+ been disconnected, the instance will cease to exist.
+ </para>
+ <para>
+ If the given object path does not represent a valid container
+ instance (see
+ <xref linkend="bus-messages-containers1-add-server"/>), the
+ <literal>org.freedesktop.DBus.Error.NotContainer</literal>
+ error is returned. In particular, if this method is called
+ twice, the second call will fail in this way.
+ </para>
+ <para>
+ If the given container instance exists but the caller of this
+ method is not allowed to stop it (for example because the
+ caller is in a container instance or because its user ID does
+ not match the user ID of the creator of the container
+ instance),
+ the <literal>org.freedesktop.DBus.Error.AccessDenied</literal>
+ error is returned and nothing is stopped.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-containers1-stop-listening">
+ <title><literal>org.freedesktop.DBus.Containers1.StopListening</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ StopListening (in OBJECT_PATH container_instance)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ The opaque object path that was returned from the
+ <literal>AddServer</literal> method, identifying a
+ container instance.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Stop listening for new connections to the server in the given
+ container instance, but do not disconnect any existing
+ connections.
+ </para>
+ <para>
+ If this method is called more than once, while the container
+ instance still exists because connections to it are still
+ open, the second and subsequent calls will be successful but
+ will have no practical effect.
+ </para>
+ <para>
+ If the given object path does not represent a valid container
+ instance (see
+ <xref linkend="bus-messages-containers1-add-server"/>), the
+ <literal>org.freedesktop.DBus.Error.NotContainer</literal>
+ error is returned. In particular, this will happen if the
+ container instance already stopped listening, and all
+ connections to it (if any) were already closed.
+ </para>
+ <para>
+ If the given container instance exists but the caller of this
+ method is not allowed to stop it (for example because the
+ caller is in a container instance or because its user ID does
+ not match the user ID of the creator of the container
+ instance),
+ the <literal>org.freedesktop.DBus.Error.AccessDenied</literal>
+ error is returned and nothing is stopped.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-containers1-get-connection-instance">
+ <title><literal>org.freedesktop.DBus.Containers1.GetConnectionInstance</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ GetConnectionInstance (in STRING bus_name,
+ out OBJECT_PATH container_instance,
+ out STRING container_type,
+ out STRING container_name,
+ out DICT<STRING,VARIANT> metadata)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>
+ Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ The opaque object path that was returned from the
+ <literal>AddServer</literal> method, identifying a
+ container instance.
+ </entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>STRING</entry>
+ <entry>
+ Reversed domain name identifying a container
+ manager or container technology, as passed to the
+ <literal>AddServer</literal> method, such as
+ <literal>org.flatpak</literal> or
+ <literal>io.snapcraft</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>3</entry>
+ <entry>STRING</entry>
+ <entry>
+ Some unique identifier for an application or container,
+ whose meaning is defined by the maintainers of the
+ container type.
+ </entry>
+ </row>
+ <row>
+ <entry>4</entry>
+ <entry>DICT<STRING,VARIANT></entry>
+ <entry>
+ Metadata describing the application or container, with the
+ keys and values defined by the maintainers of the container
+ type.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ If the given unique or well-known bus name is a connection to a
+ container server, return information about that container instance.
+ If the bus name exists but is not confined (in other words, if it
+ is a direct connection to the main message bus socket), the
+ <literal>org.freedesktop.DBus.Error.NotContainer</literal> error
+ is returned instead. If the given bus name has no owner at all, the
+ <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error
+ is returned instead.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-containers1-get-instance-info">
+ <title><literal>org.freedesktop.DBus.Containers1.GetInstanceInfo</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ GetInstanceInfo (in OBJECT_PATH container_instance,
+ out STRING container_type,
+ out STRING container_name,
+ out DICT<STRING,VARIANT> metadata)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ The opaque object path that was returned from the
+ <literal>AddServer</literal> method, identifying a
+ container instance.
+ </entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>STRING</entry>
+ <entry>
+ Reversed domain name identifying a container
+ manager or container technology, as passed to the
+ <literal>AddServer</literal> method, such as
+ <literal>org.flatpak</literal> or
+ <literal>io.snapcraft</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>STRING</entry>
+ <entry>
+ Some unique identifier for an application or container,
+ whose meaning is defined by the maintainers of the
+ container type.
+ </entry>
+ </row>
+ <row>
+ <entry>3</entry>
+ <entry>DICT<STRING,VARIANT></entry>
+ <entry>
+ Metadata describing the application or container, with the
+ keys and values defined by the maintainers of the container
+ type.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ If the given object path represents a valid container instance,
+ (see <xref linkend="bus-messages-containers1-add-server"/>),
+ return information about it. Otherwise, the
+ <literal>org.freedesktop.DBus.Error.NotContainer</literal> error
+ is returned.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-containers1-instance-removed">
+ <title><literal>org.freedesktop.DBus.Containers1.InstanceRemoved</literal></title>
+ <para>
+ As a signal emitted by the message bus:
+ <programlisting>
+ InstanceRemoved (OBJECT_PATH container_instance)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>OBJECT_PATH</entry>
+ <entry>
+ The opaque object path that was returned from the
+ <literal>AddServer</literal> method, identifying a
+ container instance.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Emitted when a container instance ceases to exist. A container
+ instance continues to exist as long as it is listening for
+ new connections, or as long as connections to the instance
+ are open, whichever is longer.
+ </para>
+ </sect3>
+
<sect3 id="bus-messages-become-monitor">
<title><literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
<para>
projects / thirdparty / dbus.git / commitdiff
