VBoxServiceControl.h@ 60622

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

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

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

Download in other formats: