GuestControlSvc.h@ 98792

Last change on this file since 98792 was 98792, checked in by vboxsync, 21 months ago
Guest Control/VBoxService: Moved all the CALLBACKDATA_ struct from GuestControlSvc.h into GuestCtrlImplPrivate.h, as these structs only belong into Main + added missing docs. bugref:9783
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 51.6 KB

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

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

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

Download in other formats: