VBoxServiceInternal.h@ 44098

Last change on this file since 44098 was 44046, checked in by vboxsync, 12 years ago
VBoxServiceControlThreadRequestAllocEx: Corrected parameter name and drop unnecessary cast. Looks like someone changed pbData to void * and didn't bother cleaning up.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.9 KB

Line
1	/* $Id: VBoxServiceInternal.h 44046 2012-12-06 08:20:58Z 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	/** @todo Document me! */
262	uint32_t uPID;
263	char *pszCmd;
264	uint32_t uFlags;
265	char **papszArgs;
266	uint32_t uNumArgs;
267	char **papszEnv;
268	uint32_t uNumEnvVars;
269	/** Name of specified user account to run the
270	* guest process under. */
271	char *pszUser;
272	/** Password of specified user account. */
273	char *pszPassword;
274	/** Overall time limit (in ms) that the guest process
275	* is allowed to run. 0 for indefinite time. */
276	uint32_t uTimeLimitMS;
277	/** Pointer to the current IPC request being
278	* processed. */
279	PVBOXSERVICECTRLREQUEST pRequest;
280	/** StdIn pipe for addressing writes to the
281	* guest process' stdin.*/
282	RTPIPE pipeStdInW;
283	/** The notification pipe associated with this guest process.
284	* This is NIL_RTPIPE for output pipes. */
285	RTPIPE hNotificationPipeW;
286	/** The other end of hNotificationPipeW. */
287	RTPIPE hNotificationPipeR;
288	} VBOXSERVICECTRLTHREAD;
289	/** Pointer to thread data. */
290	typedef VBOXSERVICECTRLTHREAD *PVBOXSERVICECTRLTHREAD;
291
292	/**
293	* Structure for one (opened) guest file.
294	*/
295	typedef struct VBOXSERVICECTRLFILE
296	{
297	/** Pointer to list archor of following
298	* list node.
299	* @todo Would be nice to have a RTListGetAnchor(). */
300	PRTLISTANCHOR pAnchor;
301	/** Node. */
302	RTLISTNODE Node;
303	/** The file name. */
304	char szName[RTPATH_MAX];
305	/** The file handle on the guest. */
306	RTFILE hFile;
307	/** File handle to identify this file. */
308	uint32_t uHandle;
309	/** Context ID. */
310	uint32_t uContextID;
311	} VBOXSERVICECTRLFILE;
312	/** Pointer to thread data. */
313	typedef VBOXSERVICECTRLFILE *PVBOXSERVICECTRLFILE;
314	#endif /* VBOX_WITH_GUEST_CONTROL */
315	#ifdef VBOX_WITH_GUEST_PROPS
316
317	/**
318	* A guest property cache.
319	*/
320	typedef struct VBOXSERVICEVEPROPCACHE
321	{
322	/** The client ID for HGCM communication. */
323	uint32_t uClientID;
324	/** Head in a list of VBOXSERVICEVEPROPCACHEENTRY nodes. */
325	RTLISTANCHOR NodeHead;
326	/** Critical section for thread-safe use. */
327	RTCRITSECT CritSect;
328	} VBOXSERVICEVEPROPCACHE;
329	/** Pointer to a guest property cache. */
330	typedef VBOXSERVICEVEPROPCACHE *PVBOXSERVICEVEPROPCACHE;
331
332	/**
333	* An entry in the property cache (VBOXSERVICEVEPROPCACHE).
334	*/
335	typedef struct VBOXSERVICEVEPROPCACHEENTRY
336	{
337	/** Node to successor.
338	* @todo r=bird: This is not really the node to the successor, but
339	* rather the OUR node in the list. If it helps, remember that
340	* its a doubly linked list. */
341	RTLISTNODE NodeSucc;
342	/** Name (and full path) of guest property. */
343	char *pszName;
344	/** The last value stored (for reference). */
345	char *pszValue;
346	/** Reset value to write if property is temporary. If NULL, it will be
347	* deleted. */
348	char *pszValueReset;
349	/** Flags. */
350	uint32_t fFlags;
351	} VBOXSERVICEVEPROPCACHEENTRY;
352	/** Pointer to a cached guest property. */
353	typedef VBOXSERVICEVEPROPCACHEENTRY *PVBOXSERVICEVEPROPCACHEENTRY;
354
355	#endif /* VBOX_WITH_GUEST_PROPS */
356
357	RT_C_DECLS_BEGIN
358
359	extern char *g_pszProgName;
360	extern int g_cVerbosity;
361	extern uint32_t g_DefaultInterval;
362	extern VBOXSERVICE g_TimeSync;
363	extern VBOXSERVICE g_Clipboard;
364	extern VBOXSERVICE g_Control;
365	extern VBOXSERVICE g_VMInfo;
366	extern VBOXSERVICE g_CpuHotPlug;
367	#ifdef VBOXSERVICE_MANAGEMENT
368	extern VBOXSERVICE g_MemBalloon;
369	extern VBOXSERVICE g_VMStatistics;
370	#endif
371	#ifdef VBOX_WITH_PAGE_SHARING
372	extern VBOXSERVICE g_PageSharing;
373	#endif
374	#ifdef VBOX_WITH_SHARED_FOLDERS
375	extern VBOXSERVICE g_AutoMount;
376	#endif
377	#ifdef DEBUG
378	extern RTCRITSECT g_csLog; /* For guest process stdout dumping. */
379	#endif
380
381	extern RTEXITCODE VBoxServiceSyntax(const char *pszFormat, ...);
382	extern RTEXITCODE VBoxServiceError(const char *pszFormat, ...);
383	extern void VBoxServiceVerbose(int iLevel, const char *pszFormat, ...);
384	extern int VBoxServiceArgUInt32(int argc, char *argv, const char psz, int pi, uint32_t pu32,
385	uint32_t u32Min, uint32_t u32Max);
386	extern int VBoxServiceStartServices(void);
387	extern int VBoxServiceStopServices(void);
388	extern void VBoxServiceMainWait(void);
389	extern int VBoxServiceReportStatus(VBoxGuestFacilityStatus enmStatus);
390	#ifdef RT_OS_WINDOWS
391	extern RTEXITCODE VBoxServiceWinInstall(void);
392	extern RTEXITCODE VBoxServiceWinUninstall(void);
393	extern RTEXITCODE VBoxServiceWinEnterCtrlDispatcher(void);
394	extern void VBoxServiceWinSetStopPendingStatus(uint32_t uCheckPoint);
395	#endif
396
397	#ifdef VBOXSERVICE_TOOLBOX
398	extern bool VBoxServiceToolboxMain(int argc, char *argv, RTEXITCODE prcExit);
399	#endif
400
401	#ifdef RT_OS_WINDOWS
402	# ifdef VBOX_WITH_GUEST_PROPS
403	extern int VBoxServiceVMInfoWinWriteUsers(char *ppszUserList, uint32_t pcUsersInList);
404	extern int VBoxServiceWinGetComponentVersions(uint32_t uiClientID);
405	# endif /* VBOX_WITH_GUEST_PROPS */
406	#endif /* RT_OS_WINDOWS */
407
408	#ifdef VBOX_WITH_GUEST_CONTROL
409	/* Guest control main thread functions. */
410	extern int VBoxServiceControlAssignPID(PVBOXSERVICECTRLTHREAD pThread, uint32_t uPID);
411	extern int VBoxServiceControlListSet(VBOXSERVICECTRLTHREADLISTTYPE enmList,
412	PVBOXSERVICECTRLTHREAD pThread);
413	extern PVBOXSERVICECTRLTHREAD VBoxServiceControlLockThread(uint32_t uPID);
414	extern void VBoxServiceControlUnlockThread(const PVBOXSERVICECTRLTHREAD pThread);
415	extern int VBoxServiceControlSetInactive(PVBOXSERVICECTRLTHREAD pThread);
416	/* Per-thread guest process functions. */
417	extern int VBoxServiceControlThreadStart(uint32_t uContext,
418	PVBOXSERVICECTRLPROCESS pProcess);
419	extern int VBoxServiceControlThreadPerform(uint32_t uPID, PVBOXSERVICECTRLREQUEST pRequest);
420	extern int VBoxServiceControlThreadStop(const PVBOXSERVICECTRLTHREAD pThread);
421	extern int VBoxServiceControlThreadWait(const PVBOXSERVICECTRLTHREAD pThread,
422	RTMSINTERVAL msTimeout, int *prc);
423	extern int VBoxServiceControlThreadFree(PVBOXSERVICECTRLTHREAD pThread);
424	/* Request handling. */
425	extern int VBoxServiceControlThreadRequestAlloc(PVBOXSERVICECTRLREQUEST *ppReq,
426	VBOXSERVICECTRLREQUESTTYPE enmType);
427	extern int VBoxServiceControlThreadRequestAllocEx(PVBOXSERVICECTRLREQUEST *ppReq,
428	VBOXSERVICECTRLREQUESTTYPE enmType,
429	void *pvData,
430	size_t cbData,
431	uint32_t uCID);
432	extern void VBoxServiceControlThreadRequestFree(PVBOXSERVICECTRLREQUEST pReq);
433	#endif /* VBOX_WITH_GUEST_CONTROL */
434
435	#ifdef VBOXSERVICE_MANAGEMENT
436	extern uint32_t VBoxServiceBalloonQueryPages(uint32_t cbPage);
437	#endif
438	#if defined(VBOX_WITH_PAGE_SHARING) && defined(RT_OS_WINDOWS)
439	extern RTEXITCODE VBoxServicePageSharingInitFork(void);
440	#endif
441	extern int VBoxServiceVMInfoSignal(void);
442
443	RT_C_DECLS_END
444
445	#endif
446

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

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

Download in other formats: