GuestControlSvc.h@ 76585

Last change on this file since 76585 was 76585, checked in by vboxsync, 6 years ago
*: scm --fix-header-guard-endif
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 42.9 KB

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

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

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

Download in other formats: