VBoxServiceControl.h@ 52890

Last change on this file since 52890 was 47551, checked in by vboxsync, 11 years ago
VBoxService/GuestCtrl: Re-added (optional debug) dumping of guest process streams, now as a (forked) per-session option.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 14.1 KB

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

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

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

Download in other formats: