VBoxServiceControl.h@ 98526

最後變更在這個檔案從98526是 98526,由 vboxsync 提交於 2 年前

Guest Control: Initial commit (work in progress, disabled by default). bugref:9783

IGuestDirectory:

Added new attributes id + status + an own event source. Also added for rewind support via rewind().

New event types for guest directory [un]registration, state changes and entry reads.

屬性 svn:eol-style 設為 native
屬性 svn:keywords 設為 Author Date Id Revision

檔案大小: 14.1 KB

行
1	/* $Id: VBoxServiceControl.h 98526 2023-02-10 15:10:50Z vboxsync $ */
2	/** @file
3	* VBoxServiceControl.h - Internal guest control definitions.
4	*/
5
6	/*
7	* Copyright (C) 2013-2023 Oracle and/or its affiliates.
8	*
9	* This file is part of VirtualBox base platform packages, as
10	* available from https://www.alldomusa.eu.org.
11	*
12	* This program is free software; you can redistribute it and/or
13	* modify it under the terms of the GNU General Public License
14	* as published by the Free Software Foundation, in version 3 of the
15	* License.
16	*
17	* This program is distributed in the hope that it will be useful, but
18	* WITHOUT ANY WARRANTY; without even the implied warranty of
19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	* General Public License for more details.
21	*
22	* You should have received a copy of the GNU General Public License
23	* along with this program; if not, see <https://www.gnu.org/licenses>.
24	*
25	* SPDX-License-Identifier: GPL-3.0-only
26	*/
27
28	#ifndef GA_INCLUDED_SRC_common_VBoxService_VBoxServiceControl_h
29	#define GA_INCLUDED_SRC_common_VBoxService_VBoxServiceControl_h
30	#ifndef RT_WITHOUT_PRAGMA_ONCE
31	# pragma once
32	#endif
33
34	#include <iprt/critsect.h>
35	#include <iprt/list.h>
36	#include <iprt/req.h>
37
38	#include <VBox/VBoxGuestLib.h>
39	#include <VBox/GuestHost/GuestControl.h>
40	#include <VBox/HostServices/GuestControlSvc.h>
41
42
43	/**
44	* Pipe IDs for handling the guest process poll set.
45	*/
46	typedef enum VBOXSERVICECTRLPIPEID
47	{
48	VBOXSERVICECTRLPIPEID_UNKNOWN = 0,
49	VBOXSERVICECTRLPIPEID_STDIN = 10,
50	VBOXSERVICECTRLPIPEID_STDIN_WRITABLE = 11,
51	/** Pipe for reading from guest process' stdout. */
52	VBOXSERVICECTRLPIPEID_STDOUT = 40,
53	/** Pipe for reading from guest process' stderr. */
54	VBOXSERVICECTRLPIPEID_STDERR = 50,
55	/** Notification pipe for waking up the guest process
56	* control thread. */
57	VBOXSERVICECTRLPIPEID_IPC_NOTIFY = 100
58	} VBOXSERVICECTRLPIPEID;
59
60	#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
61	/**
62	* Structure for one (opened) guest directory.
63	*/
64	typedef struct VBOXSERVICECTRLDIR
65	{
66	/** Pointer to list archor of following list node.
67	* @todo Would be nice to have a RTListGetAnchor(). */
68	PRTLISTANCHOR pAnchor;
69	/** Node to global guest control directory list. */
70	/** @todo Use a map later? */
71	RTLISTNODE Node;
72	/** The (absolute) directory path. */
73	char *pszPathAbs;
74	/** The directory handle on the guest. */
75	RTDIR hDir;
76	/** Directory handle to identify this directory. */
77	uint32_t uHandle;
78	/** Context ID. */
79	uint32_t uContextID;
80	} VBOXSERVICECTRLDIR;
81	/** Pointer to a guest directory. */
82	typedef VBOXSERVICECTRLDIR *PVBOXSERVICECTRLDIR;
83	#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
84
85	/**
86	* Structure for one (opened) guest file.
87	*/
88	typedef struct VBOXSERVICECTRLFILE
89	{
90	/** Pointer to list archor of following list node.
91	* @todo Would be nice to have a RTListGetAnchor(). */
92	PRTLISTANCHOR pAnchor;
93	/** Node to global guest control file list. */
94	/** @todo Use a map later? */
95	RTLISTNODE Node;
96	/** The file name. */
97	char *pszName;
98	/** The file handle on the guest. */
99	RTFILE hFile;
100	/** File handle to identify this file. */
101	uint32_t uHandle;
102	/** Context ID. */
103	uint32_t uContextID;
104	/** RTFILE_O_XXX flags. */
105	uint64_t fOpen;
106	} VBOXSERVICECTRLFILE;
107	/** Pointer to a guest file. */
108	typedef VBOXSERVICECTRLFILE *PVBOXSERVICECTRLFILE;
109
110	/**
111	* Structure for a guest session thread to
112	* observe/control the forked session instance from
113	* the VBoxService main executable.
114	*/
115	typedef struct VBOXSERVICECTRLSESSIONTHREAD
116	{
117	/** Node to global guest control session list. */
118	/** @todo Use a map later? */
119	RTLISTNODE Node;
120	/** The sessions's startup info. */
121	PVBGLR3GUESTCTRLSESSIONSTARTUPINFO
122	pStartupInfo;
123	/** Critical section for thread-safe use. */
124	RTCRITSECT CritSect;
125	/** The worker thread. */
126	RTTHREAD Thread;
127	/** Process handle for forked child. */
128	RTPROCESS hProcess;
129	/** Shutdown indicator; will be set when the thread
130	* needs (or is asked) to shutdown. */
131	bool volatile fShutdown;
132	/** Indicator set by the service thread exiting. */
133	bool volatile fStopped;
134	/** Whether the thread was started or not. */
135	bool fStarted;
136	#if 0 /* Pipe IPC not used yet. */
137	/** Pollset containing all the pipes. */
138	RTPOLLSET hPollSet;
139	RTPIPE hStdInW;
140	RTPIPE hStdOutR;
141	RTPIPE hStdErrR;
142	struct StdPipe
143	{
144	RTHANDLE hChild;
145	PRTHANDLE phChild;
146	} StdIn,
147	StdOut,
148	StdErr;
149	/** The notification pipe associated with this guest session.
150	* This is NIL_RTPIPE for output pipes. */
151	RTPIPE hNotificationPipeW;
152	/** The other end of hNotificationPipeW. */
153	RTPIPE hNotificationPipeR;
154	#endif
155	/** Pipe for handing the secret key to the session process. */
156	RTPIPE hKeyPipe;
157	/** Secret key. */
158	uint8_t abKey[_4K];
159	} VBOXSERVICECTRLSESSIONTHREAD;
160	/** Pointer to thread data. */
161	typedef VBOXSERVICECTRLSESSIONTHREAD *PVBOXSERVICECTRLSESSIONTHREAD;
162
163	/** Defines the prefix being used for telling our service executable that we're going
164	* to spawn a new (Guest Control) user session. */
165	#define VBOXSERVICECTRLSESSION_GETOPT_PREFIX "guestsession"
166
167	/** Flag indicating that this session has been spawned from
168	* the main executable. */
169	#define VBOXSERVICECTRLSESSION_FLAG_SPAWN RT_BIT(0)
170	/** Flag indicating that this session is anonymous, that is,
171	* it will run start guest processes with the same credentials
172	* as the main executable. */
173	#define VBOXSERVICECTRLSESSION_FLAG_ANONYMOUS RT_BIT(1)
174	/** Flag indicating that started guest processes will dump their
175	* stdout output to a separate file on disk. For debugging. */
176	#define VBOXSERVICECTRLSESSION_FLAG_DUMPSTDOUT RT_BIT(2)
177	/** Flag indicating that started guest processes will dump their
178	* stderr output to a separate file on disk. For debugging. */
179	#define VBOXSERVICECTRLSESSION_FLAG_DUMPSTDERR RT_BIT(3)
180
181	/**
182	* Structure for maintaining a guest session. This also
183	* contains all started threads (e.g. for guest processes).
184	*
185	* This structure can act in two different ways:
186	* - For legacy guest control handling (protocol version < 2)
187	* this acts as a per-guest process structure containing all
188	* the information needed to get a guest process up and running.
189	* - For newer guest control protocols (>= 2) this structure is
190	* part of the forked session child, maintaining all guest
191	* control objects under it.
192	*/
193	typedef struct VBOXSERVICECTRLSESSION
194	{
195	/* The session's startup information. */
196	VBGLR3GUESTCTRLSESSIONSTARTUPINFO
197	StartupInfo;
198	/** List of active guest process threads
199	* (VBOXSERVICECTRLPROCESS). */
200	RTLISTANCHOR lstProcesses;
201	/** Number of guest processes in the process list. */
202	uint32_t cProcesses;
203	#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
204	/** List of guest control files (VBOXSERVICECTRLDIR). */
205	RTLISTANCHOR lstDirs;
206	/** Number of guest directories in \a lstDirs. */
207	uint32_t cDirs;
208	#endif
209	/** List of guest control files (VBOXSERVICECTRLFILE). */
210	RTLISTANCHOR lstFiles;
211	/** Number of guest files in \a lstFiles. */
212	uint32_t cFiles;
213	/** The session's critical section. */
214	RTCRITSECT CritSect;
215	/** Internal session flags, not related
216	* to StartupInfo stuff.
217	* @sa VBOXSERVICECTRLSESSION_FLAG_* flags. */
218	uint32_t fFlags;
219	/** How many processes do we allow keeping around at a time? */
220	uint32_t uProcsMaxKept;
221	} VBOXSERVICECTRLSESSION;
222	/** Pointer to guest session. */
223	typedef VBOXSERVICECTRLSESSION *PVBOXSERVICECTRLSESSION;
224
225	/**
226	* Structure for holding data for one (started) guest process.
227	*/
228	typedef struct VBOXSERVICECTRLPROCESS
229	{
230	/** Node. */
231	RTLISTNODE Node;
232	/** Process handle. */
233	RTPROCESS hProcess;
234	/** Number of references using this struct. */
235	uint32_t cRefs;
236	/** The worker thread. */
237	RTTHREAD Thread;
238	/** The session this guest process
239	* is bound to. */
240	PVBOXSERVICECTRLSESSION pSession;
241	/** Shutdown indicator; will be set when the thread
242	* needs (or is asked) to shutdown. */
243	bool volatile fShutdown;
244	/** Whether the guest process thread was stopped or not. */
245	bool volatile fStopped;
246	/** Whether the guest process thread was started or not. */
247	bool fStarted;
248	/** Context ID. */
249	uint32_t uContextID;
250	/** Critical section for thread-safe use. */
251	RTCRITSECT CritSect;
252	/** Process startup information. */
253	PVBGLR3GUESTCTRLPROCSTARTUPINFO
254	pStartupInfo;
255	/** The process' PID assigned by the guest OS. */
256	uint32_t uPID;
257	/** The process' request queue to handle requests
258	* from the outside, e.g. the session. */
259	RTREQQUEUE hReqQueue;
260	/** Our pollset, used for accessing the process'
261	* std* pipes + the notification pipe. */
262	RTPOLLSET hPollSet;
263	/** StdIn pipe for addressing writes to the
264	* guest process' stdin.*/
265	RTPIPE hPipeStdInW;
266	/** StdOut pipe for addressing reads from
267	* guest process' stdout.*/
268	RTPIPE hPipeStdOutR;
269	/** StdOut pipe for addressing reads from
270	* guest process' stderr.*/
271	RTPIPE hPipeStdErrR;
272
273	/** The write end of the notification pipe that is used to poke the thread
274	* monitoring the process.
275	* This is NIL_RTPIPE for output pipes. */
276	RTPIPE hNotificationPipeW;
277	/** The other end of hNotificationPipeW, read by vgsvcGstCtrlProcessProcLoop(). */
278	RTPIPE hNotificationPipeR;
279	} VBOXSERVICECTRLPROCESS;
280	/** Pointer to thread data. */
281	typedef VBOXSERVICECTRLPROCESS *PVBOXSERVICECTRLPROCESS;
282
283	RT_C_DECLS_BEGIN
284
285	extern RTLISTANCHOR g_lstControlSessionThreads;
286	extern VBOXSERVICECTRLSESSION g_Session;
287	extern uint32_t g_idControlSvcClient;
288	extern uint64_t g_fControlHostFeatures0;
289	extern bool g_fControlSupportsOptimizations;
290
291
292	/** @name Guest session thread handling.
293	* @{ */
294	extern int VGSvcGstCtrlSessionThreadCreate(PRTLISTANCHOR pList, const PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pSessionStartupInfo, PVBOXSERVICECTRLSESSIONTHREAD *ppSessionThread);
295	extern int VGSvcGstCtrlSessionThreadDestroy(PVBOXSERVICECTRLSESSIONTHREAD pSession, uint32_t uFlags);
296	extern int VGSvcGstCtrlSessionThreadDestroyAll(PRTLISTANCHOR pList, uint32_t uFlags);
297	extern int VGSvcGstCtrlSessionThreadTerminate(PVBOXSERVICECTRLSESSIONTHREAD pSession);
298	extern RTEXITCODE VGSvcGstCtrlSessionSpawnInit(int argc, char **argv);
299	/** @} */
300	/** @name Per-session functions.
301	* @{ */
302	extern PVBOXSERVICECTRLPROCESS VGSvcGstCtrlSessionRetainProcess(PVBOXSERVICECTRLSESSION pSession, uint32_t uPID);
303	extern int VGSvcGstCtrlSessionClose(PVBOXSERVICECTRLSESSION pSession);
304	extern int VGSvcGstCtrlSessionDestroy(PVBOXSERVICECTRLSESSION pSession);
305	extern int VGSvcGstCtrlSessionInit(PVBOXSERVICECTRLSESSION pSession, uint32_t uFlags);
306	extern int VGSvcGstCtrlSessionHandler(PVBOXSERVICECTRLSESSION pSession, uint32_t uMsg, PVBGLR3GUESTCTRLCMDCTX pHostCtx, void pvScratchBuf, size_t cbScratchBuf, volatile bool pfShutdown);
307	extern int VGSvcGstCtrlSessionProcessAdd(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pProcess);
308	extern int VGSvcGstCtrlSessionProcessRemove(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pProcess);
309	extern int VGSvcGstCtrlSessionProcessStartAllowed(const PVBOXSERVICECTRLSESSION pSession, bool *pfAllowed);
310	extern int VGSvcGstCtrlSessionReapProcesses(PVBOXSERVICECTRLSESSION pSession);
311	/** @} */
312	/** @name Per-guest process functions.
313	* @{ */
314	extern int VGSvcGstCtrlProcessFree(PVBOXSERVICECTRLPROCESS pProcess);
315	extern int VGSvcGstCtrlProcessHandleInput(PVBOXSERVICECTRLPROCESS pProcess, PVBGLR3GUESTCTRLCMDCTX pHostCtx, bool fPendingClose, void *pvBuf, uint32_t cbBuf);
316	extern int VGSvcGstCtrlProcessHandleOutput(PVBOXSERVICECTRLPROCESS pProcess, PVBGLR3GUESTCTRLCMDCTX pHostCtx, uint32_t uHandle, uint32_t cbToRead, uint32_t uFlags);
317	extern int VGSvcGstCtrlProcessHandleTerm(PVBOXSERVICECTRLPROCESS pProcess);
318	extern void VGSvcGstCtrlProcessRelease(PVBOXSERVICECTRLPROCESS pProcess);
319	extern int VGSvcGstCtrlProcessStart(const PVBOXSERVICECTRLSESSION pSession, const PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo, uint32_t uContext);
320	extern int VGSvcGstCtrlProcessStop(PVBOXSERVICECTRLPROCESS pProcess);
321	extern int VGSvcGstCtrlProcessWait(const PVBOXSERVICECTRLPROCESS pProcess, RTMSINTERVAL msTimeout, int *pRc);
322	/** @} */
323
324	RT_C_DECLS_END
325
326	#endif /* !GA_INCLUDED_SRC_common_VBoxService_VBoxServiceControl_h */
327

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

source: vbox/trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControl.h@ 98526

以其他格式下載: