GuestControlSvc.h@ 84548

Last change on this file since 84548 was 84548, checked in by vboxsync, 5 years ago
Guest Control: Implemented guest side support for gracefully rebooting / shutting down the guest. Untested. bugref:9320
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 47.7 KB

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

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

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

Download in other formats: