VirtualBox

source: vbox/trunk/include/VBox/HostServices/GuestControlSvc.h@ 102831

最後變更 在這個檔案從102831是 102831,由 vboxsync 提交於 14 月 前

Guest Control: Added a new guest feature flag to indicate Guest Additions support for retrieving guest mount points. bugref:10415
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 54.2 KB
行 
1/* $Id: GuestControlSvc.h 102831 2024-01-11 08:56:53Z vboxsync $ */
2/** @file
3 * Guest control service - Common header for host service and guest clients.
4 */
5
6/*
7 * Copyright (C) 2011-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.alldomusa.eu.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37#ifndef VBOX_INCLUDED_HostServices_GuestControlSvc_h
38#define VBOX_INCLUDED_HostServices_GuestControlSvc_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/assert.h>
44#include <VBox/hgcmsvc.h>
45
46#include <VBox/VMMDevCoreTypes.h>
47#include <VBox/GuestHost/GuestControl.h>
48#include <VBox/VBoxGuestCoreTypes.h>
49
50/* Everything defined in this file lives in this namespace. */
51namespace guestControl {
52
53/******************************************************************************
54* Typedefs, constants and inlines *
55******************************************************************************/
56
57#define HGCMSERVICE_NAME "VBoxGuestControlSvc"
58
59/** Maximum number of concurrent guest sessions a VM can have. */
60#define VBOX_GUESTCTRL_MAX_SESSIONS 32
61/** Maximum number of concurrent guest objects (processes, files, ...)
62 * a guest session can have. */
63#define VBOX_GUESTCTRL_MAX_OBJECTS _2K
64/** Maximum of callback contexts a guest process can have. */
65#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K
66
67/** Base (start) of guest control session IDs. Session
68 * ID 0 is reserved for the root process which
69 * hosts all other guest session processes. */
70#define VBOX_GUESTCTRL_SESSION_ID_BASE 1
71
72/** Builds a context ID out of the session ID, object ID and an
73 * increasing count. */
74#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \
75 ( (uint32_t)((uSession) & 0x1f) << 27 \
76 | (uint32_t)((uObject) & 0x7ff) << 16 \
77 | (uint32_t)((uCount) & 0xffff) \
78 )
79/** Creates a context ID out of a session ID. */
80#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
81 ((uint32_t)((uSession) & 0x1f) << 27)
82/** Gets the session ID out of a context ID. */
83#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
84 (((uContextID) >> 27) & 0x1f)
85/** Gets the process ID out of a context ID. */
86#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
87 (((uContextID) >> 16) & 0x7ff)
88/** Gets the context count of a process out of a context ID. */
89#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
90 ((uContextID) & 0xffff)
91/** Filter context IDs by session. Can be used in conjunction
92 * with VbglR3GuestCtrlMsgFilterSet(). */
93#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \
94 (VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) | 0xF8000000)
95
96/**
97 * Structure keeping the context of a host callback.
98 */
99typedef struct VBOXGUESTCTRLHOSTCBCTX
100{
101 /** HGCM message number. */
102 uint32_t uMessage;
103 /** The context ID. */
104 uint32_t uContextID;
105 /** Protocol version of this guest session. Might
106 * be 0 if not supported. */
107 uint32_t uProtocol;
108} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX;
109
110/**
111 * Structure for low level HGCM host callback from
112 * the guest. No deep copy. */
113typedef struct VBOXGUESTCTRLHOSTCALLBACK
114{
115 /** Number of HGCM parameters. */
116 uint32_t mParms;
117 /** Actual HGCM parameters. */
118 PVBOXHGCMSVCPARM mpaParms;
119} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
120
121/** @name Host message destination flags.
122 *
123 * This is ORed into the context ID parameter Main after extending it to 64-bit.
124 *
125 * @internal Host internal.
126 * @{ */
127#define VBOX_GUESTCTRL_DST_ROOT_SVC RT_BIT_64(63)
128#define VBOX_GUESTCTRL_DST_SESSION RT_BIT_64(62)
129#define VBOX_GUESTCTRL_DST_BOTH ( VBOX_GUESTCTRL_DST_ROOT_SVC | VBOX_GUESTCTRL_DST_SESSION )
130/** @} */
131
132
133/**
134 * The service messages which are callable by host.
135 */
136enum eHostMsg
137{
138 /**
139 * The host asks the client to cancel all pending waits and exit.
140 */
141 HOST_MSG_CANCEL_PENDING_WAITS = 0,
142 /**
143 * The host wants to create a guest session.
144 */
145 HOST_MSG_SESSION_CREATE = 20,
146 /**
147 * The host wants to close a guest session.
148 */
149 HOST_MSG_SESSION_CLOSE = 21,
150 /**
151 * The host wants to execute something in the guest. This can be a command
152 * line or starting a program.
153 */
154 HOST_MSG_EXEC_CMD = 100,
155 /**
156 * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
157 */
158 HOST_MSG_EXEC_SET_INPUT = 101,
159 /**
160 * Gets the current status of a running process, e.g.
161 * new data on stdout/stderr, process terminated etc.
162 */
163 HOST_MSG_EXEC_GET_OUTPUT = 102,
164 /**
165 * Terminates a running guest process.
166 */
167 HOST_MSG_EXEC_TERMINATE = 110,
168 /**
169 * Waits for a certain event to happen. This can be an input, output
170 * or status event.
171 */
172 HOST_MSG_EXEC_WAIT_FOR = 120,
173 /**
174 * Opens a guest file.
175 */
176 HOST_MSG_FILE_OPEN = 240,
177 /**
178 * Closes a guest file.
179 */
180 HOST_MSG_FILE_CLOSE,
181 /**
182 * Reads from an opened guest file.
183 */
184 HOST_MSG_FILE_READ = 250,
185 /**
186 * Reads from an opened guest file at a specified offset.
187 */
188 HOST_MSG_FILE_READ_AT,
189 /**
190 * Write to an opened guest file.
191 */
192 HOST_MSG_FILE_WRITE = 260,
193 /**
194 * Write to an opened guest file at a specified offset.
195 */
196 HOST_MSG_FILE_WRITE_AT,
197 /**
198 * Changes the read & write position of an opened guest file.
199 */
200 HOST_MSG_FILE_SEEK = 270,
201 /**
202 * Gets the current file position of an opened guest file.
203 */
204 HOST_MSG_FILE_TELL = 271,
205 /**
206 * Changes the file size.
207 */
208 HOST_MSG_FILE_SET_SIZE = 272,
209#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
210 /**
211 * Removes a file on the guest.
212 */
213 HOST_MSG_FILE_REMOVE = 273,
214 /**
215 * Opens (creates) a directory on the guest.
216 */
217 HOST_MSG_DIR_OPEN = 310,
218 /**
219 * Closes a directory on the guest.
220 */
221 HOST_MSG_DIR_CLOSE = 311,
222 /**
223 * Reads the next directory entry on the guest.
224 */
225 HOST_MSG_DIR_READ = 312,
226 /**
227 * Rewinds and restarts the directory reading on the guest.
228 */
229 HOST_MSG_DIR_REWIND = 313,
230 /**
231 * Creates a directory on the guest.
232 */
233 HOST_MSG_DIR_CREATE = 314,
234 /**
235 * Lists one or multiple directory entries at once.
236 *
237 * @since 7.1
238 */
239 HOST_MSG_DIR_LIST = 315,
240#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
241 /**
242 * Removes a directory on the guest.
243 */
244 HOST_MSG_DIR_REMOVE = 320,
245 /**
246 * Renames a path on the guest.
247 */
248 HOST_MSG_PATH_RENAME = 330,
249 /**
250 * Retrieves the user's documents directory.
251 */
252 HOST_MSG_PATH_USER_DOCUMENTS = 331,
253 /**
254 * Retrieves the user's home directory.
255 */
256 HOST_MSG_PATH_USER_HOME = 332,
257 /**
258 * Issues a shutdown / reboot of the guest OS.
259 */
260 HOST_MSG_SHUTDOWN = 333,
261#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
262 /**
263 * Retrieves information about a file system object.
264 */
265 HOST_MSG_FS_OBJ_QUERY_INFO = 334,
266 /**
267 * Creates a temporary file or directory.
268 */
269 HOST_MSG_FS_CREATE_TEMP = 335,
270 /**
271 * Retrieves information about a guest file system.
272 */
273 HOST_MSG_FS_QUERY_INFO = 336,
274#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
275 /**
276 * Retrieves the currently accessible mount points from the guest.
277 *
278 * @since 7.1
279 */
280 HOST_MSG_MOUNT_POINTS = 337,
281 /** Blow the type up to 32-bits. */
282 HOST_MSG_32BIT_HACK = 0x7fffffff
283};
284
285
286/**
287 * Translates a guest control host message enum to a string.
288 *
289 * @returns Enum string name.
290 * @param enmMsg The message to translate.
291 */
292DECLINLINE(const char *) GstCtrlHostMsgtoStr(enum eHostMsg enmMsg)
293{
294 switch (enmMsg)
295 {
296 RT_CASE_RET_STR(HOST_MSG_CANCEL_PENDING_WAITS);
297 RT_CASE_RET_STR(HOST_MSG_SESSION_CREATE);
298 RT_CASE_RET_STR(HOST_MSG_SESSION_CLOSE);
299 RT_CASE_RET_STR(HOST_MSG_EXEC_CMD);
300 RT_CASE_RET_STR(HOST_MSG_EXEC_SET_INPUT);
301 RT_CASE_RET_STR(HOST_MSG_EXEC_GET_OUTPUT);
302 RT_CASE_RET_STR(HOST_MSG_EXEC_TERMINATE);
303 RT_CASE_RET_STR(HOST_MSG_EXEC_WAIT_FOR);
304 RT_CASE_RET_STR(HOST_MSG_FILE_OPEN);
305 RT_CASE_RET_STR(HOST_MSG_FILE_CLOSE);
306 RT_CASE_RET_STR(HOST_MSG_FILE_READ);
307 RT_CASE_RET_STR(HOST_MSG_FILE_READ_AT);
308 RT_CASE_RET_STR(HOST_MSG_FILE_WRITE);
309 RT_CASE_RET_STR(HOST_MSG_FILE_WRITE_AT);
310 RT_CASE_RET_STR(HOST_MSG_FILE_SEEK);
311 RT_CASE_RET_STR(HOST_MSG_FILE_TELL);
312 RT_CASE_RET_STR(HOST_MSG_FILE_SET_SIZE);
313#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
314 RT_CASE_RET_STR(HOST_MSG_FILE_REMOVE);
315 RT_CASE_RET_STR(HOST_MSG_DIR_OPEN);
316 RT_CASE_RET_STR(HOST_MSG_DIR_CLOSE);
317 RT_CASE_RET_STR(HOST_MSG_DIR_READ);
318 RT_CASE_RET_STR(HOST_MSG_DIR_REWIND);
319 RT_CASE_RET_STR(HOST_MSG_DIR_CREATE);
320 RT_CASE_RET_STR(HOST_MSG_DIR_LIST);
321#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
322 RT_CASE_RET_STR(HOST_MSG_DIR_REMOVE);
323 RT_CASE_RET_STR(HOST_MSG_PATH_RENAME);
324 RT_CASE_RET_STR(HOST_MSG_PATH_USER_DOCUMENTS);
325 RT_CASE_RET_STR(HOST_MSG_PATH_USER_HOME);
326 RT_CASE_RET_STR(HOST_MSG_SHUTDOWN);
327#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
328 RT_CASE_RET_STR(HOST_MSG_FS_OBJ_QUERY_INFO);
329 RT_CASE_RET_STR(HOST_MSG_FS_CREATE_TEMP);
330 RT_CASE_RET_STR(HOST_MSG_FS_QUERY_INFO);
331#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
332 RT_CASE_RET_STR(HOST_MSG_MOUNT_POINTS);
333 RT_CASE_RET_STR(HOST_MSG_32BIT_HACK);
334 }
335 return "Unknown";
336}
337
338
339/**
340 * The service messages which are callable by the guest.
341 *
342 * @note The message numbers cannot be changed. Please use the first non-zero
343 * number that's not in use when adding new messages.
344 *
345 * @note Remember to update service.cpp when adding new messages for Main,
346 * as it validates all incoming messages before passing them on.
347 */
348enum eGuestMsg
349{
350 /** Guest waits for a new message the host wants to process on the guest side.
351 * This is a blocking call and can be deferred.
352 *
353 * @note This message is rather odd. The above description isn't really
354 * correct. Yes, it (1) waits for a new message and will return the
355 * mesage number and parameter count when one is available. However, it
356 * is also (2) used to retrieve the message parameters. For some weird
357 * reasons it was decided that it should always return VERR_TOO_MUCH_DATA
358 * when used in the first capacity.
359 *
360 * @note Has a problem if the guest kernel module cancels the HGCM call, as the
361 * guest cannot resume waiting till the host issues a message for it and
362 * the cancelled call returns. The new message may potentially end up in
363 * /dev/null depending and hang the message conversation between the guest
364 * and the host (SIGCHLD).
365 *
366 * @deprecated Replaced by GUEST_MSG_PEEK_WAIT, GUEST_MSG_GET and
367 * GUEST_MSG_CANCEL.
368 */
369 GUEST_MSG_WAIT = 1,
370 /** Cancels pending calls for this client session.
371 *
372 * This should be used if a GUEST_MSG_PEEK_WAIT or GUEST_MSG_WAIT call gets
373 * interrupted on the client end, so as to prevent being rebuffed with
374 * VERR_RESOURCE_BUSY when restarting the call.
375 *
376 * @retval VINF_SUCCESS if cancelled any calls.
377 * @retval VWRN_NOT_FOUND if no callers.
378 * @retval VERR_INVALID_CLIENT_ID
379 * @retval VERR_WRONG_PARAMETER_COUNT
380 * @since 6.0
381 */
382 GUEST_MSG_CANCEL = 2,
383 /** Guest disconnected (terminated normally or due to a crash HGCM
384 * detected when calling service::clientDisconnect().
385 *
386 * @note This is a host side notification message that has no business in this
387 * enum. The guest cannot use this message number, host will reject it.
388 */
389 GUEST_MSG_DISCONNECTED = 3,
390 /** Sets a message filter to only get messages which have a certain
391 * context ID scheme (that is, a specific session, object etc).
392 * Since VBox 4.3+.
393 * @deprecated Replaced by GUEST_SESSION_ACCEPT.
394 */
395 GUEST_MSG_FILTER_SET = 4,
396 /** Unsets (and resets) a previously set message filter.
397 * @retval VERR_NOT_IMPLEMENTED since 6.0.
398 * @deprecated Never needed or used,
399 */
400 GUEST_MSG_FILTER_UNSET = 5,
401 /** Peeks at the next message, returning immediately.
402 *
403 * Returns two 32-bit parameters, first is the message ID and the second the
404 * parameter count. May optionally return additional 32-bit parameters with the
405 * sizes of respective message parameters. To distinguish buffer sizes from
406 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
407 * uint64_t is ~8U).
408 *
409 * Does also support the VM restore checking as in GUEST_MSG_PEEK_WAIT (64-bit
410 * param \# 0), see documentation there.
411 *
412 * @retval VINF_SUCCESS if a message was pending and is being returned.
413 * @retval VERR_TRY_AGAIN if no message pending.
414 * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that
415 * does not match VbglR3GetSessionId() any more. The new value is
416 * returned.
417 * @retval VERR_INVALID_CLIENT_ID
418 * @retval VERR_WRONG_PARAMETER_COUNT
419 * @retval VERR_WRONG_PARAMETER_TYPE
420 * @since 6.0
421 */
422 GUEST_MSG_PEEK_NOWAIT = 6,
423 /** Peeks at the next message, waiting for one to arrive.
424 *
425 * Returns two 32-bit parameters, first is the message ID and the second the
426 * parameter count. May optionally return additional 32-bit parameters with the
427 * sizes of respective message parameters. To distinguish buffer sizes from
428 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
429 * uint64_t is ~8U).
430 *
431 * To facilitate VM restore checking, the first parameter can be a 64-bit
432 * integer holding the VbglR3GetSessionId() value the guest knowns. The
433 * function will then check this before going to sleep and return
434 * VERR_VM_RESTORED if it doesn't match, same thing happens when the VM is
435 * restored.
436 *
437 * @retval VINF_SUCCESS if info about an pending message is being returned.
438 * @retval VINF_TRY_AGAIN and message set to HOST_CANCEL_PENDING_WAITS if
439 * cancelled by GUEST_MSG_CANCEL.
440 * @retval VERR_RESOURCE_BUSY if another thread already made a waiting call.
441 * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that
442 * does not match VbglR3GetSessionId() any more. The new value is
443 * returned.
444 * @retval VERR_INVALID_CLIENT_ID
445 * @retval VERR_WRONG_PARAMETER_COUNT
446 * @retval VERR_WRONG_PARAMETER_TYPE
447 * @note This replaces GUEST_MSG_WAIT.
448 * @since 6.0
449 */
450 GUEST_MSG_PEEK_WAIT = 7,
451 /** Gets the next message, returning immediately.
452 *
453 * All parameters are specific to the message being retrieved, however if the
454 * first one is an integer value it shall be an input parameter holding the
455 * ID of the message being retrieved. While it would be nice to add a separate
456 * parameter for this purpose, this is difficult without breaking GUEST_MSG_WAIT
457 * compatibility.
458 *
459 * @retval VINF_SUCCESS if message retrieved and removed from the pending queue.
460 * @retval VERR_TRY_AGAIN if no message pending.
461 * @retval VERR_MISMATCH if the incoming message ID does not match the pending.
462 * @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer
463 * size was updated to reflect the required size.
464 * @retval VERR_INVALID_CLIENT_ID
465 * @retval VERR_WRONG_PARAMETER_COUNT
466 * @retval VERR_WRONG_PARAMETER_TYPE
467 * @note This replaces GUEST_MSG_WAIT.
468 * @since 6.0
469 */
470 GUEST_MSG_GET = 8,
471 /** Skip message.
472 *
473 * This skips the current message, replying to the main backend as best it can.
474 * Takes between zero and two parameters. The first parameter is the 32-bit
475 * VBox status code to pass onto Main when skipping the message, defaults to
476 * VERR_NOT_SUPPORTED. The second parameter is the 32-bit message ID of the
477 * message to skip, by default whatever is first in the queue is removed. This
478 * is also the case if UINT32_MAX is specified.
479 *
480 * @retval VINF_SUCCESS on success.
481 * @retval VERR_NOT_FOUND if no message pending.
482 * @retval VERR_MISMATCH if the specified message ID didn't match.
483 * @retval VERR_INVALID_CLIENT_ID
484 * @retval VERR_WRONG_PARAMETER_COUNT
485 * @since 6.0
486 */
487 GUEST_MSG_SKIP = 9,
488 /**
489 * Skips the current assigned message returned by GUEST_MSG_WAIT.
490 * Needed for telling the host service to not keep stale
491 * host messages in the queue.
492 * @deprecated Replaced by GUEST_MSG_SKIP.
493 */
494 GUEST_MSG_SKIP_OLD = 10,
495 /** General reply to a host message.
496 * Only contains basic data along with a simple payload.
497 * @todo proper docs.
498 */
499 GUEST_MSG_REPLY = 11,
500 /** General message for updating a pending progress for a long task.
501 * @todo proper docs.
502 */
503 GUEST_MSG_PROGRESS_UPDATE = 12,
504 /** Sets the caller as the master.
505 *
506 * Called by the root VBoxService to explicitly tell the host that's the master
507 * service. Required to use main VBoxGuest device node. No parameters.
508 *
509 * @retval VINF_SUCCESS on success.
510 * @retval VERR_ACCESS_DENIED if not using main VBoxGuest device not
511 * @retval VERR_RESOURCE_BUSY if there is already a master.
512 * @retval VERR_VERSION_MISMATCH if VBoxGuest didn't supply requestor info.
513 * @retval VERR_INVALID_CLIENT_ID
514 * @retval VERR_WRONG_PARAMETER_COUNT
515 * @since 6.0
516 */
517 GUEST_MSG_MAKE_ME_MASTER = 13,
518 /** Prepares the starting of a session.
519 *
520 * VBoxService makes this call before spawning a session process (must be
521 * master). The first parameter is the session ID and the second is a one time
522 * key for identifying the right session process. First parameter is a 32-bit
523 * session ID with a value between 1 and 0xfff0. The second parameter is a byte
524 * buffer containing a key that GUEST_SESSION_ACCEPT checks against, minimum
525 * length is 64 bytes, maximum 16384 bytes.
526 *
527 * @retval VINF_SUCCESS on success.
528 * @retval VERR_OUT_OF_RESOURCES if too many pending sessions hanging around.
529 * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range.
530 * @retval VERR_BUFFER_OVERFLOW if key too large.
531 * @retval VERR_BUFFER_UNDERFLOW if key too small.
532 * @retval VERR_ACCESS_DENIED if not master or in legacy mode.
533 * @retval VERR_DUPLICATE if the session ID has been prepared already.
534 * @retval VERR_INVALID_CLIENT_ID
535 * @retval VERR_WRONG_PARAMETER_COUNT
536 * @retval VERR_WRONG_PARAMETER_TYPE
537 * @since 6.0
538 */
539 GUEST_MSG_SESSION_PREPARE = 14,
540 /** Cancels a prepared session.
541 *
542 * VBoxService makes this call to clean up after spawning a session process
543 * failed. One parameter, 32-bit session ID. If UINT32_MAX is passed, all
544 * prepared sessions are cancelled.
545 *
546 * @retval VINF_SUCCESS on success.
547 * @retval VWRN_NOT_FOUND if no session with the specified ID.
548 * @retval VERR_ACCESS_DENIED if not master or in legacy mode.
549 * @retval VERR_INVALID_CLIENT_ID
550 * @retval VERR_WRONG_PARAMETER_COUNT
551 * @retval VERR_WRONG_PARAMETER_TYPE
552 * @since 6.0
553 */
554 GUEST_MSG_SESSION_CANCEL_PREPARED = 15,
555 /** Accepts a prepared session.
556 *
557 * The session processes makes this call to accept a prepared session. The
558 * session ID is then uniquely associated with the HGCM client ID of the caller.
559 * The parameters must be identical to the matching GUEST_SESSION_PREPARE call.
560 *
561 * @retval VINF_SUCCESS on success.
562 * @retval VERR_NOT_FOUND if the specified session ID wasn't found.
563 * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range.
564 * @retval VERR_BUFFER_OVERFLOW if key too large.
565 * @retval VERR_BUFFER_UNDERFLOW if key too small.
566 * @retval VERR_ACCESS_DENIED if we're in legacy mode or is master.
567 * @retval VERR_RESOURCE_BUSY if the client is already associated with a session.
568 * @retval VERR_MISMATCH if the key didn't match.
569 * @retval VERR_INVALID_CLIENT_ID
570 * @retval VERR_WRONG_PARAMETER_COUNT
571 * @retval VERR_WRONG_PARAMETER_TYPE
572 * @since 6.0
573 */
574 GUEST_MSG_SESSION_ACCEPT = 16,
575 /**
576 * Guest reports back a guest session status.
577 * @todo proper docs.
578 */
579 GUEST_MSG_SESSION_NOTIFY = 20,
580 /**
581 * Guest wants to close a specific guest session.
582 * @todo proper docs.
583 */
584 GUEST_MSG_SESSION_CLOSE = 21,
585
586 /** Report guest side feature flags and retrieve the host ones.
587 *
588 * VBoxService makes this call right after becoming master to indicate to the
589 * host what features it support in addition. In return the host will return
590 * features the host supports. Two 64-bit parameters are passed in from the
591 * guest with the guest features (VBOX_GUESTCTRL_GF_XXX), the host replies by
592 * replacing the parameter values with the host ones (VBOX_GUESTCTRL_HF_XXX).
593 *
594 * @retval VINF_SUCCESS on success.
595 * @retval VERR_ACCESS_DENIED it not master.
596 * @retval VERR_INVALID_CLIENT_ID
597 * @retval VERR_WRONG_PARAMETER_COUNT
598 * @retval VERR_WRONG_PARAMETER_TYPE
599 * @since 6.0.10, 5.2.32
600 */
601 GUEST_MSG_REPORT_FEATURES,
602 /** Query the host ones feature masks.
603 *
604 * This is for the session sub-process so that it can get hold of the features
605 * from the host. Again, it is prudent to set the 127 bit and observe it being
606 * cleared on success, as older hosts might return success without doing
607 * anything.
608 *
609 * @retval VINF_SUCCESS on success.
610 * @retval VERR_INVALID_CLIENT_ID
611 * @retval VERR_WRONG_PARAMETER_COUNT
612 * @retval VERR_WRONG_PARAMETER_TYPE
613 * @since 6.0.10, 5.2.32
614 */
615 GUEST_MSG_QUERY_FEATURES,
616
617 /**
618 * Guests sends output from an executed process.
619 * @todo proper docs.
620 */
621 GUEST_MSG_EXEC_OUTPUT = 100,
622 /**
623 * Guest sends a status update of an executed process to the host.
624 * @todo proper docs.
625 */
626 GUEST_MSG_EXEC_STATUS = 101,
627 /**
628 * Guests sends an input status notification to the host.
629 * @todo proper docs.
630 */
631 GUEST_MSG_EXEC_INPUT_STATUS = 102,
632 /**
633 * Guest notifies the host about some I/O event. This can be
634 * a stdout, stderr or a stdin event. The actual event only tells
635 * how many data is available / can be sent without actually
636 * transmitting the data.
637 * @todo proper docs.
638 */
639 GUEST_MSG_EXEC_IO_NOTIFY = 210,
640 /**
641 * Guest notifies the host about some directory event.
642 * @todo proper docs.
643 */
644 GUEST_MSG_DIR_NOTIFY = 230,
645 /**
646 * Guest notifies the host about some file event.
647 * @todo proper docs.
648 */
649 GUEST_MSG_FILE_NOTIFY = 240
650#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
651 /**
652 * Guest notifies the host about some file system event.
653 *
654 * @retval VINF_SUCCESS on success.
655 * @retval VERR_INVALID_CLIENT_ID
656 * @retval VERR_WRONG_PARAMETER_COUNT
657 * @retval VERR_WRONG_PARAMETER_TYPE
658 * @since 7.1
659 */
660 , GUEST_MSG_FS_NOTIFY = 241
661#endif
662};
663
664/**
665 * Translates a guest control guest message enum to a string.
666 *
667 * @returns Enum string name.
668 * @param enmMsg The message to translate.
669 */
670DECLINLINE(const char *) GstCtrlGuestMsgToStr(enum eGuestMsg enmMsg)
671{
672 switch (enmMsg)
673 {
674 RT_CASE_RET_STR(GUEST_MSG_WAIT);
675 RT_CASE_RET_STR(GUEST_MSG_CANCEL);
676 RT_CASE_RET_STR(GUEST_MSG_DISCONNECTED);
677 RT_CASE_RET_STR(GUEST_MSG_FILTER_SET);
678 RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET);
679 RT_CASE_RET_STR(GUEST_MSG_PEEK_NOWAIT);
680 RT_CASE_RET_STR(GUEST_MSG_PEEK_WAIT);
681 RT_CASE_RET_STR(GUEST_MSG_GET);
682 RT_CASE_RET_STR(GUEST_MSG_SKIP_OLD);
683 RT_CASE_RET_STR(GUEST_MSG_REPLY);
684 RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE);
685 RT_CASE_RET_STR(GUEST_MSG_SKIP);
686 RT_CASE_RET_STR(GUEST_MSG_MAKE_ME_MASTER);
687 RT_CASE_RET_STR(GUEST_MSG_SESSION_PREPARE);
688 RT_CASE_RET_STR(GUEST_MSG_SESSION_CANCEL_PREPARED);
689 RT_CASE_RET_STR(GUEST_MSG_SESSION_ACCEPT);
690 RT_CASE_RET_STR(GUEST_MSG_SESSION_NOTIFY);
691 RT_CASE_RET_STR(GUEST_MSG_SESSION_CLOSE);
692 RT_CASE_RET_STR(GUEST_MSG_REPORT_FEATURES);
693 RT_CASE_RET_STR(GUEST_MSG_QUERY_FEATURES);
694 RT_CASE_RET_STR(GUEST_MSG_EXEC_OUTPUT);
695 RT_CASE_RET_STR(GUEST_MSG_EXEC_STATUS);
696 RT_CASE_RET_STR(GUEST_MSG_EXEC_INPUT_STATUS);
697 RT_CASE_RET_STR(GUEST_MSG_EXEC_IO_NOTIFY);
698 RT_CASE_RET_STR(GUEST_MSG_DIR_NOTIFY);
699 RT_CASE_RET_STR(GUEST_MSG_FILE_NOTIFY);
700#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
701 RT_CASE_RET_STR(GUEST_MSG_FS_NOTIFY);
702#endif
703 }
704 return "Unknown";
705}
706
707/**
708 * Guest session notification types.
709 * @sa HGCMMsgSessionNotify.
710 */
711enum GUEST_SESSION_NOTIFYTYPE
712{
713 GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0,
714 /** Something went wrong (see rc). */
715 GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
716 /** Guest session has been started. */
717 GUEST_SESSION_NOTIFYTYPE_STARTED = 11,
718 /** Guest session terminated normally. */
719 GUEST_SESSION_NOTIFYTYPE_TEN = 20,
720 /** Guest session terminated via signal. */
721 GUEST_SESSION_NOTIFYTYPE_TES = 30,
722 /** Guest session terminated abnormally. */
723 GUEST_SESSION_NOTIFYTYPE_TEA = 40,
724 /** Guest session timed out and was killed. */
725 GUEST_SESSION_NOTIFYTYPE_TOK = 50,
726 /** Guest session timed out and was not killed successfully. */
727 GUEST_SESSION_NOTIFYTYPE_TOA = 60,
728 /** Service/OS is stopping, process was killed. */
729 GUEST_SESSION_NOTIFYTYPE_DWN = 150
730};
731
732/**
733 * Guest directory notification types.
734 * @sa HGCMMsgReplyDirNotify.
735 */
736enum GUEST_DIR_NOTIFYTYPE
737{
738 GUEST_DIR_NOTIFYTYPE_UNKNOWN = 0,
739 /** Something went wrong (see rc). */
740 GUEST_DIR_NOTIFYTYPE_ERROR = 1,
741 /** Guest directory opened. */
742 GUEST_DIR_NOTIFYTYPE_OPEN = 10,
743 /** Guest directory closed. */
744 GUEST_DIR_NOTIFYTYPE_CLOSE = 20,
745#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
746 /** Guest directory read. */
747 GUEST_DIR_NOTIFYTYPE_READ = 21,
748 /** Guest directory was rewind. */
749 GUEST_DIR_NOTIFYTYPE_REWIND = 22,
750 /** Guest directory listing. */
751 GUEST_DIR_NOTIFYTYPE_LIST = 23,
752#endif
753 /** Information about an open guest directory. */
754 GUEST_DIR_NOTIFYTYPE_INFO = 40,
755 /** Guest directory created. */
756 GUEST_DIR_NOTIFYTYPE_CREATE = 70,
757 /** Guest directory deleted. */
758 GUEST_DIR_NOTIFYTYPE_REMOVE = 80
759};
760
761/**
762 * Guest file notification types.
763 * @sa HGCMMsgFileNotify.
764 */
765enum GUEST_FILE_NOTIFYTYPE
766{
767 GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
768 GUEST_FILE_NOTIFYTYPE_ERROR = 1,
769 GUEST_FILE_NOTIFYTYPE_OPEN = 10,
770 GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
771 GUEST_FILE_NOTIFYTYPE_READ = 30,
772 GUEST_FILE_NOTIFYTYPE_READ_OFFSET, /**< @since 6.0.10, 5.2.32 - VBOX_GUESTCTRL_HF_0_NOTIFY_RDWR_OFFSET */
773 GUEST_FILE_NOTIFYTYPE_WRITE = 40,
774 GUEST_FILE_NOTIFYTYPE_WRITE_OFFSET, /**< @since 6.0.10, 5.2.32 - VBOX_GUESTCTRL_HF_0_NOTIFY_RDWR_OFFSET */
775 GUEST_FILE_NOTIFYTYPE_SEEK = 50,
776 GUEST_FILE_NOTIFYTYPE_TELL = 60,
777 GUEST_FILE_NOTIFYTYPE_SET_SIZE
778};
779
780/**
781 * Guest file system notification types.
782 */
783enum GUEST_FS_NOTIFYTYPE
784{
785 /** Unknown fs notification type; do not use. */
786 GUEST_FS_NOTIFYTYPE_UNKNOWN = 0,
787 /** Temporary directory creation notification from the guest.
788 * @since 7.1 */
789 GUEST_FS_NOTIFYTYPE_CREATE_TEMP = 1,
790 /** File system object query information notification from the guest.
791 * @since 7.1 */
792 GUEST_FS_NOTIFYTYPE_QUERY_OBJ_INFO = 2,
793 /** File system query information notification from the guest.
794 * @since 7.1 */
795 GUEST_FS_NOTIFYTYPE_QUERY_INFO = 3
796};
797
798/**
799 * Guest file seeking types. Has to match FileSeekType in Main.
800 *
801 * @note This is not compatible with RTFileSeek, which is an unncessary pain.
802 */
803enum GUEST_FILE_SEEKTYPE
804{
805 GUEST_FILE_SEEKTYPE_BEGIN = 1,
806 GUEST_FILE_SEEKTYPE_CURRENT = 4,
807 GUEST_FILE_SEEKTYPE_END = 8
808};
809
810/** @name VBOX_GUESTCTRL_GF_XXX - Guest features.
811 * @sa GUEST_MSG_REPORT_FEATURES
812 * @{ */
813/** Supports HOST_MSG_FILE_SET_SIZE. */
814#define VBOX_GUESTCTRL_GF_0_SET_SIZE RT_BIT_64(0)
815/** Supports passing process arguments starting at argv[0] rather than argv[1].
816 * Guest additions which doesn't support this feature will instead use the
817 * executable image path as argv[0].
818 * @sa VBOX_GUESTCTRL_HF_0_PROCESS_ARGV0
819 * @since 6.1.6 */
820#define VBOX_GUESTCTRL_GF_0_PROCESS_ARGV0 RT_BIT_64(1)
821/** Supports passing cmd / arguments / environment blocks bigger than
822 * GUESTPROCESS_DEFAULT_CMD_LEN / GUESTPROCESS_DEFAULT_ARGS_LEN / GUESTPROCESS_DEFAULT_ENV_LEN (bytes, in total). */
823#define VBOX_GUESTCTRL_GF_0_PROCESS_DYNAMIC_SIZES RT_BIT_64(2)
824/** Supports shutting down / rebooting the guest. */
825#define VBOX_GUESTCTRL_GF_0_SHUTDOWN RT_BIT_64(3)
826/** VBoxService' toolbox commands (vbox_rm, vbox_stat, ++) are supported by
827 * dedicated built-in HGCM commands.
828 *
829 * The toolbox commands now are being marked as deprecated.
830 * @since 7.1 */
831#define VBOX_GUESTCTRL_GF_0_TOOLBOX_AS_CMDS RT_BIT_64(4)
832/** Supports specifying the working directory for run / start. */
833#define VBOX_GUESTCTRL_GF_0_PROCESS_CWD RT_BIT_64(5)
834/** Supports enumerating the guest mount points / drive letters.
835 * @since 7.1 */
836#define VBOX_GUESTCTRL_GF_0_MOUNT_POINTS_ENUM RT_BIT_64(6)
837/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
838 * correctly (old hosts might not). */
839#define VBOX_GUESTCTRL_GF_1_MUST_BE_ONE RT_BIT_64(63)
840/** @} */
841
842/** @name VBOX_GUESTCTRL_HF_XXX - Host features.
843 * @sa GUEST_MSG_REPORT_FEATURES
844 * @{ */
845/** Host supports the GUEST_FILE_NOTIFYTYPE_READ_OFFSET and
846 * GUEST_FILE_NOTIFYTYPE_WRITE_OFFSET notification types. */
847#define VBOX_GUESTCTRL_HF_0_NOTIFY_RDWR_OFFSET RT_BIT_64(0)
848/** Host supports process passing arguments starting at argv[0] rather than
849 * argv[1], when the guest additions reports VBOX_GUESTCTRL_GF_0_PROCESS_ARGV0.
850 * @since 6.1.6 */
851#define VBOX_GUESTCTRL_HF_0_PROCESS_ARGV0 RT_BIT_64(1)
852/** Host sends the working directory for run / start, if guest
853 * reports VBOX_GUESTCTRL_GF_0_PROCESS_CWD.
854 * @since 6.1.20 ?? */
855#define VBOX_GUESTCTRL_HF_0_PROCESS_CWD RT_BIT_64(2)
856/** @} */
857
858
859/*
860 * HGCM parameter structures.
861 */
862#pragma pack (1)
863
864/**
865 * Waits for a host message to arrive. The structure then contains the
866 * actual message type + required number of parameters needed to successfully
867 * retrieve that host message (in a next round).
868 */
869typedef struct HGCMMsgWaitFor
870{
871 VBGLIOCHGCMCALL hdr;
872 /** The returned message the host wants to run on the guest. */
873 HGCMFunctionParameter msg; /* OUT uint32_t */
874 /** Number of parameters the message needs. */
875 HGCMFunctionParameter num_parms; /* OUT uint32_t */
876} HGCMMsgWaitFor;
877
878/**
879 * Asks the guest control host service to set a message
880 * filter for this client. This filter will then only
881 * deliver messages to the client which match the
882 * wanted context ID (ranges).
883 */
884typedef struct HGCMMsgFilterSet
885{
886 VBGLIOCHGCMCALL hdr;
887 /** Value to filter for after filter mask was applied. */
888 HGCMFunctionParameter value; /* IN uint32_t */
889 /** Mask to add to the current set filter. */
890 HGCMFunctionParameter mask_add; /* IN uint32_t */
891 /** Mask to remove from the current set filter. */
892 HGCMFunctionParameter mask_remove; /* IN uint32_t */
893 /** Filter flags; currently unused. */
894 HGCMFunctionParameter flags; /* IN uint32_t */
895} HGCMMsgFilterSet;
896
897/**
898 * Asks the guest control host service to disable
899 * a previously set message filter again.
900 */
901typedef struct HGCMMsgFilterUnset
902{
903 VBGLIOCHGCMCALL hdr;
904 /** Unset flags; currently unused. */
905 HGCMFunctionParameter flags; /* IN uint32_t */
906} HGCMMsgFilterUnset;
907
908/**
909 * Asks the guest control host service to skip the
910 * currently assigned host message returned by
911 * VbglR3GuestCtrlMsgWaitFor().
912 */
913typedef struct HGCMMsgSkip
914{
915 VBGLIOCHGCMCALL hdr;
916 /** Skip flags; currently unused. */
917 HGCMFunctionParameter flags; /* IN uint32_t */
918} HGCMMsgSkip;
919
920/**
921 * Asks the guest control host service to cancel all pending (outstanding)
922 * waits which were not processed yet. This is handy for a graceful shutdown.
923 */
924typedef struct HGCMMsgCancelPendingWaits
925{
926 VBGLIOCHGCMCALL hdr;
927} HGCMMsgCancelPendingWaits;
928
929/**
930 * Generic reply header for reply-based messages.
931 *
932 * @note Be careful when changing this, as older Guest Additions might depend on this
933 * and other stuff can break, too. So better leave this alone.
934 */
935typedef struct HGCMReplyHdr
936{
937 VBGLIOCHGCMCALL hdr;
938 /** Context ID. */
939 HGCMFunctionParameter context;
940 /** Message type. */
941 HGCMFunctionParameter type;
942 /** IPRT result of overall operation. */
943 HGCMFunctionParameter rc;
944} HGCMReplyHdr;
945
946/** Number of HGCM parameters the HGCMReplyHdr has. */
947#define GSTCTL_HGCM_REPLY_HDR_PARMS 3
948
949/**
950 * Generic reply message from guest to the host.
951 */
952typedef struct HGCMMsgReply
953{
954 VBGLIOCHGCMCALL hdr;
955 /** Context ID. */
956 HGCMFunctionParameter context;
957 /** Message type. */
958 HGCMFunctionParameter type;
959 /** IPRT result of overall operation. */
960 HGCMFunctionParameter rc;
961 /** Optional payload to this reply
962 * Uses the REPLY_PAYLOAD_XXX structs. */
963 HGCMFunctionParameter payload;
964} HGCMMsgReply;
965
966#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
967/**
968 * Creates a temporary directory / file on the guest.
969 */
970typedef struct HGCMMsgFsCreateTemp
971{
972 VBGLIOCHGCMCALL hdr;
973 /** Context ID. */
974 HGCMFunctionParameter context;
975 /** Template name to use for file/directory creation.
976 * If \a tmpdir is set, this path will be relative to \a tmpdir and must not be an absolute path. */
977 HGCMFunctionParameter template_name;
978 /** Temporary directory to use.
979 * If empty, the guest OS' temporary directory will be determined via IPRT on the guest side. */
980 HGCMFunctionParameter tmpdir;
981 /** Creation flags.
982 * See GSTCTL_CREATETEMP_F_XXX. */
983 HGCMFunctionParameter flags;
984 /** File mode to use for creation (ignored if GSTCTL_CREATETEMP_F_SECURE is defined).
985 * See GSTCTL_CREATETEMP_F_XXX. */
986 HGCMFunctionParameter mode;
987} HGCMMsgFsCreateTemp;
988
989/**
990 * Queries information of a file system on the guest.
991 */
992typedef struct HGCMMsgFsQueryInfo
993{
994 VBGLIOCHGCMCALL hdr;
995 /** Context ID. */
996 HGCMFunctionParameter context;
997 /** Path to query file system information for. */
998 HGCMFunctionParameter path;
999} HGCMMsgFsQueryInfo;
1000
1001/**
1002 * Queries information for a file system object on the guest.
1003 */
1004typedef struct HGCMMsgFsObjQueryInfo
1005{
1006 VBGLIOCHGCMCALL hdr;
1007 /** Context ID. */
1008 HGCMFunctionParameter context;
1009 /** Path to query information for. */
1010 HGCMFunctionParameter path;
1011 /** Additional file system attributes to lookup (GSTCTLFSOBJATTRADD). */
1012 HGCMFunctionParameter add_attributes;
1013 /** Flags (GSTCTL_PATH_F_XXX). */
1014 HGCMFunctionParameter flags;
1015} HGCMMsgFsObjQueryInfo;
1016#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
1017
1018/**
1019 * Creates a guest session.
1020 */
1021typedef struct HGCMMsgSessionOpen
1022{
1023 VBGLIOCHGCMCALL hdr;
1024 /** Context ID. */
1025 HGCMFunctionParameter context;
1026 /** The guest control protocol version this
1027 * session is about to use. */
1028 HGCMFunctionParameter protocol;
1029 /** The user name to run the guest session under. */
1030 HGCMFunctionParameter username;
1031 /** The user's password. */
1032 HGCMFunctionParameter password;
1033 /** The domain to run the guest session under. */
1034 HGCMFunctionParameter domain;
1035 /** Session creation flags. */
1036 HGCMFunctionParameter flags;
1037} HGCMMsgSessionOpen;
1038
1039/**
1040 * Terminates (closes) a guest session.
1041 */
1042typedef struct HGCMMsgSessionClose
1043{
1044 VBGLIOCHGCMCALL hdr;
1045 /** Context ID. */
1046 HGCMFunctionParameter context;
1047 /** Session termination flags. */
1048 HGCMFunctionParameter flags;
1049} HGCMMsgSessionClose;
1050
1051/**
1052 * Reports back a guest session's status.
1053 */
1054typedef struct HGCMMsgSessionNotify
1055{
1056 VBGLIOCHGCMCALL hdr;
1057 /** Context ID. */
1058 HGCMFunctionParameter context;
1059 /** Notification type. */
1060 HGCMFunctionParameter type;
1061 /** Notification result. */
1062 HGCMFunctionParameter result;
1063} HGCMMsgSessionNotify;
1064
1065#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
1066/**
1067 * Opens a guest directory.
1068 */
1069typedef struct HGCMMsgDirOpen
1070{
1071 VBGLIOCHGCMCALL hdr;
1072 /** Context ID. */
1073 HGCMFunctionParameter context;
1074 /** Path of directory to open. */
1075 HGCMFunctionParameter path;
1076 /** Filter type to use when walking the directory (GSTCTLDIRFILTER). */
1077 HGCMFunctionParameter filter;
1078 /** Directory open flags (GSTCTLDIR_F_XXX). */
1079 HGCMFunctionParameter flags;
1080 /** Additional directory attributes to use
1081 * (GSTCTLFSOBJATTRADD, for subsequent directory entry read calls). */
1082 HGCMFunctionParameter read_attr_add;
1083 /** Directory reading flags (for subsequent directory entry read calls).
1084 * GSTCTL_PATH_F_ON_LINK or GSTCTL_PATH_F_FOLLOW_LINK. */
1085 HGCMFunctionParameter read_flags;
1086} HGCMMsgDirOpen;
1087
1088/**
1089 * Closes a guest directory.
1090 */
1091typedef struct HGCMMsgDirClose
1092{
1093 VBGLIOCHGCMCALL hdr;
1094 /** Context ID. */
1095 HGCMFunctionParameter context;
1096 /** Directory handle to close. */
1097 HGCMFunctionParameter handle;
1098} HGCMMsgDirClose;
1099
1100/**
1101 * Reads the next entry of a guest directory.
1102 */
1103typedef struct HGCMMsgDirRead
1104{
1105 VBGLIOCHGCMCALL hdr;
1106 /** Context ID. */
1107 HGCMFunctionParameter context;
1108 /** Handle of directory listing to read the next entry for. */
1109 HGCMFunctionParameter handle;
1110} HGCMMsgDirRead;
1111
1112/**
1113 * Rewinds the listing of a guest directory.
1114 */
1115typedef struct HGCMMsgDirRewind
1116{
1117 VBGLIOCHGCMCALL hdr;
1118 /** Context ID. */
1119 HGCMFunctionParameter context;
1120 /** Handle of directory listing to rewind. */
1121 HGCMFunctionParameter handle;
1122} HGCMMsgDirRewind;
1123
1124/**
1125 * Creates a directory on the guest.
1126 */
1127typedef struct HGCMMsgDirCreate
1128{
1129 VBGLIOCHGCMCALL hdr;
1130 /** Context ID. */
1131 HGCMFunctionParameter context;
1132 /** Path of directory to create. */
1133 HGCMFunctionParameter path;
1134 /** Creation mode. */
1135 HGCMFunctionParameter mode;
1136 /** Creation flags (GSTCTL_CREATEDIRECTORY_F_XXX). */
1137 HGCMFunctionParameter flags;
1138} HGCMMsgDirCreate;
1139
1140/**
1141 * Lists the entries of a directory on the guest.
1142 */
1143typedef struct HGCMMsgDirList
1144{
1145 VBGLIOCHGCMCALL hdr;
1146 /** Context ID. */
1147 HGCMFunctionParameter context;
1148 /** Handle of directory listing to list. */
1149 HGCMFunctionParameter handle;
1150 /** Number of entries to read at once.
1151 * Specify UINT32_MAX to read as much as possible. 0 is not allowed. */
1152 HGCMFunctionParameter num_entries;
1153 /** Listing flags (GSTCTL_DIRLIST_F_XXX). */
1154 HGCMFunctionParameter flags;
1155} HGCMMsgDirList;
1156#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
1157
1158typedef struct HGCMMsgPathRename
1159{
1160 VBGLIOCHGCMCALL hdr;
1161 /** UInt32: Context ID. */
1162 HGCMFunctionParameter context;
1163 /** Source to rename. */
1164 HGCMFunctionParameter source;
1165 /** Destination to rename source to. */
1166 HGCMFunctionParameter dest;
1167 /** UInt32: Rename flags. */
1168 HGCMFunctionParameter flags;
1169} HGCMMsgPathRename;
1170
1171typedef struct HGCMMsgPathUserDocuments
1172{
1173 VBGLIOCHGCMCALL hdr;
1174 /** UInt32: Context ID. */
1175 HGCMFunctionParameter context;
1176} HGCMMsgPathUserDocuments;
1177
1178typedef struct HGCMMsgPathUserHome
1179{
1180 VBGLIOCHGCMCALL hdr;
1181 /** UInt32: Context ID. */
1182 HGCMFunctionParameter context;
1183} HGCMMsgPathUserHome;
1184
1185/**
1186 * Shuts down / reboots the guest.
1187 */
1188typedef struct HGCMMsgShutdown
1189{
1190 VBGLIOCHGCMCALL hdr;
1191 /** UInt32: Context ID. */
1192 HGCMFunctionParameter context;
1193 /** UInt32: Action flags. */
1194 HGCMFunctionParameter action;
1195} HGCMMsgShutdown;
1196
1197/**
1198 * Executes a command inside the guest.
1199 */
1200typedef struct HGCMMsgProcExec
1201{
1202 VBGLIOCHGCMCALL hdr;
1203 /** Context ID. */
1204 HGCMFunctionParameter context;
1205 /** The command to execute on the guest. */
1206 HGCMFunctionParameter cmd;
1207 /** Execution flags (see IGuest::ProcessCreateFlag_*). */
1208 HGCMFunctionParameter flags;
1209 /** Number of arguments. */
1210 HGCMFunctionParameter num_args;
1211 /** The actual arguments. */
1212 HGCMFunctionParameter args;
1213 /** Number of environment value pairs. */
1214 HGCMFunctionParameter num_env;
1215 /** Size (in bytes) of environment block, including terminating zeros. */
1216 HGCMFunctionParameter cb_env;
1217 /** The actual environment block. */
1218 HGCMFunctionParameter env;
1219 union
1220 {
1221 struct
1222 {
1223 /** The user name to run the executed command under.
1224 * Only for VBox < 4.3 hosts. */
1225 HGCMFunctionParameter username;
1226 /** The user's password.
1227 * Only for VBox < 4.3 hosts. */
1228 HGCMFunctionParameter password;
1229 /** Timeout (in msec) which either specifies the
1230 * overall lifetime of the process or how long it
1231 * can take to bring the process up and running -
1232 * (depends on the IGuest::ProcessCreateFlag_*). */
1233 HGCMFunctionParameter timeout;
1234 } v1;
1235 struct
1236 {
1237 /** Timeout (in ms) which either specifies the
1238 * overall lifetime of the process or how long it
1239 * can take to bring the process up and running -
1240 * (depends on the IGuest::ProcessCreateFlag_*). */
1241 HGCMFunctionParameter timeout;
1242 /** Process priority. */
1243 HGCMFunctionParameter priority;
1244 /** Number of process affinity blocks. */
1245 HGCMFunctionParameter num_affinity;
1246 /** Pointer to process affinity blocks (uint64_t). */
1247 HGCMFunctionParameter affinity;
1248 /** Working directory request, filled if guest
1249 * reports VBOX_GUESTCTRL_GF_0_PROCESS_CWD. */
1250 HGCMFunctionParameter cwd;
1251 } v2;
1252 } u;
1253} HGCMMsgProcExec;
1254
1255/**
1256 * Sends input to a guest process via stdin.
1257 */
1258typedef struct HGCMMsgProcInput
1259{
1260 VBGLIOCHGCMCALL hdr;
1261 /** Context ID. */
1262 HGCMFunctionParameter context;
1263 /** The process ID (PID) to send the input to. */
1264 HGCMFunctionParameter pid;
1265 /** Input flags (see IGuest::ProcessInputFlag_*). */
1266 HGCMFunctionParameter flags;
1267 /** Data buffer. */
1268 HGCMFunctionParameter data;
1269 /** Actual size of data (in bytes). */
1270 HGCMFunctionParameter size;
1271} HGCMMsgProcInput;
1272
1273/**
1274 * Retrieves ouptut from a previously executed process
1275 * from stdout/stderr.
1276 */
1277typedef struct HGCMMsgProcOutput
1278{
1279 VBGLIOCHGCMCALL hdr;
1280 /** Context ID. */
1281 HGCMFunctionParameter context;
1282 /** The process ID (PID). */
1283 HGCMFunctionParameter pid;
1284 /** The pipe handle ID (stdout/stderr). */
1285 HGCMFunctionParameter handle;
1286 /** Optional flags. */
1287 HGCMFunctionParameter flags;
1288 /** Data buffer. */
1289 HGCMFunctionParameter data;
1290} HGCMMsgProcOutput;
1291
1292/**
1293 * Reports the current status of a guest process.
1294 */
1295typedef struct HGCMMsgProcStatus
1296{
1297 VBGLIOCHGCMCALL hdr;
1298 /** Context ID. */
1299 HGCMFunctionParameter context;
1300 /** The process ID (PID). */
1301 HGCMFunctionParameter pid;
1302 /** The process status. */
1303 HGCMFunctionParameter status;
1304 /** Optional flags (based on status). */
1305 HGCMFunctionParameter flags;
1306 /** Optional data buffer (not used atm). */
1307 HGCMFunctionParameter data;
1308} HGCMMsgProcStatus;
1309
1310/**
1311 * Reports back the status of data written to a process.
1312 */
1313typedef struct HGCMMsgProcStatusInput
1314{
1315 VBGLIOCHGCMCALL hdr;
1316 /** Context ID. */
1317 HGCMFunctionParameter context;
1318 /** The process ID (PID). */
1319 HGCMFunctionParameter pid;
1320 /** Status of the operation. */
1321 HGCMFunctionParameter status;
1322 /** Optional flags. */
1323 HGCMFunctionParameter flags;
1324 /** Data written. */
1325 HGCMFunctionParameter written;
1326} HGCMMsgProcStatusInput;
1327
1328/*
1329 * Guest control 2.0 messages.
1330 */
1331
1332/**
1333 * Terminates a guest process.
1334 */
1335typedef struct HGCMMsgProcTerminate
1336{
1337 VBGLIOCHGCMCALL hdr;
1338 /** Context ID. */
1339 HGCMFunctionParameter context;
1340 /** The process ID (PID). */
1341 HGCMFunctionParameter pid;
1342} HGCMMsgProcTerminate;
1343
1344/**
1345 * Waits for certain events to happen.
1346 */
1347typedef struct HGCMMsgProcWaitFor
1348{
1349 VBGLIOCHGCMCALL hdr;
1350 /** Context ID. */
1351 HGCMFunctionParameter context;
1352 /** The process ID (PID). */
1353 HGCMFunctionParameter pid;
1354 /** Wait (event) flags. */
1355 HGCMFunctionParameter flags;
1356 /** Timeout (in ms). */
1357 HGCMFunctionParameter timeout;
1358} HGCMMsgProcWaitFor;
1359
1360typedef struct HGCMMsgDirRemove
1361{
1362 VBGLIOCHGCMCALL hdr;
1363 /** UInt32: Context ID. */
1364 HGCMFunctionParameter context;
1365 /** Directory to remove. */
1366 HGCMFunctionParameter path;
1367 /** UInt32: Removement flags. */
1368 HGCMFunctionParameter flags;
1369} HGCMMsgDirRemove;
1370
1371/**
1372 * Opens a guest file.
1373 */
1374typedef struct HGCMMsgFileOpen
1375{
1376 VBGLIOCHGCMCALL hdr;
1377 /** UInt32: Context ID. */
1378 HGCMFunctionParameter context;
1379 /** File to open. */
1380 HGCMFunctionParameter filename;
1381 /** Open mode. */
1382 HGCMFunctionParameter openmode;
1383 /** Disposition mode. */
1384 HGCMFunctionParameter disposition;
1385 /** Sharing mode. */
1386 HGCMFunctionParameter sharing;
1387 /** UInt32: Creation mode. */
1388 HGCMFunctionParameter creationmode;
1389 /** UInt64: Initial offset. */
1390 HGCMFunctionParameter offset;
1391} HGCMMsgFileOpen;
1392
1393/**
1394 * Closes a guest file.
1395 */
1396typedef struct HGCMMsgFileClose
1397{
1398 VBGLIOCHGCMCALL hdr;
1399 /** Context ID. */
1400 HGCMFunctionParameter context;
1401 /** File handle to close. */
1402 HGCMFunctionParameter handle;
1403} HGCMMsgFileClose;
1404
1405/**
1406 * Reads from a guest file.
1407 */
1408typedef struct HGCMMsgFileRead
1409{
1410 VBGLIOCHGCMCALL hdr;
1411 /** Context ID. */
1412 HGCMFunctionParameter context;
1413 /** File handle to read from. */
1414 HGCMFunctionParameter handle;
1415 /** Size (in bytes) to read. */
1416 HGCMFunctionParameter size;
1417} HGCMMsgFileRead;
1418
1419/**
1420 * Reads at a specified offset from a guest file.
1421 */
1422typedef struct HGCMMsgFileReadAt
1423{
1424 VBGLIOCHGCMCALL hdr;
1425 /** Context ID. */
1426 HGCMFunctionParameter context;
1427 /** File handle to read from. */
1428 HGCMFunctionParameter handle;
1429 /** Offset where to start reading from. */
1430 HGCMFunctionParameter offset;
1431 /** Actual size of data (in bytes). */
1432 HGCMFunctionParameter size;
1433} HGCMMsgFileReadAt;
1434
1435/**
1436 * Writes to a guest file.
1437 */
1438typedef struct HGCMMsgFileWrite
1439{
1440 VBGLIOCHGCMCALL hdr;
1441 /** Context ID. */
1442 HGCMFunctionParameter context;
1443 /** File handle to write to. */
1444 HGCMFunctionParameter handle;
1445 /** Actual size of data (in bytes). */
1446 HGCMFunctionParameter size;
1447 /** Data buffer to write to the file. */
1448 HGCMFunctionParameter data;
1449} HGCMMsgFileWrite;
1450
1451/**
1452 * Writes at a specified offset to a guest file.
1453 */
1454typedef struct HGCMMsgFileWriteAt
1455{
1456 VBGLIOCHGCMCALL hdr;
1457 /** Context ID. */
1458 HGCMFunctionParameter context;
1459 /** File handle to write to. */
1460 HGCMFunctionParameter handle;
1461 /** Offset where to start reading from. */
1462 HGCMFunctionParameter offset;
1463 /** Actual size of data (in bytes). */
1464 HGCMFunctionParameter size;
1465 /** Data buffer to write to the file. */
1466 HGCMFunctionParameter data;
1467} HGCMMsgFileWriteAt;
1468
1469/**
1470 * Seeks the read/write position of a guest file.
1471 */
1472typedef struct HGCMMsgFileSeek
1473{
1474 VBGLIOCHGCMCALL hdr;
1475 /** Context ID. */
1476 HGCMFunctionParameter context;
1477 /** File handle to seek. */
1478 HGCMFunctionParameter handle;
1479 /** The seeking method. */
1480 HGCMFunctionParameter method;
1481 /** The seeking offset. */
1482 HGCMFunctionParameter offset;
1483} HGCMMsgFileSeek;
1484
1485/**
1486 * Tells the current read/write position of a guest file.
1487 */
1488typedef struct HGCMMsgFileTell
1489{
1490 VBGLIOCHGCMCALL hdr;
1491 /** Context ID. */
1492 HGCMFunctionParameter context;
1493 /** File handle to get the current position for. */
1494 HGCMFunctionParameter handle;
1495} HGCMMsgFileTell;
1496
1497/**
1498 * Changes the file size.
1499 */
1500typedef struct HGCMMsgFileSetSize
1501{
1502 VBGLIOCHGCMCALL Hdr;
1503 /** Context ID. */
1504 HGCMFunctionParameter id32Context;
1505 /** File handle to seek. */
1506 HGCMFunctionParameter id32Handle;
1507 /** The new file size. */
1508 HGCMFunctionParameter cb64NewSize;
1509} HGCMMsgFileSetSize;
1510
1511/**
1512 * Removes (deletes) a guest file.
1513 *
1514 * @since 7.1
1515 */
1516typedef struct HGCMMsgFileRemove
1517{
1518 VBGLIOCHGCMCALL hdr;
1519 /** UInt32: Context ID. */
1520 HGCMFunctionParameter context;
1521 /** File to open. */
1522 HGCMFunctionParameter filename;
1523} HGCMMsgFileRemove;
1524
1525
1526/******************************************************************************
1527* HGCM replies from the guest. These are handled in Main's low-level HGCM *
1528* callbacks and dispatched to the appropriate guest object. *
1529******************************************************************************/
1530
1531typedef struct HGCMReplyFileNotify
1532{
1533 VBGLIOCHGCMCALL hdr;
1534 /** Context ID. */
1535 HGCMFunctionParameter context;
1536 /** Notification type. */
1537 HGCMFunctionParameter type;
1538 /** IPRT result of overall operation. */
1539 HGCMFunctionParameter rc;
1540 union
1541 {
1542 struct
1543 {
1544 /** Guest file handle. */
1545 HGCMFunctionParameter handle;
1546 } open;
1547 /** Note: Close does not have any additional data (yet). */
1548 struct
1549 {
1550 /** Actual data read (if any). */
1551 HGCMFunctionParameter data;
1552 } read;
1553 struct
1554 {
1555 /** Actual data read (if any). */
1556 HGCMFunctionParameter pvData;
1557 /** The new file offset (signed). Negative value if non-seekable files. */
1558 HGCMFunctionParameter off64New;
1559 } ReadOffset;
1560 struct
1561 {
1562 /** How much data (in bytes) have been successfully written. */
1563 HGCMFunctionParameter written;
1564 } write;
1565 struct
1566 {
1567 /** Number of bytes that was successfully written. */
1568 HGCMFunctionParameter cb32Written;
1569 /** The new file offset (signed). Negative value if non-seekable files. */
1570 HGCMFunctionParameter off64New;
1571 } WriteOffset;
1572 struct
1573 {
1574 HGCMFunctionParameter offset;
1575 } seek;
1576 struct
1577 {
1578 HGCMFunctionParameter offset;
1579 } tell;
1580 struct
1581 {
1582 HGCMFunctionParameter cb64Size;
1583 } SetSize;
1584 } u;
1585} HGCMReplyFileNotify;
1586
1587typedef struct HGCMReplyDirNotify
1588{
1589 /** The generic reply header. */
1590 HGCMReplyHdr reply_hdr;
1591 /** Union based on \a reply_hdr.type. */
1592 union
1593 {
1594 /**
1595 * Parameters used for \a reply_hdr.type GUEST_DIR_NOTIFYTYPE_OPEN.
1596 *
1597 * @since 7.1
1598 */
1599 struct
1600 {
1601 /** Guest directory handle. */
1602 HGCMFunctionParameter handle;
1603 } open;
1604 /**
1605 * Parameters used for \a reply_hdr.type GUEST_DIR_NOTIFYTYPE_READ.
1606 *
1607 * @since 7.1
1608 */
1609 struct
1610 {
1611 /** Current read directory entry (GSTCTLDIRENTRYEX). */
1612 HGCMFunctionParameter entry;
1613 /** Resolved user ID as a string (uid). */
1614 HGCMFunctionParameter user;
1615 /** Resolved group IDs as a string.
1616 *
1617 * Multiple groups are delimited by GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR, whereas
1618 * the first group always is the primary group. */
1619 HGCMFunctionParameter groups;
1620 } read;
1621 /**
1622 * Parameters used for \a reply_hdr.type GUEST_DIR_NOTIFYTYPE_LIST.
1623 *
1624 * @since 7.1
1625 */
1626 struct
1627 {
1628 /** Number of entries in \a buffer. */
1629 HGCMFunctionParameter num_entries;
1630 /** Buffer containing the GSTCTLDIRENTRYEX entries, immediately followed
1631 * by resolved user + groups as a string (empty strings if not resolved). */
1632 HGCMFunctionParameter buffer;
1633 } list;
1634 } u;
1635} HGCMReplyDirNotify;
1636
1637/**
1638 * Reply to a HOST_MSG_FS_QUERY_INFO or HOST_MSG_FS_CREATE_TEMP message.
1639 *
1640 * @since 7.1
1641 */
1642typedef struct HGCMReplyFsNotify
1643{
1644 /** The generic reply header. */
1645 HGCMReplyHdr reply_hdr;
1646 /** Union based on \a reply_hdr.type. */
1647 union
1648 {
1649 /**
1650 * Parameters used for \a type GUEST_FS_NOTIFYTYPE_CREATE_TEMP.
1651 *
1652 * @since 7.1
1653 */
1654 struct
1655 {
1656 /** The create temporary file / directory when \a rc
1657 * indicates success. */
1658 HGCMFunctionParameter path;
1659 } createtemp;
1660 /**
1661 * Parameters used for \a type GUEST_FS_NOTIFYTYPE_QUERY_OBJ_INFO.
1662 *
1663 * @since 7.1
1664 */
1665 struct
1666 {
1667 /** File system object information (GSTCTLFSOBJINFO). */
1668 HGCMFunctionParameter obj_info;
1669 /** Resolved user ID as a string (uid). */
1670 HGCMFunctionParameter user;
1671 /** Resolved group IDs as a string.
1672 *
1673 * Multiple groups are delimited by GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR, whereas
1674 * the first group always is the primary group. */
1675 HGCMFunctionParameter groups;
1676 } queryobjinfo;
1677 /**
1678 * Parameters used for \a type GUEST_FS_NOTIFYTYPE_QUERY_INFO.
1679 *
1680 * @since 7.1
1681 */
1682 struct
1683 {
1684 /** File system object information (GSTCTLFSINFO). */
1685 HGCMFunctionParameter fs_info;
1686 } queryinfo;
1687 } u;
1688} HGCMReplyFsNotify;
1689#pragma pack ()
1690} /* namespace guestControl */
1691
1692#endif /* !VBOX_INCLUDED_HostServices_GuestControlSvc_h */
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette