From: Simon McVittie Date: Thu, 11 Jan 2018 18:20:34 +0000 (+0000) Subject: Revert "spec: Document the initial Containers1 interface" X-Git-Tag: dbus-1.13.0~50 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f8a2a03ca0f50a84578419de2a16a8e84cbeca50;p=thirdparty%2Fdbus.git Revert "spec: Document the initial Containers1 interface" This reverts commit 39262d0a2913fc8ee951beb3d0241720abf651c0. I'm reasonably sure the API for Container1 is going to change incompatibly, so it isn't ready to be in the published spec yet. Signed-off-by: Simon McVittie --- diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 2cec36a6e..860b10d70 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6449,44 +6449,6 @@ - - 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. - - - @@ -6718,520 +6680,6 @@ - - <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 by the message bus. - - - - 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 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 org.freedesktop.DBus.Error.NotContainer - error. - - - - - <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 a valid container - instance (see - ), 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 a valid container - instance (see - ), 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 a valid container instance, - (see ), - return information about it. Otherwise, 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>