VirtualBox

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

Last change on this file since 78377 was 76891, checked in by vboxsync, 6 years ago

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