VirtualBox

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

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

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

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