VirtualBox

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

Last change on this file since 58650 was 58329, checked in by vboxsync, 9 years ago

DnD: Updates/bugfixes:

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