VirtualBox

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

Last change on this file since 96429 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 39.3 KB
Line 
1/* $Id: DragAndDropSvc.h 96407 2022-08-22 17:43:14Z vboxsync $ */
2/** @file
3 * Drag and Drop service - Common header for host service and guest clients.
4 */
5
6/*
7 * Copyright (C) 2011-2022 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 /*
220 * Host -> Guest operation messages.
221 */
222
223 /** The guest acknowledges that a pending DnD operation from the host
224 * can be dropped on the currently selected area on the guest. */
225 GUEST_DND_FN_HG_ACK_OP = 400,
226 /** The guest requests the actual DnD data to be sent from the host. */
227 GUEST_DND_FN_HG_REQ_DATA = 401,
228 /** The guest reports back its progress back to the host. */
229 GUEST_DND_FN_HG_EVT_PROGRESS = 402,
230
231 /*
232 * Guest -> Host operation messages.
233 */
234
235 /**
236 * The guests acknowledges that it currently has a drag'n drop
237 * operation in progress on the guest, which eventually could be
238 * dragged over to the host.
239 */
240 GUEST_DND_FN_GH_ACK_PENDING = 500,
241 /** The guest sends the data header at the beginning of a (new)
242 * data transfer. */
243 GUEST_DND_FN_GH_SND_DATA_HDR = 503,
244 /**
245 * The guest sends data of the requested format to the host. There can
246 * be more than one message if the actual data does not fit
247 * into one.
248 */
249 GUEST_DND_FN_GH_SND_DATA = 501,
250 /** The guest reports an error back to the host. */
251 GUEST_DND_FN_GH_EVT_ERROR = 502,
252 /** The guest sends a directory entry to the host. */
253 GUEST_DND_FN_GH_SND_DIR = 700,
254 /** The guest sends file data to the host.
255 * Note: On protocol version 1 this also contains the file name
256 * and other attributes. */
257 GUEST_DND_FN_GH_SND_FILE_DATA = 701,
258 /** The guest sends a file header to the host, marking the
259 * beginning of a (new) file transfer.
260 * Note: Available since protocol version 2 (VBox 5.0). */
261 GUEST_DND_FN_GH_SND_FILE_HDR = 702,
262 /** Blow the type up to 32-bit. */
263 GUEST_DND_FN_32BIT_HACK = 0x7fffffff
264};
265
266/** @name VBOX_DND_GF_XXX - Guest features.
267 * @sa GUEST_DND_FN_REPORT_FEATURES
268 * @{ */
269/** No flags set. */
270#define VBOX_DND_GF_NONE 0
271/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
272 * correctly (old hosts might not). */
273#define VBOX_DND_GF_1_MUST_BE_ONE RT_BIT_64(63)
274/** @} */
275
276/** @name VBOX_DND_HF_XXX - Host features.
277 * @sa DND_GUEST_REPORT_FEATURES
278 * @{ */
279/** No flags set. */
280#define VBOX_DND_HF_NONE 0
281/** @} */
282
283/**
284 * DnD operation progress states.
285 */
286typedef enum DNDPROGRESS
287{
288 DND_PROGRESS_UNKNOWN = 0,
289 DND_PROGRESS_RUNNING = 1,
290 DND_PROGRESS_COMPLETE,
291 DND_PROGRESS_CANCELLED,
292 DND_PROGRESS_ERROR,
293 /** Blow the type up to 32-bit. */
294 DND_PROGRESS_32BIT_HACK = 0x7fffffff
295} DNDPROGRESS, *PDNDPROGRESS;
296
297#pragma pack (1)
298
299/*
300 * Host events
301 */
302
303/**
304 * Action message for telling the guest about the currently ongoing
305 * drag and drop action when entering the guest's area, moving around in it
306 * and dropping content into it from the host.
307 *
308 * Used by:
309 * HOST_DND_FN_HG_EVT_ENTER
310 * HOST_DND_FN_HG_EVT_MOVE
311 * HOST_DND_FN_HG_EVT_DROPPED
312 */
313typedef struct HGCMMsgHGAction
314{
315 VBGLIOCHGCMCALL hdr;
316
317 union
318 {
319 struct
320 {
321 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
322 HGCMFunctionParameter uX; /* OUT uint32_t */
323 HGCMFunctionParameter uY; /* OUT uint32_t */
324 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
325 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
326 HGCMFunctionParameter pvFormats; /* OUT ptr */
327 HGCMFunctionParameter cbFormats; /* OUT uint32_t */
328 } v1;
329 struct
330 {
331 /** Context ID. */
332 HGCMFunctionParameter uContext;
333 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
334 HGCMFunctionParameter uX; /* OUT uint32_t */
335 HGCMFunctionParameter uY; /* OUT uint32_t */
336 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
337 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
338 HGCMFunctionParameter pvFormats; /* OUT ptr */
339 HGCMFunctionParameter cbFormats; /* OUT uint32_t */
340 } v3;
341 } u;
342} HGCMMsgHGAction;
343
344/**
345 * Tells the guest that the host has left its drag and drop area on the guest.
346 *
347 * Used by:
348 * HOST_DND_FN_HG_EVT_LEAVE
349 */
350typedef struct HGCMMsgHGLeave
351{
352 VBGLIOCHGCMCALL hdr;
353 union
354 {
355 struct
356 {
357 /** Context ID. */
358 HGCMFunctionParameter uContext;
359 } v3;
360 } u;
361} HGCMMsgHGLeave;
362
363/**
364 * Tells the guest that the host wants to cancel the current drag and drop operation.
365 *
366 * Used by:
367 * HOST_DND_FN_HG_EVT_CANCEL
368 */
369typedef struct HGCMMsgHGCancel
370{
371 VBGLIOCHGCMCALL hdr;
372 union
373 {
374 struct
375 {
376 /** Context ID. */
377 HGCMFunctionParameter uContext;
378 } v3;
379 } u;
380} HGCMMsgHGCancel;
381
382/**
383 * Sends the header of an incoming (meta) data block.
384 *
385 * Used by:
386 * HOST_DND_FN_HG_SND_DATA_HDR
387 * GUEST_DND_FN_GH_SND_DATA_HDR
388 *
389 * New since protocol v3.
390 */
391typedef struct HGCMMsgHGSendDataHdr
392{
393 VBGLIOCHGCMCALL hdr;
394
395 /** Context ID. Unused at the moment. */
396 HGCMFunctionParameter uContext; /* OUT uint32_t */
397 /** Data transfer flags. Not yet used and must be 0. */
398 HGCMFunctionParameter uFlags; /* OUT uint32_t */
399 /** Screen ID where the data originates from. */
400 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
401 /** Total size (in bytes) to transfer. */
402 HGCMFunctionParameter cbTotal; /* OUT uint64_t */
403 /**
404 * Total meta data size (in bytes) to transfer.
405 * This size also is part of cbTotal already, so:
406 *
407 * cbTotal = cbMeta + additional size for files etc.
408 */
409 HGCMFunctionParameter cbMeta; /* OUT uint64_t */
410 /** Meta data format. */
411 HGCMFunctionParameter pvMetaFmt; /* OUT ptr */
412 /** Size (in bytes) of meta data format. */
413 HGCMFunctionParameter cbMetaFmt; /* OUT uint32_t */
414 /* Number of objects (files/directories) to transfer. */
415 HGCMFunctionParameter cObjects; /* OUT uint64_t */
416 /** Compression type. */
417 HGCMFunctionParameter enmCompression; /* OUT uint32_t */
418 /** Checksum type. */
419 HGCMFunctionParameter enmChecksumType; /* OUT uint32_t */
420 /** Checksum buffer for the entire data to be transferred. */
421 HGCMFunctionParameter pvChecksum; /* OUT ptr */
422 /** Size (in bytes) of checksum. */
423 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
424} HGCMMsgHGSendDataHdr;
425
426/**
427 * Sends a (meta) data block to the guest.
428 *
429 * Used by:
430 * HOST_DND_FN_HG_SND_DATA
431 */
432typedef struct HGCMMsgHGSendData
433{
434 VBGLIOCHGCMCALL hdr;
435
436 union
437 {
438 struct
439 {
440 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
441 HGCMFunctionParameter pvFormat; /* OUT ptr */
442 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
443 HGCMFunctionParameter pvData; /* OUT ptr */
444 HGCMFunctionParameter cbData; /* OUT uint32_t */
445 } v1;
446 /* No changes in v2. */
447 struct
448 {
449 /** Context ID. Unused at the moment. */
450 HGCMFunctionParameter uContext; /* OUT uint32_t */
451 /** Data block to send. */
452 HGCMFunctionParameter pvData; /* OUT ptr */
453 /** Size (in bytes) of data block to send. */
454 HGCMFunctionParameter cbData; /* OUT uint32_t */
455 /** Checksum of data block, based on the checksum
456 * type in the data header. Optional. */
457 HGCMFunctionParameter pvChecksum; /* OUT ptr */
458 /** Size (in bytes) of checksum to send. */
459 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
460 } v3;
461 } u;
462} HGCMMsgHGSendData;
463
464/**
465 * Sends more (meta) data in case the data didn't fit
466 * into the current XXX_DND_HG_SND_DATA message.
467 *
468 ** @todo Deprecated since protocol v3. Don't use! Will be removed.
469 *
470 * Used by:
471 * HOST_DND_FN_HG_SND_MORE_DATA
472 */
473typedef struct HGCMMsgHGSendMoreData
474{
475 VBGLIOCHGCMCALL hdr;
476
477 HGCMFunctionParameter pvData; /* OUT ptr */
478 HGCMFunctionParameter cbData; /* OUT uint32_t */
479} HGCMMsgHGSendMoreData;
480
481/**
482 * Directory entry event.
483 *
484 * Used by:
485 * HOST_DND_FN_HG_SND_DIR
486 * GUEST_DND_FN_GH_SND_DIR
487 */
488typedef struct HGCMMsgHGSendDir
489{
490 VBGLIOCHGCMCALL hdr;
491
492 union
493 {
494 struct
495 {
496 /** Directory name. */
497 HGCMFunctionParameter pvName; /* OUT ptr */
498 /** Size (in bytes) of directory name. */
499 HGCMFunctionParameter cbName; /* OUT uint32_t */
500 /** Directory mode. */
501 HGCMFunctionParameter fMode; /* OUT uint32_t */
502 } v1;
503 struct
504 {
505 /** Context ID. Unused at the moment. */
506 HGCMFunctionParameter uContext; /* OUT uint32_t */
507 /** Directory name. */
508 HGCMFunctionParameter pvName; /* OUT ptr */
509 /** Size (in bytes) of directory name. */
510 HGCMFunctionParameter cbName; /* OUT uint32_t */
511 /** Directory mode. */
512 HGCMFunctionParameter fMode; /* OUT uint32_t */
513 } v3;
514 } u;
515} HGCMMsgHGSendDir;
516
517/**
518 * File header message, marking the start of transferring a new file.
519 * Note: Only for protocol version 2 and up.
520 *
521 * Used by:
522 * HOST_DND_FN_HG_SND_FILE_HDR
523 * GUEST_DND_FN_GH_SND_FILE_HDR
524 */
525typedef struct HGCMMsgHGSendFileHdr
526{
527 VBGLIOCHGCMCALL hdr;
528
529 /** Context ID. Unused at the moment. */
530 HGCMFunctionParameter uContext; /* OUT uint32_t */
531 /** File path. */
532 HGCMFunctionParameter pvName; /* OUT ptr */
533 /** Size (in bytes) of file path. */
534 HGCMFunctionParameter cbName; /* OUT uint32_t */
535 /** Optional flags; unused at the moment. */
536 HGCMFunctionParameter uFlags; /* OUT uint32_t */
537 /** File creation mode. */
538 HGCMFunctionParameter fMode; /* OUT uint32_t */
539 /** Total size (in bytes). */
540 HGCMFunctionParameter cbTotal; /* OUT uint64_t */
541} HGCMMsgHGSendFileHdr;
542
543/**
544 * HG: File data (chunk) event.
545 *
546 * Used by:
547 * HOST_DND_FN_HG_SND_FILE
548 */
549typedef struct HGCMMsgHGSendFileData
550{
551 VBGLIOCHGCMCALL hdr;
552
553 union
554 {
555 /* Note: Protocol v1 sends the file name + file mode
556 * every time a file data chunk is being sent. */
557 struct
558 {
559 /** File name. */
560 HGCMFunctionParameter pvName; /* OUT ptr */
561 /** Size (in bytes) of file name. */
562 HGCMFunctionParameter cbName; /* OUT uint32_t */
563 /** Current data chunk. */
564 HGCMFunctionParameter pvData; /* OUT ptr */
565 /** Size (in bytes) of current data chunk. */
566 HGCMFunctionParameter cbData; /* OUT uint32_t */
567 /** File mode. */
568 HGCMFunctionParameter fMode; /* OUT uint32_t */
569 } v1;
570 struct
571 {
572 /** Note: pvName is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
573 /** Note: cbName is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
574 /** Context ID. Unused at the moment. */
575 HGCMFunctionParameter uContext; /* OUT uint32_t */
576 /** Current data chunk. */
577 HGCMFunctionParameter pvData; /* OUT ptr */
578 /** Size (in bytes) of current data chunk. */
579 HGCMFunctionParameter cbData; /* OUT uint32_t */
580 /** Note: fMode is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
581 } v2;
582 struct
583 {
584 /** Context ID. Unused at the moment. */
585 HGCMFunctionParameter uContext; /* OUT uint32_t */
586 /** Current data chunk. */
587 HGCMFunctionParameter pvData; /* OUT ptr */
588 /** Size (in bytes) of current data chunk. */
589 HGCMFunctionParameter cbData; /* OUT uint32_t */
590 /** Checksum of data block, based on the checksum
591 * type in the data header. Optional. */
592 HGCMFunctionParameter pvChecksum; /* OUT ptr */
593 /** Size (in bytes) of curren data chunk checksum. */
594 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
595 } v3;
596 } u;
597} HGCMMsgHGSendFileData;
598
599/**
600 * Asks the guest if a guest->host DnD operation is in progress.
601 *
602 * Used by:
603 * HOST_DND_FN_GH_REQ_PENDING
604 */
605typedef struct HGCMMsgGHReqPending
606{
607 VBGLIOCHGCMCALL hdr;
608
609 union
610 {
611 struct
612 {
613 /** Screen ID. */
614 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
615 } v1;
616 struct
617 {
618 /** Context ID. Unused at the moment. */
619 HGCMFunctionParameter uContext; /* OUT uint32_t */
620 /** Screen ID. */
621 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
622 } v3;
623 } u;
624} HGCMMsgGHReqPending;
625
626/**
627 * Tells the guest that the host has dropped the ongoing guest->host
628 * DnD operation on a valid target on the host.
629 *
630 * Used by:
631 * HOST_DND_FN_GH_EVT_DROPPED
632 */
633typedef struct HGCMMsgGHDropped
634{
635 VBGLIOCHGCMCALL hdr;
636
637 union
638 {
639 struct
640 {
641 /** Requested format for sending the data. */
642 HGCMFunctionParameter pvFormat; /* OUT ptr */
643 /** Size (in bytes) of requested format. */
644 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
645 /** Drop action peformed on the host. */
646 HGCMFunctionParameter uAction; /* OUT uint32_t */
647 } v1;
648 struct
649 {
650 /** Context ID. Unused at the moment. */
651 HGCMFunctionParameter uContext; /* OUT uint32_t */
652 /** Requested format for sending the data. */
653 HGCMFunctionParameter pvFormat; /* OUT ptr */
654 /** Size (in bytes) of requested format. */
655 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
656 /** Drop action peformed on the host. */
657 HGCMFunctionParameter uAction; /* OUT uint32_t */
658 } v3;
659 } u;
660} HGCMMsgGHDropped;
661
662/*
663 * Guest events
664 */
665
666/**
667 * Asks the host for the next command to process, along
668 * with the needed amount of parameters and an optional blocking
669 * flag.
670 *
671 * Used by:
672 * GUEST_DND_FN_GET_NEXT_HOST_MSG
673 */
674typedef struct HGCMMsgGetNext
675{
676 VBGLIOCHGCMCALL hdr;
677
678 /** Message ID. */
679 HGCMFunctionParameter uMsg; /* OUT uint32_t */
680 /** Number of parameters the message needs. */
681 HGCMFunctionParameter cParms; /* OUT uint32_t */
682 /** Whether or not to block (wait) for a
683 * new message to arrive. */
684 HGCMFunctionParameter fBlock; /* OUT uint32_t */
685} HGCMMsgGetNext;
686
687/**
688 * Guest connection request. Used to tell the DnD protocol
689 * version to the (host) service.
690 *
691 * Used by:
692 * GUEST_DND_FN_CONNECT
693 */
694typedef struct HGCMMsgConnect
695{
696 VBGLIOCHGCMCALL hdr;
697
698 union
699 {
700 struct
701 {
702 /** Protocol version to use.
703 * Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
704 HGCMFunctionParameter uProtocol; /* OUT uint32_t */
705 /** Connection flags. Optional. */
706 HGCMFunctionParameter uFlags; /* OUT uint32_t */
707 } v2;
708 struct
709 {
710 /** Context ID. Unused at the moment. */
711 HGCMFunctionParameter uContext; /* OUT uint32_t */
712 /** Protocol version to use.
713 * Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
714 HGCMFunctionParameter uProtocol; /* OUT uint32_t */
715 /** Connection flags. Optional. */
716 HGCMFunctionParameter uFlags; /* OUT uint32_t */
717 } v3;
718 } u;
719} HGCMMsgConnect;
720
721/**
722 * Acknowledges a host operation along with the allowed
723 * action(s) on the guest.
724 *
725 * Used by:
726 * GUEST_DND_FN_HG_ACK_OP
727 */
728typedef struct HGCMMsgHGAck
729{
730 VBGLIOCHGCMCALL hdr;
731
732 union
733 {
734 struct
735 {
736 HGCMFunctionParameter uAction; /* OUT uint32_t */
737 } v1;
738 struct
739 {
740 /** Context ID. Unused at the moment. */
741 HGCMFunctionParameter uContext; /* OUT uint32_t */
742 HGCMFunctionParameter uAction; /* OUT uint32_t */
743 } v3;
744 } u;
745} HGCMMsgHGAck;
746
747/**
748 * Requests data to be sent to the guest.
749 *
750 * Used by:
751 * GUEST_DND_FN_HG_REQ_DATA
752 */
753typedef struct HGCMMsgHGReqData
754{
755 VBGLIOCHGCMCALL hdr;
756
757 union
758 {
759 struct
760 {
761 HGCMFunctionParameter pvFormat; /* OUT ptr */
762 } v1;
763 struct
764 {
765 /** Context ID. Unused at the moment. */
766 HGCMFunctionParameter uContext; /* OUT uint32_t */
767 HGCMFunctionParameter pvFormat; /* OUT ptr */
768 HGCMFunctionParameter cbFormat; /* OUT uint32_t */
769 } v3;
770 } u;
771} HGCMMsgHGReqData;
772
773typedef struct HGCMMsgHGProgress
774{
775 VBGLIOCHGCMCALL hdr;
776
777 union
778 {
779 struct
780 {
781 HGCMFunctionParameter uStatus; /* OUT uint32_t */
782 HGCMFunctionParameter uPercent; /* OUT uint32_t */
783 HGCMFunctionParameter rc; /* OUT uint32_t */
784 } v1;
785 struct
786 {
787 /** Context ID. Unused at the moment. */
788 HGCMFunctionParameter uContext; /* OUT uint32_t */
789 HGCMFunctionParameter uStatus; /* OUT uint32_t */
790 HGCMFunctionParameter uPercent; /* OUT uint32_t */
791 HGCMFunctionParameter rc; /* OUT uint32_t */
792 } v3;
793 } u;
794} HGCMMsgHGProgress;
795
796/**
797 * Acknowledges a pending guest drag and drop event to the host.
798 *
799 * Used by:
800 * GUEST_DND_FN_GH_ACK_PENDING
801 */
802typedef struct HGCMMsgGHAckPending
803{
804 VBGLIOCHGCMCALL hdr;
805
806 union
807 {
808 struct
809 {
810 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
811 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
812 HGCMFunctionParameter pvFormats; /* OUT ptr */
813 } v1;
814 struct
815 {
816 /** Context ID. Unused at the moment. */
817 HGCMFunctionParameter uContext; /* OUT uint32_t */
818 HGCMFunctionParameter uDefAction; /* OUT uint32_t */
819 HGCMFunctionParameter uAllActions; /* OUT uint32_t */
820 HGCMFunctionParameter pvFormats; /* OUT ptr */
821 HGCMFunctionParameter cbFormats; /* OUT uint32_t */
822 } v3;
823 } u;
824} HGCMMsgGHAckPending;
825
826/**
827 * Sends the header of an incoming data block
828 * to the host.
829 *
830 * Used by:
831 * GUEST_DND_FN_GH_SND_DATA_HDR
832 *
833 * New since protocol v3.
834 */
835typedef struct HGCMMsgHGSendDataHdr HGCMMsgGHSendDataHdr;
836
837/**
838 * Sends a (meta) data block to the host.
839 *
840 * Used by:
841 * GUEST_DND_FN_GH_SND_DATA
842 */
843typedef struct HGCMMsgGHSendData
844{
845 VBGLIOCHGCMCALL hdr;
846
847 union
848 {
849 struct
850 {
851 HGCMFunctionParameter pvData; /* OUT ptr */
852 /** Total bytes to send. This can be more than
853 * the data block specified in pvData above, e.g.
854 * when sending over file objects afterwards. */
855 HGCMFunctionParameter cbTotalBytes; /* OUT uint32_t */
856 } v1;
857 struct
858 {
859 /** Context ID. Unused at the moment. */
860 HGCMFunctionParameter uContext; /* OUT uint32_t */
861 /** Data block to send. */
862 HGCMFunctionParameter pvData; /* OUT ptr */
863 /** Size (in bytes) of data block to send. */
864 HGCMFunctionParameter cbData; /* OUT uint32_t */
865 /** (Rolling) Checksum, based on checksum type in data header. */
866 HGCMFunctionParameter pvChecksum; /* OUT ptr */
867 /** Size (in bytes) of checksum. */
868 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
869 } v3;
870 } u;
871} HGCMMsgGHSendData;
872
873/**
874 * Sends a directory entry to the host.
875 *
876 * Used by:
877 * GUEST_DND_FN_GH_SND_DIR
878 */
879typedef struct HGCMMsgHGSendDir HGCMMsgGHSendDir;
880
881/**
882 * Sends a file header to the host.
883 *
884 * Used by:
885 * GUEST_DND_FN_GH_SND_FILE_HDR
886 *
887 * New since protocol v2.
888 */
889typedef struct HGCMMsgHGSendFileHdr HGCMMsgGHSendFileHdr;
890
891/**
892 * Sends file data to the host.
893 *
894 * Used by:
895 * GUEST_DND_FN_GH_SND_FILE_DATA
896 */
897typedef struct HGCMMsgHGSendFileData HGCMMsgGHSendFileData;
898
899/**
900 * Sends a guest error event to the host.
901 *
902 * Used by:
903 * GUEST_DND_FN_GH_EVT_ERROR
904 */
905typedef struct HGCMMsgGHError
906{
907 VBGLIOCHGCMCALL hdr;
908
909 union
910 {
911 struct
912 {
913 HGCMFunctionParameter rc; /* OUT uint32_t */
914 } v1;
915 struct
916 {
917 /** Context ID. Unused at the moment. */
918 HGCMFunctionParameter uContext; /* OUT uint32_t */
919 HGCMFunctionParameter rc; /* OUT uint32_t */
920 } v3;
921 } u;
922} HGCMMsgGHError;
923
924#pragma pack()
925
926/** Builds a callback magic out of the function ID and the version
927 * of the callback data. */
928#define VBOX_DND_CB_MAGIC_MAKE(uFn, uVer) \
929 RT_MAKE_U32(uVer, uFn)
930
931/*
932 * Callback magics.
933 */
934enum eDnDCallbackMagics
935{
936 CB_MAGIC_DND_CONNECT = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_CONNECT, 0),
937 CB_MAGIC_DND_REPORT_FEATURES = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_REPORT_FEATURES, 0),
938 CB_MAGIC_DND_HG_GET_NEXT_HOST_MSG = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GET_NEXT_HOST_MSG, 0),
939 CB_MAGIC_DND_HG_ACK_OP = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_ACK_OP, 0),
940 CB_MAGIC_DND_HG_REQ_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_REQ_DATA, 0),
941 CB_MAGIC_DND_HG_EVT_PROGRESS = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_EVT_PROGRESS, 0),
942 CB_MAGIC_DND_GH_ACK_PENDING = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_ACK_PENDING, 0),
943 CB_MAGIC_DND_GH_SND_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DATA, 0),
944 CB_MAGIC_DND_GH_SND_DATA_HDR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DATA_HDR, 0),
945 CB_MAGIC_DND_GH_SND_DIR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DIR, 0),
946 CB_MAGIC_DND_GH_SND_FILE_HDR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_FILE_HDR, 0),
947 CB_MAGIC_DND_GH_SND_FILE_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_FILE_DATA, 0),
948 CB_MAGIC_DND_GH_EVT_ERROR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_EVT_ERROR, 0)
949};
950
951typedef struct VBOXDNDCBHEADERDATA
952{
953 /** Magic number to identify the structure. */
954 uint32_t uMagic;
955 /** Context ID to identify callback data. */
956 uint32_t uContextID;
957} VBOXDNDCBHEADERDATA, *PVBOXDNDCBHEADERDATA;
958
959typedef struct VBOXDNDCBCONNECTDATA
960{
961 /** Callback data header. */
962 VBOXDNDCBHEADERDATA hdr;
963 /** Protocol version to use.
964 * Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
965 uint32_t uProtocolVersion;
966 /** Connection flags; currently unused. */
967 uint32_t fFlags;
968} VBOXDNDCBCONNECTDATA, *PVBOXDNDCBCONNECTDATA;
969
970typedef struct VBOXDNDCBREPORTFEATURESDATA
971{
972 /** Callback data header. */
973 VBOXDNDCBHEADERDATA hdr;
974 uint32_t fGuestFeatures0;
975} VBOXDNDCBREPORTFEATURESDATA, *PVBOXDNDCBREPORTFEATURESDATA;
976
977typedef struct VBOXDNDCBDISCONNECTMSGDATA
978{
979 /** Callback data header. */
980 VBOXDNDCBHEADERDATA hdr;
981} VBOXDNDCBDISCONNECTMSGDATA, *PVBOXDNDCBDISCONNECTMSGDATA;
982
983typedef struct VBOXDNDCBHGGETNEXTHOSTMSG
984{
985 /** Callback data header. */
986 VBOXDNDCBHEADERDATA hdr;
987 uint32_t uMsg;
988 uint32_t cParms;
989} VBOXDNDCBHGGETNEXTHOSTMSG, *PVBOXDNDCBHGGETNEXTHOSTMSG;
990
991typedef struct VBOXDNDCBHGGETNEXTHOSTMSGDATA
992{
993 /** Callback data header. */
994 VBOXDNDCBHEADERDATA hdr;
995 uint32_t uMsg;
996 uint32_t cParms;
997 PVBOXHGCMSVCPARM paParms;
998} VBOXDNDCBHGGETNEXTHOSTMSGDATA, *PVBOXDNDCBHGGETNEXTHOSTMSGDATA;
999
1000typedef struct VBOXDNDCBHGACKOPDATA
1001{
1002 /** Callback data header. */
1003 VBOXDNDCBHEADERDATA hdr;
1004 uint32_t uAction;
1005} VBOXDNDCBHGACKOPDATA, *PVBOXDNDCBHGACKOPDATA;
1006
1007typedef struct VBOXDNDCBHGREQDATADATA
1008{
1009 /** Callback data header. */
1010 VBOXDNDCBHEADERDATA hdr;
1011 char *pszFormat;
1012 uint32_t cbFormat;
1013} VBOXDNDCBHGREQDATADATA, *PVBOXDNDCBHGREQDATADATA;
1014
1015typedef struct VBOXDNDCBHGEVTPROGRESSDATA
1016{
1017 /** Callback data header. */
1018 VBOXDNDCBHEADERDATA hdr;
1019 uint32_t uPercentage;
1020 uint32_t uStatus;
1021 uint32_t rc;
1022} VBOXDNDCBHGEVTPROGRESSDATA, *PVBOXDNDCBHGEVTPROGRESSDATA;
1023
1024typedef struct VBOXDNDCBGHACKPENDINGDATA
1025{
1026 /** Callback data header. */
1027 VBOXDNDCBHEADERDATA hdr;
1028 uint32_t uDefAction;
1029 uint32_t uAllActions;
1030 char *pszFormat;
1031 uint32_t cbFormat;
1032} VBOXDNDCBGHACKPENDINGDATA, *PVBOXDNDCBGHACKPENDINGDATA;
1033
1034/**
1035 * Data header.
1036 * New since protocol v3.
1037 */
1038typedef struct VBOXDNDDATAHDR
1039{
1040 /** Data transfer flags. Not yet used and must be 0. */
1041 uint32_t uFlags;
1042 /** Screen ID where the data originates from. */
1043 uint32_t uScreenId;
1044 /** Total size (in bytes) to transfer. */
1045 uint64_t cbTotal;
1046 /** Meta data size (in bytes) to transfer.
1047 * This size also is part of cbTotal already. */
1048 uint32_t cbMeta;
1049 /** Meta format buffer. */
1050 void *pvMetaFmt;
1051 /** Size (in bytes) of meta format buffer. */
1052 uint32_t cbMetaFmt;
1053 /** Number of objects (files/directories) to transfer. */
1054 uint64_t cObjects;
1055 /** Compression type. Currently unused, so specify 0.
1056 **@todo Add IPRT compression type enumeration as soon as it's available. */
1057 uint32_t enmCompression;
1058 /** Checksum type. Currently unused, so specify RTDIGESTTYPE_INVALID. */
1059 RTDIGESTTYPE enmChecksumType;
1060 /** The actual checksum buffer for the entire data to be transferred,
1061 * based on enmChksumType. If RTDIGESTTYPE_INVALID is specified,
1062 * no checksum is being used and pvChecksum will be NULL. */
1063 void *pvChecksum;
1064 /** Size (in bytes) of checksum. */
1065 uint32_t cbChecksum;
1066} VBOXDNDDATAHDR, *PVBOXDNDSNDDATAHDR;
1067
1068/* New since protocol v3. */
1069typedef struct VBOXDNDCBSNDDATAHDRDATA
1070{
1071 /** Callback data header. */
1072 VBOXDNDCBHEADERDATA hdr;
1073 /** Actual header data. */
1074 VBOXDNDDATAHDR data;
1075} VBOXDNDCBSNDDATAHDRDATA, *PVBOXDNDCBSNDDATAHDRDATA;
1076
1077typedef struct VBOXDNDSNDDATA
1078{
1079 union
1080 {
1081 struct
1082 {
1083 /** Data block buffer. */
1084 void *pvData;
1085 /** Size (in bytes) of data block. */
1086 uint32_t cbData;
1087 /** Total metadata size (in bytes). This is transmitted
1088 * with every message because the size can change. */
1089 uint32_t cbTotalSize;
1090 } v1;
1091 /* Protocol v2: No changes. */
1092 struct
1093 {
1094 /** Data block buffer. */
1095 void *pvData;
1096 /** Size (in bytes) of data block. */
1097 uint32_t cbData;
1098 /** (Rolling) Checksum. Not yet implemented. */
1099 void *pvChecksum;
1100 /** Size (in bytes) of checksum. Not yet implemented. */
1101 uint32_t cbChecksum;
1102 } v3;
1103 } u;
1104} VBOXDNDSNDDATA, *PVBOXDNDSNDDATA;
1105
1106typedef struct VBOXDNDCBSNDDATADATA
1107{
1108 /** Callback data header. */
1109 VBOXDNDCBHEADERDATA hdr;
1110 /** Actual data. */
1111 VBOXDNDSNDDATA data;
1112} VBOXDNDCBSNDDATADATA, *PVBOXDNDCBSNDDATADATA;
1113
1114typedef struct VBOXDNDCBSNDDIRDATA
1115{
1116 /** Callback data header. */
1117 VBOXDNDCBHEADERDATA hdr;
1118 /** Directory path. */
1119 char *pszPath;
1120 /** Size (in bytes) of path. */
1121 uint32_t cbPath;
1122 /** Directory creation mode. */
1123 uint32_t fMode;
1124} VBOXDNDCBSNDDIRDATA, *PVBOXDNDCBSNDDIRDATA;
1125
1126/* Note: Only for protocol version 2 and up (>= VBox 5.0). */
1127typedef struct VBOXDNDCBSNDFILEHDRDATA
1128{
1129 /** Callback data header. */
1130 VBOXDNDCBHEADERDATA hdr;
1131 /** File path (name). */
1132 char *pszFilePath;
1133 /** Size (in bytes) of file path. */
1134 uint32_t cbFilePath;
1135 /** Total size (in bytes) of this file. */
1136 uint64_t cbSize;
1137 /** File (creation) mode. */
1138 uint32_t fMode;
1139 /** Additional flags. Not used at the moment. */
1140 uint32_t fFlags;
1141} VBOXDNDCBSNDFILEHDRDATA, *PVBOXDNDCBSNDFILEHDRDATA;
1142
1143typedef struct VBOXDNDCBSNDFILEDATADATA
1144{
1145 /** Callback data header. */
1146 VBOXDNDCBHEADERDATA hdr;
1147 /** Current file data chunk. */
1148 void *pvData;
1149 /** Size (in bytes) of current data chunk. */
1150 uint32_t cbData;
1151 union
1152 {
1153 struct
1154 {
1155 /** File path (name). */
1156 char *pszFilePath;
1157 /** Size (in bytes) of file path. */
1158 uint32_t cbFilePath;
1159 /** File (creation) mode. */
1160 uint32_t fMode;
1161 } v1;
1162 /* Protocol v2 + v3: Have the file attributes (name, size, mode, ...)
1163 in the VBOXDNDCBSNDFILEHDRDATA structure. */
1164 struct
1165 {
1166 /** Checksum for current file data chunk. */
1167 void *pvChecksum;
1168 /** Size (in bytes) of current data chunk. */
1169 uint32_t cbChecksum;
1170 } v3;
1171 } u;
1172} VBOXDNDCBSNDFILEDATADATA, *PVBOXDNDCBSNDFILEDATADATA;
1173
1174typedef struct VBOXDNDCBEVTERRORDATA
1175{
1176 /** Callback data header. */
1177 VBOXDNDCBHEADERDATA hdr;
1178 int32_t rc;
1179} VBOXDNDCBEVTERRORDATA, *PVBOXDNDCBEVTERRORDATA;
1180
1181} /* namespace DragAndDropSvc */
1182
1183#endif /* !VBOX_INCLUDED_HostServices_DragAndDropSvc_h */
1184
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette