VirtualBox

source: vbox/trunk/include/VBox/HostServices/VBoxClipboardSvc.h@ 103224

Last change on this file since 103224 was 100367, checked in by vboxsync, 17 months ago

Shared Clipboard: More work on making the internal APIs more fine grained and easier to follow. bugref:9437

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 41.8 KB
Line 
1/** @file
2 * Shared Clipboard - Common header for host service and guest clients.
3 *
4 * Protocol history notes (incomplete):
5 *
6 * - VirtualBox 6.1.0 betas: Started work on adding support for copying &
7 * pasting files and directories, refactoring the protocol in the process.
8 * - Adds guest/host feature flags.
9 * - Adds context IDs (via guest feature flags).
10 * - Borrowed the message handling from guest controls.
11 * - Adds a multitude of functions and messages for dealing with file & dir
12 * copying, most inte
13 *
14 * - VirtualBox x.x.x: Missing a lot of gradual improvements here.
15 *
16 * - VirtualBox 1.3.2 (r17182): Initial implementation, supporting text.
17 */
18
19/*
20 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
21 *
22 * This file is part of VirtualBox base platform packages, as
23 * available from https://www.virtualbox.org.
24 *
25 * This program is free software; you can redistribute it and/or
26 * modify it under the terms of the GNU General Public License
27 * as published by the Free Software Foundation, in version 3 of the
28 * License.
29 *
30 * This program is distributed in the hope that it will be useful, but
31 * WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
33 * General Public License for more details.
34 *
35 * You should have received a copy of the GNU General Public License
36 * along with this program; if not, see <https://www.gnu.org/licenses>.
37 *
38 * The contents of this file may alternatively be used under the terms
39 * of the Common Development and Distribution License Version 1.0
40 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
41 * in the VirtualBox distribution, in which case the provisions of the
42 * CDDL are applicable instead of those of the GPL.
43 *
44 * You may elect to license modified versions of this file under the
45 * terms and conditions of either the GPL or the CDDL or both.
46 *
47 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
48 */
49
50#ifndef VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h
51#define VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h
52#ifndef RT_WITHOUT_PRAGMA_ONCE
53# pragma once
54#endif
55
56#include <VBox/VMMDevCoreTypes.h>
57#include <VBox/VBoxGuestCoreTypes.h>
58#include <VBox/hgcmsvc.h>
59
60
61/** @name VBOX_SHCL_MODE_XXX - The Shared Clipboard modes of operation.
62 * @{
63 */
64/** Shared Clipboard is disabled completely. */
65#define VBOX_SHCL_MODE_OFF 0
66/** Only transfers from host to the guest are possible. */
67#define VBOX_SHCL_MODE_HOST_TO_GUEST 1
68/** Only transfers from guest to the host are possible. */
69#define VBOX_SHCL_MODE_GUEST_TO_HOST 2
70/** Bidirectional transfers between guest and host are possible. */
71#define VBOX_SHCL_MODE_BIDIRECTIONAL 3
72/** @} */
73
74/** @name VBOX_SHCL_TRANSFER_MODE_XXX - The Shared Clipboard file transfer mode flags.
75 * @{
76 */
77/** Shared Clipboard file transfers are disabled. */
78#define VBOX_SHCL_TRANSFER_MODE_F_NONE UINT32_C(0)
79/** Shared Clipboard file transfers are enabled. */
80#define VBOX_SHCL_TRANSFER_MODE_F_ENABLED RT_BIT(0)
81/** Shared Clipboard file transfer mode valid mask. */
82#define VBOX_SHCL_TRANSFER_MODE_F_VALID_MASK UINT32_C(0x1)
83/** @} */
84
85
86/** @name VBOX_SHCL_HOST_FN_XXX - The service functions which are callable by host.
87 * @note These are not sacred and can be modified at will as long as all host
88 * clients are updated accordingly (probably just Main).
89 * @{
90 */
91/** Sets the current Shared Clipboard operation mode. */
92#define VBOX_SHCL_HOST_FN_SET_MODE 1
93/** Sets the current Shared Clipboard (file) transfers mode.
94 * Operates on the VBOX_SHCL_TRANSFERS_XXX defines.
95 * @since 6.1 */
96#define VBOX_SHCL_HOST_FN_SET_TRANSFER_MODE 2
97/** Run headless on the host, i.e. do not touch the host clipboard. */
98#define VBOX_SHCL_HOST_FN_SET_HEADLESS 3
99
100/** Reports cancellation of the current operation to the guest.
101 * @since 6.1 - still a todo */
102#define VBOX_SHCL_HOST_FN_CANCEL 4
103/** Reports an error to the guest.
104 * @since 6.1 - still a todo */
105#define VBOX_SHCL_HOST_FN_ERROR 5
106/** @} */
107
108
109/** @name VBOX_SHCL_HOST_MSG_XXX - The host messages for the guest.
110 * @{
111 */
112/** Returned only when the HGCM client session is closed (by different thread).
113 *
114 * This can require no futher host interaction since the session has been
115 * closed.
116 *
117 * @since 1.3.2
118 */
119#define VBOX_SHCL_HOST_MSG_QUIT 1
120/** Request data for a specific format from the guest.
121 *
122 * Two parameters, first the 32-bit message ID followed by a 32-bit format bit
123 * (VBOX_SHCL_FMT_XXX). The guest will respond by issuing a
124 * VBOX_SHCL_GUEST_FN_DATA_WRITE.
125 *
126 * @note The host may sometimes incorrectly set more than one format bit, in
127 * which case it's up to the guest to pick which to write back.
128 * @since 1.3.2
129 */
130#define VBOX_SHCL_HOST_MSG_READ_DATA 2
131/** Reports available clipboard format on the host to the guest.
132 *
133 * Two parameters, first the 32-bit message ID followed by a 32-bit format mask
134 * containing zero or more VBOX_SHCL_FMT_XXX flags. The guest is not require to
135 * respond to the host when receiving this message.
136 *
137 * @since 1.3.2
138 */
139#define VBOX_SHCL_HOST_MSG_FORMATS_REPORT 3
140/** Message PEEK or GET operation was canceled, try again.
141 *
142 * This is returned by VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT and
143 * VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT in response to the guest calling
144 * VBOX_SHCL_GUEST_FN_MSG_CANCEL. The 2nd parameter is set to zero (be it
145 * thought of as a parameter count or a format mask).
146 *
147 * @since 6.1.0
148 */
149#define VBOX_SHCL_HOST_MSG_CANCELED 4
150
151/** Request data for a specific format from the guest with context ID.
152 *
153 * This is send instead of the VBOX_SHCL_HOST_MSG_READ_DATA message to guest
154 * that advertises VBOX_SHCL_GF_0_CONTEXT_ID. The first parameter is a 64-bit
155 * context ID which is to be used when issuing VBOX_SHCL_GUEST_F_DATA_WRITE, and
156 * the second parameter is a 32-bit format bit (VBOX_SHCL_FMT_XXX). The guest
157 * will respond by issuing a VBOX_SHCL_GUEST_F_DATA_WRITE.
158 *
159 * @note The host may sometimes incorrectly set more than one format bit, in
160 * which case it's up to the guest to pick which to write back.
161 * @since 6.1.2
162 */
163#define VBOX_SHCL_HOST_MSG_READ_DATA_CID 5
164
165/** Sends a transfer status to the guest side.
166 * @since 7.1
167 */
168#define VBOX_SHCL_HOST_MSG_TRANSFER_STATUS 50
169/** Reads the root list header from the guest.
170 * @since 7.1
171 */
172#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_HDR_READ 51
173/** Writes the root list header to the guest.
174 * @since 7.1
175 */
176#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_HDR_WRITE 52
177/** Reads a root list entry from the guest.
178 * @since 7.1
179 */
180#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_ENTRY_READ 53
181/** Writes a root list entry to the guest.
182 * @since 7.1
183 */
184#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_ENTRY_WRITE 54
185/** Open a transfer list on the guest side.
186 * @since 7.1
187 */
188#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_OPEN 55
189/** Closes a formerly opened transfer list on the guest side.
190 * @since 7.1
191 */
192#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_CLOSE 56
193/** Reads a list header from the guest.
194 * @since 7.1
195 */
196#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_HDR_READ 57
197/** Writes a list header to the guest.
198 * @since 7.1
199 */
200#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_HDR_WRITE 58
201/** Reads a list entry from the guest.
202 * @since 7.1
203 */
204#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_ENTRY_READ 59
205/** Writes a list entry to the guest.
206 * @since 7.1
207 */
208#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_ENTRY_WRITE 60
209/** Open a transfer object on the guest side.
210 * @since 7.1
211 */
212#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_OPEN 61
213/** Closes a formerly opened transfer object on the guest side.
214 * @since 7.1
215 */
216#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_CLOSE 62
217/** Reads from an object on the guest side.
218 * @since 7.1
219 */
220#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_READ 63
221/** Writes to an object on the guest side.
222 * @since 7.1
223 */
224#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_WRITE 64
225/** Indicates that the host has canceled a transfer.
226 * @since 7.1
227 */
228#define VBOX_SHCL_HOST_MSG_TRANSFER_CANCEL 65
229/** Indicates that the an unrecoverable error on the host occurred.
230 * @since 7.1
231 */
232#define VBOX_SHCL_HOST_MSG_TRANSFER_ERROR 66
233/** @} */
234
235
236/** @name VBOX_SHCL_GUEST_FN_XXX - The service functions which are called by guest.
237 * @{
238 */
239/** Calls the host and waits (blocking) for an host event VBOX_SHCL_HOST_MSG_XXX.
240 *
241 * @deprecated Replaced by VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT,
242 * VBOX_SHCL_GUEST_FN_MSG_GET, VBOX_SHCL_GUEST_FN_MSG_CANCEL.
243 * @since 1.3.2
244 */
245#define VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT 1
246/** Sends a list of available formats to the host.
247 *
248 * This function takes a single parameter, a 32-bit set of formats
249 * (VBOX_SHCL_FMT_XXX), this can be zero if the clipboard is empty or previously
250 * reported formats are no longer avaible (logout, shutdown, whatever).
251 *
252 * There was a period during 6.1 development where it would take three
253 * parameters, a 64-bit context ID preceeded the formats and a 32-bit MBZ flags
254 * parameter was appended. This is still accepted, though deprecated.
255 *
256 * @returns May return informational statuses indicating partial success, just
257 * ignore it.
258 * @retval VINF_SUCCESS on success.
259 * @retval VERR_INVALID_CLIENT_ID
260 * @retval VERR_WRONG_PARAMETER_COUNT
261 * @retval VERR_WRONG_PARAMETER_TYPE
262 * @retval VERR_NOT_SUPPORTED if all the formats are unsupported, host
263 * clipboard will be empty.
264 * @since 1.3.2
265 */
266#define VBOX_SHCL_GUEST_FN_REPORT_FORMATS 2
267/** Reads data in specified format from the host.
268 *
269 * This function takes three parameters, a 32-bit format bit
270 * (VBOX_SHCL_FMT_XXX), a buffer and 32-bit number of bytes read (output).
271 *
272 * There was a period during 6.1 development where it would take five parameters
273 * when VBOX_SHCL_GF_0_CONTEXT_ID was reported by the guest. A 64-bit context
274 * ID (ignored as purpose undefined), a 32-bit unused flag (MBZ), then the
275 * 32-bit format bits, number of bytes read (output), and the buffer. This
276 * format is still accepted.
277 *
278 * @retval VINF_SUCCESS on success.
279 * @retval VINF_BUFFER_OVERLFLOW (VBox >= 6.1 only) if not enough buffer space
280 * has been given to retrieve the actual data, no data actually copied.
281 * The call then must be repeated with a buffer size returned from the
282 * host in cbData.
283 * @retval VERR_INVALID_CLIENT_ID
284 * @retval VERR_WRONG_PARAMETER_COUNT
285 * @retval VERR_WRONG_PARAMETER_TYPE
286 * @since 1.3.2
287 */
288#define VBOX_SHCL_GUEST_FN_DATA_READ 3
289/** Writes requested data to the host.
290 *
291 * This function takes either 2 or 3 parameters. The last two parameters are a
292 * 32-bit format bit (VBOX_SHCL_FMT_XXX) and a data buffer holding the related
293 * data. The three parameter variant have a context ID first, which shall be a
294 * copy of the ID in the data request message.
295 *
296 * There was a period during 6.1 development where there would be a 5 parameter
297 * version of this, inserting an unused flags parameter between the context ID
298 * and the format bit, as well as a 32-bit data buffer size repate between the
299 * format bit and the data buffer. This format is still accepted, though
300 * deprecated.
301 *
302 * @retval VINF_SUCCESS on success.
303 * @retval VERR_INVALID_CLIENT_ID
304 * @retval VERR_WRONG_PARAMETER_COUNT
305 * @retval VERR_WRONG_PARAMETER_TYPE
306 * @retval VERR_INVALID_CONTEXT if the context ID didn't match up.
307 * @since 1.3.2
308 */
309#define VBOX_SHCL_GUEST_FN_DATA_WRITE 4
310
311/** This is a left-over from the 6.1 dev cycle and will always fail.
312 *
313 * It used to take three 32-bit parameters, only one of which was actually used.
314 *
315 * It was replaced by VBOX_SHCL_GUEST_FN_REPORT_FEATURES and
316 * VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE.
317 *
318 * @retval VERR_NOT_IMPLEMENTED
319 * @since 6.1
320 */
321#define VBOX_SHCL_GUEST_FN_CONNECT 5
322/** Report guest side feature flags and retrieve the host ones.
323 *
324 * Two 64-bit parameters are passed in from the guest with the guest features
325 * (VBOX_SHCL_GF_XXX), the host replies by replacing the parameter values with
326 * the host ones (VBOX_SHCL_HF_XXX).
327 *
328 * @retval VINF_SUCCESS on success.
329 * @retval VERR_INVALID_CLIENT_ID
330 * @retval VERR_WRONG_PARAMETER_COUNT
331 * @retval VERR_WRONG_PARAMETER_TYPE
332 * @since 7.1.0
333 */
334#define VBOX_SHCL_GUEST_FN_REPORT_FEATURES 6
335/** Query the host ones feature masks.
336 *
337 * That way the guest (client) can get hold of the features from the host.
338 * Again, it is prudent to set the 127 bit and observe it being cleared on
339 * success, as older hosts might return success without doing anything.
340 *
341 * @retval VINF_SUCCESS on success.
342 * @retval VERR_INVALID_CLIENT_ID
343 * @retval VERR_WRONG_PARAMETER_COUNT
344 * @retval VERR_WRONG_PARAMETER_TYPE
345 * @since 7.1.0
346 */
347#define VBOX_SHCL_GUEST_FN_QUERY_FEATURES 7
348/** Peeks at the next message, returning immediately.
349 *
350 * Returns two 32-bit parameters, first is the message ID and the second the
351 * parameter count. May optionally return additional 32-bit parameters with the
352 * sizes of respective message parameters. To distinguish buffer sizes from
353 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
354 * uint64_t is ~8U).
355 *
356 * Does also support the VM restore checking as in VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT
357 * (64-bit param \# 0), see documentation there.
358 *
359 * @retval VINF_SUCCESS if a message was pending and is being returned.
360 * @retval VERR_TRY_AGAIN if no message pending.
361 * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that
362 * does not match VbglR3GetSessionId() any more. The new value is
363 * returned.
364 * @retval VERR_INVALID_CLIENT_ID
365 * @retval VERR_WRONG_PARAMETER_COUNT
366 * @retval VERR_WRONG_PARAMETER_TYPE
367 * @since 7.1.0
368 */
369#define VBOX_SHCL_GUEST_FN_MSG_PEEK_NOWAIT 8
370/** Peeks at the next message, waiting for one to arrive.
371 *
372 * Returns two 32-bit parameters, first is the message ID and the second the
373 * parameter count. May optionally return additional 32-bit parameters with the
374 * sizes of respective message parameters. To distinguish buffer sizes from
375 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
376 * uint64_t is ~8U).
377 *
378 * To facilitate VM restore checking, the first parameter can be a 64-bit
379 * integer holding the VbglR3GetSessionId() value the guest knowns. The
380 * function will then check this before going to sleep and return
381 * VERR_VM_RESTORED if it doesn't match, same thing happens when the VM is
382 * restored.
383 *
384 * @retval VINF_SUCCESS if info about an pending message is being returned.
385 * @retval VINF_TRY_AGAIN and message set to VBOX_SHCL_HOST_MSG_CANCELED if
386 * cancelled by VBOX_SHCL_GUEST_FN_MSG_CANCEL.
387 * @retval VERR_RESOURCE_BUSY if another thread already made a waiting call.
388 * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that
389 * does not match VbglR3GetSessionId() any more. The new value is
390 * returned.
391 * @retval VERR_INVALID_CLIENT_ID
392 * @retval VERR_WRONG_PARAMETER_COUNT
393 * @retval VERR_WRONG_PARAMETER_TYPE
394 * @note This replaces VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT.
395 * @since 7.1.0
396 */
397#define VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT 9
398/** Gets the next message, returning immediately.
399 *
400 * All parameters are specific to the message being retrieved, however if the
401 * first one is an integer value it shall be an input parameter holding the
402 * ID of the message being retrieved. While it would be nice to add a separate
403 * parameter for this purpose, this is done so because the code was liften from
404 * Guest Controls which had backwards compatibilities to consider and we just
405 * kept it like that.
406 *
407 * @retval VINF_SUCCESS if message retrieved and removed from the pending queue.
408 * @retval VERR_TRY_AGAIN if no message pending.
409 * @retval VERR_MISMATCH if the incoming message ID does not match the pending.
410 * @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer
411 * size was updated to reflect the required size.
412 * @retval VERR_INVALID_CLIENT_ID
413 * @retval VERR_WRONG_PARAMETER_COUNT
414 * @retval VERR_WRONG_PARAMETER_TYPE
415 * @note This replaces VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT.
416 * @since 6.1.0
417 */
418#define VBOX_SHCL_GUEST_FN_MSG_GET 10
419/** Cancels pending calls for this client session.
420 *
421 * This should be used if a VBOX_SHCL_GUEST_FN__MSG_PEEK_WAIT or
422 * VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT call gets interrupted on the client end,
423 * so as to prevent being rebuffed with VERR_RESOURCE_BUSY when restarting the
424 * call.
425 *
426 * @retval VINF_SUCCESS if cancelled any calls.
427 * @retval VWRN_NOT_FOUND if no callers.
428 * @retval VERR_INVALID_CLIENT_ID
429 * @retval VERR_WRONG_PARAMETER_COUNT
430 * @since 6.1.0
431 */
432#define VBOX_SHCL_GUEST_FN_MSG_CANCEL 26
433
434/** Replies to a function from the host.
435 *
436 * @retval VINF_SUCCESS on success.
437 * @retval VERR_INVALID_CLIENT_ID
438 * @retval VERR_WRONG_PARAMETER_COUNT
439 * @retval VERR_WRONG_PARAMETER_TYPE
440 * @since 6.1.x
441 */
442#define VBOX_SHCL_GUEST_FN_REPLY 11
443/** Gets the transfer root list header from the host.
444 *
445 * @retval VINF_SUCCESS on success.
446 * @retval VERR_INVALID_CLIENT_ID
447 * @retval VERR_WRONG_PARAMETER_COUNT
448 * @retval VERR_WRONG_PARAMETER_TYPE
449 * @since 7.1.x
450 */
451#define VBOX_SHCL_GUEST_FN_ROOT_LIST_HDR_READ 12
452/** Sends the transfer root list header to the host.
453 *
454 * @retval VINF_SUCCESS on success.
455 * @retval VERR_INVALID_CLIENT_ID
456 * @retval VERR_WRONG_PARAMETER_COUNT
457 * @retval VERR_WRONG_PARAMETER_TYPE
458 * @since 7.1.x
459 */
460#define VBOX_SHCL_GUEST_FN_ROOT_LIST_HDR_WRITE 13
461/** Gets a transfer root list root entry from the host.
462 *
463 * @retval VINF_SUCCESS on success.
464 * @retval VERR_INVALID_CLIENT_ID
465 * @retval VERR_WRONG_PARAMETER_COUNT
466 * @retval VERR_WRONG_PARAMETER_TYPE
467 * @since 7.1.x
468 */
469#define VBOX_SHCL_GUEST_FN_ROOT_LIST_ENTRY_READ 14
470/** Sends a transfer root list root entry to the host.
471 *
472 * @retval VINF_SUCCESS on success.
473 * @retval VERR_INVALID_CLIENT_ID
474 * @retval VERR_WRONG_PARAMETER_COUNT
475 * @retval VERR_WRONG_PARAMETER_TYPE
476 * @since 7.1.x
477 */
478#define VBOX_SHCL_GUEST_FN_ROOT_LIST_ENTRY_WRITE 15
479/** Opens / gets a transfer list handle from the host.
480 *
481 * @retval VINF_SUCCESS on success.
482 * @retval VERR_INVALID_CLIENT_ID
483 * @retval VERR_WRONG_PARAMETER_COUNT
484 * @retval VERR_WRONG_PARAMETER_TYPE
485 * @since 7.1.x
486 */
487#define VBOX_SHCL_GUEST_FN_LIST_OPEN 16
488/** Closes a transfer list handle from the host.
489 *
490 * @retval VINF_SUCCESS on success.
491 * @retval VERR_INVALID_CLIENT_ID
492 * @retval VERR_WRONG_PARAMETER_COUNT
493 * @retval VERR_WRONG_PARAMETER_TYPE
494 * @since 7.1.x
495 */
496#define VBOX_SHCL_GUEST_FN_LIST_CLOSE 17
497/** Reads a transfer list header from the host.
498 *
499 * @retval VINF_SUCCESS on success.
500 * @retval VERR_INVALID_CLIENT_ID
501 * @retval VERR_WRONG_PARAMETER_COUNT
502 * @retval VERR_WRONG_PARAMETER_TYPE
503 * @since 7.1.x
504 */
505#define VBOX_SHCL_GUEST_FN_LIST_HDR_READ 18
506/** Writes a transfer list header to the host.
507 *
508 * @retval VINF_SUCCESS on success.
509 * @retval VERR_INVALID_CLIENT_ID
510 * @retval VERR_WRONG_PARAMETER_COUNT
511 * @retval VERR_WRONG_PARAMETER_TYPE
512 * @since 7.1.x
513 */
514#define VBOX_SHCL_GUEST_FN_LIST_HDR_WRITE 19
515/** Reads a transfer list entry from the host.
516 *
517 * @retval VINF_SUCCESS on success.
518 * @retval VERR_INVALID_CLIENT_ID
519 * @retval VERR_WRONG_PARAMETER_COUNT
520 * @retval VERR_WRONG_PARAMETER_TYPE
521 * @since 7.1.x
522 */
523#define VBOX_SHCL_GUEST_FN_LIST_ENTRY_READ 20
524/** Sends a transfer list entry to the host.
525 *
526 * @retval VINF_SUCCESS on success.
527 * @retval VERR_INVALID_CLIENT_ID
528 * @retval VERR_WRONG_PARAMETER_COUNT
529 * @retval VERR_WRONG_PARAMETER_TYPE
530 * @since 7.1.x
531 */
532#define VBOX_SHCL_GUEST_FN_LIST_ENTRY_WRITE 21
533/** Opens a transfer object on the host.
534 *
535 * @retval VINF_SUCCESS on success.
536 * @retval VERR_INVALID_CLIENT_ID
537 * @retval VERR_WRONG_PARAMETER_COUNT
538 * @retval VERR_WRONG_PARAMETER_TYPE
539 * @since 7.1.x
540 */
541#define VBOX_SHCL_GUEST_FN_OBJ_OPEN 22
542/** Closes a transfer object on the host.
543 *
544 * @retval VINF_SUCCESS on success.
545 * @retval VERR_INVALID_CLIENT_ID
546 * @retval VERR_WRONG_PARAMETER_COUNT
547 * @retval VERR_WRONG_PARAMETER_TYPE
548 * @since 7.1.x
549 */
550#define VBOX_SHCL_GUEST_FN_OBJ_CLOSE 23
551/** Reads from a transfer object on the host.
552 *
553 * @retval VINF_SUCCESS on success.
554 * @retval VERR_INVALID_CLIENT_ID
555 * @retval VERR_WRONG_PARAMETER_COUNT
556 * @retval VERR_WRONG_PARAMETER_TYPE
557 * @since 7.1.x
558 */
559#define VBOX_SHCL_GUEST_FN_OBJ_READ 24
560/** Writes to a transfer object on the host.
561 *
562 * @retval VINF_SUCCESS on success.
563 * @retval VERR_INVALID_CLIENT_ID
564 * @retval VERR_WRONG_PARAMETER_COUNT
565 * @retval VERR_WRONG_PARAMETER_TYPE
566 * @since 7.1.x
567 */
568#define VBOX_SHCL_GUEST_FN_OBJ_WRITE 25
569/** Reports a transfer error to the host.
570 *
571 * @todo r=bird: Smells like GUEST_MSG_SKIP
572 *
573 * @retval VINF_SUCCESS on success.
574 * @retval VERR_INVALID_CLIENT_ID
575 * @retval VERR_WRONG_PARAMETER_COUNT
576 * @retval VERR_WRONG_PARAMETER_TYPE
577 * @since 6.1
578 */
579#define VBOX_SHCL_GUEST_FN_ERROR 27
580
581/** For negotiating a chunk size between the guest and host.
582 *
583 * Takes two 32-bit parameters both being byte counts, the first one gives the
584 * maximum chunk size the guest can handle and the second the preferred choice
585 * of the guest. Upon return, the host will have updated both of them to
586 * reflect the maximum and default chunk sizes this client connect. The guest
587 * may set the 2nd value to zero and let the host choose.
588 *
589 * @retval VINF_SUCCESS on success.
590 * @retval VERR_INVALID_CLIENT_ID
591 * @retval VERR_WRONG_PARAMETER_COUNT
592 * @retval VERR_WRONG_PARAMETER_TYPE
593 * @retval VERR_INVALID_PARAMETER if the 2nd parameter is larger than the
594 * first one
595 * @since 7.1
596 */
597#define VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE 28
598
599/** The last function number (used for validation/sanity). */
600#define VBOX_SHCL_GUEST_FN_LAST VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE
601/** @} */
602
603
604/** Maximum chunk size for a single data transfer. */
605#define VBOX_SHCL_MAX_CHUNK_SIZE VMMDEV_MAX_HGCM_DATA_SIZE - _4K
606/** Default chunk size for a single data transfer. */
607#define VBOX_SHCL_DEFAULT_CHUNK_SIZE RT_MIN(_64K, VBOX_SHCL_MAX_CHUNK_SIZE);
608
609
610/** @name VBOX_SHCL_GF_XXX - Guest features.
611 * @sa VBOX_SHCL_GUEST_FN_REPORT_FEATURES
612 * @{ */
613/** No flags set. */
614#define VBOX_SHCL_GF_NONE 0
615/** The guest can handle context IDs where applicable. */
616#define VBOX_SHCL_GF_0_CONTEXT_ID RT_BIT_64(0)
617/** The guest can copy & paste files and directories.
618 * @since 6.x */
619#define VBOX_SHCL_GF_0_TRANSFERS RT_BIT_64(1)
620/** The guest supports a (guest OS-)native frontend for showing and handling file transfers.
621 * If not set, the host will show a modal progress dialog instead and transferring file to
622 * a guest-specific temporary location first.
623 * Currently only supported for Windows guests (integrated into Windows Explorer via IDataObject). */
624#define VBOX_SHCL_GF_0_TRANSFERS_FRONTEND RT_BIT_64(2)
625/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
626 * correctly (old hosts might not). */
627#define VBOX_SHCL_GF_1_MUST_BE_ONE RT_BIT_64(63)
628/** @} */
629
630/** @name VBOX_GUESTCTRL_HF_XXX - Host features.
631 * @sa VBOX_SHCL_GUEST_FN_REPORT_FEATURES
632 * @{ */
633/** No flags set. */
634#define VBOX_SHCL_HF_NONE 0
635/** The host can handle context IDs where applicable as well as the new
636 * message handling functions. */
637#define VBOX_SHCL_HF_0_CONTEXT_ID RT_BIT_64(0)
638/** The host can copy & paste files and directories.
639 * This includes messages like
640 * @since 7.1 */
641#define VBOX_SHCL_HF_0_TRANSFERS RT_BIT_64(1)
642/** @} */
643
644/** @name Context ID related macros and limits
645 * @{ */
646/**
647 * Creates a context ID out of a client ID, a transfer ID and an event ID (count).
648 */
649#define VBOX_SHCL_CONTEXTID_MAKE(a_idSession, a_idTransfer, a_idEvent) \
650 ( ((uint64_t)((a_idSession) & 0xffff) << 48) \
651 | ((uint64_t)((a_idTransfer) & 0xffff) << 32) \
652 | ((uint32_t) (a_idEvent)) \
653 )
654/** Creates a context ID out of a session ID. */
655#define VBOX_SHCL_CONTEXTID_MAKE_SESSION(a_idSession) VBOX_SHCL_CONTEXTID_MAKE(a_idSession, 0, 0)
656/** Gets the session ID out of a context ID. */
657#define VBOX_SHCL_CONTEXTID_GET_SESSION(a_idContext) ( (uint16_t)(((a_idContext) >> 48) & UINT16_MAX) )
658/** Gets the transfer ID out of a context ID. */
659#define VBOX_SHCL_CONTEXTID_GET_TRANSFER(a_idContext) ( (uint16_t)(((a_idContext) >> 32) & UINT16_MAX) )
660/** Gets the transfer event out of a context ID. */
661#define VBOX_SHCL_CONTEXTID_GET_EVENT(a_idContext) ( (uint32_t)( (a_idContext) & UINT32_MAX) )
662
663/** Maximum number of concurrent Shared Clipboard client sessions a VM can have. */
664#define VBOX_SHCL_MAX_SESSIONS (UINT16_MAX - 1)
665/** Maximum number of concurrent Shared Clipboard transfers a single client can have. */
666#define VBOX_SHCL_MAX_TRANSFERS (UINT16_MAX - 1)
667/** Maximum number of events a single Shared Clipboard transfer can have. */
668#define VBOX_SHCL_MAX_EVENTS (UINT32_MAX - 1)
669/** @} */
670
671
672/*
673 * HGCM parameter structures.
674 */
675/** @todo r=bird: These structures are mostly pointless, as they're only
676 * ever used by the VbglR3 part. The host service does not use these
677 * structures for decoding guest requests, instead it's all hardcoded. */
678#pragma pack(1)
679/**
680 * Waits (blocking) for a new host message to arrive.
681 * Deprecated; do not use anymore.
682 * Kept for maintaining compatibility with older Guest Additions.
683 */
684typedef struct _VBoxShClGetHostMsgOld
685{
686 VBGLIOCHGCMCALL hdr;
687
688 /** uint32_t, out: Host message type. */
689 HGCMFunctionParameter msg;
690 /** uint32_t, out: VBOX_SHCL_FMT_*, depends on the 'msg'.
691 * r=andy This actual can have *different* meanings, depending on the host message type. */
692 HGCMFunctionParameter formats; /* OUT uint32_t */
693} VBoxShClGetHostMsgOld;
694
695#define VBOX_SHCL_CPARMS_GET_HOST_MSG_OLD 2
696
697/** @name VBOX_SHCL_GUEST_FN_REPORT_FORMATS
698 * @{ */
699/** VBOX_SHCL_GUEST_FN_REPORT_FORMATS parameters. */
700typedef struct VBoxShClParmReportFormats
701{
702 /** uint32_t, int: Zero or more VBOX_SHCL_FMT_XXX bits. */
703 HGCMFunctionParameter f32Formats;
704} VBoxShClParmReportFormats;
705
706#define VBOX_SHCL_CPARMS_REPORT_FORMATS 1 /**< The parameter count for VBOX_SHCL_GUEST_FN_REPORT_FORMATS. */
707#define VBOX_SHCL_CPARMS_REPORT_FORMATS_61B 3 /**< The 6.1 dev cycle variant, see VBOX_SHCL_GUEST_FN_REPORT_FORMATS. */
708/** @} */
709
710/** @name VBOX_SHCL_GUEST_FN_DATA_READ
711 * @{ */
712/** VBOX_SHCL_GUEST_FN_DATA_READ parameters. */
713typedef struct VBoxShClParmDataRead
714{
715 /** uint32_t, in: Requested format (VBOX_SHCL_FMT_XXX). */
716 HGCMFunctionParameter f32Format;
717 /** ptr, out: The data buffer to put the data in on success. */
718 HGCMFunctionParameter pData;
719 /** uint32_t, out: Size of returned data, if larger than the buffer, then no
720 * data was actually transferred and the guest must repeat the call. */
721 HGCMFunctionParameter cb32Needed;
722} VBoxShClParmDataRead;
723
724#define VBOX_SHCL_CPARMS_DATA_READ 3 /**< The parameter count for VBOX_SHCL_GUEST_FN_DATA_READ. */
725#define VBOX_SHCL_CPARMS_DATA_READ_61B 5 /**< The 6.1 dev cycle variant, see VBOX_SHCL_GUEST_FN_DATA_READ. */
726/** @} */
727
728/** @name
729 * @{ */
730
731/** VBOX_SHCL_GUEST_FN_DATA_WRITE parameters. */
732typedef struct VBoxShClParmDataWrite
733{
734 /** uint64_t, in: Context ID from VBOX_SHCL_HOST_MSG_READ_DATA. */
735 HGCMFunctionParameter id64Context;
736 /** uint32_t, in: The data format (VBOX_SHCL_FMT_XXX). */
737 HGCMFunctionParameter f32Format;
738 /** ptr, in: The data. */
739 HGCMFunctionParameter pData;
740} VBoxShClParmDataWrite;
741
742/** Old VBOX_SHCL_GUEST_FN_DATA_WRITE parameters. */
743typedef struct VBoxShClParmDataWriteOld
744{
745 /** uint32_t, in: The data format (VBOX_SHCL_FMT_XXX). */
746 HGCMFunctionParameter f32Format;
747 /** ptr, in: The data. */
748 HGCMFunctionParameter pData;
749} VBoxShClParmDataWriteOld;
750
751#define VBOX_SHCL_CPARMS_DATA_WRITE 3 /**< The variant used when VBOX_SHCL_GF_0_CONTEXT_ID is reported. */
752#define VBOX_SHCL_CPARMS_DATA_WRITE_OLD 2 /**< The variant used when VBOX_SHCL_GF_0_CONTEXT_ID isn't reported. */
753#define VBOX_SHCL_CPARMS_DATA_WRITE_61B 5 /**< The 6.1 dev cycle variant, see VBOX_SHCL_GUEST_FN_DATA_WRITE. */
754/** @} */
755
756/**
757 * Reports a transfer status.
758 */
759typedef struct _VBoxShClTransferStatusMsg
760{
761 VBGLIOCHGCMCALL hdr;
762
763 /** uint64_t, out: Context ID. */
764 HGCMFunctionParameter uContext;
765 /** uint32_t, out: Direction of transfer; of type SHCLTRANSFERDIR_. */
766 HGCMFunctionParameter enmDir;
767 /** uint32_t, out: Status to report; of type SHCLTRANSFERSTATUS_. */
768 HGCMFunctionParameter enmStatus;
769 /** uint32_t, out: Result code to report. Optional. */
770 HGCMFunctionParameter rc;
771 /** uint32_t, out: Reporting flags. Currently unused and must be 0. */
772 HGCMFunctionParameter fFlags;
773} VBoxShClTransferStatusMsg;
774
775#define VBOX_SHCL_CPARMS_TRANSFER_STATUS 5
776
777/**
778 * Asks the host for the next command to process, along
779 * with the needed amount of parameters and an optional blocking
780 * flag.
781 *
782 * Used by: VBOX_SHCL_GUEST_FN_GET_HOST_MSG
783 *
784 */
785typedef struct _VBoxShClGetHostMsg
786{
787 VBGLIOCHGCMCALL hdr;
788
789 /** uint32_t, out: Message ID. */
790 HGCMFunctionParameter uMsg;
791 /** uint32_t, out: Number of parameters the message needs. */
792 HGCMFunctionParameter cParms;
793 /** uint32_t, in: Whether or not to block (wait) for a new message to arrive. */
794 HGCMFunctionParameter fBlock;
795} VBoxShClPeekMsg;
796
797#define VBOX_SHCL_CPARMS_GET_HOST_MSG 3
798
799/** No listing flags specified. */
800#define VBOX_SHCL_LIST_F_NONE 0
801/** Only returns one entry per read. */
802#define VBOX_SHCL_LIST_F_RETURN_ONE RT_BIT(0)
803/** Restarts reading a list from the beginning. */
804#define VBOX_SHCL_LIST_F_RESTART RT_BIT(1)
805/** Listing flags valid mask. */
806#define VBOX_SHCL_LIST_F_VALID_MASK 0x3
807
808/** No list header flags specified. */
809#define VBOX_SHCL_LISTHDR_F_NONE 0
810/** List header flags valid mask. */
811#define VBOX_SHCL_LISTHDR_F_VALID_MASK 0x0
812
813/** No additional information provided. */
814#define VBOX_SHCL_INFO_F_NONE 0
815/** Get object information of type SHCLFSOBJINFO. */
816#define VBOX_SHCL_INFO_F_FSOBJINFO RT_BIT(0)
817/** Info flags valid mask. */
818#define VBOX_SHCL_INFO_F_VALID_MASK 0x1
819
820/**
821 * Status message for lists and objects.
822 */
823typedef struct _VBoxShClStatusMsg
824{
825 VBGLIOCHGCMCALL hdr;
826
827 /** uint64_t, in: Context ID. */
828 HGCMFunctionParameter uContext;
829 /** uint32_t, in: Transfer status of type SHCLTRANSFERSTATUS. */
830 HGCMFunctionParameter uStatus;
831 /** pointer, in: Optional payload of this status, based on the status type. */
832 HGCMFunctionParameter pvPayload;
833} VBoxShClStatusMsg;
834
835#define VBOX_SHCL_CPARMS_STATUS 3
836
837/** Invalid message type, do not use. */
838#define VBOX_SHCL_TX_REPLYMSGTYPE_INVALID 0
839/** Replies a transfer status. */
840#define VBOX_SHCL_TX_REPLYMSGTYPE_TRANSFER_STATUS 1
841/** Replies a list open status. */
842#define VBOX_SHCL_TX_REPLYMSGTYPE_LIST_OPEN 2
843/** Replies a list close status. */
844#define VBOX_SHCL_TX_REPLYMSGTYPE_LIST_CLOSE 3
845/** Replies an object open status. */
846#define VBOX_SHCL_TX_REPLYMSGTYPE_OBJ_OPEN 4
847/** Replies an object close status. */
848#define VBOX_SHCL_TX_REPLYMSGTYPE_OBJ_CLOSE 5
849
850/**
851 * Generic reply message.
852 */
853typedef struct _VBoxShClReplyMsg
854{
855 VBGLIOCHGCMCALL hdr;
856
857 /** uint64_t, out: Context ID. */
858 HGCMFunctionParameter uContext;
859 /** uint32_t, out: Message type of type VBOX_SHCL_TX_REPLYMSGTYPE_XXX. */
860 HGCMFunctionParameter enmType;
861 /** uint32_t, out: IPRT result of overall operation. */
862 HGCMFunctionParameter rc;
863 /** pointer, out: Optional payload of this reply, based on the message type. */
864 HGCMFunctionParameter pvPayload;
865 union
866 {
867 struct
868 {
869 HGCMFunctionParameter enmStatus;
870 } TransferStatus;
871 struct
872 {
873 HGCMFunctionParameter uHandle;
874 } ListOpen;
875 struct
876 {
877 HGCMFunctionParameter uHandle;
878 } ObjOpen;
879 struct
880 {
881 HGCMFunctionParameter uHandle;
882 } ObjClose;
883 } u;
884} VBoxShClReplyMsg;
885
886/** Minimum parameters (HGCM function parameters minus the union) a reply message must have. */
887#define VBOX_SHCL_CPARMS_REPLY_MIN 4
888
889/**
890 * Structure for keeping root list message parameters.
891 */
892typedef struct _VBoxShClRootListParms
893{
894 /** uint64_t, in: Context ID. */
895 HGCMFunctionParameter uContext;
896 /** uint32_t, in: Roots listing flags; unused at the moment. */
897 HGCMFunctionParameter fRoots;
898} VBoxShClRootListParms;
899
900#define VBOX_SHCL_CPARMS_ROOT_LIST 2
901
902/**
903 * Requests to read the root list header.
904 */
905typedef struct _VBoxShClRootListReadReqMsg
906{
907 VBGLIOCHGCMCALL hdr;
908
909 VBoxShClRootListParms ReqParms;
910} VBoxShClRootListReadReqMsg;
911
912#define VBOX_SHCL_CPARMS_ROOT_LIST_HDR_READ_REQ VBOX_SHCL_CPARMS_ROOT_LIST
913
914/**
915 * Reads / Writes a root list header.
916 */
917typedef struct _VBoxShClRootListHdrMsg
918{
919 VBGLIOCHGCMCALL hdr;
920
921 VBoxShClRootListParms ReqParms;
922 /** uint64_t, in/out: Number of total root list entries. */
923 HGCMFunctionParameter cRoots;
924} VBoxShClRootListHdrMsg;
925
926#define VBOX_SHCL_CPARMS_ROOT_LIST_HDR_READ VBOX_SHCL_CPARMS_ROOT_LIST + 1
927#define VBOX_SHCL_CPARMS_ROOT_LIST_HDR_WRITE VBOX_SHCL_CPARMS_ROOT_LIST + 1
928
929/**
930 * Structure for keeping list entry message parameters.
931 */
932typedef struct _VBoxShClRootListEntryParms
933{
934 /** uint64_t, in: Context ID. */
935 HGCMFunctionParameter uContext;
936 /** uint32_t, in: VBOX_SHCL_INFO_F_XXX. */
937 HGCMFunctionParameter fInfo;
938 /** uint64_t, in: Index of root list entry to get (zero-based). */
939 HGCMFunctionParameter uIndex;
940} VBoxShClRootListEntryParms;
941
942#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY 3
943
944/**
945 * Request to read a list root entry.
946 */
947typedef struct _VBoxShClRootListEntryReadReqMsg
948{
949 VBGLIOCHGCMCALL hdr;
950
951 /** in: Request parameters. */
952 VBoxShClRootListEntryParms Parms;
953} VBoxShClRootListEntryReadReqMsg;
954
955#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY_READ_REQ VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY
956
957/**
958 * Reads / Writes a root list entry.
959 */
960typedef struct _VBoxShClRootListEntryMsg
961{
962 VBGLIOCHGCMCALL hdr;
963
964 /** in/out: Request parameters. */
965 VBoxShClRootListEntryParms Parms;
966 /** pointer, in/out: Entry name.
967 * Up to SHCLLISTENTRY_MAX_NAME. */
968 HGCMFunctionParameter szName;
969 /** uint32_t, out: Bytes to be used for information/How many bytes were used. */
970 HGCMFunctionParameter cbInfo;
971 /** pointer, in/out: Information to be set/get (SHCLFSOBJINFO only currently).
972 * Do not forget to set the SHCLFSOBJINFO::Attr::enmAdditional for Get operation as well. */
973 HGCMFunctionParameter pvInfo;
974} VBoxShClRootListEntryMsg;
975
976#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY_READ VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY + 3
977#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY_WRITE VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY + 3
978
979/**
980 * Opens a list.
981 */
982typedef struct _VBoxShClListOpenMsg
983{
984 VBGLIOCHGCMCALL hdr;
985
986 /** uint64_t, in: Context ID. */
987 HGCMFunctionParameter uContext;
988 /** uint32_t, in: Listing flags (see VBOX_SHCL_LIST_FLAG_XXX). */
989 HGCMFunctionParameter fList;
990 /** pointer, in: Filter string. */
991 HGCMFunctionParameter pvFilter;
992 /** pointer, in: Listing poth. If empty or NULL the listing's root path will be opened. */
993 HGCMFunctionParameter pvPath;
994 /** uint64_t, out: List handle. */
995 HGCMFunctionParameter uHandle;
996} VBoxShClListOpenMsg;
997
998#define VBOX_SHCL_CPARMS_LIST_OPEN 5
999
1000/**
1001 * Closes a list.
1002 */
1003typedef struct _VBoxShClListCloseMsg
1004{
1005 VBGLIOCHGCMCALL hdr;
1006
1007 /** uint64_t, in/out: Context ID. */
1008 HGCMFunctionParameter uContext;
1009 /** uint64_t, in: List handle. */
1010 HGCMFunctionParameter uHandle;
1011} VBoxShClListCloseMsg;
1012
1013#define VBOX_SHCL_CPARMS_LIST_CLOSE 2
1014
1015typedef struct _VBoxShClListHdrReqParms
1016{
1017 /** uint64_t, in: Context ID. */
1018 HGCMFunctionParameter uContext;
1019 /** uint64_t, in: List handle. */
1020 HGCMFunctionParameter uHandle;
1021 /** uint32_t, in: Flags of type VBOX_SHCL_LISTHDR_FLAG_XXX. */
1022 HGCMFunctionParameter fFlags;
1023} VBoxShClListHdrReqParms;
1024
1025#define VBOX_SHCL_CPARMS_LIST_HDR_REQ 3
1026
1027/**
1028 * Request to read a list header.
1029 */
1030typedef struct _VBoxShClListHdrReadReqMsg
1031{
1032 VBGLIOCHGCMCALL hdr;
1033
1034 VBoxShClListHdrReqParms ReqParms;
1035} VBoxShClListHdrReadReqMsg;
1036
1037#define VBOX_SHCL_CPARMS_LIST_HDR_READ_REQ VBOX_SHCL_CPARMS_LIST_HDR_REQ
1038
1039/**
1040 * Reads / Writes a list header.
1041 */
1042typedef struct _VBoxShClListHdrMsg
1043{
1044 VBGLIOCHGCMCALL hdr;
1045
1046 VBoxShClListHdrReqParms ReqParms;
1047 /** uint32_t, in/out: Feature flags (see VBOX_SHCL_FEATURE_FLAG_XXX). */
1048 HGCMFunctionParameter fFeatures;
1049 /** uint64_t, in/out: Number of total objects to transfer. */
1050 HGCMFunctionParameter cTotalObjects;
1051 /** uint64_t, in/out: Number of total bytes to transfer. */
1052 HGCMFunctionParameter cbTotalSize;
1053} VBoxShClListHdrMsg;
1054
1055#define VBOX_SHCL_CPARMS_LIST_HDR VBOX_SHCL_CPARMS_LIST_HDR_REQ + 3
1056
1057typedef struct _VBoxShClListEntryReqParms
1058{
1059 /** uint64_t, in: Context ID. */
1060 HGCMFunctionParameter uContext;
1061 /** uint64_t, in: List handle. */
1062 HGCMFunctionParameter uHandle;
1063 /** uint32_t, in: VBOX_SHCL_INFO_F_XXX. */
1064 HGCMFunctionParameter fInfo;
1065} VBoxShClListEntryReqParms;
1066
1067#define VBOX_SHCL_CPARMS_LIST_ENTRY_REQ 3
1068
1069/**
1070 * Request to read a list entry.
1071 */
1072typedef struct _VBoxShClListEntryReadReqMsg
1073{
1074 VBGLIOCHGCMCALL hdr;
1075
1076 VBoxShClListEntryReqParms ReqParms;
1077} VBoxShClListEntryReadReqMsg;
1078
1079#define VBOX_SHCL_CPARMS_LIST_ENTRY_READ VBOX_SHCL_CPARMS_LIST_ENTRY_REQ
1080
1081/**
1082 * Reads / Writes a list entry.
1083 */
1084typedef struct _VBoxShClListEntryMsg
1085{
1086 VBGLIOCHGCMCALL hdr;
1087
1088 /** in/out: Request parameters. */
1089 VBoxShClListEntryReqParms ReqParms;
1090 /** pointer, in/out: Entry name. */
1091 HGCMFunctionParameter szName;
1092 /** uint32_t, out: Bytes to be used for information/How many bytes were used. */
1093 HGCMFunctionParameter cbInfo;
1094 /** pointer, in/out: Information to be set/get (SHCLFSOBJINFO only currently).
1095 * Do not forget to set the SHCLFSOBJINFO::Attr::enmAdditional for Get operation as well. */
1096 HGCMFunctionParameter pvInfo;
1097} VBoxShClListEntryMsg;
1098
1099#define VBOX_SHCL_CPARMS_LIST_ENTRY VBOX_SHCL_CPARMS_LIST_ENTRY_REQ + 3
1100
1101/**
1102 * Opens a Shared Clipboard object.
1103 */
1104typedef struct _VBoxShClObjOpenMsg
1105{
1106 VBGLIOCHGCMCALL hdr;
1107
1108 /** uint64_t, in/out: Context ID. */
1109 HGCMFunctionParameter uContext;
1110 /** uint64_t, out: Object handle. */
1111 HGCMFunctionParameter uHandle;
1112 /** pointer, in: Absoulte path of object to open/create. */
1113 HGCMFunctionParameter szPath;
1114 /** uint32_t in: Open / Create flags of type SHCL_OBJ_CF_. */
1115 HGCMFunctionParameter fCreate;
1116} VBoxShClObjOpenMsg;
1117
1118#define VBOX_SHCL_CPARMS_OBJ_OPEN 4
1119
1120/**
1121 * Closes a Shared Clipboard object.
1122 */
1123typedef struct _VBoxShClObjCloseMsg
1124{
1125 VBGLIOCHGCMCALL hdr;
1126
1127 /** uint64_t, in/out: Context ID. */
1128 HGCMFunctionParameter uContext;
1129 /** uint64_t, in: SHCLOBJHANDLE of object to close. */
1130 HGCMFunctionParameter uHandle;
1131} VBoxShClObjCloseMsg;
1132
1133#define VBOX_SHCL_CPARMS_OBJ_CLOSE 2
1134
1135/**
1136 * Structure for keeping read parameters of a Shared Clipboard object.
1137 */
1138typedef struct _VBoxShClObjReadReqParms
1139{
1140 /** uint64_t, in: Context ID. */
1141 HGCMFunctionParameter uContext;
1142 /** uint64_t, in: SHCLOBJHANDLE of object to write to. */
1143 HGCMFunctionParameter uHandle;
1144 /** uint32_t, in: How many bytes to read. */
1145 HGCMFunctionParameter cbToRead;
1146 /** uint32_t, in: Read flags. Currently unused and must be 0. */
1147 HGCMFunctionParameter fRead;
1148} VBoxShClObjReadReqParms;
1149
1150/**
1151 * Reads from a Shared Clipboard object.
1152 */
1153typedef struct _VBoxShClObjReadReqMsg
1154{
1155 VBGLIOCHGCMCALL hdr;
1156
1157 VBoxShClObjReadReqParms ReqParms;
1158} VBoxShClObjReadReqMsg;
1159
1160#define VBOX_SHCL_CPARMS_OBJ_READ_REQ 4
1161
1162/**
1163 * Reads / writes data of / to an object.
1164 *
1165 * Used by:
1166 * VBOX_SHCL_FN_OBJ_READ
1167 * VBOX_SHCL_FN_OBJ_WRITE
1168 */
1169typedef struct _VBoxShClObjReadWriteMsg
1170{
1171 VBGLIOCHGCMCALL hdr;
1172
1173 /** uint64_t, in/out: Context ID. */
1174 HGCMFunctionParameter uContext;
1175 /** uint64_t, in/out: SHCLOBJHANDLE of object to write to. */
1176 HGCMFunctionParameter uHandle;
1177 /** uint32_t, out: Size (in bytes) read/written. */
1178 HGCMFunctionParameter cbData;
1179 /** pointer, in/out: Current data chunk. */
1180 HGCMFunctionParameter pvData;
1181 /** uint32_t, in/out: Size (in bytes) of current data chunk checksum. */
1182 HGCMFunctionParameter cbChecksum;
1183 /** pointer, in/out: Checksum of data block, based on the checksum
1184 * type in the data header. Optional. */
1185 HGCMFunctionParameter pvChecksum;
1186} VBoxShClObjReadWriteMsg;
1187
1188#define VBOX_SHCL_CPARMS_OBJ_READ 6
1189#define VBOX_SHCL_CPARMS_OBJ_WRITE 6
1190
1191/**
1192 * Sends an error event.
1193 *
1194 * Used by:
1195 * VBOX_SHCL_FN_WRITE_ERROR
1196 */
1197typedef struct _VBoxShClErrorMsg
1198{
1199 VBGLIOCHGCMCALL hdr;
1200
1201 /** uint64_t, in: Context ID. */
1202 HGCMFunctionParameter uContext;
1203 /** uint32_t, in: The error code (IPRT-style). */
1204 HGCMFunctionParameter rc;
1205} VBoxShClWriteErrorMsg;
1206
1207#define VBOX_SHCL_CPARMS_ERROR 2
1208
1209/** @name VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE
1210 * @{ */
1211/** VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE parameters. */
1212typedef struct _VBoxShClParmNegotiateChunkSize
1213{
1214 VBGLIOCHGCMCALL hdr;
1215
1216 /** uint32_t, in: Maximum chunk size. */
1217 HGCMFunctionParameter cb32MaxChunkSize;
1218 /** uint32_t, in: Default chunk size. */
1219 HGCMFunctionParameter cb32ChunkSize;
1220} VBoxShClParmNegotiateChunkSize;
1221
1222#define VBOX_SHCL_CPARMS_NEGOTIATE_CHUNK_SIZE 2
1223/** @} */
1224
1225#pragma pack()
1226
1227#endif /* !VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h */
1228
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