VirtualBox

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

Last change on this file since 90346 was 84548, checked in by vboxsync, 5 years ago

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

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