GuestControlSvc.h@ 100016

Last change on this file since 100016 was 99262, checked in by vboxsync, 20 months ago
Guest Control: Implements IGuestSession::fsQueryInfo() and IGuestSession::fsQueryFreeSpace(). bugref:10414
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 53.9 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: