GuestControlSvc.h@ 75758

Last change on this file since 75758 was 75757, checked in by vboxsync, 6 years ago
GuestControlSvc: Defined 4 new commands that will succeed GUEST_MSG_WAIT - completely untested. [corrections]
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 34.5 KB

Line
1	/* $Id: GuestControlSvc.h 75757 2018-11-27 04:24:13Z vboxsync $ */
2	/** @file
3	* Guest control service - Common header for host service and guest clients.
4	*/
5
6	/*
7	* Copyright (C) 2011-2018 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_HostService_GuestControlService_h
28	#define ___VBox_HostService_GuestControlService_h
29
30	#include <VBox/VMMDevCoreTypes.h>
31	#include <VBox/VBoxGuestCoreTypes.h>
32	#include <VBox/hgcmsvc.h>
33	#include <iprt/assert.h>
34
35	/* Everything defined in this file lives in this namespace. */
36	namespace guestControl {
37
38	/******************************************************************************
39	* Typedefs, constants and inlines *
40	******************************************************************************/
41
42	#define HGCMSERVICE_NAME "VBoxGuestControlSvc"
43
44	/** Maximum number of concurrent guest sessions a VM can have. */
45	#define VBOX_GUESTCTRL_MAX_SESSIONS 32
46	/** Maximum number of concurrent guest objects (processes, files, ...)
47	* a guest session can have. */
48	#define VBOX_GUESTCTRL_MAX_OBJECTS _2K
49	/** Maximum of callback contexts a guest process can have. */
50	#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K
51
52	/** Base (start) of guest control session IDs. Session
53	* ID 0 is reserved for the root process which
54	* hosts all other guest session processes. */
55	#define VBOX_GUESTCTRL_SESSION_ID_BASE 1
56
57	/** Builds a context ID out of the session ID, object ID and an
58	* increasing count. */
59	#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \
60	( (uint32_t)((uSession) & 0x1f) << 27 \
61	\| (uint32_t)((uObject) & 0x7ff) << 16 \
62	\| (uint32_t)((uCount) & 0xffff) \
63	)
64	/** Creates a context ID out of a session ID. */
65	#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
66	((uint32_t)((uSession) & 0x1f) << 27)
67	/** Gets the session ID out of a context ID. */
68	#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
69	(((uContextID) >> 27) & 0x1f)
70	/** Gets the process ID out of a context ID. */
71	#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
72	(((uContextID) >> 16) & 0x7ff)
73	/** Gets the context count of a process out of a context ID. */
74	#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
75	((uContextID) & 0xffff)
76	/** Filter context IDs by session. Can be used in conjunction
77	* with VbglR3GuestCtrlMsgFilterSet(). */
78	#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \
79	(VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \| 0xF8000000)
80
81	/**
82	* Structure keeping the context of a host callback.
83	*/
84	typedef struct VBoxGuestCtrlHostCbCtx
85	{
86	/** HGCM Function number. */
87	uint32_t uFunction;
88	/** The context ID. */
89	uint32_t uContextID;
90	/** Protocol version of this guest session. Might
91	* be 0 if not supported. */
92	uint32_t uProtocol;
93
94	} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX;
95
96	/**
97	* Structure for low level HGCM host callback from
98	* the guest. No deep copy. */
99	typedef struct VBoxGuestCtrlHostCallback
100	{
101	VBoxGuestCtrlHostCallback(uint32_t cParms, VBOXHGCMSVCPARM paParms[])
102	: mParms(cParms), mpaParms(paParms) { }
103
104	/** Number of HGCM parameters. */
105	uint32_t mParms;
106	/** Actual HGCM parameters. */
107	PVBOXHGCMSVCPARM mpaParms;
108
109	} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
110
111	/**
112	* The service functions which are callable by host.
113	*/
114	enum eHostFn
115	{
116	/**
117	* The host asks the client to cancel all pending waits and exit.
118	*/
119	HOST_CANCEL_PENDING_WAITS = 0,
120	/**
121	* The host wants to create a guest session.
122	*/
123	HOST_SESSION_CREATE = 20,
124	/**
125	* The host wants to close a guest session.
126	*/
127	HOST_SESSION_CLOSE = 21,
128	/**
129	* The host wants to execute something in the guest. This can be a command line
130	* or starting a program.
131	** Note: Legacy (VBox < 4.3) command.
132	*/
133	HOST_EXEC_CMD = 100,
134	/**
135	* Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
136	** Note: Legacy (VBox < 4.3) command.
137	*/
138	HOST_EXEC_SET_INPUT = 101,
139	/**
140	* Gets the current status of a running process, e.g.
141	* new data on stdout/stderr, process terminated etc.
142	** Note: Legacy (VBox < 4.3) command.
143	*/
144	HOST_EXEC_GET_OUTPUT = 102,
145	/**
146	* Terminates a running guest process.
147	*/
148	HOST_EXEC_TERMINATE = 110,
149	/**
150	* Waits for a certain event to happen. This can be an input, output
151	* or status event.
152	*/
153	HOST_EXEC_WAIT_FOR = 120,
154	/**
155	* Opens a guest file.
156	*/
157	HOST_FILE_OPEN = 240,
158	/**
159	* Closes a guest file.
160	*/
161	HOST_FILE_CLOSE = 241,
162	/**
163	* Reads from an opened guest file.
164	*/
165	HOST_FILE_READ = 250,
166	/**
167	* Reads from an opened guest file at
168	* a specified offset.
169	*/
170	HOST_FILE_READ_AT = 251,
171	/**
172	* Write to an opened guest file.
173	*/
174	HOST_FILE_WRITE = 260,
175	/**
176	* Write to an opened guest file at
177	* a specified offset.
178	*/
179	HOST_FILE_WRITE_AT = 261,
180	/**
181	* Changes the read & write position of an opened guest file.
182	*/
183	HOST_FILE_SEEK = 270,
184	/**
185	* Gets the current file position of an opened guest file.
186	*/
187	HOST_FILE_TELL = 271,
188	/**
189	* Removes a directory on the guest.
190	*/
191	HOST_DIR_REMOVE = 320,
192	/**
193	* Renames a path on the guest.
194	*/
195	HOST_PATH_RENAME = 330,
196	/**
197	* Retrieves the user's documents directory.
198	*/
199	HOST_PATH_USER_DOCUMENTS = 331,
200	/**
201	* Retrieves the user's home directory.
202	*/
203	HOST_PATH_USER_HOME = 332
204	};
205
206	/**
207	* The service functions which are called by guest. The numbers may not change,
208	* so we hardcode them.
209	*/
210	enum eGuestFn
211	{
212	/**
213	* Guest waits for a new message the host wants to process on the guest side.
214	* This is a blocking call and can be deferred.
215	*
216	* @note This command is rather odd. The above description isn't really
217	* correct. Yes, it (1) waits for a new message and will return the
218	* mesage number and parameter count when one is available. However, it
219	* is also (2) used to retrieve the message parameters. For some weird
220	* reasons it was decided that it should always return VERR_TOO_MUCH_DATA
221	* when used in the first capacity.
222	*
223	* @note Has a problem if the guest kernel module cancels the HGCM call, as the
224	* guest cannot resume waiting till the host issues a message for it and
225	* the cancelled call returns. The new message may potentially end up in
226	* /dev/null depending and hang the message conversation between the guest
227	* and the host (SIGCHLD).
228	*
229	* @deprecated Replaced by GUEST_MSG_PEEK_WAIT, GUEST_MSG_GET and
230	* GUEST_MSG_CANCEL.
231	*/
232	GUEST_MSG_WAIT = 1,
233	/**
234	* Guest asks the host to cancel all pending waits the guest itself waits on.
235	* This becomes necessary when the guest wants to quit but still waits for
236	* commands from the host.
237	*/
238	GUEST_CANCEL_PENDING_WAITS = 2,
239	/**
240	* Guest disconnected (terminated normally or due to a crash HGCM
241	* detected when calling service::clientDisconnect().
242	*/
243	GUEST_DISCONNECTED = 3,
244	/**
245	* Sets a message filter to only get messages which have a certain
246	* context ID scheme (that is, a specific session, object etc).
247	* Since VBox 4.3+.
248	*/
249	GUEST_MSG_FILTER_SET = 4,
250	/**
251	* Unsets (and resets) a previously set message filter.
252	*/
253	GUEST_MSG_FILTER_UNSET = 5,
254	/**
255	* Skips the current assigned message returned by GUEST_MSG_WAIT.
256	* Needed for telling the host service to not keep stale
257	* host commands in the queue.
258	*/
259	GUEST_MSG_SKIP = 10,
260	/**
261	* General reply to a host message. Only contains basic data
262	* along with a simple payload.
263	*/
264	GUEST_MSG_REPLY = 11,
265	/**
266	* General message for updating a pending progress for
267	* a long task.
268	*/
269	GUEST_MSG_PROGRESS_UPDATE = 12,
270
271	/** Peeks at the next message, returning immediately.
272	*
273	* Returns two 32-bit parameters, first is the message ID and the second the
274	* parameter count. May optionally return additional 32-bit parameters with the
275	* sizes of respective message parameters. To distinguish buffer sizes from
276	* integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
277	* uint64_t is ~8U).
278	*
279	* @retval VINF_SUCCESS if a message was pending and is being returned.
280	* @retval VERR_TRY_AGAIN if no message pending.
281	* @retval VERR_INVALID_HANDLE if invalid client ID.
282	* @retval VERR_INVALID_PARAMETER if incorrect parameter count or types.
283	* @since 6.0
284	*/
285	GUEST_MSG_PEEK_NOWAIT,
286	/** Peeks at the next message, waiting for one to arrive.
287	*
288	* Returns two 32-bit parameters, first is the message ID and the second the
289	* parameter count. May optionally return additional 32-bit parameters with the
290	* sizes of respective message parameters. To distinguish buffer sizes from
291	* integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
292	* uint64_t is ~8U).
293	*
294	* @retval VINF_SUCCESS if info about an pending message is being returned.
295	* @retval VINF_TRY_AGAIN and message set to HOST_CANCEL_PENDING_WAITS if
296	* cancelled by GUEST_MSG_CANCEL or GUEST_CANCEL_PENDING_WAITS.
297	* @retval VERR_RESOURCE_BUSY if another thread already made a waiting call.
298	* @retval VERR_INVALID_HANDLE if invalid client ID.
299	* @retval VERR_INVALID_PARAMETER if incorrect parameter count or types.
300	* @note This replaces GUEST_MSG_WAIT.
301	* @since 6.0
302	*/
303	GUEST_MSG_PEEK_WAIT,
304	/** Gets the next message, returning immediately.
305	*
306	* All parameters are specific to the message being retrieved, however if the
307	* first one is an integer value it shall be an input parameter holding the
308	* ID of the message being retrieved. While it would be nice to add a separate
309	* parameter for this purpose, this is difficult without breaking GUEST_MSG_WAIT
310	* compatibility.
311	*
312	* @retval VINF_SUCCESS if message retrieved and removed from the pending queue.
313	* @retval VERR_TRY_AGAIN if no message pending.
314	* @retval VERR_MISMATCH if the incoming message ID does not match the pending.
315	* @retval VERR_OUT_OF_RANGE if the wrong parameter count.
316	* @retval VERR_WRONG_TYPE if a parameter has the wrong type.
317	* @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer
318	* size was updated to reflect the required size.
319	* @retval VERR_INVALID_HANDLE if invalid client ID.
320	* @note This replaces GUEST_MSG_WAIT.
321	* @since 6.0
322	*/
323	GUEST_MSG_GET,
324	/** Cancels pending calls for this client session.
325	*
326	* This should be used if a GUEST_MSG_PEEK_WAIT or GUEST_MSG_WAIT call gets
327	* interrupted on the client end, so as to prevent being rebuffed with
328	* VERR_RESOURCE_BUSY when restarting the call.
329	*
330	* @retval VINF_SUCCESS if cancelled any calls.
331	* @retval VWRN_NOT_FOUND if no callers.
332	* @retval VERR_INVALID_PARAMETER if any parameters specified (expects zero).
333	* @retval VERR_INVALID_HANDLE if invalid client ID.
334	* @since 6.0
335	*/
336	GUEST_MSG_CANCEL,
337
338	/**
339	* Guest reports back a guest session status.
340	*/
341	GUEST_SESSION_NOTIFY = 20,
342	/**
343	* Guest wants to close a specific guest session.
344	*/
345	GUEST_SESSION_CLOSE = 21,
346
347	/**
348	* Guests sends output from an executed process.
349	*/
350	GUEST_EXEC_OUTPUT = 100,
351	/**
352	* Guest sends a status update of an executed process to the host.
353	*/
354	GUEST_EXEC_STATUS = 101,
355	/**
356	* Guests sends an input status notification to the host.
357	*/
358	GUEST_EXEC_INPUT_STATUS = 102,
359	/**
360	* Guest notifies the host about some I/O event. This can be
361	* a stdout, stderr or a stdin event. The actual event only tells
362	* how many data is available / can be sent without actually
363	* transmitting the data.
364	*/
365	GUEST_EXEC_IO_NOTIFY = 210,
366	/**
367	* Guest notifies the host about some directory event.
368	*/
369	GUEST_DIR_NOTIFY = 230,
370	/**
371	* Guest notifies the host about some file event.
372	*/
373	GUEST_FILE_NOTIFY = 240
374	};
375
376	/**
377	* Guest session notification types.
378	* @sa HGCMMsgSessionNotify.
379	*/
380	enum GUEST_SESSION_NOTIFYTYPE
381	{
382	GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0,
383	/** Something went wrong (see rc). */
384	GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
385	/** Guest session has been started. */
386	GUEST_SESSION_NOTIFYTYPE_STARTED = 11,
387	/** Guest session terminated normally. */
388	GUEST_SESSION_NOTIFYTYPE_TEN = 20,
389	/** Guest session terminated via signal. */
390	GUEST_SESSION_NOTIFYTYPE_TES = 30,
391	/** Guest session terminated abnormally. */
392	GUEST_SESSION_NOTIFYTYPE_TEA = 40,
393	/** Guest session timed out and was killed. */
394	GUEST_SESSION_NOTIFYTYPE_TOK = 50,
395	/** Guest session timed out and was not killed successfully. */
396	GUEST_SESSION_NOTIFYTYPE_TOA = 60,
397	/** Service/OS is stopping, process was killed. */
398	GUEST_SESSION_NOTIFYTYPE_DWN = 150
399	};
400
401	/**
402	* Guest directory notification types.
403	* @sa HGCMMsgDirNotify.
404	*/
405	enum GUEST_DIR_NOTIFYTYPE
406	{
407	GUEST_DIR_NOTIFYTYPE_UNKNOWN = 0,
408	/** Something went wrong (see rc). */
409	GUEST_DIR_NOTIFYTYPE_ERROR = 1,
410	/** Guest directory opened. */
411	GUEST_DIR_NOTIFYTYPE_OPEN = 10,
412	/** Guest directory closed. */
413	GUEST_DIR_NOTIFYTYPE_CLOSE = 20,
414	/** Information about an open guest directory. */
415	GUEST_DIR_NOTIFYTYPE_INFO = 40,
416	/** Guest directory created. */
417	GUEST_DIR_NOTIFYTYPE_CREATE = 70,
418	/** Guest directory deleted. */
419	GUEST_DIR_NOTIFYTYPE_REMOVE = 80
420	};
421
422	/**
423	* Guest file notification types.
424	* @sa HGCMMsgFileNotify.
425	*/
426	enum GUEST_FILE_NOTIFYTYPE
427	{
428	GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
429	GUEST_FILE_NOTIFYTYPE_ERROR = 1,
430	GUEST_FILE_NOTIFYTYPE_OPEN = 10,
431	GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
432	GUEST_FILE_NOTIFYTYPE_READ = 30,
433	GUEST_FILE_NOTIFYTYPE_WRITE = 40,
434	GUEST_FILE_NOTIFYTYPE_SEEK = 50,
435	GUEST_FILE_NOTIFYTYPE_TELL = 60
436	};
437
438	/**
439	* Guest file seeking types. Has to
440	* match FileSeekType in Main.
441	*/
442	enum GUEST_FILE_SEEKTYPE
443	{
444	GUEST_FILE_SEEKTYPE_BEGIN = 1,
445	GUEST_FILE_SEEKTYPE_CURRENT = 4,
446	GUEST_FILE_SEEKTYPE_END = 8
447	};
448
449	/*
450	* HGCM parameter structures.
451	*/
452	#pragma pack (1)
453
454	/**
455	* Waits for a host command to arrive. The structure then contains the
456	* actual message type + required number of parameters needed to successfully
457	* retrieve that host command (in a next round).
458	*/
459	typedef struct HGCMMsgCmdWaitFor
460	{
461	VBGLIOCHGCMCALL hdr;
462	/**
463	* The returned command the host wants to
464	* run on the guest.
465	*/
466	HGCMFunctionParameter msg; /* OUT uint32_t */
467	/** Number of parameters the message needs. */
468	HGCMFunctionParameter num_parms; /* OUT uint32_t */
469	} HGCMMsgCmdWaitFor;
470
471	/**
472	* Asks the guest control host service to set a command
473	* filter for this client. This filter will then only
474	* deliver messages to the client which match the
475	* wanted context ID (ranges).
476	*/
477	typedef struct HGCMMsgCmdFilterSet
478	{
479	VBGLIOCHGCMCALL hdr;
480	/** Value to filter for after filter mask
481	* was applied. */
482	HGCMFunctionParameter value; /* IN uint32_t */
483	/** Mask to add to the current set filter. */
484	HGCMFunctionParameter mask_add; /* IN uint32_t */
485	/** Mask to remove from the current set filter. */
486	HGCMFunctionParameter mask_remove; /* IN uint32_t */
487	/** Filter flags; currently unused. */
488	HGCMFunctionParameter flags; /* IN uint32_t */
489	} HGCMMsgCmdFilterSet;
490
491	/**
492	* Asks the guest control host service to disable
493	* a previously set message filter again.
494	*/
495	typedef struct HGCMMsgCmdFilterUnset
496	{
497	VBGLIOCHGCMCALL hdr;
498	/** Unset flags; currently unused. */
499	HGCMFunctionParameter flags; /* IN uint32_t */
500	} HGCMMsgCmdFilterUnset;
501
502	/**
503	* Asks the guest control host service to skip the
504	* currently assigned host command returned by
505	* VbglR3GuestCtrlMsgWaitFor().
506	*/
507	typedef struct HGCMMsgCmdSkip
508	{
509	VBGLIOCHGCMCALL hdr;
510	/** Skip flags; currently unused. */
511	HGCMFunctionParameter flags; /* IN uint32_t */
512	} HGCMMsgCmdSkip;
513
514	/**
515	* Asks the guest control host service to cancel all pending (outstanding)
516	* waits which were not processed yet. This is handy for a graceful shutdown.
517	*/
518	typedef struct HGCMMsgCancelPendingWaits
519	{
520	VBGLIOCHGCMCALL hdr;
521	} HGCMMsgCancelPendingWaits;
522
523	typedef struct HGCMMsgCmdReply
524	{
525	VBGLIOCHGCMCALL hdr;
526	/** Context ID. */
527	HGCMFunctionParameter context;
528	/** Message type. */
529	HGCMFunctionParameter type;
530	/** IPRT result of overall operation. */
531	HGCMFunctionParameter rc;
532	/** Optional payload to this reply. */
533	HGCMFunctionParameter payload;
534	} HGCMMsgCmdReply;
535
536	/**
537	* Creates a guest session.
538	*/
539	typedef struct HGCMMsgSessionOpen
540	{
541	VBGLIOCHGCMCALL hdr;
542	/** Context ID. */
543	HGCMFunctionParameter context;
544	/** The guest control protocol version this
545	* session is about to use. */
546	HGCMFunctionParameter protocol;
547	/** The user name to run the guest session under. */
548	HGCMFunctionParameter username;
549	/** The user's password. */
550	HGCMFunctionParameter password;
551	/** The domain to run the guest session under. */
552	HGCMFunctionParameter domain;
553	/** Session creation flags. */
554	HGCMFunctionParameter flags;
555	} HGCMMsgSessionOpen;
556
557	/**
558	* Terminates (closes) a guest session.
559	*/
560	typedef struct HGCMMsgSessionClose
561	{
562	VBGLIOCHGCMCALL hdr;
563	/** Context ID. */
564	HGCMFunctionParameter context;
565	/** Session termination flags. */
566	HGCMFunctionParameter flags;
567	} HGCMMsgSessionClose;
568
569	/**
570	* Reports back a guest session's status.
571	*/
572	typedef struct HGCMMsgSessionNotify
573	{
574	VBGLIOCHGCMCALL hdr;
575	/** Context ID. */
576	HGCMFunctionParameter context;
577	/** Notification type. */
578	HGCMFunctionParameter type;
579	/** Notification result. */
580	HGCMFunctionParameter result;
581	} HGCMMsgSessionNotify;
582
583	typedef struct HGCMMsgPathRename
584	{
585	VBGLIOCHGCMCALL hdr;
586	/** UInt32: Context ID. */
587	HGCMFunctionParameter context;
588	/** Source to rename. */
589	HGCMFunctionParameter source;
590	/** Destination to rename source to. */
591	HGCMFunctionParameter dest;
592	/** UInt32: Rename flags. */
593	HGCMFunctionParameter flags;
594	} HGCMMsgPathRename;
595
596	typedef struct HGCMMsgPathUserDocuments
597	{
598	VBGLIOCHGCMCALL hdr;
599	/** UInt32: Context ID. */
600	HGCMFunctionParameter context;
601	} HGCMMsgPathUserDocuments;
602
603	typedef struct HGCMMsgPathUserHome
604	{
605	VBGLIOCHGCMCALL hdr;
606	/** UInt32: Context ID. */
607	HGCMFunctionParameter context;
608	} HGCMMsgPathUserHome;
609
610	/**
611	* Executes a command inside the guest.
612	*/
613	typedef struct HGCMMsgProcExec
614	{
615	VBGLIOCHGCMCALL hdr;
616	/** Context ID. */
617	HGCMFunctionParameter context;
618	/** The command to execute on the guest. */
619	HGCMFunctionParameter cmd;
620	/** Execution flags (see IGuest::ProcessCreateFlag_). /
621	HGCMFunctionParameter flags;
622	/** Number of arguments. */
623	HGCMFunctionParameter num_args;
624	/** The actual arguments. */
625	HGCMFunctionParameter args;
626	/** Number of environment value pairs. */
627	HGCMFunctionParameter num_env;
628	/** Size (in bytes) of environment block, including terminating zeros. */
629	HGCMFunctionParameter cb_env;
630	/** The actual environment block. */
631	HGCMFunctionParameter env;
632	union
633	{
634	struct
635	{
636	/** The user name to run the executed command under.
637	* Only for VBox < 4.3 hosts. */
638	HGCMFunctionParameter username;
639	/** The user's password.
640	* Only for VBox < 4.3 hosts. */
641	HGCMFunctionParameter password;
642	/** Timeout (in msec) which either specifies the
643	* overall lifetime of the process or how long it
644	* can take to bring the process up and running -
645	* (depends on the IGuest::ProcessCreateFlag_). /
646	HGCMFunctionParameter timeout;
647	} v1;
648	struct
649	{
650	/** Timeout (in ms) which either specifies the
651	* overall lifetime of the process or how long it
652	* can take to bring the process up and running -
653	* (depends on the IGuest::ProcessCreateFlag_). /
654	HGCMFunctionParameter timeout;
655	/** Process priority. */
656	HGCMFunctionParameter priority;
657	/** Number of process affinity blocks. */
658	HGCMFunctionParameter num_affinity;
659	/** Pointer to process affinity blocks (uint64_t). */
660	HGCMFunctionParameter affinity;
661	} v2;
662	} u;
663	} HGCMMsgProcExec;
664
665	/**
666	* Sends input to a guest process via stdin.
667	*/
668	typedef struct HGCMMsgProcInput
669	{
670	VBGLIOCHGCMCALL hdr;
671	/** Context ID. */
672	HGCMFunctionParameter context;
673	/** The process ID (PID) to send the input to. */
674	HGCMFunctionParameter pid;
675	/** Input flags (see IGuest::ProcessInputFlag_). /
676	HGCMFunctionParameter flags;
677	/** Data buffer. */
678	HGCMFunctionParameter data;
679	/** Actual size of data (in bytes). */
680	HGCMFunctionParameter size;
681	} HGCMMsgProcInput;
682
683	/**
684	* Retrieves ouptut from a previously executed process
685	* from stdout/stderr.
686	*/
687	typedef struct HGCMMsgProcOutput
688	{
689	VBGLIOCHGCMCALL hdr;
690	/** Context ID. */
691	HGCMFunctionParameter context;
692	/** The process ID (PID). */
693	HGCMFunctionParameter pid;
694	/** The pipe handle ID (stdout/stderr). */
695	HGCMFunctionParameter handle;
696	/** Optional flags. */
697	HGCMFunctionParameter flags;
698	/** Data buffer. */
699	HGCMFunctionParameter data;
700	} HGCMMsgProcOutput;
701
702	/**
703	* Reports the current status of a guest process.
704	*/
705	typedef struct HGCMMsgProcStatus
706	{
707	VBGLIOCHGCMCALL hdr;
708	/** Context ID. */
709	HGCMFunctionParameter context;
710	/** The process ID (PID). */
711	HGCMFunctionParameter pid;
712	/** The process status. */
713	HGCMFunctionParameter status;
714	/** Optional flags (based on status). */
715	HGCMFunctionParameter flags;
716	/** Optional data buffer (not used atm). */
717	HGCMFunctionParameter data;
718	} HGCMMsgProcStatus;
719
720	/**
721	* Reports back the status of data written to a process.
722	*/
723	typedef struct HGCMMsgProcStatusInput
724	{
725	VBGLIOCHGCMCALL hdr;
726	/** Context ID. */
727	HGCMFunctionParameter context;
728	/** The process ID (PID). */
729	HGCMFunctionParameter pid;
730	/** Status of the operation. */
731	HGCMFunctionParameter status;
732	/** Optional flags. */
733	HGCMFunctionParameter flags;
734	/** Data written. */
735	HGCMFunctionParameter written;
736	} HGCMMsgProcStatusInput;
737
738	/*
739	* Guest control 2.0 messages.
740	*/
741
742	/**
743	* Terminates a guest process.
744	*/
745	typedef struct HGCMMsgProcTerminate
746	{
747	VBGLIOCHGCMCALL hdr;
748	/** Context ID. */
749	HGCMFunctionParameter context;
750	/** The process ID (PID). */
751	HGCMFunctionParameter pid;
752	} HGCMMsgProcTerminate;
753
754	/**
755	* Waits for certain events to happen.
756	*/
757	typedef struct HGCMMsgProcWaitFor
758	{
759	VBGLIOCHGCMCALL hdr;
760	/** Context ID. */
761	HGCMFunctionParameter context;
762	/** The process ID (PID). */
763	HGCMFunctionParameter pid;
764	/** Wait (event) flags. */
765	HGCMFunctionParameter flags;
766	/** Timeout (in ms). */
767	HGCMFunctionParameter timeout;
768	} HGCMMsgProcWaitFor;
769
770	typedef struct HGCMMsgDirRemove
771	{
772	VBGLIOCHGCMCALL hdr;
773	/** UInt32: Context ID. */
774	HGCMFunctionParameter context;
775	/** Directory to remove. */
776	HGCMFunctionParameter path;
777	/** UInt32: Removement flags. */
778	HGCMFunctionParameter flags;
779	} HGCMMsgDirRemove;
780
781	/**
782	* Opens a guest file.
783	*/
784	typedef struct HGCMMsgFileOpen
785	{
786	VBGLIOCHGCMCALL hdr;
787	/** UInt32: Context ID. */
788	HGCMFunctionParameter context;
789	/** File to open. */
790	HGCMFunctionParameter filename;
791	/** Open mode. */
792	HGCMFunctionParameter openmode;
793	/** Disposition mode. */
794	HGCMFunctionParameter disposition;
795	/** Sharing mode. */
796	HGCMFunctionParameter sharing;
797	/** UInt32: Creation mode. */
798	HGCMFunctionParameter creationmode;
799	/** UInt64: Initial offset. */
800	HGCMFunctionParameter offset;
801	} HGCMMsgFileOpen;
802
803	/**
804	* Closes a guest file.
805	*/
806	typedef struct HGCMMsgFileClose
807	{
808	VBGLIOCHGCMCALL hdr;
809	/** Context ID. */
810	HGCMFunctionParameter context;
811	/** File handle to close. */
812	HGCMFunctionParameter handle;
813	} HGCMMsgFileClose;
814
815	/**
816	* Reads from a guest file.
817	*/
818	typedef struct HGCMMsgFileRead
819	{
820	VBGLIOCHGCMCALL hdr;
821	/** Context ID. */
822	HGCMFunctionParameter context;
823	/** File handle to read from. */
824	HGCMFunctionParameter handle;
825	/** Size (in bytes) to read. */
826	HGCMFunctionParameter size;
827	} HGCMMsgFileRead;
828
829	/**
830	* Reads at a specified offset from a guest file.
831	*/
832	typedef struct HGCMMsgFileReadAt
833	{
834	VBGLIOCHGCMCALL hdr;
835	/** Context ID. */
836	HGCMFunctionParameter context;
837	/** File handle to read from. */
838	HGCMFunctionParameter handle;
839	/** Offset where to start reading from. */
840	HGCMFunctionParameter offset;
841	/** Actual size of data (in bytes). */
842	HGCMFunctionParameter size;
843	} HGCMMsgFileReadAt;
844
845	/**
846	* Writes to a guest file.
847	*/
848	typedef struct HGCMMsgFileWrite
849	{
850	VBGLIOCHGCMCALL hdr;
851	/** Context ID. */
852	HGCMFunctionParameter context;
853	/** File handle to write to. */
854	HGCMFunctionParameter handle;
855	/** Actual size of data (in bytes). */
856	HGCMFunctionParameter size;
857	/** Data buffer to write to the file. */
858	HGCMFunctionParameter data;
859	} HGCMMsgFileWrite;
860
861	/**
862	* Writes at a specified offset to a guest file.
863	*/
864	typedef struct HGCMMsgFileWriteAt
865	{
866	VBGLIOCHGCMCALL hdr;
867	/** Context ID. */
868	HGCMFunctionParameter context;
869	/** File handle to write to. */
870	HGCMFunctionParameter handle;
871	/** Offset where to start reading from. */
872	HGCMFunctionParameter offset;
873	/** Actual size of data (in bytes). */
874	HGCMFunctionParameter size;
875	/** Data buffer to write to the file. */
876	HGCMFunctionParameter data;
877	} HGCMMsgFileWriteAt;
878
879	/**
880	* Seeks the read/write position of a guest file.
881	*/
882	typedef struct HGCMMsgFileSeek
883	{
884	VBGLIOCHGCMCALL hdr;
885	/** Context ID. */
886	HGCMFunctionParameter context;
887	/** File handle to seek. */
888	HGCMFunctionParameter handle;
889	/** The seeking method. */
890	HGCMFunctionParameter method;
891	/** The seeking offset. */
892	HGCMFunctionParameter offset;
893	} HGCMMsgFileSeek;
894
895	/**
896	* Tells the current read/write position of a guest file.
897	*/
898	typedef struct HGCMMsgFileTell
899	{
900	VBGLIOCHGCMCALL hdr;
901	/** Context ID. */
902	HGCMFunctionParameter context;
903	/** File handle to get the current position for. */
904	HGCMFunctionParameter handle;
905	} HGCMMsgFileTell;
906
907	/******************************************************************************
908	* HGCM replies from the guest. These are handled in Main's low-level HGCM *
909	* callbacks and dispatched to the appropriate guest object. *
910	******************************************************************************/
911
912	typedef struct HGCMReplyFileNotify
913	{
914	VBGLIOCHGCMCALL hdr;
915	/** Context ID. */
916	HGCMFunctionParameter context;
917	/** Notification type. */
918	HGCMFunctionParameter type;
919	/** IPRT result of overall operation. */
920	HGCMFunctionParameter rc;
921	union
922	{
923	struct
924	{
925	/** Guest file handle. */
926	HGCMFunctionParameter handle;
927	} open;
928	/** Note: Close does not have any additional data (yet). */
929	struct
930	{
931	/** Actual data read (if any). */
932	HGCMFunctionParameter data;
933	} read;
934	struct
935	{
936	/** How much data (in bytes) have been successfully written. */
937	HGCMFunctionParameter written;
938	} write;
939	struct
940	{
941	HGCMFunctionParameter offset;
942	} seek;
943	struct
944	{
945	HGCMFunctionParameter offset;
946	} tell;
947	} u;
948	} HGCMReplyFileNotify;
949
950	typedef struct HGCMReplyDirNotify
951	{
952	VBGLIOCHGCMCALL hdr;
953	/** Context ID. */
954	HGCMFunctionParameter context;
955	/** Notification type. */
956	HGCMFunctionParameter type;
957	/** IPRT result of overall operation. */
958	HGCMFunctionParameter rc;
959	union
960	{
961	struct
962	{
963	/** Directory information. */
964	HGCMFunctionParameter objInfo;
965	} info;
966	struct
967	{
968	/** Guest directory handle. */
969	HGCMFunctionParameter handle;
970	} open;
971	struct
972	{
973	/** Current read directory entry. */
974	HGCMFunctionParameter entry;
975	/** Extended entry object information. Optional. */
976	HGCMFunctionParameter objInfo;
977	} read;
978	} u;
979	} HGCMReplyDirNotify;
980
981	#pragma pack ()
982
983	/******************************************************************************
984	* Callback data structures. *
985	******************************************************************************/
986
987	/**
988	* The guest control callback data header. Must come first
989	* on each callback structure defined below this struct.
990	*/
991	typedef struct CALLBACKDATA_HEADER
992	{
993	/** Context ID to identify callback data. This is
994	* and must be the very first parameter in this
995	* structure to still be backwards compatible. */
996	uint32_t uContextID;
997	} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER;
998
999	/*
1000	* These structures make up the actual low level HGCM callback data sent from
1001	* the guest back to the host.
1002	*/
1003
1004	typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
1005	{
1006	/** Callback data header. */
1007	CALLBACKDATA_HEADER hdr;
1008	} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED;
1009
1010	typedef struct CALLBACKDATA_MSG_REPLY
1011	{
1012	/** Callback data header. */
1013	CALLBACKDATA_HEADER hdr;
1014	/** Notification type. */
1015	uint32_t uType;
1016	/** Notification result. Note: int vs. uint32! */
1017	uint32_t rc;
1018	/** Pointer to optional payload. */
1019	void *pvPayload;
1020	/** Payload size (in bytes). */
1021	uint32_t cbPayload;
1022	} CALLBACKDATA_MSG_REPLY, *PCALLBACKDATA_MSG_REPLY;
1023
1024	typedef struct CALLBACKDATA_SESSION_NOTIFY
1025	{
1026	/** Callback data header. */
1027	CALLBACKDATA_HEADER hdr;
1028	/** Notification type. */
1029	uint32_t uType;
1030	/** Notification result. Note: int vs. uint32! */
1031	uint32_t uResult;
1032	} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY;
1033
1034	typedef struct CALLBACKDATA_PROC_STATUS
1035	{
1036	/** Callback data header. */
1037	CALLBACKDATA_HEADER hdr;
1038	/** The process ID (PID). */
1039	uint32_t uPID;
1040	/** The process status. */
1041	uint32_t uStatus;
1042	/** Optional flags, varies, based on u32Status. */
1043	uint32_t uFlags;
1044	/** Optional data buffer (not used atm). */
1045	void *pvData;
1046	/** Size of optional data buffer (not used atm). */
1047	uint32_t cbData;
1048	} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS;
1049
1050	typedef struct CALLBACKDATA_PROC_OUTPUT
1051	{
1052	/** Callback data header. */
1053	CALLBACKDATA_HEADER hdr;
1054	/** The process ID (PID). */
1055	uint32_t uPID;
1056	/** The handle ID (stdout/stderr). */
1057	uint32_t uHandle;
1058	/** Optional flags (not used atm). */
1059	uint32_t uFlags;
1060	/** Optional data buffer. */
1061	void *pvData;
1062	/** Size (in bytes) of optional data buffer. */
1063	uint32_t cbData;
1064	} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT;
1065
1066	typedef struct CALLBACKDATA_PROC_INPUT
1067	{
1068	/** Callback data header. */
1069	CALLBACKDATA_HEADER hdr;
1070	/** The process ID (PID). */
1071	uint32_t uPID;
1072	/** Current input status. */
1073	uint32_t uStatus;
1074	/** Optional flags. */
1075	uint32_t uFlags;
1076	/** Size (in bytes) of processed input data. */
1077	uint32_t uProcessed;
1078	} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT;
1079
1080	/**
1081	* General guest directory notification callback.
1082	*/
1083	typedef struct CALLBACKDATA_DIR_NOTIFY
1084	{
1085	/** Callback data header. */
1086	CALLBACKDATA_HEADER hdr;
1087	/** Notification type. */
1088	uint32_t uType;
1089	/** IPRT result of overall operation. */
1090	uint32_t rc;
1091	union
1092	{
1093	struct
1094	{
1095	/** Size (in bytes) of directory information. */
1096	uint32_t cbObjInfo;
1097	/** Pointer to directory information. */
1098	void *pvObjInfo;
1099	} info;
1100	struct
1101	{
1102	/** Guest directory handle. */
1103	uint32_t uHandle;
1104	} open;
1105	/** Note: Close does not have any additional data (yet). */
1106	struct
1107	{
1108	/** Size (in bytes) of directory entry information. */
1109	uint32_t cbEntry;
1110	/** Pointer to directory entry information. */
1111	void *pvEntry;
1112	/** Size (in bytes) of directory entry object information. */
1113	uint32_t cbObjInfo;
1114	/** Pointer to directory entry object information. */
1115	void *pvObjInfo;
1116	} read;
1117	} u;
1118	} CALLBACKDATA_DIR_NOTIFY, *PCALLBACKDATA_DIR_NOTIFY;
1119
1120	/**
1121	* General guest file notification callback.
1122	*/
1123	typedef struct CALLBACKDATA_FILE_NOTIFY
1124	{
1125	/** Callback data header. */
1126	CALLBACKDATA_HEADER hdr;
1127	/** Notification type. */
1128	uint32_t uType;
1129	/** IPRT result of overall operation. */
1130	uint32_t rc;
1131	union
1132	{
1133	struct
1134	{
1135	/** Guest file handle. */
1136	uint32_t uHandle;
1137	} open;
1138	/** Note: Close does not have any additional data (yet). */
1139	struct
1140	{
1141	/** How much data (in bytes) have been read. */
1142	uint32_t cbData;
1143	/** Actual data read (if any). */
1144	void *pvData;
1145	} read;
1146	struct
1147	{
1148	/** How much data (in bytes) have been successfully written. */
1149	uint32_t cbWritten;
1150	} write;
1151	struct
1152	{
1153	/** New file offset after successful seek. */
1154	uint64_t uOffActual;
1155	} seek;
1156	struct
1157	{
1158	/** New file offset after successful tell. */
1159	uint64_t uOffActual;
1160	} tell;
1161	} u;
1162	} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
1163
1164	} /* namespace guestControl */
1165
1166	#endif /* !___VBox_HostService_GuestControlService_h */
1167

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

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

Download in other formats: