GuestControlSvc.h@ 102654

Last change on this file since 102654 was 102654, checked in by vboxsync, 14 months ago
Guest Control: Implemented IGuestSession::getMountPoints. bugref:10415
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 54.1 KB

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

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

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

Download in other formats: