VBoxServiceControl.h@ 44869

Last change on this file since 44869 was 44869, checked in by vboxsync, 12 years ago
Build fix.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 14.4 KB

Line
1	/* $Id: VBoxServiceControl.h 44869 2013-02-28 15:42:02Z 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 holding information for starting a guest
128	* process.
129	*/
130	typedef struct VBOXSERVICECTRLPROCSTARTUPINFO
131	{
132	/** Full qualified path of process to start (without arguments). */
133	char szCmd[GUESTPROCESS_MAX_CMD_LEN];
134	/** Process execution flags. @sa */
135	uint32_t uFlags;
136	/** Command line arguments. */
137	char szArgs[GUESTPROCESS_MAX_ARGS_LEN];
138	/** Number of arguments specified in pszArgs. */
139	uint32_t uNumArgs;
140	/** String of environment variables ("FOO=BAR") to pass to the process
141	* to start. */
142	char szEnv[GUESTPROCESS_MAX_ENV_LEN];
143	/** Size (in bytes) of environment variables block. */
144	uint32_t cbEnv;
145	/** Number of environment variables specified in pszEnv. */
146	uint32_t uNumEnvVars;
147	/** User name (account) to start the process under. */
148	char szUser[GUESTPROCESS_MAX_USER_LEN];
149	/** Password of specified user name (account). */
150	char szPassword[GUESTPROCESS_MAX_PASSWORD_LEN];
151	/** Time limit (in ms) of the process' life time. */
152	uint32_t uTimeLimitMS;
153	/** Process priority. */
154	uint32_t uPriority;
155	/** Process affinity. At the moment we support
156	* up to 4 * 64 = 256 CPUs. */
157	uint64_t uAffinity[4];
158	/** Number of used process affinity blocks. */
159	uint32_t uNumAffinity;
160	} VBOXSERVICECTRLPROCSTARTUPINFO;
161	/** Pointer to a guest process block. */
162	typedef VBOXSERVICECTRLPROCSTARTUPINFO *PVBOXSERVICECTRLPROCESS;
163
164	/**
165	* Structure for holding data for one (started) guest process.
166	*/
167	typedef struct VBOXSERVICECTRLTHREAD
168	{
169	/** Pointer to list archor of following
170	* list node.
171	* @todo Would be nice to have a RTListGetAnchor(). */
172	PRTLISTANCHOR pAnchor;
173	/** Node. */
174	RTLISTNODE Node;
175	/** The worker thread. */
176	RTTHREAD Thread;
177	/** Shutdown indicator; will be set when the thread
178	* needs (or is asked) to shutdown. */
179	bool volatile fShutdown;
180	/** Indicator set by the service thread exiting. */
181	bool volatile fStopped;
182	/** Whether the service was started or not. */
183	bool fStarted;
184	/** Client ID. */
185	uint32_t uClientID;
186	/** Context ID. */
187	uint32_t uContextID;
188	/** Critical section for thread-safe use. */
189	RTCRITSECT CritSect;
190	/** @todo Document me! */
191	uint32_t uPID;
192	char *pszCmd;
193	uint32_t uFlags;
194	char **papszArgs;
195	uint32_t uNumArgs;
196	char **papszEnv;
197	uint32_t uNumEnvVars;
198	/** Name of specified user account to run the
199	* guest process under. */
200	char *pszUser;
201	/** Password of specified user account. */
202	char *pszPassword;
203	/** Overall time limit (in ms) that the guest process
204	* is allowed to run. 0 for indefinite time. */
205	uint32_t uTimeLimitMS;
206	/** Pointer to the current IPC request being
207	* processed. */
208	PVBOXSERVICECTRLREQUEST pRequest;
209	/** StdIn pipe for addressing writes to the
210	* guest process' stdin.*/
211	RTPIPE pipeStdInW;
212	/** The notification pipe associated with this guest process.
213	* This is NIL_RTPIPE for output pipes. */
214	RTPIPE hNotificationPipeW;
215	/** The other end of hNotificationPipeW. */
216	RTPIPE hNotificationPipeR;
217	} VBOXSERVICECTRLTHREAD;
218	/** Pointer to thread data. */
219	typedef VBOXSERVICECTRLTHREAD *PVBOXSERVICECTRLTHREAD;
220
221	/**
222	* Structure for one (opened) guest file.
223	*/
224	typedef struct VBOXSERVICECTRLFILE
225	{
226	/** Pointer to list archor of following
227	* list node.
228	* @todo Would be nice to have a RTListGetAnchor(). */
229	PRTLISTANCHOR pAnchor;
230	/** Node to global guest control file list. */
231	/** @todo Use a map later? */
232	RTLISTNODE Node;
233	/** The file name. */
234	char szName[RTPATH_MAX];
235	/** The file handle on the guest. */
236	RTFILE hFile;
237	/** File handle to identify this file. */
238	uint32_t uHandle;
239	/** Context ID. */
240	uint32_t uContextID;
241	} VBOXSERVICECTRLFILE;
242	/** Pointer to thread data. */
243	typedef VBOXSERVICECTRLFILE *PVBOXSERVICECTRLFILE;
244
245	typedef struct VBOXSERVICECTRLSESSIONSTARTUPINFO
246	{
247	/** The session's protocol version to use. */
248	uint32_t uProtocol;
249	/** The session's ID. */
250	uint32_t uSessionID;
251	/** User name (account) to start the guest session under. */
252	char szUser[GUESTPROCESS_MAX_USER_LEN];
253	/** Password of specified user name (account). */
254	char szPassword[GUESTPROCESS_MAX_PASSWORD_LEN];
255	/** Domain of the user account. */
256	char szDomain[GUESTPROCESS_MAX_DOMAIN_LEN];
257	/** Session creation flags. */
258	uint32_t uFlags;
259	} VBOXSERVICECTRLSESSIONSTARTUPINFO;
260	/** Pointer to thread data. */
261	typedef VBOXSERVICECTRLSESSIONSTARTUPINFO *PVBOXSERVICECTRLSESSIONSTARTUPINFO;
262
263	/**
264	* Structure for one (opened) guest session.
265	*/
266	typedef struct VBOXSERVICECTRLSESSION
267	{
268	/** Node to global guest control session list. */
269	/** @todo Use a map later? */
270	RTLISTNODE Node;
271	/** The sessions's startup info. */
272	VBOXSERVICECTRLSESSIONSTARTUPINFO
273	StartupInfo;
274	/** The worker thread. */
275	RTTHREAD Thread;
276	/** Critical section for thread-safe use. */
277	RTCRITSECT CritSect;
278	/** Process handle for forked child. */
279	RTPROCESS hProcess;
280	/** Pollset containing all the pipes. */
281	RTPOLLSET hPollSet;
282	RTPIPE hStdInW;
283	RTPIPE hStdOutR;
284	RTPIPE hStdErrR;
285	struct StdPipe
286	{
287	RTHANDLE hChild;
288	PRTHANDLE phChild;
289	} StdIn,
290	StdOut,
291	StdErr;
292	/** The notification pipe associated with this guest session.
293	* This is NIL_RTPIPE for output pipes. */
294	RTPIPE hNotificationPipeW;
295	/** The other end of hNotificationPipeW. */
296	RTPIPE hNotificationPipeR;
297	} VBOXSERVICECTRLSESSION;
298	/** Pointer to thread data. */
299	typedef VBOXSERVICECTRLSESSION *PVBOXSERVICECTRLSESSION;
300
301	RT_C_DECLS_BEGIN
302
303	/**
304	* Note on naming conventions:
305	* - VBoxServiceControl* is named everything sub service module related, e.g.
306	* everything which is callable by main() and/or the service dispatcher(s).
307	* - GstCntl* is named everything which declared extern and thus can be called
308	* by different guest control modules as needed.
309	* - gstcntl (all lowercase) is a purely static function to split up functionality
310	* inside a module.
311	*/
312
313	/* Guest session handling. */
314	extern int GstCntlSessionOpen(const PVBOXSERVICECTRLSESSIONSTARTUPINFO pSessionStartupInfo, PRTLISTNODE pNode);
315	extern int GstCntlSessionClose(PVBOXSERVICECTRLSESSION pSession, uint32_t uFlags);
316	extern RTEXITCODE VBoxServiceControlSessionForkInit(int argc, char **argv);
317
318	/* Guest control main thread functions. */
319	extern int GstCntlAssignPID(PVBOXSERVICECTRLTHREAD pThread, uint32_t uPID);
320	extern int GstCntlListSet(VBOXSERVICECTRLTHREADLISTTYPE enmList, PVBOXSERVICECTRLTHREAD pThread);
321	extern PVBOXSERVICECTRLTHREAD GstCntlLockThread(uint32_t uPID);
322	extern void GstCntlUnlockThread(const PVBOXSERVICECTRLTHREAD pThread);
323	extern int GstCntlSetInactive(PVBOXSERVICECTRLTHREAD pThread);
324	/* Per-thread guest process functions. */
325	extern int GstcntlProcessSetupPipe(const char pszHowTo, int fd, PRTHANDLE ph, PRTHANDLE pph, PRTPIPE phPipe);
326	extern int GstCntlProcessStart(uint32_t uContext, PVBOXSERVICECTRLPROCESS pProcess);
327	extern int GstCntlProcessPerform(uint32_t uPID, PVBOXSERVICECTRLREQUEST pRequest);
328	extern int GstCntlProcessStop(const PVBOXSERVICECTRLTHREAD pThread);
329	extern int GstCntlProcessWait(const PVBOXSERVICECTRLTHREAD pThread, RTMSINTERVAL msTimeout, int *prc);
330	extern int GstCntlProcessFree(PVBOXSERVICECTRLTHREAD pThread);
331	/* Request handling. */
332	extern int GstCntlProcessRequestAlloc(PVBOXSERVICECTRLREQUEST *ppReq, VBOXSERVICECTRLREQUESTTYPE enmType);
333	extern int GstCntlProcessRequestAllocEx(PVBOXSERVICECTRLREQUEST ppReq, VBOXSERVICECTRLREQUESTTYPE enmType, void pvData, size_t cbData, uint32_t uCID);
334	extern void GstCntlProcessRequestFree(PVBOXSERVICECTRLREQUEST pReq);
335	/******************************************************************************
336	* Guest file command handling. *
337	*****************************************************************************/
338	extern int gstcntlHandleFileOpen(uint32_t idClient, uint32_t cParms);
339	extern int gstcntlHandleFileClose(uint32_t idClient, uint32_t cParms);
340	extern int gstcntlHandleFileRead(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
341	extern int gstcntlHandleFileReadAt(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
342	extern int gstcntlHandleFileWrite(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
343	extern int gstcntlHandleFileWriteAt(uint32_t idClient, uint32_t cParms, void *pvScratchBuf, size_t cbScratchBuf);
344	extern int gstcntlHandleFileSeek(uint32_t idClient, uint32_t cParms);
345	extern int gstcntlHandleFileTell(uint32_t idClient, uint32_t cParms);
346
347	RT_C_DECLS_END
348
349	#endif /* ___VBoxServiceControl_h */
350

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

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

Download in other formats: