VirtualBox

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

最後變更 在這個檔案從99085是 99085,由 vboxsync 提交於 2 年 前

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

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