GuestControlSvc.h@ 76958

Last change on this file since 76958 was 76958, checked in by vboxsync, 6 years ago
Guest Control: Unifying terminology for (client/host) commands, functions and messages; it's all about messages now. Renaming, no functional changes.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 43.0 KB

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

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

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

Download in other formats: