GuestControlSvc.h@ 99256

Last change on this file since 99256 was 99256, checked in by vboxsync, 20 months ago
Guest Control: More renaming; required for preparation of implementing querying guest file system information. bugref:10414
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 53.0 KB

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

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

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

Download in other formats: