USB portal (cont.) #1354
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| env: | ||
| IMAGE_TAG: 20241024-3 | ||
|
|
||
| on: | ||
| workflow_call: | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| <?xml version="1.0"?> | ||
| <!-- | ||
| Copyright (C) 2023 GNOME Foundation Inc. | ||
|
|
||
| This library is free software; you can redistribute it and/or | ||
| modify it under the terms of the GNU Lesser General Public | ||
| License as published by the Free Software Foundation; either | ||
| version 2 of the License, or (at your option) any later version. | ||
|
|
||
| This library is distributed in the hope that it will be useful, | ||
| but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| Lesser General Public License for more details. | ||
|
|
||
| You should have received a copy of the GNU Lesser General Public | ||
| License along with this library. If not, see <http://www.gnu.org/licenses/>. | ||
|
|
||
| Author: Georges Basile Stavracas Neto <[email protected]> | ||
| --> | ||
|
|
||
| <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> | ||
| <!-- | ||
| org.freedesktop.impl.portal.Usb: | ||
| @short_description: USB portal backend interface | ||
|
|
||
| This portal lets applications register global shortcuts so they can | ||
| act regardless of the system state upon an input event. | ||
|
|
||
| This documentation describes version 1 of this interface. | ||
| --> | ||
| <interface name="org.freedesktop.impl.portal.Usb"> | ||
|
|
||
| <!-- | ||
| AcquireDevices: | ||
| @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call | ||
| @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`. | ||
| @app_id: App id of the application | ||
| @devices: Array of identifier, device information, and access options for each device | ||
| @options: Vardict with optional further information | ||
| @response: Numeric Request response | ||
| @results: Vardict with the results of the call | ||
|
|
||
| Selects the devices to open. | ||
|
|
||
| Each element of the @devices array contains the ID, information and | ||
| access options for each device the app wants to acquire. | ||
| The supported keys in the information vardict are the same as the | ||
| keys in the @devices vardict of | ||
| :ref:`org.freedesktop.portal.Usb.EnumerateDevices`. | ||
|
|
||
| The supported keys in the access options vardict are: | ||
|
|
||
| * ``writable`` (``b``) | ||
|
|
||
| Whether the device will be opened in read-write or read-only mode. | ||
| Default: False | ||
|
|
||
| There are no supported keys in the @options vardict. | ||
|
|
||
| The following results get returned via the @results vardict: | ||
|
|
||
| * ``devices`` (``a(sa{sv})``) | ||
|
|
||
| An array of identifier and access options which is a subset of | ||
| what was passed in via @devices. | ||
| --> | ||
| <method name="AcquireDevices"> | ||
| <arg type="o" name="handle" direction="in"/> | ||
| <arg type="s" name="parent_window" direction="in"/> | ||
| <arg type="s" name="app_id" direction="in"/> | ||
| <arg type="a(sa{sv}a{sv})" name="devices" direction="in"/> | ||
| <annotation name="org.qtproject.QtDBus.QtTypeName.In4" value="QVariantMap"/> | ||
| <arg type="a{sv}" name="options" direction="in"/> | ||
| <arg type="u" name="response" direction="out"/> | ||
| <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/> | ||
| <arg type="a{sv}" name="results" direction="out"/> | ||
| </method> | ||
|
|
||
| <property name="version" type="u" access="read"/> | ||
| </interface> | ||
| </node> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,243 @@ | ||
| <?xml version="1.0"?> | ||
| <!-- | ||
| Copyright (C) 2020 Endless OS Foundation LLC | ||
| 2023 GNOME Foundation Inc. | ||
|
|
||
| This library is free software; you can redistribute it and/or | ||
| modify it under the terms of the GNU Lesser General Public | ||
| License as published by the Free Software Foundation; either | ||
| version 2 of the License, or (at your option) any later version. | ||
|
|
||
| This library is distributed in the hope that it will be useful, | ||
| but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| Lesser General Public License for more details. | ||
|
|
||
| You should have received a copy of the GNU Lesser General Public | ||
| License along with this library. If not, see <http://www.gnu.org/licenses/>. | ||
|
|
||
| Author: Georges Basile Stavracas Neto <[email protected]> | ||
| Ryan Gonzalez <[email protected]> | ||
| --> | ||
|
|
||
| <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> | ||
| <!-- | ||
| org.freedesktop.portal.Usb: | ||
| @short_description: Portal for USB device access | ||
|
|
||
| This interface lets sandboxed applications monitor and request | ||
| access to connected USB devices. | ||
|
|
||
| Applications should prefer specialized portals for specific | ||
| device types, such as the Camera portal for cameras. | ||
|
|
||
| This documentation describes version 1 of this interface. | ||
| --> | ||
| <interface name="org.freedesktop.portal.Usb"> | ||
|
|
||
| <!-- | ||
| CreateSession: | ||
| @options: Vardict with optional further information | ||
| @session_handle: Object path for the session. | ||
|
|
||
| Creates an USB monitoring session. This is only necessary to | ||
| receive device events, like device being plugged or unplugged. | ||
|
|
||
| Supported keys in the @options vardict include: | ||
|
|
||
| * ``session_handle_token`` (``s``) | ||
|
|
||
| A string that will be used as the last element of the session handle. Must be a valid | ||
| object path element. See the #org.freedesktop.portal.Session documentation for | ||
| more information about the session handle. | ||
| --> | ||
| <method name="CreateSession"> | ||
| <arg type="a{sv}" name="options" direction="in"/> | ||
| <arg type="o" name="session_handle" direction="out"/> | ||
| </method> | ||
|
|
||
| <!-- | ||
| EnumerateDevices: | ||
| @options: Vardict with optional further information. There is currently | ||
| no option supported. | ||
|
|
||
| Enumerates all connected USB devices that this application has permission | ||
| to see. | ||
|
|
||
| The following results are returned in the @device vardict: | ||
|
|
||
| * ``id`` (``s``) | ||
|
|
||
| Each element of the @devices array contains the device ID, and a | ||
| device information vardict with the following keys: | ||
|
|
||
| * ``parent`` (``s``) | ||
|
|
||
| Device ID of the parent device. | ||
|
|
||
| * ``readable`` (``b``) | ||
|
|
||
| Whether the device can be opened for reading with | ||
| org.freedesktop.portal.Usb.AcquireDevices(). If not present, then | ||
| it should be assumed to be false. | ||
|
|
||
| * ``writable`` (``b``) | ||
|
|
||
| Whether the device can be opened for writing with | ||
| org.freedesktop.portal.Usb.AcquireDevices(). If not present, then | ||
| it should be assumed to be false. | ||
|
|
||
| * ``device-file`` (``s``) | ||
|
|
||
| A string path to the device node inside the /dev filesystem. | ||
|
|
||
| * ``properties`` (``a{sv}``) | ||
|
|
||
| A list of udev properties that this device has. These properties | ||
|
There was a problem hiding this comment. I'm really worried about this. It essentially makes udev a stable API even though it really is not. |
||
| are not parsed in any way by the portal, it is up to apps to parse | ||
| them. | ||
| --> | ||
| <method name="EnumerateDevices"> | ||
| <arg type="a{sv}" name="options" direction="in"/> | ||
| <arg type="a(sa{sv})" name="devices" direction="out"/> | ||
| </method> | ||
|
|
||
| <!-- | ||
| AcquireDevices: | ||
| @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`. | ||
| @devices: Array of device identifiers and access options | ||
| @options: Vardict with optional further information | ||
| @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call | ||
|
|
||
| Request to acquires (i.e. open) the given device nodes. The | ||
| process of acquiring is finished by calling | ||
| `FinishAcquireDevices` after the request emitted a `Success` | ||
| response. | ||
|
|
||
| Each element of the @devices array contains the device ID, and an | ||
| access option vardict with the following keys: | ||
|
|
||
| * ``writable`` (``b``) | ||
|
|
||
| Whether the device will be opened in read-write or read-only mode. | ||
| Default: False | ||
|
|
||
| Supported keys in the @options vardict include: | ||
|
|
||
| * ``handle_token`` (``s``) | ||
|
|
||
| A string that will be used as the last element of the @handle. Must be a valid | ||
| object path element. See the :ref:`org.freedesktop.portal.Request` documentation | ||
| for more information about the @handle. | ||
|
|
||
| The #org.freedesktop.portal.Request::Response signal is emitted without | ||
| any extra information. | ||
| --> | ||
| <method name="AcquireDevices"> | ||
| <arg type="s" name="parent_window" direction="in"/> | ||
| <arg type="a(sa{sv})" name="devices" direction="in"/> | ||
| <arg type="a{sv}" name="options" direction="in"/> | ||
| <arg type="o" name="handle" direction="out"/> | ||
| </method> | ||
|
|
||
| <!-- | ||
| FinishAcquireDevices: | ||
| @handle: The request object path for the acquisition to finish | ||
| @options: Vardict with optional further information | ||
| @results: Array of device ids, and the result of the access | ||
| @finished: Whether all device results were reported | ||
|
|
||
| Retrieves the file descriptors of the devices requested during | ||
| org.freedesktop.portal.Usb.AcquireDevices(). The file | ||
| descriptors remain usable until the underlying device is | ||
| removed, they are released with `ReleaseDevices`, the dbus | ||
| connections is closed, or the portal revokes the file | ||
| descriptor which can happen at any point. Devices which are | ||
| not needed anymore should be passed to `ReleaseDevices`. | ||
|
|
||
| If not all devices could be send, @finished will be false and | ||
| org.freedesktop.portal.Usb.FinishAcquireDevices must be called again | ||
| until @finished is true, before calling | ||
| org.freedesktop.portal.Usb.AcquireDevices again. | ||
|
|
||
| This method can only be called once for a given token, and only | ||
| after calling org.freedesktop.portal.Usb.AcquireDevices(). | ||
|
|
||
| Each element of the @results array contains the device ID, and | ||
| a vardict with the following keys: | ||
|
|
||
| * ``success`` (``b``) | ||
|
|
||
| Whether the device access was successful or not. | ||
|
|
||
| * ``fd`` (``h``) | ||
|
|
||
| The file descriptor representing the device. The file | ||
| descriptor is meant to be passed on to the USB library. | ||
|
|
||
| Only present if this was a successful device access. | ||
|
|
||
| * ``error`` (``s``) | ||
|
|
||
| Error message describing why accessing the device was not | ||
| successful. Only present if this was an failed device access. | ||
|
|
||
| There are no supported keys in the @options vardict. | ||
| --> | ||
| <method name="FinishAcquireDevices"> | ||
| <arg type="o" name="handle" direction="in"/> | ||
| <arg type="a{sv}" name="options" direction="in"/> | ||
| <arg type="a(sa{sv})" name="results" direction="out"/> | ||
| <arg type="b" name="finished" direction="out"/> | ||
| </method> | ||
|
|
||
| <!-- | ||
| ReleaseDevices: | ||
| @devices: Array of device identifiers | ||
| @options: Vardict with optional further information | ||
|
|
||
| Releases previously acquired devices. The file descriptors of | ||
| thoses devices might become unusable as a result of this. | ||
|
|
||
| Each element of the @devices array contains the device ID of the device. | ||
|
|
||
| There are no supported keys in the @options vardict. | ||
| --> | ||
| <method name="ReleaseDevices"> | ||
|
There was a problem hiding this comment. Should probably say something about the relation to the session and connection. I assume closing the session or connection implicitly also releases all devices? There was a problem hiding this comment. Eh, there is no session involved with acquiring and releasing devices, only a connection. The question still remains: what happens when the connection is closed. Same as release? Nothing? There was a problem hiding this comment. when the dbus connection is closed all the devices are removed (ie released) There was a problem hiding this comment. I think my suggestion on |
||
| <arg type="as" name="devices" direction="in"/> | ||
| <arg type="a{sv}" name="options" direction="in"/> | ||
| </method> | ||
|
|
||
| <!-- | ||
| DeviceEvents: | ||
| @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object | ||
| @events: A list of events which occured. | ||
|
|
||
| The DeviceEvents signal is emitted when one or more USB devices have | ||
| been added, changed, or removed. This signal is only emitted for active | ||
| sessions created with org.freedesktop.portal.Usb.CreateSession(). | ||
|
|
||
| Each element of the @events array is composed of the following fields: | ||
|
|
||
| * ``action`` (``s``) | ||
|
|
||
| Type of event that occurred. One of "add", "change", or "remove". | ||
|
There was a problem hiding this comment. What happens when one has acquired a device and it got removed? Is the fd still usable? Only sometimes? We don't have a mechanism for revoking the fd so a real device unplug will result in a remove with the fd becoming unusable but when the user wants to revoke a device, we can't do anything with the existing fd on the client and so it won't be. There was a problem hiding this comment. I think my suggestion on FinishAcquireDevices would resolve this thread as well. |
||
|
|
||
| * ``id`` (``s``) | ||
|
|
||
| Device ID that the event occurred on. | ||
|
|
||
| * ``device`` (``a{sv}``) | ||
|
|
||
| Device properties attached to the ID. See | ||
| org.freedesktop.portal.Usb.EnumerateDevices() for a list of all | ||
| the properties that may be present in the vardict. | ||
| --> | ||
| <signal name="DeviceEvents"> | ||
| <arg type="o" name="session_handle" direction="out"/> | ||
| <arg type="a(ssa{sv})" name="events" direction="out"/> | ||
| </signal> | ||
|
|
||
| <property name="version" type="u" access="read"/> | ||
| </interface> | ||
| </node> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What use is a device which can not be read from?
AcquireDevicesalso doesn't have areadableonly awritable. Pretty sure this should just be removed.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Until very recently it would have listed the devices even if it couldn't access them.
See #1354 (comment)
It is devices that can be enumerated after all.