Changeset 81329 in vbox for trunk/src/VBox/HostServices/SharedClipboard
- Timestamp:
- Oct 17, 2019 8:20:06 PM (5 years ago)
- svn:sync-xref-src-repo-rev:
- 134042
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/VBox/HostServices/SharedClipboard/VBoxSharedClipboardSvc.cpp
r81286 r81329 19 19 /** @page pg_hostclip The Shared Clipboard Host Service 20 20 * 21 * The shared clipboard host service provides a proxy between the host's 22 * clipboard and a similar proxy running on a guest. The service is split 23 * into a platform-independent core and platform-specific backends. The 24 * service defines two communication protocols - one to communicate with the 25 * clipboard service running on the guest, and one to communicate with the 26 * backend. These will be described in a very skeletal fashion here. 21 * The shared clipboard host service is the host half of the clibpoard proxying 22 * between the host and the guest. The guest parts live in VBoxClient, VBoxTray 23 * and VBoxService depending on the OS, with code shared between host and guest 24 * under src/VBox/GuestHost/SharedClipboard/. 25 * 26 * The service is split into a platform-independent core and platform-specific 27 * backends. The service defines two communication protocols - one to 28 * communicate with the clipboard service running on the guest, and one to 29 * communicate with the backend. These will be described in a very skeletal 30 * fashion here. 31 * 32 * r=bird: The "two communication protocols" does not seems to be factual, there 33 * is only one protocol, the first one mentioned. It cannot be backend 34 * specific, because the guest/host protocol is platform and backend agnostic in 35 * nature. You may call it versions, but I take a great dislike to "protocol 36 * versions" here, as you've just extended the existing protocol with a feature 37 * that allows to transfer files and directories too. See @bugref{9437#c39}. 38 * 27 39 * 28 40 * @section sec_hostclip_guest_proto The guest communication protocol 29 41 * 30 * The guest clipboard service communicates with the host service viaHGCM31 * (the host service runs as an HGCM service). The guest clipboard must32 * connect to the host service before all else (Windows hosts currently only33 * support one simultaneous connection). Once it has connected, it can send34 * HGCM messages to the host services, some of which will receive replies from35 * the host. The host can only reply to a guest message, it cannot initiate36 * a ny communication. The guest can in theory send any number of messages in37 * parallel (see the descriptions of the messages for the practice), and the38 * host will receive these in sequence, and may reply to them at once39 * (releasing the caller in the guest) or defer the reply until later.42 * The guest clipboard service communicates with the host service over HGCM 43 * (the host is a HGCM service). HGCM is connection based, so the guest side 44 * has to connect before anything else can be done. (Windows hosts currently 45 * only support one simultaneous connection.) Once it has connected, it can 46 * send messages to the host services, some of which will receive immediate 47 * replies from the host, others which will block till a reply becomes 48 * available. The latter is because HGCM does't allow the host to initiate 49 * communication, it must be guest triggered. The HGCM service is single 50 * threaded, so it doesn't matter if the guest tries to send lots of requests in 51 * parallel, the service will process them one at the time. 40 52 * 41 53 * There are currently four messages defined. The first is 42 * VBOX_SHCL_ FN_GET_HOST_MSG, which waits for a message from the43 * host. If a host message is sent while the guest is not waiting, it will be44 * queued until the guest requests it. The host code only supports a single45 * simultaneous VBOX_SHCL_FN_GET_HOST_MSG call from oneguest.46 * 47 * The second guest message is VBOX_SHCL_ FN_FORMATS, which tells54 * VBOX_SHCL_GUEST_FN_MSG_GET / VBOX_SHCL_GUEST_FN_GET_HOST_MSG_OLD, which waits 55 * for a message from the host. If a host message is sent while the guest is 56 * not waiting, it will be queued until the guest requests it. The host code 57 * only supports a single simultaneous GET call from one client guest. 58 * 59 * The second guest message is VBOX_SHCL_GUEST_FN_FORMATS_REPORT, which tells 48 60 * the host that the guest has new clipboard data available. The third is 49 * VBOX_SHCL_ FN_READ_DATA, which asks the host to send its50 * clipboard data and waits until it arrives. The host supports at most one51 * simultaneous VBOX_SHCL_FN_READ_DATA call from a guest - if a52 * second call is made before the first has returned, the first will be53 * aborted.54 * 55 * The last guest message is VBOX_SHCL_FN_WRITE_DATA, which is56 * used to send the contents of the guest clipboard to the host. This call57 * should be used after the host has requested data from the guest.61 * VBOX_SHCL_GUEST_FN_DATA_READ, which asks the host to send its clipboard data 62 * and waits until it arrives. The host supports at most one simultaneous 63 * VBOX_SHCL_GUEST_FN_DATA_READ call from a guest - if a second call is made 64 * before the first has returned, the first will be aborted. 65 * 66 * The last guest message is VBOX_SHCL_GUEST_FN_DATA_WRITE, which is used to 67 * send the contents of the guest clipboard to the host. This call should be 68 * used after the host has requested data from the guest. 69 * 58 70 * 59 71 * @section sec_hostclip_backend_proto The communication protocol with the … … 80 92 * 81 93 * Also see the protocol changelog at VBoxShClSvc.h. 94 * 82 95 * 83 96 * @section sec_uri_intro Transferring files … … 122 135 * @todo We might use some VFS / container (IPRT?) for this instead of the 123 136 * host's file system directly? 137 * bird> Yes, but may take some work as we don't have the pick and choose 138 * kind of VFS containers implemented yet. 124 139 * 125 140 * @section sec_transfer_structure Transfer handling structure … … 129 144 * duplication where applicable. 130 145 * 131 * Per HGCM client there is a so-called "transfer context", which in turn can have 132 * one or mulitple so-called "Shared Clipboard transfer" objects. At the moment we only support 133 * on concurrent Shared Clipboard transfer per transfer context. It's being used for reading from a 134 * source or writing to destination, depening on its direction. An Shared Clipboard transfer 135 * can have optional callbacks which might be needed by various implementations. 136 * Also, transfers optionally can run in an asynchronous thread to prevent 137 * blocking the UI while running. 138 * 139 * An Shared Clipboard transfer can maintain its own clipboard area; for the host service such 140 * a clipboard area is coupled to a clipboard area registered or attached with 141 * VBoxSVC. This is needed because multiple transfers from multiple VMs (n:n) can 142 * rely on the same clipboard area, so there needs a master keeping tracking of 143 * a clipboard area. To minimize IPC traffic only the minimum de/attaching is done 144 * at the moment. A clipboard area gets cleaned up (i.e. physically deleted) if 145 * no references are held to it anymore, or if VBoxSVC goes down. 146 * Per HGCM client there is a so-called "transfer context", which in turn can 147 * have one or mulitple so-called "Shared Clipboard transfer" objects. At the 148 * moment we only support on concurrent Shared Clipboard transfer per transfer 149 * context. It's being used for reading from a source or writing to destination, 150 * depening on its direction. An Shared Clipboard transfer can have optional 151 * callbacks which might be needed by various implementations. Also, transfers 152 * optionally can run in an asynchronous thread to prevent blocking the UI while 153 * running. 154 * 155 * A Shared Clipboard transfer can maintain its own clipboard area; for the host 156 * service such a clipboard area is coupled to a clipboard area registered or 157 * attached with VBoxSVC. This is needed because multiple transfers from 158 * multiple VMs (n:n) can rely on the same clipboard area, so there needs a 159 * master keeping tracking of a clipboard area. To minimize IPC traffic only the 160 * minimum de/attaching is done at the moment. A clipboard area gets cleaned up 161 * (i.e. physically deleted) if no references are held to it anymore, or if 162 * VBoxSVC goes down. 146 163 * 147 164 * @section sec_transfer_providers Transfer providers
Note:
See TracChangeset
for help on using the changeset viewer.
