VBoxServiceControl.h@ 98709

Last change on this file since 98709 was 98709, checked in by vboxsync, 2 years ago
Guest Control: Implemented directory handling / walking as non-toolbox variants. bugref:9783
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 14.2 KB

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

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

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

Download in other formats: