VBoxServiceControl.h@ 83826

Last change on this file since 83826 was 83409, checked in by vboxsync, 5 years ago
Guest Control/VBoxService: Resolved another @todo: Don't ignore non-options in the guest session argument handler. bugref:9320
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 15.1 KB

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

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

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

Download in other formats: