#3981 more subsystems docs

Xpra-org · Sep 2, 2023 · 8c7b3c9 · 8c7b3c9
1 parent 64e78b5
commit 8c7b3c9
Show file tree

Hide file tree

Showing 7 changed files with 170 additions and 39 deletions.
diff --git a/docs/Network/Protocol.md b/docs/Network/Protocol.md
@@ -105,7 +105,7 @@ Floating point numbers and `None` values can be encoded but should be avoided.
 ## Hello
 
 The `hello` packet is the initial packet used as handshake.
-The connection is now fully established until both ends have received a `hello` packet.
+The connection is not fully established until both ends have received a `hello` packet.
 
 The `hello` packet contains a single argument which is a dictionary
 containing all the capabilities advertised by the peer.

diff --git a/docs/Subsystems/Audio.md b/docs/Subsystems/Audio.md
@@ -2,12 +2,21 @@
 
 For usage related information, see [audio feature](../Features/Audio.md).
 
+
+## Implementations
+
+| Component         | Link                                                             |
+|-------------------|------------------------------------------------------------------|
+| client            | [xpra.client.mixins.audio](../../xpra/client/mixins/audio.py) |
+| client connection | [xpra.server.source.audio](../../xpra/server/source/audio.py)      |
+| server            | [xpra.server.mixins.audio](../../xpra/server/mixins/audio.py)      |
+
 ## Common
 
 [xpra.audio](https://github.com/Xpra-org/xpra/tree/master/xpra/audio/) contains the components used for capturing and playing back audio streams
 using [GStreamer](https://gstreamer.freedesktop.org/).  
 In order to avoid interfering with the performance of the main thread,
-all audio processing is done in a separate process.
+all audio processing is done in a separate process.  
 For historical reasons, this is done using a [subprocess wrapper](https://github.com/Xpra-org/xpra/tree/master/xpra/audio/wrapper.py)
 rather than the builtin [multiprocessing](https://docs.python.org/3/library/multiprocessing.html) module.
 
@@ -36,20 +45,6 @@ You can run [xpra.audio.gstreamer_util](../../xpra/audio/gstreamer_util.py) to s
 encoders and decoders are available on the system.
 
 
-## Client
-
-[xpra.client.mixins.audio](../../xpra/client/mixins/audio.py)
-
-
-## Server
-
-[xpra.server.mixins.audio](../../xpra/server/mixins/audio.py)
-
-## Client connection
-
-[xpra.server.source.audio](../../xpra/server/source/audio.py)
-
-
 ## Network Packets
 
 This protocol is identical in both directions.

diff --git a/docs/Subsystems/Clipboard.md b/docs/Subsystems/Clipboard.md
@@ -2,8 +2,18 @@
 
 For usage related information, see [clipboard feature](../Features/Clipboard.md).
 
+
 ## Implementations
 
+| Component         | Link                                                             |
+|-------------------|------------------------------------------------------------------|
+| client            | [xpra.client.mixins.clipboard](../../xpra/client/mixins/clipboard.py) |
+| client connection | [xpra.server.source.clipboard](../../xpra/server/source/clipboard.py)      |
+| server            | [xpra.server.mixins.clipboard](../../xpra/server/mixins/clipboard.py)      |
+
+
+## Platforms
+
 [xpra.clipboard](https://github.com/Xpra-org/xpra/tree/master/xpra/clipboard/) contains the platform independent base class
 used by all the backends.
 It contains common features such as basic configuration, scheduling, filtering, etc.
@@ -16,10 +26,11 @@ It contains common features such as basic configuration, scheduling, filtering,
 | others   | [xpra.gtk_common.gtk_clipboard](../../xpra/gtk_common/gtk_clipboard.py)           |
 
 
+
 ## Capabilities
 
 The client and server should expose the following capabilities in their `hello` packet
-with the `clipboard` prefix:
+using the `clipboard` prefix:
 
 | Capability          | Value                       | Information                                                                          |
 |---------------------|-----------------------------|--------------------------------------------------------------------------------------|
@@ -34,20 +45,6 @@ Notes:
 * `MacOS` clients set the `want_targets` flag
 * both `MacOS` and `MS Windows` clients set the `greedy` flag
 
-## Client
-
-[xpra.client.mixins.clipboard](../../xpra/client/mixins/clipboard.py)
-
-
-## Server
-
-[xpra.server.mixins.clipboard](../../xpra/server/mixins/clipboard.py)
-
-## Client connection
-
-[xpra.server.source.clipboard](../../xpra/server/source/clipboard.py)
-
-
 ## Network Packets
 
 This protocol is identical in both directions,

diff --git a/docs/Subsystems/Logging.md b/docs/Subsystems/Logging.md
@@ -0,0 +1,33 @@
+# Logging
+
+For usage related information, see [logging usage](../Usage/Logging.md).
+
+The `logging` modules are used for sending log events to the peer.
+
+It is generally used for sending client log messages to the server,
+but it can also be used in the opposite direction.
+
+## Implementations
+
+| Component         | Link                                                                            |
+|-------------------|---------------------------------------------------------------------------------|
+| client            | [xpra.client.mixins.remote_logging](../../xpra/client/mixins/remote_logging.py) |
+| client connection | none                                                                            |
+| server            | [xpra.server.mixins.logging](../../xpra/server/mixins/logging.py)               |
+
+
+## Capabilities
+
+The server exposes two flags using the `remote-logging` capability prefix:
+* `receive` if the server is able to receive log events from the client
+* `send` if the server is able to send its log events to the client
+
+## Network Packets
+
+| Packet Type       | Arguments                                                                        | Direction        |
+|-------------------|----------------------------------------------------------------------------------|------------------|
+| `logging`         | `level` : integer<br/>`message` : string or list of strings<br/>`time` : integer | both             |
+| `logging-control` | `action` : string, only either `start` or `stop`                                 | client to server |
+
+The `logging` packets can be sent to the server if it exposes the `receive` capability,
+or sent from the server to the client following a `start` `logging-control` request.
diff --git a/docs/Subsystems/MMAP.md b/docs/Subsystems/MMAP.md
@@ -1,3 +1,44 @@
 # MMAP
 
-TBD
+The `mmap` modules are used for fast memory transfers
+between client and server when both reside on the same host.
+
+## Implementations
+
+| Component         | Link                                                        |
+|-------------------|-------------------------------------------------------------|
+| client            | [xpra.client.mixins.mmap](../../xpra/client/mixins/mmap.py) |
+| client connection | [xpra.server.source.mmap](../../xpra/server/source/mmap.py) |
+| server            | [xpra.server.mixins.mmap](../../xpra/server/mixins/mmap.py) |
+
+
+## Capabilities
+
+The client and server should expose the following capabilities in their `hello` packet
+using the `clipboard` prefix.
+
+The client creates an `mmap` backing file,
+writes a random token at a random position within this mmap area
+and sends the following capabilities:
+
+| Capability    | Value                                |
+|---------------|--------------------------------------|
+| `file`        | path to the mmap backing file        |
+| `size`        | size of the mmap area                |
+| `token`       | random token value generated         |
+| `token_index` | position where the token was written |
+| `token_bytes` | length of the token in bytes         |
+
+The server should attempt to open the mmap file specified,
+and verify that the token is found.
+
+To use this mmap file, it must write a new token
+and return this information to the client.
+(using the same format, excluding the `file` and `size` that the client has already specified)
+
+The client then verifies that the mmap file can be used bi-directionally.
+
+
+## Network Packets
+
+There are no specific `mmap` packets used, `mmap` is used as an [encoding](../Usage/Encodings.md).
diff --git a/docs/Subsystems/Notifications.md b/docs/Subsystems/Notifications.md
@@ -0,0 +1,59 @@
+# Notifications
+
+For usage related information, see [notitications feature](../Features/Notifications.md).
+
+
+## Implementations
+
+| Component         | Link                                                                          |
+|-------------------|-------------------------------------------------------------------------------|
+| client            | [xpra.client.mixins.notifications](../../xpra/client/mixins/notifications.py) |
+| client connection | [xpra.server.source.notification](../../xpra/server/source/notification.py)   |
+| server            | [xpra.server.mixins.notification](../../xpra/server/mixins/notification.py)   |
+
+
+## Capabilities
+
+The server exposes a single `enabled` flag using the `notifications` capability prefix.
+
+
+## Network Packets
+
+| Packet Type            | Arguments                                                        | Direction        |
+|------------------------|------------------------------------------------------------------|------------------|
+| `notify_show`          | notification data (see below)                                    | server to client |
+| `notify_close`         | `notification id` : integer                                      | server to client |
+| `notification-close`   | `notification id` : integer, `reason` : integer, `text` : string | client to server |
+| `notification-action`  | `notification id` : integer, `action_key` : integer              | client to server |
+| `set-notify`           | `enabled` : boolean                                              | client to server |
+
+
+### Notification data
+
+| Argument                    | Type                    | Notes                            |
+|-----------------------------|-------------------------|----------------------------------|
+| `dbus_id`                   | `integer`               | 0 if unused                      |
+| `notification id`           | `integer`               | should be unique                 |                
+| `applciation name`          | `string`                |                                  |
+| `replaced notification id`  | `integer`               | 0 if unused                      |
+| `application icon`          | `string`                | the name of the icon to show     |
+| `summary`                   | `string`                | the title of the notification    |
+| `body`                      | `string`                | the contents of the notification |
+| `timeout`                   | `integer`               | in seconds, zero if unused       |
+| `icon data`                 | `list` (optional)       | the icon data to use, see below  |
+| `actions`                   | `list`  (optional)      | see below                        |
+| `hints`                     | `dictionary` (optional) | see below                        |
+
+### Notification Icon
+
+The icon data is a list or tuple with 4 elements:
+
+| Argument | Type      |
+|----------|-----------|
+| `format` | `string`  |
+| `width`  | `integer` |
+| `height` | `integer` |
+| `data`   | `bytes`   |
+
+The only format which is guaranteed to be supported is `png`.
+Other formats should not be used.
diff --git a/docs/Subsystems/README.md b/docs/Subsystems/README.md
@@ -1,12 +1,18 @@
 # Subsystems
 
-This documentation refers to individual features,
-it links to the implementation and technical documentation of each subsystem.
+This documentation refers to individual protocol features,
+it links to the implementation and technical documentation for each subsystem.
 
+Most modules are optional, see [security considerations](../Usage/Security.md).
 
-| Subsystem                   | [Client Module](../../xpra/client/mixins/)         | [Server Module](../../xpra/server/mixins)          | [Client Connection Module](../../xpra/server/source/)            |
-|-----------------------------|----------------------------------------------------|----------------------------------------------------|------------------------------------------------------------------|
-| [Audio](./Audio.md)         | [clipboard](../../xpra/client/mixins/audio.py)     | [audio](../../xpra/server/mixins/audio.py)     | [audio](../../xpra/server/source/audio.py) |
-| [Clipboard](./Clipboard.md) | [clipboard](../../xpra/client/mixins/clipboard.py) | [clipboard](../../xpra/server/mixins/clipboard.py) | [clipboard](../../xpra/server/source/clipboard.py) |
-
+* Client Module: feature implementation loaded by the client, it interfaces with the corresponding "Client Connection Module" on the server side
+* Client Connection Module: for each connection to a client, the server will instantiate this module
+* Server Module: feature implemented by the server, it may interact with multiple "Client Connection Modules"
 
+| Subsystem                           | [Client Module](../../xpra/client/mixins/)                   | [Server Module](../../xpra/server/mixins)          | [Client Connection Module](../../xpra/server/source/)    | User Documentation                                      |
+|-------------------------------------|--------------------------------------------------------------|----------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------|
+| [Audio](./Audio.md)                 | [audio](../../xpra/client/mixins/audio.py)                   | [audio](../../xpra/server/mixins/audio.py)         | [audio](../../xpra/server/source/audio.py)               | [audio feature](../Features/Audio.md)                   |
+| [Clipboard](./Clipboard.md)         | [clipboard](../../xpra/client/mixins/clipboard.py)           | [clipboard](../../xpra/server/mixins/clipboard.py) | [clipboard](../../xpra/server/source/clipboard.py)       | [clipboard feature](../Features/Clipboard.md)           |
+| [MMAP](./MMAP.md)                   | [mmap](../../xpra/client/mixins/mmap.py)                     | [mmap](../../xpra/server/mixins/mmap.py)           | [mmap](../../xpra/server/source/mmap.py)                 | enabled automatically                            |
+| [Logging](./Logging.md)             | [remote-logging](../../xpra/client/mixins/remote_logging.py) | [logging](../../xpra/server/mixins/logging.py)     | none                                                     | [logging usage](../Usage/Logging.md)                    |
+| [Notifications](./Notifications.md) | [notifications](../../xpra/client/mixins/notifications.py)  | [logging](../../xpra/server/mixins/notification.py) | [notification](../../xpra/server/source/notification.py) | [notifications feature](../Features/Notifications.md)   |