VirtualBox

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

Last change on this file since 74883 was 74442, checked in by vboxsync, 6 years ago

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