VBoxServiceControl.h@ 45091

Last change on this file since 45091 was 45010, checked in by vboxsync, 12 years ago
GuestCtrl: More code for guest session infrastructure handling (untested, work in progress).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.5 KB

Line
1	/* $Id: VBoxServiceControl.h 45010 2013-03-12 17:47:56Z 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/list.h>
22	#include <iprt/critsect.h>
23
24	#include <VBox/VBoxGuestLib.h>
25	#include <VBox/HostServices/GuestControlSvc.h>
26
27
28	/**
29	* Pipe IDs for handling the guest process poll set.
30	*/
31	typedef enum VBOXSERVICECTRLPIPEID
32	{
33	VBOXSERVICECTRLPIPEID_UNKNOWN = 0,
34	VBOXSERVICECTRLPIPEID_STDIN = 10,
35	VBOXSERVICECTRLPIPEID_STDIN_WRITABLE = 11,
36	/** Pipe for reading from guest process' stdout. */
37	VBOXSERVICECTRLPIPEID_STDOUT = 40,
38	/** Pipe for reading from guest process' stderr. */
39	VBOXSERVICECTRLPIPEID_STDERR = 50,
40	/** Notification pipe for waking up the guest process
41	* control thread. */
42	VBOXSERVICECTRLPIPEID_IPC_NOTIFY = 100
43	} VBOXSERVICECTRLPIPEID;
44
45	/**
46	* Request types to perform on a started guest process.
47	*/
48	typedef enum VBOXSERVICECTRLREQUESTTYPE
49	{
50	/** Unknown request. */
51	VBOXSERVICECTRLREQUEST_UNKNOWN = 0,
52	/** Main control thread asked used to quit. */
53	VBOXSERVICECTRLREQUEST_QUIT = 1,
54	/** Performs reading from stdout. */
55	VBOXSERVICECTRLREQUEST_PROC_STDOUT = 50,
56	/** Performs reading from stderr. */
57	VBOXSERVICECTRLREQUEST_PROC_STDERR = 60,
58	/** Performs writing to stdin. */
59	VBOXSERVICECTRLREQUEST_PROC_STDIN = 70,
60	/** Same as VBOXSERVICECTRLREQUEST_STDIN_WRITE, but
61	* marks the end of input. */
62	VBOXSERVICECTRLREQUEST_PROC_STDIN_EOF = 71,
63	/** Kill/terminate process. */
64	VBOXSERVICECTRLREQUEST_PROC_TERM = 90,
65	/** Gently ask process to terminate. */
66	/** @todo Implement this! */
67	VBOXSERVICECTRLREQUEST_PROC_HUP = 91,
68	/** Wait for a certain event to happen. */
69	VBOXSERVICECTRLREQUEST_WAIT_FOR = 100
70	} VBOXSERVICECTRLREQUESTTYPE;
71
72	/**
73	* Thread list types.
74	*/
75	typedef enum VBOXSERVICECTRLTHREADLISTTYPE
76	{
77	/** Unknown list -- uncool to use. */
78	VBOXSERVICECTRLTHREADLIST_UNKNOWN = 0,
79	/** Stopped list: Here all guest threads end up
80	* when they reached the stopped state and can
81	* be shut down / free'd safely. */
82	VBOXSERVICECTRLTHREADLIST_STOPPED = 1,
83	/**
84	* Started list: Here all threads are registered
85	* when they're up and running (that is, accepting
86	* commands).
87	*/
88	VBOXSERVICECTRLTHREADLIST_RUNNING = 2
89	} VBOXSERVICECTRLTHREADLISTTYPE;
90
91	/**
92	* Structure to perform a request on a started guest
93	* process. Needed for letting the main guest control thread
94	* to communicate (and wait) for a certain operation which
95	* will be done in context of the started guest process thread.
96	*/
97	typedef struct VBOXSERVICECTRLREQUEST
98	{
99	/** Event semaphore to serialize access. */
100	RTSEMEVENTMULTI Event;
101	/** The request type to handle. */
102	VBOXSERVICECTRLREQUESTTYPE enmType;
103	/** Payload size; on input, this contains the (maximum) amount
104	* of data the caller wants to write or to read. On output,
105	* this show the actual amount of data read/written. */
106	size_t cbData;
107	/** Payload data; a pre-allocated data buffer for input/output. */
108	void *pvData;
109	/** The context ID which is required to complete the
110	* request. Not used at the moment. */
111	uint32_t uCID;
112	/** The overall result of the operation. */
113	int rc;
114	} VBOXSERVICECTRLREQUEST;
115	/** Pointer to request. */
116	typedef VBOXSERVICECTRLREQUEST *PVBOXSERVICECTRLREQUEST;
117
118	typedef struct VBOXSERVICECTRLREQDATA_WAIT_FOR
119	{
120	/** Waiting flags. */
121	uint32_t uWaitFlags;
122	/** Timeout in (ms) for the waiting operation. */
123	uint32_t uTimeoutMS;
124	} VBOXSERVICECTRLREQDATA_WAIT_FOR, *PVBOXSERVICECTRLREQDATA_WAIT_FOR;
125
126	/**
127	* Structure for one (opened) guest file.
128	*/
129	typedef struct VBOXSERVICECTRLFILE
130	{
131	/** Pointer to list archor of following
132	* list node.
133	* @todo Would be nice to have a RTListGetAnchor(). */
134	PRTLISTANCHOR pAnchor;
135	/** Node to global guest control file list. */
136	/** @todo Use a map later? */
137	RTLISTNODE Node;
138	/** The file name. */
139	char szName[RTPATH_MAX];
140	/** The file handle on the guest. */
141	RTFILE hFile;
142	/** File handle to identify this file. */
143	uint32_t uHandle;
144	/** Context ID. */
145	uint32_t uContextID;
146	} VBOXSERVICECTRLFILE;
147	/** Pointer to thread data. */
148	typedef VBOXSERVICECTRLFILE *PVBOXSERVICECTRLFILE;
149
150	typedef struct VBOXSERVICECTRLSESSIONSTARTUPINFO
151	{
152	/** The session's protocol version to use. */
153	uint32_t uProtocol;
154	/** The session's ID. */
155	uint32_t uSessionID;
156	/** User name (account) to start the guest session under. */
157	char szUser[GUESTPROCESS_MAX_USER_LEN];
158	/** Password of specified user name (account). */
159	char szPassword[GUESTPROCESS_MAX_PASSWORD_LEN];
160	/** Domain of the user account. */
161	char szDomain[GUESTPROCESS_MAX_DOMAIN_LEN];
162	/** Session creation flags.
163	* @sa VBOXSERVICECTRLSESSIONSTARTUPFLAG_* flags. */
164	uint32_t uFlags;
165	} VBOXSERVICECTRLSESSIONSTARTUPINFO;
166	/** Pointer to thread data. */
167	typedef VBOXSERVICECTRLSESSIONSTARTUPINFO *PVBOXSERVICECTRLSESSIONSTARTUPINFO;
168
169	/**
170	* Structure for a guest session thread to
171	* observe the forked session instance.
172	*/
173	typedef struct VBOXSERVICECTRLSESSIONTHREAD
174	{
175	/** Node to global guest control session list. */
176	/** @todo Use a map later? */
177	RTLISTNODE Node;
178	/** The sessions's startup info. */
179	VBOXSERVICECTRLSESSIONSTARTUPINFO
180	StartupInfo;
181	/** The worker thread. */
182	RTTHREAD Thread;
183	/** Critical section for thread-safe use. */
184	RTCRITSECT CritSect;
185	/** Process handle for forked child. */
186	RTPROCESS hProcess;
187	/** Shutdown indicator; will be set when the thread
188	* needs (or is asked) to shutdown. */
189	bool volatile fShutdown;
190	/** Indicator set by the service thread exiting. */
191	bool volatile fStopped;
192	/** Whether the thread was started or not. */
193	bool fStarted;
194	#if 0 /* Pipe IPC not used yet. */
195	/** Pollset containing all the pipes. */
196	RTPOLLSET hPollSet;
197	RTPIPE hStdInW;
198	RTPIPE hStdOutR;
199	RTPIPE hStdErrR;
200	struct StdPipe
201	{
202	RTHANDLE hChild;
203	PRTHANDLE phChild;
204	} StdIn,
205	StdOut,
206	StdErr;
207	/** The notification pipe associated with this guest session.
208	* This is NIL_RTPIPE for output pipes. */
209	RTPIPE hNotificationPipeW;
210	/** The other end of hNotificationPipeW. */
211	RTPIPE hNotificationPipeR;
212	#endif
213	} VBOXSERVICECTRLSESSIONTHREAD;
214	/** Pointer to thread data. */
215	typedef VBOXSERVICECTRLSESSIONTHREAD *PVBOXSERVICECTRLSESSIONTHREAD;
216
217	/** Flag indicating that this session has been forked from
218	* the main executable. */
219	#define VBOXSERVICECTRLSESSION_FLAG_FORK RT_BIT(0)
220	/** Flag indicating that this session is anonymous, that is,
221	* it will run start guest processes with the same credentials
222	* as the main executable. */
223	#define VBOXSERVICECTRLSESSION_FLAG_ANONYMOUS RT_BIT(1)
224	/** Flag indicating that start guest processes will dump their
225	* stdout output to a separate file on disk. For debugging. */
226	#define VBOXSERVICECTRLSESSION_FLAG_DUMPSTDOUT RT_BIT(2)
227	/** Flag indicating that start guest processes will dump their
228	* stderr output to a separate file on disk. For debugging. */
229	#define VBOXSERVICECTRLSESSION_FLAG_DUMPSTDERR RT_BIT(3)
230
231	/**
232	* Strucutre for maintaining a guest session. This also
233	* contains all started threads (e.g. for guest processes).
234	*
235	* This structure can act in two different ways:
236	* - For legacy guest control handling (protocol version < 2)
237	* this acts as a per-guest process structure containing all
238	* the information needed to get a guest process up and running.
239	* - For newer guest control protocols (>= 2) this structure is
240	* part of the forked session child, maintaining all guest
241	* control objects under it.
242	*/
243	typedef struct VBOXSERVICECTRLSESSION
244	{
245	VBOXSERVICECTRLSESSIONSTARTUPINFO
246	StartupInfo;
247	/** List of active guest control threads (VBOXSERVICECTRLTHREAD). */
248	RTLISTANCHOR lstControlThreadsActive;
249	/** List of inactive guest control threads (VBOXSERVICECTRLTHREAD). */
250	/** @todo Still needed? */
251	RTLISTANCHOR lstControlThreadsInactive;
252	/** List of guest control files (VBOXSERVICECTRLFILE). */
253	RTLISTANCHOR lstFiles;
254	/** Critical section for protecting the guest process
255	* threading list. */
256	RTCRITSECT csControlThreads;
257	/** Session flags. */
258	uint32_t uFlags;
259	/** How many processes do we allow keeping around at a time? */
260	uint32_t uProcsMaxKept;
261	} VBOXSERVICECTRLSESSION;
262	/** Pointer to guest session. */
263	typedef VBOXSERVICECTRLSESSION *PVBOXSERVICECTRLSESSION;
264
265	/**
266	* Structure holding information for starting a guest
267	* process.
268	*/
269	typedef struct VBOXSERVICECTRLPROCSTARTUPINFO
270	{
271	/** Full qualified path of process to start (without arguments). */
272	char szCmd[GUESTPROCESS_MAX_CMD_LEN];
273	/** Process execution flags. @sa */
274	uint32_t uFlags;
275	/** Command line arguments. */
276	char szArgs[GUESTPROCESS_MAX_ARGS_LEN];
277	/** Number of arguments specified in pszArgs. */
278	uint32_t uNumArgs;
279	/** String of environment variables ("FOO=BAR") to pass to the process
280	* to start. */
281	char szEnv[GUESTPROCESS_MAX_ENV_LEN];
282	/** Size (in bytes) of environment variables block. */
283	uint32_t cbEnv;
284	/** Number of environment variables specified in pszEnv. */
285	uint32_t uNumEnvVars;
286	/** User name (account) to start the process under. */
287	char szUser[GUESTPROCESS_MAX_USER_LEN];
288	/** Password of specified user name (account). */
289	char szPassword[GUESTPROCESS_MAX_PASSWORD_LEN];
290	/** Time limit (in ms) of the process' life time. */
291	uint32_t uTimeLimitMS;
292	/** Process priority. */
293	uint32_t uPriority;
294	/** Process affinity. At the moment we support
295	* up to 4 * 64 = 256 CPUs. */
296	uint64_t uAffinity[4];
297	/** Number of used process affinity blocks. */
298	uint32_t uNumAffinity;
299	} VBOXSERVICECTRLPROCSTARTUPINFO;
300	/** Pointer to a guest process block. */
301	typedef VBOXSERVICECTRLPROCSTARTUPINFO *PVBOXSERVICECTRLPROCSTARTUPINFO;
302
303	/**
304	* Structure for holding data for one (started) guest process.
305	*/
306	typedef struct VBOXSERVICECTRLPROCESS
307	{
308	/** Pointer to list archor of following
309	* list node.
310	* @todo Would be nice to have a RTListGetAnchor(). */
311	PRTLISTANCHOR pAnchor;
312	/** Node. */
313	RTLISTNODE Node;
314	/** The worker thread. */
315	RTTHREAD Thread;
316	/** The session this guest process
317	* is bound to. */
318	PVBOXSERVICECTRLSESSION pSession;
319	/** Shutdown indicator; will be set when the thread
320	* needs (or is asked) to shutdown. */
321	bool volatile fShutdown;
322	/** Indicator set by the service thread exiting. */
323	bool volatile fStopped;
324	/** Whether the service was started or not. */
325	bool fStarted;
326	/** Client ID. */
327	uint32_t uClientID;
328	/** Context ID. */
329	uint32_t uContextID;
330	/** Critical section for thread-safe use. */
331	RTCRITSECT CritSect;
332	/** @todo Document me! */
333	uint32_t uPID;
334	char *pszCmd;
335	uint32_t uFlags;
336	char **papszArgs;
337	uint32_t uNumArgs;
338	char **papszEnv;
339	uint32_t uNumEnvVars;
340	/** Name of specified user account to run the
341	* guest process under. */
342	char *pszUser;
343	/** Password of specified user account. */
344	char *pszPassword;
345	/** Overall time limit (in ms) that the guest process
346	* is allowed to run. 0 for indefinite time. */
347	uint32_t uTimeLimitMS;
348	/** Pointer to the current IPC request being
349	* processed. */
350	PVBOXSERVICECTRLREQUEST pRequest;
351	/** StdIn pipe for addressing writes to the
352	* guest process' stdin.*/
353	RTPIPE pipeStdInW;
354	/** The notification pipe associated with this guest process.
355	* This is NIL_RTPIPE for output pipes. */
356	RTPIPE hNotificationPipeW;
357	/** The other end of hNotificationPipeW. */
358	RTPIPE hNotificationPipeR;
359	} VBOXSERVICECTRLPROCESS;
360	/** Pointer to thread data. */
361	typedef VBOXSERVICECTRLPROCESS *PVBOXSERVICECTRLPROCESS;
362
363	RT_C_DECLS_BEGIN
364
365	/**
366	* Note on naming conventions:
367	* - VBoxServiceControl* is named everything sub service module related, e.g.
368	* everything which is callable by main() and/or the service dispatcher(s).
369	* - GstCntl* is named everything which declared extern and thus can be called
370	* by different guest control modules as needed.
371	* - gstcntl (all lowercase) is a purely static function to split up functionality
372	* inside a module.
373	*/
374
375	/* Guest session thread handling. */
376	extern int GstCntlSessionThreadOpen(PRTLISTANCHOR pList, const PVBOXSERVICECTRLSESSIONSTARTUPINFO pSessionStartupInfo, PVBOXSERVICECTRLSESSIONTHREAD *ppSessionThread);
377	extern int GstCntlSessionThreadClose(PVBOXSERVICECTRLSESSIONTHREAD pSession, uint32_t uFlags);
378	extern int GstCntlSessionThreadCloseAll(PRTLISTANCHOR pList, uint32_t uFlags);
379	extern int GstCntlSessionThreadTerminate(PVBOXSERVICECTRLSESSIONTHREAD pSession);
380	extern RTEXITCODE VBoxServiceControlSessionForkInit(int argc, char **argv);
381
382	/* asdf */
383	extern PVBOXSERVICECTRLPROCESS GstCntlSessionAcquireProcess(PVBOXSERVICECTRLSESSION pSession, uint32_t uPID);
384	extern int GstCntlSessionClose(PVBOXSERVICECTRLSESSION pSession);
385	extern int GstCntlSessionDestroy(PVBOXSERVICECTRLSESSION pSession);
386	extern int GstCntlSessionInit(PVBOXSERVICECTRLSESSION pSession, uint32_t uFlags);
387	extern int GstCntlSessionHandler(PVBOXSERVICECTRLSESSION pSession, uint32_t uMsg, PVBGLR3GUESTCTRLHOSTCTX pHostCtx, void pvScratchBuf, size_t cbScratchBuf, volatile bool pfShutdown);
388	extern int GstCntlSessionListSet(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pThread, VBOXSERVICECTRLTHREADLISTTYPE enmList);
389	extern int GstCntlSessionProcessStartAllowed(const PVBOXSERVICECTRLSESSION pSession, bool *pbAllowed);
390	extern int GstCntlSessionReapProcesses(PVBOXSERVICECTRLSESSION pSession);
391	/* Per-thread guest process functions. */
392	extern int GstCntlProcessPerform(PVBOXSERVICECTRLPROCESS pProcess, PVBOXSERVICECTRLREQUEST pRequest);
393	extern int GstCntlProcessStart(const PVBOXSERVICECTRLSESSION pSession, const PVBOXSERVICECTRLPROCSTARTUPINFO pStartupInfo, uint32_t uContext);
394	extern int GstCntlProcessStop(const PVBOXSERVICECTRLPROCESS pThread);
395	extern void GstCntlProcessRelease(const PVBOXSERVICECTRLPROCESS pThread);
396	extern int GstCntlProcessWait(const PVBOXSERVICECTRLPROCESS pThread, RTMSINTERVAL msTimeout, int *prc);
397	extern int GstCntlProcessFree(PVBOXSERVICECTRLPROCESS pThread);
398	/* Process request handling. */
399	extern int GstCntlProcessRequestAlloc(PVBOXSERVICECTRLREQUEST *ppReq, VBOXSERVICECTRLREQUESTTYPE enmType);
400	extern int GstCntlProcessRequestAllocEx(PVBOXSERVICECTRLREQUEST ppReq, VBOXSERVICECTRLREQUESTTYPE enmType, void pvData, size_t cbData, uint32_t uCID);
401	extern void GstCntlProcessRequestFree(PVBOXSERVICECTRLREQUEST pReq);
402	/* Per-session functions. */
403	extern int gstcntlHandleFileOpen(uint32_t idClient, uint32_t cParms);
404	extern int gstcntlHandleFileClose(uint32_t idClient, uint32_t cParms);
405	extern int gstcntlHandleFileRead(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
406	extern int gstcntlHandleFileReadAt(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
407	extern int gstcntlHandleFileWrite(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
408	extern int gstcntlHandleFileWriteAt(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
409	extern int gstcntlHandleFileSeek(uint32_t idClient, uint32_t cParms);
410	extern int gstcntlHandleFileTell(uint32_t idClient, uint32_t cParms);
411	extern int GstCntlSessionHandleProcExec(const PVBOXSERVICECTRLSESSION pSession, PVBGLR3GUESTCTRLHOSTCTX pHostCtx);
412	extern int GstCntlSessionHandleProcInput(const PVBOXSERVICECTRLSESSION pSession, PVBGLR3GUESTCTRLHOSTCTX pHostCtx, void *pvScratchBuf, size_t cbScratchBuf);
413	extern int GstCntlSessionHandleProcOutput(const PVBOXSERVICECTRLSESSION pSession, PVBGLR3GUESTCTRLHOSTCTX pHostCtx);
414	extern int GstCntlSessionHandleProcTerminate(const PVBOXSERVICECTRLSESSION pSession, PVBGLR3GUESTCTRLHOSTCTX pHostCtx);
415	extern int GstCntlSessionHandleProcWaitFor(const PVBOXSERVICECTRLSESSION pSession, PVBGLR3GUESTCTRLHOSTCTX pHostCtx);
416
417	RT_C_DECLS_END
418
419	#endif /* ___VBoxServiceControl_h */
420

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

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

Download in other formats: