VBoxServiceInternal.h@ 42469

Last change on this file since 42469 was 40682, checked in by vboxsync, 13 years ago
VBoxService/GuestCtrl: Bugfixes.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.1 KB

Line
1	/* $Id: VBoxServiceInternal.h 40682 2012-03-28 14:36:01Z vboxsync $ */
2	/** @file
3	* VBoxService - Guest Additions Services.
4	*/
5
6	/*
7	* Copyright (C) 2007-2012 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 ___VBoxServiceInternal_h
19	#define ___VBoxServiceInternal_h
20
21	#include <stdio.h>
22	#ifdef RT_OS_WINDOWS
23	# include <Windows.h>
24	# include <process.h> /* Needed for file version information. */
25	#endif
26
27	#include <iprt/list.h>
28	#include <iprt/critsect.h>
29
30	#include <VBox/VBoxGuestLib.h>
31	#include <VBox/HostServices/GuestControlSvc.h>
32
33	/**
34	* A service descriptor.
35	*/
36	typedef struct
37	{
38	/** The short service name. */
39	const char *pszName;
40	/** The longer service name. */
41	const char *pszDescription;
42	/** The usage options stuff for the --help screen. */
43	const char *pszUsage;
44	/** The option descriptions for the --help screen. */
45	const char *pszOptions;
46
47	/**
48	* Called before parsing arguments.
49	* @returns VBox status code.
50	*/
51	DECLCALLBACKMEMBER(int, pfnPreInit)(void);
52
53	/**
54	* Tries to parse the given command line option.
55	*
56	* @returns 0 if we parsed, -1 if it didn't and anything else means exit.
57	* @param ppszShort If not NULL it points to the short option iterator. a short argument.
58	* If NULL examine argv[*pi].
59	* @param argc The argument count.
60	* @param argv The argument vector.
61	* @param pi The argument vector index. Update if any value(s) are eaten.
62	*/
63	DECLCALLBACKMEMBER(int, pfnOption)(const char ppszShort, int argc, char argv, int *pi);
64
65	/**
66	* Called before parsing arguments.
67	* @returns VBox status code.
68	*/
69	DECLCALLBACKMEMBER(int, pfnInit)(void);
70
71	/** Called from the worker thread.
72	*
73	* @returns VBox status code.
74	* @retval VINF_SUCCESS if exitting because *pfTerminate was set.
75	* @param pfTerminate Pointer to a per service termination flag to check
76	* before and after blocking.
77	*/
78	DECLCALLBACKMEMBER(int, pfnWorker)(bool volatile *pfTerminate);
79
80	/**
81	* Stop an service.
82	*/
83	DECLCALLBACKMEMBER(void, pfnStop)(void);
84
85	/**
86	* Does termination cleanups.
87	*
88	* @remarks This may be called even if pfnInit hasn't been called!
89	*/
90	DECLCALLBACKMEMBER(void, pfnTerm)(void);
91	} VBOXSERVICE;
92	/** Pointer to a VBOXSERVICE. */
93	typedef VBOXSERVICE *PVBOXSERVICE;
94	/** Pointer to a const VBOXSERVICE. */
95	typedef VBOXSERVICE const *PCVBOXSERVICE;
96
97	/** The service name.
98	* @note Used on windows to name the service as well as the global mutex. */
99	#define VBOXSERVICE_NAME "VBoxService"
100
101	#ifdef RT_OS_WINDOWS
102	/** The friendly service name. */
103	# define VBOXSERVICE_FRIENDLY_NAME "VirtualBox Guest Additions Service"
104	/** The service description (only W2K+ atm) */
105	# define VBOXSERVICE_DESCRIPTION "Manages VM runtime information, time synchronization, guest control execution and miscellaneous utilities for guest operating systems."
106	/** The following constant may be defined by including NtStatus.h. */
107	# define STATUS_SUCCESS ((NTSTATUS)0x00000000L)
108	#endif /* RT_OS_WINDOWS */
109
110	#ifdef VBOX_WITH_GUEST_CONTROL
111	/**
112	* Pipe IDs for handling the guest process poll set.
113	*/
114	typedef enum VBOXSERVICECTRLPIPEID
115	{
116	VBOXSERVICECTRLPIPEID_UNKNOWN = 0,
117	VBOXSERVICECTRLPIPEID_STDIN = 10,
118	VBOXSERVICECTRLPIPEID_STDIN_WRITABLE = 11,
119	/** Pipe for reading from guest process' stdout. */
120	VBOXSERVICECTRLPIPEID_STDOUT = 40,
121	/** Pipe for reading from guest process' stderr. */
122	VBOXSERVICECTRLPIPEID_STDERR = 50,
123	/** Notification pipe for waking up the guest process
124	* control thread. */
125	VBOXSERVICECTRLPIPEID_IPC_NOTIFY = 100
126	} VBOXSERVICECTRLPIPEID;
127
128	/**
129	* Request types to perform on a started guest process.
130	*/
131	typedef enum VBOXSERVICECTRLREQUESTTYPE
132	{
133	/** Unknown request. */
134	VBOXSERVICECTRLREQUEST_UNKNOWN = 0,
135	/** Main control thread asked used to quit. */
136	VBOXSERVICECTRLREQUEST_QUIT = 1,
137	/** Performs reading from stdout. */
138	VBOXSERVICECTRLREQUEST_STDOUT_READ = 50,
139	/** Performs reading from stderr. */
140	VBOXSERVICECTRLREQUEST_STDERR_READ = 60,
141	/** Performs writing to stdin. */
142	VBOXSERVICECTRLREQUEST_STDIN_WRITE = 70,
143	/** Same as VBOXSERVICECTRLREQUEST_STDIN_WRITE, but
144	* marks the end of input. */
145	VBOXSERVICECTRLREQUEST_STDIN_WRITE_EOF = 71,
146	/** Kill/terminate process.
147	* @todo Implement this! */
148	VBOXSERVICECTRLREQUEST_KILL = 90,
149	/** Gently ask process to terminate.
150	* @todo Implement this! */
151	VBOXSERVICECTRLREQUEST_HANGUP = 91,
152	/** Ask the process in which status it
153	* currently is.
154	* @todo Implement this! */
155	VBOXSERVICECTRLREQUEST_STATUS = 100
156	} VBOXSERVICECTRLREQUESTTYPE;
157
158	/**
159	* Thread list types.
160	*/
161	typedef enum VBOXSERVICECTRLTHREADLISTTYPE
162	{
163	/** Unknown list -- uncool to use. */
164	VBOXSERVICECTRLTHREADLIST_UNKNOWN = 0,
165	/** Stopped list: Here all guest threads end up
166	* when they reached the stopped state and can
167	* be shut down / free'd safely. */
168	VBOXSERVICECTRLTHREADLIST_STOPPED = 1,
169	/**
170	* Started list: Here all threads are registered
171	* when they're up and running (that is, accepting
172	* commands).
173	*/
174	VBOXSERVICECTRLTHREADLIST_RUNNING = 2
175	} VBOXSERVICECTRLTHREADLISTTYPE;
176
177	/**
178	* Structure to perform a request on a started guest
179	* process. Needed for letting the main guest control thread
180	* to communicate (and wait) for a certain operation which
181	* will be done in context of the started guest process thread.
182	*/
183	typedef struct VBOXSERVICECTRLREQUEST
184	{
185	/** Event semaphore to serialize access. */
186	RTSEMEVENTMULTI Event;
187	/** The request type to handle. */
188	VBOXSERVICECTRLREQUESTTYPE enmType;
189	/** Payload size; on input, this contains the (maximum) amount
190	* of data the caller wants to write or to read. On output,
191	* this show the actual amount of data read/written. */
192	size_t cbData;
193	/** Payload data; a pre-allocated data buffer for input/output. */
194	void *pvData;
195	/** The context ID which is required to complete the
196	* request. Not used at the moment. */
197	uint32_t uCID;
198	/** The overall result of the operation. */
199	int rc;
200	} VBOXSERVICECTRLREQUEST;
201	/** Pointer to request. */
202	typedef VBOXSERVICECTRLREQUEST *PVBOXSERVICECTRLREQUEST;
203
204	/**
205	* Structure holding information for starting a guest
206	* process.
207	*/
208	typedef struct VBOXSERVICECTRLPROCESS
209	{
210	/** Full qualified path of process to start (without arguments). */
211	char szCmd[GUESTPROCESS_MAX_CMD_LEN];
212	/** Process execution flags. @sa */
213	uint32_t uFlags;
214	/** Command line arguments. */
215	char szArgs[GUESTPROCESS_MAX_ARGS_LEN];
216	/** Number of arguments specified in pszArgs. */
217	uint32_t uNumArgs;
218	/** String of environment variables ("FOO=BAR") to pass to the process
219	* to start. */
220	char szEnv[GUESTPROCESS_MAX_ENV_LEN];
221	/** Size (in bytes) of environment variables block. */
222	uint32_t cbEnv;
223	/** Number of environment variables specified in pszEnv. */
224	uint32_t uNumEnvVars;
225	/** User name (account) to start the process under. */
226	char szUser[GUESTPROCESS_MAX_USER_LEN];
227	/** Password of specified user name (account). */
228	char szPassword[GUESTPROCESS_MAX_PASSWORD_LEN];
229	/** Time limit (in ms) of the process' life time. */
230	uint32_t uTimeLimitMS;
231	} VBOXSERVICECTRLPROCESS;
232	/** Pointer to a guest process block. */
233	typedef VBOXSERVICECTRLPROCESS *PVBOXSERVICECTRLPROCESS;
234
235	/**
236	* Structure for holding data for one (started) guest process.
237	*/
238	typedef struct VBOXSERVICECTRLTHREAD
239	{
240	/** Pointer to list archor of following
241	* list node.
242	* @todo Would be nice to have a RTListGetAnchor(). */
243	PRTLISTANCHOR pAnchor;
244	/** Node. */
245	RTLISTNODE Node;
246	/** The worker thread. */
247	RTTHREAD Thread;
248	/** Shutdown indicator; will be set when the thread
249	* needs (or is asked) to shutdown. */
250	bool volatile fShutdown;
251	/** Indicator set by the service thread exiting. */
252	bool volatile fStopped;
253	/** Whether the service was started or not. */
254	bool fStarted;
255	/** Client ID. */
256	uint32_t uClientID;
257	/** Context ID. */
258	uint32_t uContextID;
259	/** Critical section for thread-safe use. */
260	RTCRITSECT CritSect;
261
262	/** @todo Document me! */
263	uint32_t uPID;
264	char *pszCmd;
265	uint32_t uFlags;
266	char **papszArgs;
267	uint32_t uNumArgs;
268	char **papszEnv;
269	uint32_t uNumEnvVars;
270	/** Name of specified user account to run the
271	* guest process under. */
272	char *pszUser;
273	/** Password of specified user account. */
274	char *pszPassword;
275	/** Overall time limit (in ms) that the guest process
276	* is allowed to run. 0 for indefinite time. */
277	uint32_t uTimeLimitMS;
278	/** Pointer to the current IPC request being
279	* processed. */
280	PVBOXSERVICECTRLREQUEST pRequest;
281	/** StdIn pipe for addressing writes to the
282	* guest process' stdin.*/
283	RTPIPE pipeStdInW;
284	/** The notification pipe associated with this guest process.
285	* This is NIL_RTPIPE for output pipes. */
286	RTPIPE hNotificationPipeW;
287	/** The other end of hNotificationPipeW. */
288	RTPIPE hNotificationPipeR;
289	} VBOXSERVICECTRLTHREAD;
290	/** Pointer to thread data. */
291	typedef VBOXSERVICECTRLTHREAD *PVBOXSERVICECTRLTHREAD;
292	#endif /* VBOX_WITH_GUEST_CONTROL */
293	#ifdef VBOX_WITH_GUEST_PROPS
294
295	/**
296	* A guest property cache.
297	*/
298	typedef struct VBOXSERVICEVEPROPCACHE
299	{
300	/** The client ID for HGCM communication. */
301	uint32_t uClientID;
302	/** Head in a list of VBOXSERVICEVEPROPCACHEENTRY nodes. */
303	RTLISTANCHOR NodeHead;
304	/** Critical section for thread-safe use. */
305	RTCRITSECT CritSect;
306	} VBOXSERVICEVEPROPCACHE;
307	/** Pointer to a guest property cache. */
308	typedef VBOXSERVICEVEPROPCACHE *PVBOXSERVICEVEPROPCACHE;
309
310	/**
311	* An entry in the property cache (VBOXSERVICEVEPROPCACHE).
312	*/
313	typedef struct VBOXSERVICEVEPROPCACHEENTRY
314	{
315	/** Node to successor.
316	* @todo r=bird: This is not really the node to the successor, but
317	* rather the OUR node in the list. If it helps, remember that
318	* its a doubly linked list. */
319	RTLISTNODE NodeSucc;
320	/** Name (and full path) of guest property. */
321	char *pszName;
322	/** The last value stored (for reference). */
323	char *pszValue;
324	/** Reset value to write if property is temporary. If NULL, it will be
325	* deleted. */
326	char *pszValueReset;
327	/** Flags. */
328	uint32_t fFlags;
329	} VBOXSERVICEVEPROPCACHEENTRY;
330	/** Pointer to a cached guest property. */
331	typedef VBOXSERVICEVEPROPCACHEENTRY *PVBOXSERVICEVEPROPCACHEENTRY;
332
333	#endif /* VBOX_WITH_GUEST_PROPS */
334
335	RT_C_DECLS_BEGIN
336
337	extern char *g_pszProgName;
338	extern int g_cVerbosity;
339	extern uint32_t g_DefaultInterval;
340	extern VBOXSERVICE g_TimeSync;
341	extern VBOXSERVICE g_Clipboard;
342	extern VBOXSERVICE g_Control;
343	extern VBOXSERVICE g_VMInfo;
344	extern VBOXSERVICE g_CpuHotPlug;
345	#ifdef VBOXSERVICE_MANAGEMENT
346	extern VBOXSERVICE g_MemBalloon;
347	extern VBOXSERVICE g_VMStatistics;
348	#endif
349	#ifdef VBOX_WITH_PAGE_SHARING
350	extern VBOXSERVICE g_PageSharing;
351	#endif
352	#ifdef VBOX_WITH_SHARED_FOLDERS
353	extern VBOXSERVICE g_AutoMount;
354	#endif
355	#ifdef DEBUG
356	extern RTCRITSECT g_csLog; /* For guest process stdout dumping. */
357	#endif
358
359	extern RTEXITCODE VBoxServiceSyntax(const char *pszFormat, ...);
360	extern RTEXITCODE VBoxServiceError(const char *pszFormat, ...);
361	extern void VBoxServiceVerbose(int iLevel, const char *pszFormat, ...);
362	extern int VBoxServiceArgUInt32(int argc, char *argv, const char psz, int pi, uint32_t pu32,
363	uint32_t u32Min, uint32_t u32Max);
364	extern int VBoxServiceStartServices(void);
365	extern int VBoxServiceStopServices(void);
366	extern void VBoxServiceMainWait(void);
367	extern int VBoxServiceReportStatus(VBoxGuestFacilityStatus enmStatus);
368	#ifdef RT_OS_WINDOWS
369	extern RTEXITCODE VBoxServiceWinInstall(void);
370	extern RTEXITCODE VBoxServiceWinUninstall(void);
371	extern RTEXITCODE VBoxServiceWinEnterCtrlDispatcher(void);
372	extern void VBoxServiceWinSetStopPendingStatus(uint32_t uCheckPoint);
373	#endif
374
375	#ifdef VBOXSERVICE_TOOLBOX
376	extern bool VBoxServiceToolboxMain(int argc, char *argv, RTEXITCODE prcExit);
377	#endif
378
379	#ifdef RT_OS_WINDOWS
380	# ifdef VBOX_WITH_GUEST_PROPS
381	extern int VBoxServiceVMInfoWinWriteUsers(char *ppszUserList, uint32_t pcUsersInList);
382	extern int VBoxServiceWinGetComponentVersions(uint32_t uiClientID);
383	# endif /* VBOX_WITH_GUEST_PROPS */
384	#endif /* RT_OS_WINDOWS */
385
386	#ifdef VBOX_WITH_GUEST_CONTROL
387	/* Guest control main thread functions. */
388	extern int VBoxServiceControlAssignPID(PVBOXSERVICECTRLTHREAD pThread, uint32_t uPID);
389	extern int VBoxServiceControlListSet(VBOXSERVICECTRLTHREADLISTTYPE enmList,
390	PVBOXSERVICECTRLTHREAD pThread);
391	extern PVBOXSERVICECTRLTHREAD VBoxServiceControlLockThread(uint32_t uPID);
392	extern void VBoxServiceControlUnlockThread(const PVBOXSERVICECTRLTHREAD pThread);
393	extern int VBoxServiceControlSetInactive(PVBOXSERVICECTRLTHREAD pThread);
394	/* Per-thread guest process functions. */
395	extern int VBoxServiceControlThreadStart(uint32_t uContext,
396	PVBOXSERVICECTRLPROCESS pProcess);
397	extern int VBoxServiceControlThreadPerform(uint32_t uPID, PVBOXSERVICECTRLREQUEST pRequest);
398	extern int VBoxServiceControlThreadStop(const PVBOXSERVICECTRLTHREAD pThread);
399	extern int VBoxServiceControlThreadWait(const PVBOXSERVICECTRLTHREAD pThread,
400	RTMSINTERVAL msTimeout, int *prc);
401	extern int VBoxServiceControlThreadFree(PVBOXSERVICECTRLTHREAD pThread);
402	/* Request handling. */
403	extern int VBoxServiceControlThreadRequestAlloc(PVBOXSERVICECTRLREQUEST *ppReq,
404	VBOXSERVICECTRLREQUESTTYPE enmType);
405	extern int VBoxServiceControlThreadRequestAllocEx(PVBOXSERVICECTRLREQUEST *ppReq,
406	VBOXSERVICECTRLREQUESTTYPE enmType,
407	void* pbData,
408	size_t cbData,
409	uint32_t uCID);
410	extern void VBoxServiceControlThreadRequestFree(PVBOXSERVICECTRLREQUEST pReq);
411	#endif /* VBOX_WITH_GUEST_CONTROL */
412
413	#ifdef VBOXSERVICE_MANAGEMENT
414	extern uint32_t VBoxServiceBalloonQueryPages(uint32_t cbPage);
415	#endif
416	#if defined(VBOX_WITH_PAGE_SHARING) && defined(RT_OS_WINDOWS)
417	extern RTEXITCODE VBoxServicePageSharingInitFork(void);
418	#endif
419	extern int VBoxServiceVMInfoSignal(void);
420
421	RT_C_DECLS_END
422
423	#endif
424

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

source: vbox/trunk/src/VBox/Additions/common/VBoxService/VBoxServiceInternal.h@ 42469

Download in other formats: