VirtualBox

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

Last change on this file was 103165, checked in by vboxsync, 4 months ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use