VirtualBox

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

Last change on this file since 93115 was 93115, checked in by vboxsync, 3 years ago

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