From a7214a4741f50752b80755a5a62ca495b8a9cb91 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 2 Jun 2017 14:52:03 +0100 Subject: [PATCH] spec: Document the initial Containers1 interface Signed-off-by: Simon McVittie --- Consistently say application, not app. Rename AddContainerServer() etc. to AddServer() etc. Consistently say application, not app. Consistently end argument descriptions with a full stop. Try to clarify that each call to AddServer creates a new unique object path. Add missing documentation for InstanceRemoved signal. Clarify that a second call to StopInstance() will fail, but StopListening() is idempotent (except in the trivial case of no connections left alive, in which case it's equivalent to StopInstance()). Say that container types (container technology names) are syntactically interface names. https://bugs.freedesktop.org/show_bug.cgi?id=101354 --- doc/dbus-specification.xml | 542 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 542 insertions(+) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c33f0a0c..f7f66726 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6416,6 +6416,44 @@ + + org.freedesktop.DBus.Containers1.Instance + OBJECT_PATH + + The container instance object path of the server through + which this connection is connected, as returned by + AddServer. Omitted from the + dictionary if this connection is not via a container's + server. + + + + + org.freedesktop.DBus.Containers1.Type + STRING + + The container technology that created the container + instance, as passed to AddServer. + 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 + org.flatpak. + + + + + org.freedesktop.DBus.Containers1.Name + STRING + + The contained app name for the container instance, + as passed to AddServer. 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 + org.gnome.Weather. + + + @@ -6647,6 +6685,510 @@ + + <literal>org.freedesktop.DBus.Containers1.AddServer</literal> + + As a method: + + 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) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + + Reversed domain name identifying a container manager + or container technology, such as + org.flatpak or + io.snapcraft. It must follow the + same syntactic rules as a + D-Bus + interface name. + + + + 1 + STRING + + 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. + + + + 2 + DICT<STRING,VARIANT> + + Metadata describing the application or container, with the + keys and values defined by the maintainers of the container + type. + + + + 3 + DICT<STRING,VARIANT> + + Additional arguments that extend this method. + The only named arguments that are allowed are the ones + listed in the + org.freedesktop.DBus.Containers1.SupportedArguments + property. All other named arguments are an error. + + + + 4 + OBJECT_PATH + + An opaque object path identifying the new container + instance. + + + + 5 + ARRAY<BYTE> + + The absolute filesystem path of the resulting + AF_UNIX socket, followed by a single + zero (nul) byte, for example + /run/user/1000/dbus-12345vwxyz\x00 + where \x00 represents the terminating zero byte. + + + + 6 + STRING + + A connectable D-Bus address, for example + unix:path=/run/user/1000/dbus-12345vwxyz. + + + + + + + + + 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 + not accessible by the confined application. + + + + Each call to this method creates a new + container instance, 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. + + + + 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. + + The method call may fail with the error + org.freedesktop.DBus.Error.LimitsExceeded + if the caller provides more metadata than the message bus + is willing to store. + + + + The last argument (the named arguments) + will be used in future versions of this specification to modify + the behaviour of this method call; all keys in this dictionary not + containing . 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 + org.gtk.GDBus.SomeArgument if it used this + extension point. + + + + In the most basic form of a call to this method, the new server + socket is an AF_UNIX 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. + + + + Connections to the new server socket are said to be + confined. 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. + + + + 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 StopListening 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. + + + + The container instance object path remains valid for as long + as either the server socket is listening for new connections, + or any confined connection via the same server socket remains + open. + + + + + <literal>org.freedesktop.DBus.Containers1.StopInstance</literal> + + As a method: + + StopInstance (in OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer method, identifying a + container instance. + + + + + + + + + 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. + + + If the given object path does not represent an active + container instance, the + org.freedesktop.DBus.Error.NotContainer + error is returned. In particular, if this method is called + twice, the second call will fail in this way. + + + 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 org.freedesktop.DBus.Error.AccessDenied + error is returned and nothing is stopped. + + + + + <literal>org.freedesktop.DBus.Containers1.StopListening</literal> + + As a method: + + StopListening (in OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer method, identifying a + container instance. + + + + + + + + + Stop listening for new connections to the server in the given + container instance, but do not disconnect any existing + connections. + + + 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. + + + If the given object path does not represent an active container + instance, the + org.freedesktop.DBus.Error.NotContainer + 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. + + + 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 org.freedesktop.DBus.Error.AccessDenied + error is returned and nothing is stopped. + + + + + <literal>org.freedesktop.DBus.Containers1.GetConnectionInstance</literal> + + As a method: + + GetConnectionInstance (in STRING bus_name, + out OBJECT_PATH container_instance, + out STRING container_type, + out STRING container_name, + out DICT<STRING,VARIANT> metadata) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea. + + + + 1 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer method, identifying a + container instance. + + + + 2 + STRING + + Reversed domain name identifying a container + manager or container technology, as passed to the + AddServer method, such as + org.flatpak or + io.snapcraft. + + + + 3 + STRING + + Some unique identifier for an application or container, + whose meaning is defined by the maintainers of the + container type. + + + + 4 + DICT<STRING,VARIANT> + + Metadata describing the application or container, with the + keys and values defined by the maintainers of the container + type. + + + + + + + + + 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 + org.freedesktop.DBus.Error.NotContainer error + is returned instead. If the given bus name has no owner at all, the + org.freedesktop.DBus.Error.NameHasNoOwner error + is returned instead. + + + + + <literal>org.freedesktop.DBus.Containers1.GetInstanceInfo</literal> + + As a method: + + GetInstanceInfo (in OBJECT_PATH container_instance, + out STRING container_type, + out STRING container_name, + out DICT<STRING,VARIANT> metadata) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer method, identifying a + container instance. + + + + 1 + STRING + + Reversed domain name identifying a container + manager or container technology, as passed to the + AddServer method, such as + org.flatpak or + io.snapcraft. + + + + 2 + STRING + + Some unique identifier for an application or container, + whose meaning is defined by the maintainers of the + container type. + + + + 3 + DICT<STRING,VARIANT> + + Metadata describing the application or container, with the + keys and values defined by the maintainers of the container + type. + + + + + + + + + If the given object path represents an active container instance, + return information about it. If not, the + org.freedesktop.DBus.Error.NotContainer error + is returned. + + + + + <literal>org.freedesktop.DBus.Containers1.InstanceRemoved</literal> + + As a signal emitted by the message bus: + + InstanceRemoved (OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer method, identifying a + container instance. + + + + + + + + + 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. + + + <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal> -- 2.13.3