VirtualBox

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

Last change on this file since 98824 was 98824, checked in by vboxsync, 15 months ago

Guest Control: Made the directory entry reading really dynamic by letting the guest tell us the size it reports to the guest (limited by GSTCTL_DIRENTRY_MAX_SIZE). Re-introduced the #pragma pack(1) because we need the structures on mixed bitness (32 / 64 or vice versa) with the same size. bugref:9783
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.0 KB
Line 
1/* $Id: VBoxServiceControl.h 98824 2023-03-02 17:06:36Z vboxsync $ */
2/** @file
3 * VBoxServiceControl.h - Internal guest control definitions.
4 */
5
6/*
7 * Copyright (C) 2013-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * SPDX-License-Identifier: GPL-3.0-only
26 */
27
28#ifndef GA_INCLUDED_SRC_common_VBoxService_VBoxServiceControl_h
29#define GA_INCLUDED_SRC_common_VBoxService_VBoxServiceControl_h
30#ifndef RT_WITHOUT_PRAGMA_ONCE
31# pragma once
32#endif
33
34#include <iprt/critsect.h>
35#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
36# include <iprt/dir.h>
37#endif
38#include <iprt/list.h>
39#include <iprt/req.h>
40
41#include <VBox/VBoxGuestLib.h>
42#include <VBox/GuestHost/GuestControl.h>
43#include <VBox/HostServices/GuestControlSvc.h>
44
45#include "VBoxServiceUtils.h" /* For VGSVCIDCACHE. */
46
47
48/**
49 * Pipe IDs for handling the guest process poll set.
50 */
51typedef enum VBOXSERVICECTRLPIPEID
52{
53 VBOXSERVICECTRLPIPEID_UNKNOWN = 0,
54 VBOXSERVICECTRLPIPEID_STDIN = 10,
55 VBOXSERVICECTRLPIPEID_STDIN_WRITABLE = 11,
56 /** Pipe for reading from guest process' stdout. */
57 VBOXSERVICECTRLPIPEID_STDOUT = 40,
58 /** Pipe for reading from guest process' stderr. */
59 VBOXSERVICECTRLPIPEID_STDERR = 50,
60 /** Notification pipe for waking up the guest process
61 * control thread. */
62 VBOXSERVICECTRLPIPEID_IPC_NOTIFY = 100
63} VBOXSERVICECTRLPIPEID;
64
65#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
66/**
67 * Structure for one (opened) guest directory.
68 */
69typedef struct VBOXSERVICECTRLDIR
70{
71 /** Pointer to list archor of following list node.
72 * @todo Would be nice to have a RTListGetAnchor(). */
73 PRTLISTANCHOR pAnchor;
74 /** Node to global guest control directory list. */
75 /** @todo Use a map later? */
76 RTLISTNODE Node;
77 /** The (absolute) directory path. */
78 char *pszPathAbs;
79 /** The directory handle on the guest. */
80 RTDIR hDir;
81 /** Directory handle to identify this directory. */
82 uint32_t uHandle;
83 /** Context ID. */
84 uint32_t uContextID;
85 /** Flags for reading directory entries. */
86 uint32_t fRead;
87 /** Additional attributes enumeration to use for reading directory entries. */
88 GSTCTLFSOBJATTRADD enmReadAttrAdd;
89} VBOXSERVICECTRLDIR;
90/** Pointer to a guest directory. */
91typedef VBOXSERVICECTRLDIR *PVBOXSERVICECTRLDIR;
92#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
93
94/**
95 * Structure for one (opened) guest file.
96 */
97typedef struct VBOXSERVICECTRLFILE
98{
99 /** Pointer to list archor of following list node.
100 * @todo Would be nice to have a RTListGetAnchor(). */
101 PRTLISTANCHOR pAnchor;
102 /** Node to global guest control file list. */
103 /** @todo Use a map later? */
104 RTLISTNODE Node;
105 /** The file name. */
106 char *pszName;
107 /** The file handle on the guest. */
108 RTFILE hFile;
109 /** File handle to identify this file. */
110 uint32_t uHandle;
111 /** Context ID. */
112 uint32_t uContextID;
113 /** RTFILE_O_XXX flags. */
114 uint64_t fOpen;
115} VBOXSERVICECTRLFILE;
116/** Pointer to a guest file. */
117typedef VBOXSERVICECTRLFILE *PVBOXSERVICECTRLFILE;
118
119/**
120 * Structure for a guest session thread to
121 * observe/control the forked session instance from
122 * the VBoxService main executable.
123 */
124typedef struct VBOXSERVICECTRLSESSIONTHREAD
125{
126 /** Node to global guest control session list. */
127 /** @todo Use a map later? */
128 RTLISTNODE Node;
129 /** The sessions's startup info. */
130 PVBGLR3GUESTCTRLSESSIONSTARTUPINFO
131 pStartupInfo;
132 /** Critical section for thread-safe use. */
133 RTCRITSECT CritSect;
134 /** The worker thread. */
135 RTTHREAD Thread;
136 /** Process handle for forked child. */
137 RTPROCESS hProcess;
138 /** Shutdown indicator; will be set when the thread
139 * needs (or is asked) to shutdown. */
140 bool volatile fShutdown;
141 /** Indicator set by the service thread exiting. */
142 bool volatile fStopped;
143 /** Whether the thread was started or not. */
144 bool fStarted;
145#if 0 /* Pipe IPC not used yet. */
146 /** Pollset containing all the pipes. */
147 RTPOLLSET hPollSet;
148 RTPIPE hStdInW;
149 RTPIPE hStdOutR;
150 RTPIPE hStdErrR;
151 struct StdPipe
152 {
153 RTHANDLE hChild;
154 PRTHANDLE phChild;
155 } StdIn,
156 StdOut,
157 StdErr;
158 /** The notification pipe associated with this guest session.
159 * This is NIL_RTPIPE for output pipes. */
160 RTPIPE hNotificationPipeW;
161 /** The other end of hNotificationPipeW. */
162 RTPIPE hNotificationPipeR;
163#endif
164 /** Pipe for handing the secret key to the session process. */
165 RTPIPE hKeyPipe;
166 /** Secret key. */
167 uint8_t abKey[_4K];
168} VBOXSERVICECTRLSESSIONTHREAD;
169/** Pointer to thread data. */
170typedef VBOXSERVICECTRLSESSIONTHREAD *PVBOXSERVICECTRLSESSIONTHREAD;
171
172/** Defines the prefix being used for telling our service executable that we're going
173 * to spawn a new (Guest Control) user session. */
174#define VBOXSERVICECTRLSESSION_GETOPT_PREFIX "guestsession"
175
176/** Flag indicating that this session has been spawned from
177 * the main executable. */
178#define VBOXSERVICECTRLSESSION_FLAG_SPAWN RT_BIT(0)
179/** Flag indicating that this session is anonymous, that is,
180 * it will run start guest processes with the same credentials
181 * as the main executable. */
182#define VBOXSERVICECTRLSESSION_FLAG_ANONYMOUS RT_BIT(1)
183/** Flag indicating that started guest processes will dump their
184 * stdout output to a separate file on disk. For debugging. */
185#define VBOXSERVICECTRLSESSION_FLAG_DUMPSTDOUT RT_BIT(2)
186/** Flag indicating that started guest processes will dump their
187 * stderr output to a separate file on disk. For debugging. */
188#define VBOXSERVICECTRLSESSION_FLAG_DUMPSTDERR RT_BIT(3)
189
190/**
191 * Structure for maintaining a guest session. This also
192 * contains all started threads (e.g. for guest processes).
193 *
194 * This structure can act in two different ways:
195 * - For legacy guest control handling (protocol version < 2)
196 * this acts as a per-guest process structure containing all
197 * the information needed to get a guest process up and running.
198 * - For newer guest control protocols (>= 2) this structure is
199 * part of the forked session child, maintaining all guest
200 * control objects under it.
201 */
202typedef struct VBOXSERVICECTRLSESSION
203{
204 /* The session's startup information. */
205 VBGLR3GUESTCTRLSESSIONSTARTUPINFO
206 StartupInfo;
207 /** List of active guest process threads
208 * (VBOXSERVICECTRLPROCESS). */
209 RTLISTANCHOR lstProcesses;
210 /** Number of guest processes in the process list. */
211 uint32_t cProcesses;
212#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
213 /** List of guest control files (VBOXSERVICECTRLDIR). */
214 RTLISTANCHOR lstDirs;
215 /** Number of guest directories in \a lstDirs. */
216 uint32_t cDirs;
217#endif
218 /** List of guest control files (VBOXSERVICECTRLFILE). */
219 RTLISTANCHOR lstFiles;
220 /** Number of guest files in \a lstFiles. */
221 uint32_t cFiles;
222 /** The session's critical section. */
223 RTCRITSECT CritSect;
224 /** Internal session flags, not related
225 * to StartupInfo stuff.
226 * @sa VBOXSERVICECTRLSESSION_FLAG_* flags. */
227 uint32_t fFlags;
228 /** How many processes do we allow keeping around at a time? */
229 uint32_t uProcsMaxKept;
230#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
231 /** The uid cache for this session. */
232 VGSVCIDCACHE UidCache;
233 /** The gid cache for this session. */
234 VGSVCIDCACHE GidCache;
235 /** Scratch buffer for holding the directory reading entry.
236 * Currently NOT serialized, i.e. only can be used for one read at a time. */
237 PRTDIRENTRYEX pDirEntryEx;
238 /** Size (in bytes) of \a pDirEntryEx. */
239 size_t cbDirEntryEx;
240#endif
241} VBOXSERVICECTRLSESSION;
242/** Pointer to guest session. */
243typedef VBOXSERVICECTRLSESSION *PVBOXSERVICECTRLSESSION;
244
245/**
246 * Structure for holding data for one (started) guest process.
247 */
248typedef struct VBOXSERVICECTRLPROCESS
249{
250 /** Node. */
251 RTLISTNODE Node;
252 /** Process handle. */
253 RTPROCESS hProcess;
254 /** Number of references using this struct. */
255 uint32_t cRefs;
256 /** The worker thread. */
257 RTTHREAD Thread;
258 /** The session this guest process
259 * is bound to. */
260 PVBOXSERVICECTRLSESSION pSession;
261 /** Shutdown indicator; will be set when the thread
262 * needs (or is asked) to shutdown. */
263 bool volatile fShutdown;
264 /** Whether the guest process thread was stopped or not. */
265 bool volatile fStopped;
266 /** Whether the guest process thread was started or not. */
267 bool fStarted;
268 /** Context ID. */
269 uint32_t uContextID;
270 /** Critical section for thread-safe use. */
271 RTCRITSECT CritSect;
272 /** Process startup information. */
273 PVBGLR3GUESTCTRLPROCSTARTUPINFO
274 pStartupInfo;
275 /** The process' PID assigned by the guest OS. */
276 uint32_t uPID;
277 /** The process' request queue to handle requests
278 * from the outside, e.g. the session. */
279 RTREQQUEUE hReqQueue;
280 /** Our pollset, used for accessing the process'
281 * std* pipes + the notification pipe. */
282 RTPOLLSET hPollSet;
283 /** StdIn pipe for addressing writes to the
284 * guest process' stdin.*/
285 RTPIPE hPipeStdInW;
286 /** StdOut pipe for addressing reads from
287 * guest process' stdout.*/
288 RTPIPE hPipeStdOutR;
289 /** StdOut pipe for addressing reads from
290 * guest process' stderr.*/
291 RTPIPE hPipeStdErrR;
292
293 /** The write end of the notification pipe that is used to poke the thread
294 * monitoring the process.
295 * This is NIL_RTPIPE for output pipes. */
296 RTPIPE hNotificationPipeW;
297 /** The other end of hNotificationPipeW, read by vgsvcGstCtrlProcessProcLoop(). */
298 RTPIPE hNotificationPipeR;
299} VBOXSERVICECTRLPROCESS;
300/** Pointer to thread data. */
301typedef VBOXSERVICECTRLPROCESS *PVBOXSERVICECTRLPROCESS;
302
303RT_C_DECLS_BEGIN
304
305extern RTLISTANCHOR g_lstControlSessionThreads;
306extern VBOXSERVICECTRLSESSION g_Session;
307extern uint32_t g_idControlSvcClient;
308extern uint64_t g_fControlHostFeatures0;
309extern bool g_fControlSupportsOptimizations;
310
311
312/** @name Guest session thread handling.
313 * @{ */
314extern int VGSvcGstCtrlSessionThreadCreate(PRTLISTANCHOR pList, const PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pSessionStartupInfo, PVBOXSERVICECTRLSESSIONTHREAD *ppSessionThread);
315extern int VGSvcGstCtrlSessionThreadDestroy(PVBOXSERVICECTRLSESSIONTHREAD pSession, uint32_t uFlags);
316extern int VGSvcGstCtrlSessionThreadDestroyAll(PRTLISTANCHOR pList, uint32_t uFlags);
317extern int VGSvcGstCtrlSessionThreadTerminate(PVBOXSERVICECTRLSESSIONTHREAD pSession);
318extern RTEXITCODE VGSvcGstCtrlSessionSpawnInit(int argc, char **argv);
319/** @} */
320/** @name Per-session functions.
321 * @{ */
322extern PVBOXSERVICECTRLPROCESS VGSvcGstCtrlSessionRetainProcess(PVBOXSERVICECTRLSESSION pSession, uint32_t uPID);
323extern int VGSvcGstCtrlSessionClose(PVBOXSERVICECTRLSESSION pSession);
324extern int VGSvcGstCtrlSessionDestroy(PVBOXSERVICECTRLSESSION pSession);
325extern int VGSvcGstCtrlSessionInit(PVBOXSERVICECTRLSESSION pSession, uint32_t uFlags);
326extern int VGSvcGstCtrlSessionHandler(PVBOXSERVICECTRLSESSION pSession, uint32_t uMsg, PVBGLR3GUESTCTRLCMDCTX pHostCtx, void *pvScratchBuf, size_t cbScratchBuf, volatile bool *pfShutdown);
327extern int VGSvcGstCtrlSessionProcessAdd(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pProcess);
328extern int VGSvcGstCtrlSessionProcessRemove(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pProcess);
329extern int VGSvcGstCtrlSessionProcessStartAllowed(const PVBOXSERVICECTRLSESSION pSession, bool *pfAllowed);
330extern int VGSvcGstCtrlSessionReapProcesses(PVBOXSERVICECTRLSESSION pSession);
331/** @} */
332/** @name Per-guest process functions.
333 * @{ */
334extern int VGSvcGstCtrlProcessFree(PVBOXSERVICECTRLPROCESS pProcess);
335extern int VGSvcGstCtrlProcessHandleInput(PVBOXSERVICECTRLPROCESS pProcess, PVBGLR3GUESTCTRLCMDCTX pHostCtx, bool fPendingClose, void *pvBuf, uint32_t cbBuf);
336extern int VGSvcGstCtrlProcessHandleOutput(PVBOXSERVICECTRLPROCESS pProcess, PVBGLR3GUESTCTRLCMDCTX pHostCtx, uint32_t uHandle, uint32_t cbToRead, uint32_t uFlags);
337extern int VGSvcGstCtrlProcessHandleTerm(PVBOXSERVICECTRLPROCESS pProcess);
338extern void VGSvcGstCtrlProcessRelease(PVBOXSERVICECTRLPROCESS pProcess);
339extern int VGSvcGstCtrlProcessStart(const PVBOXSERVICECTRLSESSION pSession, const PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo, uint32_t uContext);
340extern int VGSvcGstCtrlProcessStop(PVBOXSERVICECTRLPROCESS pProcess);
341extern int VGSvcGstCtrlProcessWait(const PVBOXSERVICECTRLPROCESS pProcess, RTMSINTERVAL msTimeout, int *pRc);
342/** @} */
343
344RT_C_DECLS_END
345
346#endif /* !GA_INCLUDED_SRC_common_VBoxService_VBoxServiceControl_h */
347
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use