Changeset 80469 in vbox for trunk/src/VBox/HostServices

Timestamp:

Aug 28, 2019 10:50:23 AM (5 years ago)

Author:

vboxsync

Message:

Shared Clipboard/URI: Docs.

File:

• trunk/src/VBox/HostServices/SharedClipboard/VBoxSharedClipboardSvc.cpp (modified) (6 diffs)

trunk/src/VBox/HostServices/SharedClipboard/VBoxSharedClipboardSvc.cpp

@@ -67 +67 @@
  *                                      platform-specific backend
  *
- * This section may be written in the future :)
- *
- * @section sec_uri_intro               Transferring files.
+ * The initial protocol implementation (called protocol v0) was very simple,
+ * and could only handle simple data (like copied text and so on).
+ *
+ * Since VBox 6.0 a newer protocol (v1) has been established to also support
+ * file transfers. This protocol does not rely on the old ReportMsg() / ReturnMsg()
+ * mechanism anymore and uses a (per-client) message queue instead
+ * (see VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG_OLD vs. VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG).
+ *
+ * The protocol also support out-of-order messages by using so-called "context IDs",
+ * which are generated by the host. A context ID consists of a so-called "source event ID"
+ * and a so-called "event ID". Each HGCM client has an own, random, source event ID and
+ * generates non-deterministic event IDs so that the guest side does not known what
+ * comes next; the guest side has to reply with the same conext ID which was sent by
+ * the host request.
+ *
+ * @section sec_uri_intro               Transferring files
  *
  * Since VBox x.x.x transferring files via Shared Clipboard is supported.
  * See the VBOX_WITH_SHARED_CLIPBOARD_URI_LIST define for supported / enabled
- * platforms.
+ * platforms. This is called "URI transfers".
  *
  * Copying files / directories from guest A to guest B requires the host
@@ -111 +124 @@
  *       host's file system directly?
  *
- * @section sec_uri_structure           URI handling structure.
+ * @section sec_uri_structure           URI handling structure
  *
  * All structures / classes are designed for running on both, on the guest
@@ -133 +146 @@
  * no references are held to it  anymore, or if VBoxSVC goes down.
  *
- * @section sec_uri_providers           URI providers.
+ * @section sec_uri_providers           URI providers
  *
  * For certain implementations (for example on Windows guests / hosts, using
@@ -141 +154 @@
  * the rest of the code stays the same.
  *
- * @section sec_uri_protocol            URI protocol.
+ * @section sec_uri_protocol            URI protocol
  *
  * The host service issues commands which the guest has to respond with an own
@@ -147 +160 @@
  * directories and open/close/read/write file system objects.
  *
- * The protocol does not rely on the old ReportMsg() / ReturnMsg() mechanism anymore
- * and uses a (per-client) message queue instead (see VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG_OLD
- * vs. VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG).
- *
  * Note that this is different from the DnD approach, as Shared Clipboard transfers
  * need to be deeper integrated within the host / guest OS (i.e. for progress UI),
  * and this might require non-monolithic / random access APIs to achieve.
- *
- * One transfer always is handled by an own (HGCM) client, so for multiple transfers
- * at the same time, multiple clients (client IDs) are being used. How this transfer
- * is implemented on the guest (and / or host) side depends upon the actual
- * implementation, e.g. via an own thread per transfer (see ClipboardStreamImpl-win.cpp
- * for example).
  *
  * As there can be multiple file system objects (fs objects) selected for transfer,
@@ -167 +170 @@
  * provider provides appropriate interface for this, even if not all implementations
  * might need this mechanism.
+ *
+ * An URI transfer has three stages:
+ *  - 1. Announcement: An URI transfer-compatible format (currently only one format available)
+ *          has been announced, the destination side creates a transfer object, which then,
+ *          depending on the actual implementation, can be used to tell the OS that
+ *          there is URI (file) data available.
+ *          At this point this just acts as a (kind-of) promise to the OS that we
+ *          can provide (file) data at some later point in time.
+ *
+ *  - 2. Initialization: As soon as the OS requests the (file) data, mostly triggered
+ *          by the user starting a paste operation (CTRL + V), the transfer get initialized
+ *          on the destination side, which in turn lets the source know that a transfer
+ *          is going to happen.
+ *
+ *  - 3. Transfer: At this stage the actual transfer from source to the destination takes
+ *          place. How the actual transfer is structurized (e.g. which files / directories
+ *          are transferred in which order) depends on the destination implementation. This
+ *          is necessary in order to fulfill requirements on the destination side with
+ *          regards to ETA calculation or other dependencies.
+ *          Both sides can abort or cancel the transfer at any time.
  */