GuestControlSvc.h

Last change on this file was 106061, checked in by vboxsync, 3 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 55.0 KB

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

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

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

Download in other formats: