VirtualBox

source: vbox/trunk/include/VBox/HostServices/DragAndDropSvc.h

Last change on this file was 98103, checked in by vboxsync, 16 months ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 39.7 KB
Line 
1/* $Id: DragAndDropSvc.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * Drag and Drop service - Common header for host service and guest clients.
4 */
5
6/*
7 * Copyright (C) 2011-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37/**
38 * Protocol handling and notes:
39 * All client/server components should be backwards compatible.
40 *
41 ******************************************************************************
42 *
43 * Protocol changelog:
44 *
45 * Protocol v1 (VBox < 5.0, deprecated):
46 * | Initial implementation which only implemented host to guest transfers.
47 * | For file transfers all file information such as the file name and file size were
48 * transferred with every file data chunk being sent.
49 *
50 * Protocol v2 (VBox 5.0 - VBox 5.0.8, deprecated):
51 * + Added support for guest to host transfers.
52 * + Added protocol version support through VBOXDNDCONNECTMSG. The host takes the installed
53 * Guest Additions version as indicator which protocol to use for communicating with the guest.
54 * The guest itself uses VBOXDNDCONNECTMSG to report its supported protocol version to the DnD service.
55 *
56 * Protocol v3 (VBox 5.0.10 and up, deprecated):
57 * + Added VBOXDNDDISCONNECTMSG for being able to track client disconnects on host side (Main).
58 * + Added context IDs for every HGCM message. Not used yet and must be 0.
59 * + Added VBOXDNDSNDDATAHDR and VBOXDNDCBSNDDATAHDRDATA to support (simple) accounting of objects
60 * being transferred, along with supplying separate meta data size (which is part of the total size being sent).
61 * + Added new HOST_DND_FN_HG_SND_DATA_HDR + GUEST_DND_FN_GH_SND_DATA_HDR commands which now allow specifying an optional
62 * compression type and defining a checksum for the overall data transfer.
63 * + Enhannced VBOXDNDGHSENDDATAMSG to support (rolling) checksums for the supplied data block.
64 * + VBOXDNDHGSENDDATAMSG and VBOXDNDGHSENDDATAMSG can now contain an optional checksum for the current data block.
65 * | VBOXDNDHGSENDFILEDATAMSG and VBOXDNDGHSENDFILEDATAMSG are now sharing the same HGCM mesasge.
66 * - Removed unused HOST_DND_FN_GH_RECV_DIR, HOST_DND_FN_GH_RECV_FILE_DATA and HOST_DND_FN_GH_RECV_FILE_HDR commands.
67 *
68 * VBox 6.1.x and up, current:
69 * + Added GUEST_DND_FN_QUERY_FEATURES + GUEST_DND_FN_REPORT_FEATURES.
70 * - Protocol versioning support in VBOXDNDCONNECTMSG is now marked as being deprecated.
71 *
72 ** @todo:
73 * - Split up messages which use VBOXDNDHGACTIONMSG into own functions and remove parameters which
74 * are not actually needed / used by a function. Why does HOST_DND_FN_HG_EVT_MOVE need all the format stuff, for example?
75 */
76
77#ifndef VBOX_INCLUDED_HostServices_DragAndDropSvc_h
78#define VBOX_INCLUDED_HostServices_DragAndDropSvc_h
79#ifndef RT_WITHOUT_PRAGMA_ONCE
80# pragma once
81#endif
82
83#include <VBox/hgcmsvc.h>
84#include <VBox/VMMDevCoreTypes.h>
85#include <VBox/VBoxGuestCoreTypes.h>
86
87#include <VBox/GuestHost/DragAndDropDefs.h>
88
89namespace DragAndDropSvc {
90
91/******************************************************************************
92* Typedefs, constants and inlines *
93******************************************************************************/
94
95/**
96 * The service functions which are callable by host.
97 * Note: When adding new functions to this table, make sure that the actual ID
98 * does *not* overlap with the eGuestFn enumeration below!
99 */
100enum eHostFn
101{
102 /** The host sets a new DnD mode. */
103 HOST_DND_FN_SET_MODE = 100,
104 /** The host requests to cancel the current DnD operation on
105 * the guest side. This can happen on user request on the host's
106 * UI side or due to some host error which has happened.
107 *
108 * Note: This is a fire-and-forget message, as the host should
109 * not rely on an answer from the guest side in order to
110 * properly cancel the operation. */
111 HOST_DND_FN_CANCEL = 204,
112
113 /*
114 * Host -> Guest messages
115 */
116
117 /** The host enters the VM window for starting an actual
118 * DnD operation. */
119 HOST_DND_FN_HG_EVT_ENTER = 200,
120 /** The host's DnD cursor moves within the VM window. */
121 HOST_DND_FN_HG_EVT_MOVE = 201,
122 /** The host leaves the guest VM window. */
123 HOST_DND_FN_HG_EVT_LEAVE = 202,
124 /** The host issues a "drop" event, meaning that the host is
125 * ready to transfer data over to the guest. */
126 HOST_DND_FN_HG_EVT_DROPPED = 203,
127 /** The host sends the data header at the beginning of a (new)
128 * data transfer. */
129 HOST_DND_FN_HG_SND_DATA_HDR = 210,
130 /**
131 * The host sends the actual meta data, based on
132 * the format(s) specified by HOST_DND_FN_HG_EVT_ENTER.
133 *
134 * Protocol v1/v2: If the guest supplied buffer too small to send
135 * the actual data, the host will send a HOST_DND_FN_HG_SND_MORE_DATA
136 * message as follow-up.
137 * Protocol v3+: The incoming meta data size is specified upfront in the
138 * HOST_DND_FN_HG_SND_DATA_HDR message and must be handled accordingly.
139 */
140 HOST_DND_FN_HG_SND_DATA = 205,
141 /** The host sends more data in case the data did not entirely fit in
142 * the HOST_DND_FN_HG_SND_DATA message. */
143 /** @todo Deprecated function; do not use anymore. */
144 HOST_DND_FN_HG_SND_MORE_DATA = 206,
145 /** The host sends a directory entry to the guest. */
146 HOST_DND_FN_HG_SND_DIR = 207,
147 /** The host sends a file data chunk to the guest. */
148 HOST_DND_FN_HG_SND_FILE_DATA = 208,
149 /** The host sends a file header to the guest.
150 * Note: Only for protocol version 2 and up (>= VBox 5.0). */
151 HOST_DND_FN_HG_SND_FILE_HDR = 209,
152
153 /*
154 * Guest -> Host messages
155 */
156
157 /** The host asks the guest whether a DnD operation
158 * is in progress when the mouse leaves the guest window. */
159 HOST_DND_FN_GH_REQ_PENDING = 600,
160 /** The host informs the guest that a DnD drop operation
161 * has been started and that the host wants the data in
162 * a specific MIME type. */
163 HOST_DND_FN_GH_EVT_DROPPED = 601,
164 /** Blow the type up to 32-bit. */
165 HOST_DND_FN_32BIT_HACK = 0x7fffffff
166};
167
168/**
169 * The service functions which are called by guest.
170 * Note: When adding new functions to this table, make sure that the actual ID
171 * does *not* overlap with the eHostFn enumeration above!
172 */
173enum eGuestFn
174{
175 /**
176 * The guest sends a connection request to the HGCM service,
177 * along with some additional information like supported
178 * protocol version and flags.
179 * Note: New since protocol version 2. */
180 GUEST_DND_FN_CONNECT = 10,
181
182 /** The guest client disconnects from the HGCM service. */
183 GUEST_DND_FN_DISCONNECT = 11,
184
185 /** Report guest side feature flags and retrieve the host ones.
186 *
187 * Two 64-bit parameters are passed in from the guest with the guest features
188 * (VBOX_DND_GF_XXX), the host replies by replacing the parameter values with
189 * the host ones (VBOX_DND_HF_XXX).
190 *
191 * @retval VINF_SUCCESS on success.
192 * @retval VERR_INVALID_CLIENT_ID
193 * @retval VERR_WRONG_PARAMETER_COUNT
194 * @retval VERR_WRONG_PARAMETER_TYPE
195 * @since 6.1.x
196 */
197 GUEST_DND_FN_REPORT_FEATURES = 12,
198
199 /** Query the host ones feature masks.
200 *
201 * That way the guest (client) can get hold of the features from the host.
202 * Again, it is prudent to set the 127 bit and observe it being cleared on
203 * success, as older hosts might return success without doing anything.
204 *
205 * @retval VINF_SUCCESS on success.
206 * @retval VERR_INVALID_CLIENT_ID
207 * @retval VERR_WRONG_PARAMETER_COUNT
208 * @retval VERR_WRONG_PARAMETER_TYPE
209 * @since 6.1.x
210 */
211 GUEST_DND_FN_QUERY_FEATURES = 13,
212
213 /**
214 * The guest waits for a new message the host wants to process
215 * on the guest side. This can be a blocking call.
216 */
217 GUEST_DND_FN_GET_NEXT_HOST_MSG = 300,
218
219 /** Reports back an error to the host.
220 *
221 * Note: Don't change the ID to also support older hosts
222 * (was GUEST_DND_FN_GH_EVT_ERROR before < 7.0, only for G->H transfers).
223 *
224 * This was changed to GUEST_DND_FN_EVT_ERROR to be a generic event
225 * that also can be used for H->G transfers.
226 *
227 * @retval VINF_SUCCESS on success.
228 * @retval VERR_INVALID_CLIENT_ID
229 * @retval VERR_WRONG_PARAMETER_COUNT
230 * @retval VERR_WRONG_PARAMETER_TYPE
231 * @since 7.0.x
232 */
233 GUEST_DND_FN_EVT_ERROR = 502,
234
235 /*
236 * Host -> Guest operation messages.
237 */
238
239 /** The guest acknowledges that a pending DnD operation from the host
240 * can be dropped on the currently selected area on the guest. */
241 GUEST_DND_FN_HG_ACK_OP = 400,
242 /** The guest requests the actual DnD data to be sent from the host. */
243 GUEST_DND_FN_HG_REQ_DATA = 401,
244 /** The guest reports back its progress back to the host. */
245 GUEST_DND_FN_HG_EVT_PROGRESS = 402,
246
247 /*
248 * Guest -> Host operation messages.
249 */
250
251 /**
252 * The guests acknowledges that it currently has a drag'n drop
253 * operation in progress on the guest, which eventually could be
254 * dragged over to the host.
255 */
256 GUEST_DND_FN_GH_ACK_PENDING = 500,
257 /** The guest sends the data header at the beginning of a (new)
258 * data transfer. */
259 GUEST_DND_FN_GH_SND_DATA_HDR = 503,
260 /**
261 * The guest sends data of the requested format to the host. There can
262 * be more than one message if the actual data does not fit
263 * into one.
264 */
265 GUEST_DND_FN_GH_SND_DATA = 501,
266 /** The guest sends a directory entry to the host. */
267 GUEST_DND_FN_GH_SND_DIR = 700,
268 /** The guest sends file data to the host.
269 * Note: On protocol version 1 this also contains the file name
270 * and other attributes. */
271 GUEST_DND_FN_GH_SND_FILE_DATA = 701,
272 /** The guest sends a file header to the host, marking the
273 * beginning of a (new) file transfer.
274 * Note: Available since protocol version 2 (VBox 5.0). */
275 GUEST_DND_FN_GH_SND_FILE_HDR = 702,
276 /** Blow the type up to 32-bit. */
277 GUEST_DND_FN_32BIT_HACK = 0x7fffffff
278};
279
280/** @name VBOX_DND_GF_XXX - Guest features.
281 * @sa GUEST_DND_FN_REPORT_FEATURES
282 * @{ */
283/** No flags set. */
284#define VBOX_DND_GF_NONE 0
285/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
286 * correctly (old hosts might not). */
287#define VBOX_DND_GF_1_MUST_BE_ONE RT_BIT_64(63)
288/** @} */
289
290/** @name VBOX_DND_HF_XXX - Host features.
291 * @sa DND_GUEST_REPORT_FEATURES
292 * @{ */
293/** No flags set. */
294#define VBOX_DND_HF_NONE 0
295/** @} */
296
297/**
298 * DnD operation progress states.
299 */
300typedef enum DNDPROGRESS
301{
302 DND_PROGRESS_UNKNOWN = 0,
303 DND_PROGRESS_RUNNING = 1,
304 DND_PROGRESS_COMPLETE,
305 DND_PROGRESS_CANCELLED,
306 DND_PROGRESS_ERROR,
307 /** Blow the type up to 32-bit. */
308 DND_PROGRESS_32BIT_HACK = 0x7fffffff
309} DNDPROGRESS, *PDNDPROGRESS;
310
311#pragma pack (1)
312
313/*
314 * Host events
315 */
316
317/**
318 * Action message for telling the guest about the currently ongoing
319 * drag and drop action when entering the guest's area, moving around in it
320 * and dropping content into it from the host.
321 *
322 * Used by:
323 * HOST_DND_FN_HG_EVT_ENTER
324 * HOST_DND_FN_HG_EVT_MOVE
325 * HOST_DND_FN_HG_EVT_DROPPED
326 */
327typedef struct HGCMMsgHGAction
328{
329 VBGLIOCHGCMCALL hdr;
330
331 union
332 {
333 struct
334 {
335 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
336 HGCMFunctionParameter uX; /* OUT uint32_t */
337 HGCMFunctionParameter uY; /* OUT uint32_t */
338 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
339 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
340 HGCMFunctionParameter pvFormats; /* OUT ptr */
341 HGCMFunctionParameter cbFormats; /* OUT uint32_t */
342 } v1;
343 struct
344 {
345 /** Context ID. */
346 HGCMFunctionParameter uContext;
347 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
348 HGCMFunctionParameter uX; /* OUT uint32_t */
349 HGCMFunctionParameter uY; /* OUT uint32_t */
350 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
351 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
352 HGCMFunctionParameter pvFormats; /* OUT ptr */
353 HGCMFunctionParameter cbFormats; /* OUT uint32_t */
354 } v3;
355 } u;
356} HGCMMsgHGAction;
357
358/**
359 * Tells the guest that the host has left its drag and drop area on the guest.
360 *
361 * Used by:
362 * HOST_DND_FN_HG_EVT_LEAVE
363 */
364typedef struct HGCMMsgHGLeave
365{
366 VBGLIOCHGCMCALL hdr;
367 union
368 {
369 struct
370 {
371 /** Context ID. */
372 HGCMFunctionParameter uContext;
373 } v3;
374 } u;
375} HGCMMsgHGLeave;
376
377/**
378 * Tells the guest that the host wants to cancel the current drag and drop operation.
379 *
380 * Used by:
381 * HOST_DND_FN_HG_EVT_CANCEL
382 */
383typedef struct HGCMMsgHGCancel
384{
385 VBGLIOCHGCMCALL hdr;
386 union
387 {
388 struct
389 {
390 /** Context ID. */
391 HGCMFunctionParameter uContext;
392 } v3;
393 } u;
394} HGCMMsgHGCancel;
395
396/**
397 * Sends the header of an incoming (meta) data block.
398 *
399 * Used by:
400 * HOST_DND_FN_HG_SND_DATA_HDR
401 * GUEST_DND_FN_GH_SND_DATA_HDR
402 *
403 * New since protocol v3.
404 */
405typedef struct HGCMMsgHGSendDataHdr
406{
407 VBGLIOCHGCMCALL hdr;
408
409 /** Context ID. Unused at the moment. */
410 HGCMFunctionParameter uContext; /* OUT uint32_t */
411 /** Data transfer flags. Not yet used and must be 0. */
412 HGCMFunctionParameter uFlags; /* OUT uint32_t */
413 /** Screen ID where the data originates from. */
414 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
415 /** Total size (in bytes) to transfer. */
416 HGCMFunctionParameter cbTotal; /* OUT uint64_t */
417 /**
418 * Total meta data size (in bytes) to transfer.
419 * This size also is part of cbTotal already, so:
420 *
421 * cbTotal = cbMeta + additional size for files etc.
422 */
423 HGCMFunctionParameter cbMeta; /* OUT uint64_t */
424 /** Meta data format. */
425 HGCMFunctionParameter pvMetaFmt; /* OUT ptr */
426 /** Size (in bytes) of meta data format. */
427 HGCMFunctionParameter cbMetaFmt; /* OUT uint32_t */
428 /* Number of objects (files/directories) to transfer. */
429 HGCMFunctionParameter cObjects; /* OUT uint64_t */
430 /** Compression type. */
431 HGCMFunctionParameter enmCompression; /* OUT uint32_t */
432 /** Checksum type. */
433 HGCMFunctionParameter enmChecksumType; /* OUT uint32_t */
434 /** Checksum buffer for the entire data to be transferred. */
435 HGCMFunctionParameter pvChecksum; /* OUT ptr */
436 /** Size (in bytes) of checksum. */
437 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
438} HGCMMsgHGSendDataHdr;
439
440/**
441 * Sends a (meta) data block to the guest.
442 *
443 * Used by:
444 * HOST_DND_FN_HG_SND_DATA
445 */
446typedef struct HGCMMsgHGSendData
447{
448 VBGLIOCHGCMCALL hdr;
449
450 union
451 {
452 struct
453 {
454 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
455 HGCMFunctionParameter pvFormat; /* OUT ptr */
456 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
457 HGCMFunctionParameter pvData; /* OUT ptr */
458 HGCMFunctionParameter cbData; /* OUT uint32_t */
459 } v1;
460 /* No changes in v2. */
461 struct
462 {
463 /** Context ID. Unused at the moment. */
464 HGCMFunctionParameter uContext; /* OUT uint32_t */
465 /** Data block to send. */
466 HGCMFunctionParameter pvData; /* OUT ptr */
467 /** Size (in bytes) of data block to send. */
468 HGCMFunctionParameter cbData; /* OUT uint32_t */
469 /** Checksum of data block, based on the checksum
470 * type in the data header. Optional. */
471 HGCMFunctionParameter pvChecksum; /* OUT ptr */
472 /** Size (in bytes) of checksum to send. */
473 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
474 } v3;
475 } u;
476} HGCMMsgHGSendData;
477
478/**
479 * Sends more (meta) data in case the data didn't fit
480 * into the current XXX_DND_HG_SND_DATA message.
481 *
482 ** @todo Deprecated since protocol v3. Don't use! Will be removed.
483 *
484 * Used by:
485 * HOST_DND_FN_HG_SND_MORE_DATA
486 */
487typedef struct HGCMMsgHGSendMoreData
488{
489 VBGLIOCHGCMCALL hdr;
490
491 HGCMFunctionParameter pvData; /* OUT ptr */
492 HGCMFunctionParameter cbData; /* OUT uint32_t */
493} HGCMMsgHGSendMoreData;
494
495/**
496 * Directory entry event.
497 *
498 * Used by:
499 * HOST_DND_FN_HG_SND_DIR
500 * GUEST_DND_FN_GH_SND_DIR
501 */
502typedef struct HGCMMsgHGSendDir
503{
504 VBGLIOCHGCMCALL hdr;
505
506 union
507 {
508 struct
509 {
510 /** Directory name. */
511 HGCMFunctionParameter pvName; /* OUT ptr */
512 /** Size (in bytes) of directory name. */
513 HGCMFunctionParameter cbName; /* OUT uint32_t */
514 /** Directory mode. */
515 HGCMFunctionParameter fMode; /* OUT uint32_t */
516 } v1;
517 struct
518 {
519 /** Context ID. Unused at the moment. */
520 HGCMFunctionParameter uContext; /* OUT uint32_t */
521 /** Directory name. */
522 HGCMFunctionParameter pvName; /* OUT ptr */
523 /** Size (in bytes) of directory name. */
524 HGCMFunctionParameter cbName; /* OUT uint32_t */
525 /** Directory mode. */
526 HGCMFunctionParameter fMode; /* OUT uint32_t */
527 } v3;
528 } u;
529} HGCMMsgHGSendDir;
530
531/**
532 * File header message, marking the start of transferring a new file.
533 * Note: Only for protocol version 2 and up.
534 *
535 * Used by:
536 * HOST_DND_FN_HG_SND_FILE_HDR
537 * GUEST_DND_FN_GH_SND_FILE_HDR
538 */
539typedef struct HGCMMsgHGSendFileHdr
540{
541 VBGLIOCHGCMCALL hdr;
542
543 /** Context ID. Unused at the moment. */
544 HGCMFunctionParameter uContext; /* OUT uint32_t */
545 /** File path. */
546 HGCMFunctionParameter pvName; /* OUT ptr */
547 /** Size (in bytes) of file path. */
548 HGCMFunctionParameter cbName; /* OUT uint32_t */
549 /** Optional flags; unused at the moment. */
550 HGCMFunctionParameter uFlags; /* OUT uint32_t */
551 /** File creation mode. */
552 HGCMFunctionParameter fMode; /* OUT uint32_t */
553 /** Total size (in bytes). */
554 HGCMFunctionParameter cbTotal; /* OUT uint64_t */
555} HGCMMsgHGSendFileHdr;
556
557/**
558 * HG: File data (chunk) event.
559 *
560 * Used by:
561 * HOST_DND_FN_HG_SND_FILE
562 */
563typedef struct HGCMMsgHGSendFileData
564{
565 VBGLIOCHGCMCALL hdr;
566
567 union
568 {
569 /* Note: Protocol v1 sends the file name + file mode
570 * every time a file data chunk is being sent. */
571 struct
572 {
573 /** File name. */
574 HGCMFunctionParameter pvName; /* OUT ptr */
575 /** Size (in bytes) of file name. */
576 HGCMFunctionParameter cbName; /* OUT uint32_t */
577 /** Current data chunk. */
578 HGCMFunctionParameter pvData; /* OUT ptr */
579 /** Size (in bytes) of current data chunk. */
580 HGCMFunctionParameter cbData; /* OUT uint32_t */
581 /** File mode. */
582 HGCMFunctionParameter fMode; /* OUT uint32_t */
583 } v1;
584 struct
585 {
586 /** Note: pvName is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
587 /** Note: cbName is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
588 /** Context ID. Unused at the moment. */
589 HGCMFunctionParameter uContext; /* OUT uint32_t */
590 /** Current data chunk. */
591 HGCMFunctionParameter pvData; /* OUT ptr */
592 /** Size (in bytes) of current data chunk. */
593 HGCMFunctionParameter cbData; /* OUT uint32_t */
594 /** Note: fMode is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
595 } v2;
596 struct
597 {
598 /** Context ID. Unused at the moment. */
599 HGCMFunctionParameter uContext; /* OUT uint32_t */
600 /** Current data chunk. */
601 HGCMFunctionParameter pvData; /* OUT ptr */
602 /** Size (in bytes) of current data chunk. */
603 HGCMFunctionParameter cbData; /* OUT uint32_t */
604 /** Checksum of data block, based on the checksum
605 * type in the data header. Optional. */
606 HGCMFunctionParameter pvChecksum; /* OUT ptr */
607 /** Size (in bytes) of curren data chunk checksum. */
608 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
609 } v3;
610 } u;
611} HGCMMsgHGSendFileData;
612
613/**
614 * Asks the guest if a guest->host DnD operation is in progress.
615 *
616 * Used by:
617 * HOST_DND_FN_GH_REQ_PENDING
618 */
619typedef struct HGCMMsgGHReqPending
620{
621 VBGLIOCHGCMCALL hdr;
622
623 union
624 {
625 struct
626 {
627 /** Screen ID. */
628 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
629 } v1;
630 struct
631 {
632 /** Context ID. Unused at the moment. */
633 HGCMFunctionParameter uContext; /* OUT uint32_t */
634 /** Screen ID. */
635 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
636 } v3;
637 } u;
638} HGCMMsgGHReqPending;
639
640/**
641 * Tells the guest that the host has dropped the ongoing guest->host
642 * DnD operation on a valid target on the host.
643 *
644 * Used by:
645 * HOST_DND_FN_GH_EVT_DROPPED
646 */
647typedef struct HGCMMsgGHDropped
648{
649 VBGLIOCHGCMCALL hdr;
650
651 union
652 {
653 struct
654 {
655 /** Requested format for sending the data. */
656 HGCMFunctionParameter pvFormat; /* OUT ptr */
657 /** Size (in bytes) of requested format. */
658 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
659 /** Drop action peformed on the host. */
660 HGCMFunctionParameter uAction; /* OUT uint32_t */
661 } v1;
662 struct
663 {
664 /** Context ID. Unused at the moment. */
665 HGCMFunctionParameter uContext; /* OUT uint32_t */
666 /** Requested format for sending the data. */
667 HGCMFunctionParameter pvFormat; /* OUT ptr */
668 /** Size (in bytes) of requested format. */
669 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
670 /** Drop action peformed on the host. */
671 HGCMFunctionParameter uAction; /* OUT uint32_t */
672 } v3;
673 } u;
674} HGCMMsgGHDropped;
675
676/*
677 * Guest events
678 */
679
680/**
681 * Asks the host for the next command to process, along
682 * with the needed amount of parameters and an optional blocking
683 * flag.
684 *
685 * Used by:
686 * GUEST_DND_FN_GET_NEXT_HOST_MSG
687 */
688typedef struct HGCMMsgGetNext
689{
690 VBGLIOCHGCMCALL hdr;
691
692 /** Message ID. */
693 HGCMFunctionParameter uMsg; /* OUT uint32_t */
694 /** Number of parameters the message needs. */
695 HGCMFunctionParameter cParms; /* OUT uint32_t */
696 /** Whether or not to block (wait) for a
697 * new message to arrive. */
698 HGCMFunctionParameter fBlock; /* OUT uint32_t */
699} HGCMMsgGetNext;
700
701/**
702 * Guest connection request. Used to tell the DnD protocol
703 * version to the (host) service.
704 *
705 * Used by:
706 * GUEST_DND_FN_CONNECT
707 */
708typedef struct HGCMMsgConnect
709{
710 VBGLIOCHGCMCALL hdr;
711
712 union
713 {
714 struct
715 {
716 /** Protocol version to use.
717 * Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
718 HGCMFunctionParameter uProtocol; /* OUT uint32_t */
719 /** Connection flags. Optional. */
720 HGCMFunctionParameter uFlags; /* OUT uint32_t */
721 } v2;
722 struct
723 {
724 /** Context ID. Unused at the moment. */
725 HGCMFunctionParameter uContext; /* OUT uint32_t */
726 /** Protocol version to use.
727 * Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
728 HGCMFunctionParameter uProtocol; /* OUT uint32_t */
729 /** Connection flags. Optional. */
730 HGCMFunctionParameter uFlags; /* OUT uint32_t */
731 } v3;
732 } u;
733} HGCMMsgConnect;
734
735/**
736 * Acknowledges a host operation along with the allowed
737 * action(s) on the guest.
738 *
739 * Used by:
740 * GUEST_DND_FN_HG_ACK_OP
741 */
742typedef struct HGCMMsgHGAck
743{
744 VBGLIOCHGCMCALL hdr;
745
746 union
747 {
748 struct
749 {
750 HGCMFunctionParameter uAction; /* OUT uint32_t */
751 } v1;
752 struct
753 {
754 /** Context ID. Unused at the moment. */
755 HGCMFunctionParameter uContext; /* OUT uint32_t */
756 HGCMFunctionParameter uAction; /* OUT uint32_t */
757 } v3;
758 } u;
759} HGCMMsgHGAck;
760
761/**
762 * Requests data to be sent to the guest.
763 *
764 * Used by:
765 * GUEST_DND_FN_HG_REQ_DATA
766 */
767typedef struct HGCMMsgHGReqData
768{
769 VBGLIOCHGCMCALL hdr;
770
771 union
772 {
773 struct
774 {
775 HGCMFunctionParameter pvFormat; /* OUT ptr */
776 } v1;
777 struct
778 {
779 /** Context ID. Unused at the moment. */
780 HGCMFunctionParameter uContext; /* OUT uint32_t */
781 HGCMFunctionParameter pvFormat; /* OUT ptr */
782 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
783 } v3;
784 } u;
785} HGCMMsgHGReqData;
786
787typedef struct HGCMMsgHGProgress
788{
789 VBGLIOCHGCMCALL hdr;
790
791 union
792 {
793 struct
794 {
795 HGCMFunctionParameter uStatus; /* OUT uint32_t */
796 HGCMFunctionParameter uPercent; /* OUT uint32_t */
797 HGCMFunctionParameter rc; /* OUT uint32_t */
798 } v1;
799 struct
800 {
801 /** Context ID. Unused at the moment. */
802 HGCMFunctionParameter uContext; /* OUT uint32_t */
803 HGCMFunctionParameter uStatus; /* OUT uint32_t */
804 HGCMFunctionParameter uPercent; /* OUT uint32_t */
805 HGCMFunctionParameter rc; /* OUT uint32_t */
806 } v3;
807 } u;
808} HGCMMsgHGProgress;
809
810/**
811 * Acknowledges a pending guest drag and drop event to the host.
812 *
813 * Used by:
814 * GUEST_DND_FN_GH_ACK_PENDING
815 */
816typedef struct HGCMMsgGHAckPending
817{
818 VBGLIOCHGCMCALL hdr;
819
820 union
821 {
822 struct
823 {
824 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
825 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
826 HGCMFunctionParameter pvFormats; /* OUT ptr */
827 } v1;
828 struct
829 {
830 /** Context ID. Unused at the moment. */
831 HGCMFunctionParameter uContext; /* OUT uint32_t */
832 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
833 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
834 HGCMFunctionParameter pvFormats; /* OUT ptr */
835 HGCMFunctionParameter cbFormats; /* OUT uint32_t */
836 } v3;
837 } u;
838} HGCMMsgGHAckPending;
839
840/**
841 * Sends the header of an incoming data block
842 * to the host.
843 *
844 * Used by:
845 * GUEST_DND_FN_GH_SND_DATA_HDR
846 *
847 * New since protocol v3.
848 */
849typedef struct HGCMMsgHGSendDataHdr HGCMMsgGHSendDataHdr;
850
851/**
852 * Sends a (meta) data block to the host.
853 *
854 * Used by:
855 * GUEST_DND_FN_GH_SND_DATA
856 */
857typedef struct HGCMMsgGHSendData
858{
859 VBGLIOCHGCMCALL hdr;
860
861 union
862 {
863 struct
864 {
865 HGCMFunctionParameter pvData; /* OUT ptr */
866 /** Total bytes to send. This can be more than
867 * the data block specified in pvData above, e.g.
868 * when sending over file objects afterwards. */
869 HGCMFunctionParameter cbTotalBytes; /* OUT uint32_t */
870 } v1;
871 struct
872 {
873 /** Context ID. Unused at the moment. */
874 HGCMFunctionParameter uContext; /* OUT uint32_t */
875 /** Data block to send. */
876 HGCMFunctionParameter pvData; /* OUT ptr */
877 /** Size (in bytes) of data block to send. */
878 HGCMFunctionParameter cbData; /* OUT uint32_t */
879 /** (Rolling) Checksum, based on checksum type in data header. */
880 HGCMFunctionParameter pvChecksum; /* OUT ptr */
881 /** Size (in bytes) of checksum. */
882 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
883 } v3;
884 } u;
885} HGCMMsgGHSendData;
886
887/**
888 * Sends a directory entry to the host.
889 *
890 * Used by:
891 * GUEST_DND_FN_GH_SND_DIR
892 */
893typedef struct HGCMMsgHGSendDir HGCMMsgGHSendDir;
894
895/**
896 * Sends a file header to the host.
897 *
898 * Used by:
899 * GUEST_DND_FN_GH_SND_FILE_HDR
900 *
901 * New since protocol v2.
902 */
903typedef struct HGCMMsgHGSendFileHdr HGCMMsgGHSendFileHdr;
904
905/**
906 * Sends file data to the host.
907 *
908 * Used by:
909 * GUEST_DND_FN_GH_SND_FILE_DATA
910 */
911typedef struct HGCMMsgHGSendFileData HGCMMsgGHSendFileData;
912
913/**
914 * Sends a guest error event to the host.
915 *
916 * Used by:
917 * GUEST_DND_FN_GH_EVT_ERROR
918 */
919typedef struct HGCMMsgGHError
920{
921 VBGLIOCHGCMCALL hdr;
922
923 union
924 {
925 struct
926 {
927 HGCMFunctionParameter rc; /* OUT uint32_t */
928 } v1;
929 struct
930 {
931 /** Context ID. Unused at the moment. */
932 HGCMFunctionParameter uContext; /* OUT uint32_t */
933 HGCMFunctionParameter rc; /* OUT uint32_t */
934 } v3;
935 } u;
936} HGCMMsgGHError;
937
938#pragma pack()
939
940/** Builds a callback magic out of the function ID and the version
941 * of the callback data. */
942#define VBOX_DND_CB_MAGIC_MAKE(uFn, uVer) \
943 RT_MAKE_U32(uVer, uFn)
944
945/*
946 * Callback magics.
947 */
948enum eDnDCallbackMagics
949{
950 CB_MAGIC_DND_CONNECT = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_CONNECT, 0),
951 CB_MAGIC_DND_REPORT_FEATURES = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_REPORT_FEATURES, 0),
952 CB_MAGIC_DND_EVT_ERROR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_EVT_ERROR, 0),
953 CB_MAGIC_DND_HG_GET_NEXT_HOST_MSG = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GET_NEXT_HOST_MSG, 0),
954 CB_MAGIC_DND_HG_ACK_OP = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_ACK_OP, 0),
955 CB_MAGIC_DND_HG_REQ_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_REQ_DATA, 0),
956 CB_MAGIC_DND_HG_EVT_PROGRESS = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_EVT_PROGRESS, 0),
957 CB_MAGIC_DND_GH_ACK_PENDING = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_ACK_PENDING, 0),
958 CB_MAGIC_DND_GH_SND_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DATA, 0),
959 CB_MAGIC_DND_GH_SND_DATA_HDR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DATA_HDR, 0),
960 CB_MAGIC_DND_GH_SND_DIR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DIR, 0),
961 CB_MAGIC_DND_GH_SND_FILE_HDR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_FILE_HDR, 0),
962 CB_MAGIC_DND_GH_SND_FILE_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_FILE_DATA, 0)
963};
964
965typedef struct VBOXDNDCBHEADERDATA
966{
967 /** Magic number to identify the structure. */
968 uint32_t uMagic;
969 /** Context ID to identify callback data. */
970 uint32_t uContextID;
971} VBOXDNDCBHEADERDATA, *PVBOXDNDCBHEADERDATA;
972
973typedef struct VBOXDNDCBCONNECTDATA
974{
975 /** Callback data header. */
976 VBOXDNDCBHEADERDATA hdr;
977 /** Protocol version to use.
978 * Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
979 uint32_t uProtocolVersion;
980 /** Connection flags; currently unused. */
981 uint32_t fFlags;
982} VBOXDNDCBCONNECTDATA, *PVBOXDNDCBCONNECTDATA;
983
984typedef struct VBOXDNDCBREPORTFEATURESDATA
985{
986 /** Callback data header. */
987 VBOXDNDCBHEADERDATA hdr;
988 uint32_t fGuestFeatures0;
989} VBOXDNDCBREPORTFEATURESDATA, *PVBOXDNDCBREPORTFEATURESDATA;
990
991typedef struct VBOXDNDCBDISCONNECTMSGDATA
992{
993 /** Callback data header. */
994 VBOXDNDCBHEADERDATA hdr;
995} VBOXDNDCBDISCONNECTMSGDATA, *PVBOXDNDCBDISCONNECTMSGDATA;
996
997typedef struct VBOXDNDCBHGGETNEXTHOSTMSG
998{
999 /** Callback data header. */
1000 VBOXDNDCBHEADERDATA hdr;
1001 uint32_t uMsg;
1002 uint32_t cParms;
1003} VBOXDNDCBHGGETNEXTHOSTMSG, *PVBOXDNDCBHGGETNEXTHOSTMSG;
1004
1005typedef struct VBOXDNDCBHGGETNEXTHOSTMSGDATA
1006{
1007 /** Callback data header. */
1008 VBOXDNDCBHEADERDATA hdr;
1009 uint32_t uMsg;
1010 uint32_t cParms;
1011 PVBOXHGCMSVCPARM paParms;
1012} VBOXDNDCBHGGETNEXTHOSTMSGDATA, *PVBOXDNDCBHGGETNEXTHOSTMSGDATA;
1013
1014typedef struct VBOXDNDCBHGACKOPDATA
1015{
1016 /** Callback data header. */
1017 VBOXDNDCBHEADERDATA hdr;
1018 uint32_t uAction;
1019} VBOXDNDCBHGACKOPDATA, *PVBOXDNDCBHGACKOPDATA;
1020
1021typedef struct VBOXDNDCBHGREQDATADATA
1022{
1023 /** Callback data header. */
1024 VBOXDNDCBHEADERDATA hdr;
1025 char *pszFormat;
1026 uint32_t cbFormat;
1027} VBOXDNDCBHGREQDATADATA, *PVBOXDNDCBHGREQDATADATA;
1028
1029typedef struct VBOXDNDCBHGEVTPROGRESSDATA
1030{
1031 /** Callback data header. */
1032 VBOXDNDCBHEADERDATA hdr;
1033 uint32_t uPercentage;
1034 uint32_t uStatus;
1035 uint32_t rc;
1036} VBOXDNDCBHGEVTPROGRESSDATA, *PVBOXDNDCBHGEVTPROGRESSDATA;
1037
1038typedef struct VBOXDNDCBGHACKPENDINGDATA
1039{
1040 /** Callback data header. */
1041 VBOXDNDCBHEADERDATA hdr;
1042 uint32_t uDefAction;
1043 uint32_t uAllActions;
1044 char *pszFormat;
1045 uint32_t cbFormat;
1046} VBOXDNDCBGHACKPENDINGDATA, *PVBOXDNDCBGHACKPENDINGDATA;
1047
1048/**
1049 * Data header.
1050 * New since protocol v3.
1051 */
1052typedef struct VBOXDNDDATAHDR
1053{
1054 /** Data transfer flags. Not yet used and must be 0. */
1055 uint32_t uFlags;
1056 /** Screen ID where the data originates from. */
1057 uint32_t uScreenId;
1058 /** Total size (in bytes) to transfer. */
1059 uint64_t cbTotal;
1060 /** Meta data size (in bytes) to transfer.
1061 * This size also is part of cbTotal already. */
1062 uint32_t cbMeta;
1063 /** Meta format buffer. */
1064 void *pvMetaFmt;
1065 /** Size (in bytes) of meta format buffer. */
1066 uint32_t cbMetaFmt;
1067 /** Number of objects (files/directories) to transfer. */
1068 uint64_t cObjects;
1069 /** Compression type. Currently unused, so specify 0.
1070 **@todo Add IPRT compression type enumeration as soon as it's available. */
1071 uint32_t enmCompression;
1072 /** Checksum type. Currently unused, so specify RTDIGESTTYPE_INVALID. */
1073 RTDIGESTTYPE enmChecksumType;
1074 /** The actual checksum buffer for the entire data to be transferred,
1075 * based on enmChksumType. If RTDIGESTTYPE_INVALID is specified,
1076 * no checksum is being used and pvChecksum will be NULL. */
1077 void *pvChecksum;
1078 /** Size (in bytes) of checksum. */
1079 uint32_t cbChecksum;
1080} VBOXDNDDATAHDR, *PVBOXDNDSNDDATAHDR;
1081
1082/* New since protocol v3. */
1083typedef struct VBOXDNDCBSNDDATAHDRDATA
1084{
1085 /** Callback data header. */
1086 VBOXDNDCBHEADERDATA hdr;
1087 /** Actual header data. */
1088 VBOXDNDDATAHDR data;
1089} VBOXDNDCBSNDDATAHDRDATA, *PVBOXDNDCBSNDDATAHDRDATA;
1090
1091typedef struct VBOXDNDSNDDATA
1092{
1093 union
1094 {
1095 struct
1096 {
1097 /** Data block buffer. */
1098 void *pvData;
1099 /** Size (in bytes) of data block. */
1100 uint32_t cbData;
1101 /** Total metadata size (in bytes). This is transmitted
1102 * with every message because the size can change. */
1103 uint32_t cbTotalSize;
1104 } v1;
1105 /* Protocol v2: No changes. */
1106 struct
1107 {
1108 /** Data block buffer. */
1109 void *pvData;
1110 /** Size (in bytes) of data block. */
1111 uint32_t cbData;
1112 /** (Rolling) Checksum. Not yet implemented. */
1113 void *pvChecksum;
1114 /** Size (in bytes) of checksum. Not yet implemented. */
1115 uint32_t cbChecksum;
1116 } v3;
1117 } u;
1118} VBOXDNDSNDDATA, *PVBOXDNDSNDDATA;
1119
1120typedef struct VBOXDNDCBSNDDATADATA
1121{
1122 /** Callback data header. */
1123 VBOXDNDCBHEADERDATA hdr;
1124 /** Actual data. */
1125 VBOXDNDSNDDATA data;
1126} VBOXDNDCBSNDDATADATA, *PVBOXDNDCBSNDDATADATA;
1127
1128typedef struct VBOXDNDCBSNDDIRDATA
1129{
1130 /** Callback data header. */
1131 VBOXDNDCBHEADERDATA hdr;
1132 /** Directory path. */
1133 char *pszPath;
1134 /** Size (in bytes) of path. */
1135 uint32_t cbPath;
1136 /** Directory creation mode. */
1137 uint32_t fMode;
1138} VBOXDNDCBSNDDIRDATA, *PVBOXDNDCBSNDDIRDATA;
1139
1140/* Note: Only for protocol version 2 and up (>= VBox 5.0). */
1141typedef struct VBOXDNDCBSNDFILEHDRDATA
1142{
1143 /** Callback data header. */
1144 VBOXDNDCBHEADERDATA hdr;
1145 /** File path (name). */
1146 char *pszFilePath;
1147 /** Size (in bytes) of file path. */
1148 uint32_t cbFilePath;
1149 /** Total size (in bytes) of this file. */
1150 uint64_t cbSize;
1151 /** File (creation) mode. */
1152 uint32_t fMode;
1153 /** Additional flags. Not used at the moment. */
1154 uint32_t fFlags;
1155} VBOXDNDCBSNDFILEHDRDATA, *PVBOXDNDCBSNDFILEHDRDATA;
1156
1157typedef struct VBOXDNDCBSNDFILEDATADATA
1158{
1159 /** Callback data header. */
1160 VBOXDNDCBHEADERDATA hdr;
1161 /** Current file data chunk. */
1162 void *pvData;
1163 /** Size (in bytes) of current data chunk. */
1164 uint32_t cbData;
1165 union
1166 {
1167 struct
1168 {
1169 /** File path (name). */
1170 char *pszFilePath;
1171 /** Size (in bytes) of file path. */
1172 uint32_t cbFilePath;
1173 /** File (creation) mode. */
1174 uint32_t fMode;
1175 } v1;
1176 /* Protocol v2 + v3: Have the file attributes (name, size, mode, ...)
1177 in the VBOXDNDCBSNDFILEHDRDATA structure. */
1178 struct
1179 {
1180 /** Checksum for current file data chunk. */
1181 void *pvChecksum;
1182 /** Size (in bytes) of current data chunk. */
1183 uint32_t cbChecksum;
1184 } v3;
1185 } u;
1186} VBOXDNDCBSNDFILEDATADATA, *PVBOXDNDCBSNDFILEDATADATA;
1187
1188typedef struct VBOXDNDCBEVTERRORDATA
1189{
1190 /** Callback data header. */
1191 VBOXDNDCBHEADERDATA hdr;
1192 int32_t rc;
1193} VBOXDNDCBEVTERRORDATA, *PVBOXDNDCBEVTERRORDATA;
1194
1195} /* namespace DragAndDropSvc */
1196
1197#endif /* !VBOX_INCLUDED_HostServices_DragAndDropSvc_h */
1198
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use