GuestControl.h@ 103165

Last change on this file since 103165 was 102837, checked in by vboxsync, 14 months ago
Guest Control/GuestControl.h: Docs.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.9 KB

Line
1	/* $Id: GuestControl.h 102837 2024-01-11 12:15:07Z vboxsync $ */
2	/** @file
3	* Guest Control - Common Guest and Host Code.
4	*
5	* @todo r=bird: Just merge this with GuestControlSvc.h!
6	*/
7
8	/*
9	* Copyright (C) 2016-2023 Oracle and/or its affiliates.
10	*
11	* This file is part of VirtualBox base platform packages, as
12	* available from https://www.virtualbox.org.
13	*
14	* This program is free software; you can redistribute it and/or
15	* modify it under the terms of the GNU General Public License
16	* as published by the Free Software Foundation, in version 3 of the
17	* License.
18	*
19	* This program is distributed in the hope that it will be useful, but
20	* WITHOUT ANY WARRANTY; without even the implied warranty of
21	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22	* General Public License for more details.
23	*
24	* You should have received a copy of the GNU General Public License
25	* along with this program; if not, see <https://www.gnu.org/licenses>.
26	*
27	* The contents of this file may alternatively be used under the terms
28	* of the Common Development and Distribution License Version 1.0
29	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
30	* in the VirtualBox distribution, in which case the provisions of the
31	* CDDL are applicable instead of those of the GPL.
32	*
33	* You may elect to license modified versions of this file under the
34	* terms and conditions of either the GPL or the CDDL or both.
35	*
36	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
37	*/
38
39	#ifndef VBOX_INCLUDED_GuestHost_GuestControl_h
40	#define VBOX_INCLUDED_GuestHost_GuestControl_h
41	#ifndef RT_WITHOUT_PRAGMA_ONCE
42	# pragma once
43	#endif
44
45	#include <iprt/time.h>
46	#include <iprt/path.h>
47	#include <iprt/types.h>
48
49	/* Everything defined in this file lives in this namespace. */
50	namespace guestControl {
51
52	/**
53	* Process status when executed in the guest.
54	*/
55	enum eProcessStatus
56	{
57	/** Process is in an undefined state. */
58	PROC_STS_UNDEFINED = 0,
59	/** Process has been started. */
60	PROC_STS_STARTED = 1,
61	/** Process terminated normally. */
62	PROC_STS_TEN = 2,
63	/** Process terminated via signal. */
64	PROC_STS_TES = 3,
65	/** Process terminated abnormally. */
66	PROC_STS_TEA = 4,
67	/** Process timed out and was killed. */
68	PROC_STS_TOK = 5,
69	/** Process timed out and was not killed successfully. */
70	PROC_STS_TOA = 6,
71	/** Service/OS is stopping, process was killed. */
72	PROC_STS_DWN = 7,
73	/** Something went wrong (error code in flags). */
74	PROC_STS_ERROR = 8
75	};
76
77	/**
78	* Input flags, set by the host. This is needed for
79	* handling flags on the guest side.
80	* Note: Has to match Main's ProcessInputFlag_* flags!
81	*/
82	#define GUEST_PROC_IN_FLAG_NONE 0x0
83	#define GUEST_PROC_IN_FLAG_EOF RT_BIT(0)
84
85	/**
86	* Guest session creation flags.
87	* Only handled internally at the moment.
88	*/
89	#define SESSIONCREATIONFLAG_NONE 0x0
90
91	/** @name DIRREMOVEREC_FLAG_XXX - Guest directory removement flags.
92	* Essentially using what IPRT's RTDIRRMREC_F_
93	* defines have to offer.
94	* @{
95	*/
96	/** No remove flags specified. */
97	#define DIRREMOVEREC_FLAG_NONE UINT32_C(0x0)
98	/** Recursively deletes the directory contents. */
99	#define DIRREMOVEREC_FLAG_RECURSIVE RT_BIT(0)
100	/** Delete the content of the directory and the directory itself. */
101	#define DIRREMOVEREC_FLAG_CONTENT_AND_DIR RT_BIT(1)
102	/** Only delete the content of the directory, omit the directory it self. */
103	#define DIRREMOVEREC_FLAG_CONTENT_ONLY RT_BIT(2)
104	/** Mask of valid flags. */
105	#define DIRREMOVEREC_FLAG_VALID_MASK UINT32_C(0x00000007)
106	/** @} */
107
108	/** @name GUEST_PROC_CREATE_FLAG_XXX - Guest process creation flags.
109	* @note Has to match Main's ProcessCreateFlag_* flags!
110	* @{
111	*/
112	#define GUEST_PROC_CREATE_FLAG_NONE UINT32_C(0x0)
113	#define GUEST_PROC_CREATE_FLAG_WAIT_START RT_BIT(0)
114	#define GUEST_PROC_CREATE_FLAG_IGNORE_ORPHANED RT_BIT(1)
115	#define GUEST_PROC_CREATE_FLAG_HIDDEN RT_BIT(2)
116	#define GUEST_PROC_CREATE_FLAG_PROFILE RT_BIT(3)
117	#define GUEST_PROC_CREATE_FLAG_WAIT_STDOUT RT_BIT(4)
118	#define GUEST_PROC_CREATE_FLAG_WAIT_STDERR RT_BIT(5)
119	#define GUEST_PROC_CREATE_FLAG_EXPAND_ARGUMENTS RT_BIT(6)
120	#define GUEST_PROC_CREATE_FLAG_UNQUOTED_ARGS RT_BIT(7)
121	/** @} */
122
123	/** @name GUEST_PROC_OUT_H_XXX - Pipe handle IDs used internally for referencing
124	* to a certain pipe buffer.
125	* @{
126	*/
127	#define GUEST_PROC_OUT_H_STDOUT_DEPRECATED 0 /*< Needed for VBox hosts < 4.1.0. /
128	#define GUEST_PROC_OUT_H_STDOUT 1
129	#define GUEST_PROC_OUT_H_STDERR 2
130	/** @} */
131
132	/** @name PATHRENAME_FLAG_XXX - Guest path rename flags.
133	* Essentially using what IPRT's RTPATHRENAME_FLAGS_XXX have to offer.
134	* @{
135	*/
136	/** Do not replace anything. */
137	#define PATHRENAME_FLAG_NO_REPLACE UINT32_C(0)
138	/** This will replace attempt any target which isn't a directory. */
139	#define PATHRENAME_FLAG_REPLACE RT_BIT(0)
140	/** Don't allow symbolic links as part of the path. */
141	#define PATHRENAME_FLAG_NO_SYMLINKS RT_BIT(1)
142	/** Mask of valid flags. */
143	#define PATHRENAME_FLAG_VALID_MASK UINT32_C(0x00000003)
144	/** @} */
145
146	/** @name GSTCTL_CREATETEMP_F_XXX - Guest temporary directory/file creation flags.
147	* @{
148	*/
149	/** Does not specify anything. */
150	#define GSTCTL_CREATETEMP_F_NONE UINT32_C(0)
151	/** Creates a directory instead of a file. */
152	#define GSTCTL_CREATETEMP_F_DIRECTORY RT_BIT(0)
153	/** Creates a secure temporary file / directory.
154	* Might not be supported on all (guest) OSes.
155	*
156	* @sa IPRT's implementation of RTDirCreateTempSecure() / RTFileCreateTempSecure(). */
157	#define GSTCTL_CREATETEMP_F_SECURE RT_BIT(1)
158	/** Mask of valid flags. */
159	#define GSTCTL_CREATETEMP_F_VALID_MASK UINT32_C(0x00000003)
160	/** @} */
161
162	/** @name GSTCTL_CREATEDIRECTORY_F_XXX - Guest directory creation flags.
163	* @{
164	*/
165	/** Does not specify anything. */
166	#define GSTCTL_CREATEDIRECTORY_F_NONE UINT32_C(0)
167	/** Also creates parent directories if they don't exist yet. */
168	#define GSTCTL_CREATEDIRECTORY_F_PARENTS RT_BIT(0)
169	/** Don't allow symbolic links as part of the path. */
170	#define GSTCTL_CREATEDIRECTORY_F_NO_SYMLINKS RT_BIT(1)
171	/** Set the not-content-indexed flag (default). Windows only atm. */
172	#define GSTCTL_CREATEDIRECTORY_F_NOT_CONTENT_INDEXED_DONT_SET RT_BIT(2)
173	/** Ignore errors setting the not-content-indexed flag. Windows only atm. */
174	#define GSTCTL_CREATEDIRECTORY_F_NOT_CONTENT_INDEXED_NOT_CRITICAL RT_BIT(3)
175	/** Ignore umask when applying the mode. */
176	#define GSTCTL_CREATEDIRECTORY_F_IGNORE_UMASK RT_BIT(4)
177	/** Mask of valid flags. */
178	#define GSTCTL_CREATEDIRECTORY_F_VALID_MASK UINT32_C(0x0000001F)
179	/** @} */
180
181	/** @name GUEST_SHUTDOWN_FLAG_XXX - Guest shutdown flags.
182	*
183	* @note Must match Main's GuestShutdownFlag_ definitions.
184	* @{
185	*/
186	#define GUEST_SHUTDOWN_FLAG_NONE UINT32_C(0)
187	#define GUEST_SHUTDOWN_FLAG_POWER_OFF RT_BIT(0)
188	#define GUEST_SHUTDOWN_FLAG_REBOOT RT_BIT(1)
189	#define GUEST_SHUTDOWN_FLAG_FORCE RT_BIT(2)
190	/** @} */
191
192	/** @name Defines for default (initial) guest process buffer lengths.
193	* Note: These defaults were the maximum values before; so be careful when raising those in order to
194	* not break running with older Guest Additions.
195	* @{
196	*/
197	#define GUEST_PROC_DEF_CMD_LEN _1K
198	#define GUEST_PROC_DEF_CWD_LEN _1K
199	#define GUEST_PROC_DEF_ARGS_LEN _1K
200	#define GUEST_PROC_DEF_ENV_LEN _1K
201	#define GUEST_PROC_DEF_USER_LEN 128
202	#define GUEST_PROC_DEF_PASSWORD_LEN 128
203	#define GUEST_PROC_DEF_DOMAIN_LEN 256
204	/** @} */
205
206	/** @name Defines for maximum guest process buffer lengths.
207	* @{
208	*/
209	#define GUEST_PROC_MAX_CMD_LEN _1M
210	#define GUEST_PROC_MAX_CWD_LEN RTPATH_MAX
211	#define GUEST_PROC_MAX_ARGS_LEN _2M
212	#define GUEST_PROC_MAX_ENV_LEN _4M
213	#define GUEST_PROC_MAX_USER_LEN _64K
214	#define GUEST_PROC_MAX_PASSWORD_LEN _64K
215	#define GUEST_PROC_MAX_DOMAIN_LEN _64K
216	/** @} */
217
218	/** @name Internal tools built into VBoxService which are used in order
219	* to accomplish tasks host<->guest.
220	*
221	* @deprecated Since 7.1 the built-in VBoxService tools aren't used anymore.
222	* @{
223	*/
224	#define VBOXSERVICE_TOOL_CAT "vbox_cat"
225	#define VBOXSERVICE_TOOL_LS "vbox_ls"
226	#define VBOXSERVICE_TOOL_RM "vbox_rm"
227	#define VBOXSERVICE_TOOL_MKDIR "vbox_mkdir"
228	#define VBOXSERVICE_TOOL_MKTEMP "vbox_mktemp"
229	#define VBOXSERVICE_TOOL_STAT "vbox_stat"
230	/** @} */
231
232	/** Special process exit codes for "vbox_cat".
233	*
234	* @deprecated Since 7.1 the built-in VBoxService tools aren't used anymore.
235	*/
236	typedef enum VBOXSERVICETOOLBOX_CAT_EXITCODE
237	{
238	VBOXSERVICETOOLBOX_CAT_EXITCODE_ACCESS_DENIED = RTEXITCODE_END,
239	VBOXSERVICETOOLBOX_CAT_EXITCODE_FILE_NOT_FOUND,
240	VBOXSERVICETOOLBOX_CAT_EXITCODE_PATH_NOT_FOUND,
241	VBOXSERVICETOOLBOX_CAT_EXITCODE_SHARING_VIOLATION,
242	VBOXSERVICETOOLBOX_CAT_EXITCODE_IS_A_DIRECTORY,
243	/** The usual 32-bit type hack. */
244	VBOXSERVICETOOLBOX_CAT_32BIT_HACK = 0x7fffffff
245	} VBOXSERVICETOOLBOX_CAT_EXITCODE;
246
247	/** Special process exit codes for "vbox_stat".
248	*
249	* @deprecated Since 7.1 the built-in VBoxService tools aren't used anymore.
250	*/
251	typedef enum VBOXSERVICETOOLBOX_STAT_EXITCODE
252	{
253	VBOXSERVICETOOLBOX_STAT_EXITCODE_ACCESS_DENIED = RTEXITCODE_END,
254	VBOXSERVICETOOLBOX_STAT_EXITCODE_FILE_NOT_FOUND,
255	VBOXSERVICETOOLBOX_STAT_EXITCODE_PATH_NOT_FOUND,
256	VBOXSERVICETOOLBOX_STAT_EXITCODE_NET_PATH_NOT_FOUND,
257	VBOXSERVICETOOLBOX_STAT_EXITCODE_INVALID_NAME,
258	/** The usual 32-bit type hack. */
259	VBOXSERVICETOOLBOX_STAT_32BIT_HACK = 0x7fffffff
260	} VBOXSERVICETOOLBOX_STAT_EXITCODE;
261
262	/**
263	* Input status, reported by the client.
264	*/
265	enum eInputStatus
266	{
267	/** Input is in an undefined state. */
268	INPUT_STS_UNDEFINED = 0,
269	/** Input was written (partially, see cbProcessed). */
270	INPUT_STS_WRITTEN = 1,
271	/** Input failed with an error (see flags for rc). */
272	INPUT_STS_ERROR = 20,
273	/** Process has abandoned / terminated input handling. */
274	INPUT_STS_TERMINATED = 21,
275	/** Too much input data. */
276	INPUT_STS_OVERFLOW = 30
277	};
278
279	/** @name Guest filesystem flags.
280	*
281	* @{
282	*/
283	/** No guest file system flags set. */
284	#define GSTCTLFSINFO_F_NONE UINT32_C(0)
285	/** If the filesystem is remote or not. */
286	#define GSTCTLFSINFO_F_IS_REMOTE RT_BIT(0)
287	/** If the filesystem is case sensitive or not. */
288	#define GSTCTLFSINFO_F_IS_CASE_SENSITIVE RT_BIT(1)
289	/** If the filesystem is mounted read only or not. */
290	#define GSTCTLFSINFO_F_IS_READ_ONLY RT_BIT(2)
291	/** If the filesystem is compressed or not. */
292	#define GSTCTLFSINFO_F_IS_COMPRESSED RT_BIT(3)
293	/** Valid mask. */
294	#define GSTCTLFSINFO_F_VALID_MASK 0xF
295	/** @} */
296
297	/** @name Guest filesystem feature flags.
298	*
299	* @{
300	*/
301	/** No guest file system feature flags set. */
302	#define GSTCTLFSINFO_FEATURE_F_NONE UINT32_C(0)
303	/** If the filesystem can handle Unicode or not. */
304	#define GSTCTLFSINFO_FEATURE_F_UNICODE RT_BIT(0)
305	/** If the filesystem supports sparse files or not. */
306	#define GSTCTLFSINFO_FEATURE_F_SPARSE_FILES RT_BIT(1)
307	/** If the filesystem features compression of individual files or not. */
308	#define GSTCTLFSINFO_FEATURE_F_FILE_COMPRESSION RT_BIT(2)
309	/** Valid mask. */
310	#define GSTCTLFSINFO_FEATURE_F_VALID_MASK 0x7
311	/** @} */
312
313	/** Maximum length (in characters) of a guest file name. */
314	#define GSTCTL_FS_NAME_MAX 255
315	/** Maximum length (in characters) of a guest file label. */
316	#define GSTCTL_FS_LABEL_MAX 255
317	/** Maximum length (in characters) of a guest filesystem mount point. */
318	#define GSTCTL_FS_MOUNTPOINT_MAX RTPATH_MAX
319
320	/**
321	* Guest filesystem information.
322	*/
323	#pragma pack(1)
324	typedef struct GSTCTLFSINFO
325	{
326	/** Remaining free space (in bytes) of the filesystem. */
327	uint64_t cbFree;
328	/** Total space (in bytes) of the filesystem. */
329	uint64_t cbTotalSize;
330	/** Block size (in bytes) of the filesystem. */
331	uint32_t cbBlockSize;
332	/** Sector size (in bytes) of the filesystem. */
333	uint32_t cbSectorSize;
334	/** Serial number of the filesystem. */
335	uint32_t uSerialNumber;
336	/** Flags (of type GSTCTLFSINFO_F_XXX). */
337	uint32_t fFlags;
338	/** Feature flags (of type GSTCTLFSINFO_FEATURE_F_XXX). */
339	uint32_t fFeatures;
340	/** The maximum size (in characters) of a filesystem object name. */
341	uint32_t cMaxComponent;
342	/** Name of the filesystem type. */
343	char szName[GSTCTL_FS_NAME_MAX];
344	/** Label of the filesystem. */
345	char szLabel[GSTCTL_FS_LABEL_MAX];
346	/** Size (in bytes) of \a szMountpoint. */
347	uint16_t cbMountpoint;
348	/** Mount point of the filesystem.
349	* Will be dynamically allocated, based on \a cbMountpoint. */
350	char szMountpoint[1];
351	} GSTCTLFSINFO;
352	#pragma pack()
353	AssertCompileSize(GSTCTLFSINFO, 553);
354	/** Pointer to a guest filesystem structure. */
355	typedef GSTCTLFSINFO *PGSTCTLFSINFO;
356	/** Pointer to a const guest filesystem structure. */
357	typedef const GSTCTLFSINFO *PCGSTCTLFSINFO;
358
359	/**
360	* Guest file system object -- additional information in a GSTCTLFSOBJATTR object.
361	*/
362	enum GSTCTLFSOBJATTRADD
363	{
364	/** No additional information is available / requested. */
365	GSTCTLFSOBJATTRADD_NOTHING = 1,
366	/** The additional unix attributes (RTFSOBJATTR::u::Unix) are available /
367	* requested. */
368	GSTCTLFSOBJATTRADD_UNIX,
369	/** The additional unix attributes (RTFSOBJATTR::u::UnixOwner) are
370	* available / requested. */
371	GSTCTLFSOBJATTRADD_UNIX_OWNER,
372	/** The additional unix attributes (RTFSOBJATTR::u::UnixGroup) are
373	* available / requested. */
374	GSTCTLFSOBJATTRADD_UNIX_GROUP,
375	/** The additional extended attribute size (RTFSOBJATTR::u::EASize) is available / requested. */
376	GSTCTLFSOBJATTRADD_EASIZE,
377	/** The last valid item (inclusive).
378	* The valid range is RTFSOBJATTRADD_NOTHING thru RTFSOBJATTRADD_LAST. */
379	GSTCTLFSOBJATTRADD_LAST = GSTCTLFSOBJATTRADD_EASIZE,
380
381	/** The usual 32-bit hack. */
382	GSTCTLFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
383	};
384
385	/** The number of bytes reserved for the additional attribute union. */
386	#define GSTCTLFSOBJATTRUNION_MAX_SIZE 128
387
388	/* Validate stuff used in the structures used below. */
389	AssertCompileSize(RTINODE, 8);
390	AssertCompileSize(RTDEV, 4);
391	AssertCompileSize(RTGID, 4);
392	AssertCompileSize(RTUID, 4);
393
394	/**
395	* Additional Unix Attributes (GSTCTLFSOBJATTRADD_UNIX).
396	*/
397	#pragma pack(1)
398	typedef struct GSTCTLFSOBJATTRUNIX
399	{
400	/** The user owning the filesystem object (st_uid).
401	* This field is NIL_RTUID if not supported. */
402	RTUID uid;
403
404	/** The group the filesystem object is assigned (st_gid).
405	* This field is NIL_RTGID if not supported. */
406	RTGID gid;
407
408	/** Number of hard links to this filesystem object (st_nlink).
409	* This field is 1 if the filesystem doesn't support hardlinking or
410	* the information isn't available.
411	*/
412	uint32_t cHardlinks;
413
414	/** The device number of the device which this filesystem object resides on (st_dev).
415	* This field is 0 if this information is not available. */
416	RTDEV INodeIdDevice;
417
418	/** The unique identifier (within the filesystem) of this filesystem object (st_ino).
419	* Together with INodeIdDevice, this field can be used as a OS wide unique id
420	* when both their values are not 0.
421	* This field is 0 if the information is not available.
422	*
423	* @remarks The special '..' dir always shows up with 0 on NTFS/Windows. */
424	RTINODE INodeId;
425
426	/** User flags (st_flags).
427	* This field is 0 if this information is not available. */
428	uint32_t fFlags;
429
430	/** The current generation number (st_gen).
431	* This field is 0 if this information is not available. */
432	uint32_t GenerationId;
433
434	/** The device number of a character or block device type object (st_rdev).
435	* This field is 0 if the file isn't of a character or block device type and
436	* when the OS doesn't subscribe to the major+minor device idenfication scheme. */
437	RTDEV Device;
438	} GSTCTLFSOBJATTRUNIX;
439	#pragma pack()
440	AssertCompileSize(GSTCTLFSOBJATTRUNIX, 36);
441
442	/**
443	* Additional guest Unix attributes (GSTCTLFSOBJATTRADD_UNIX_OWNER).
444	*/
445	typedef struct GSTCTLFSOBJATTRUNIXOWNER
446	{
447	/** The user owning the filesystem object (st_uid).
448	* This field is NIL_RTUID if not supported. */
449	RTUID uid;
450	/** The user name.
451	* Empty if not available or not supported, truncated if too long. */
452	char szName[GSTCTLFSOBJATTRUNION_MAX_SIZE - sizeof(RTUID)];
453	} GSTCTLFSOBJATTRUNIXOWNER;
454	AssertCompileSize(GSTCTLFSOBJATTRUNIXOWNER, 128);
455
456	/**
457	* Additional guest Unix attributes (GSTCTLFSOBJATTRADD_UNIX_GROUP).
458	*/
459	typedef struct GSTCTLFSOBJATTRUNIXGROUP
460	{
461	/** The user owning the filesystem object (st_uid).
462	* This field is NIL_RTUID if not supported. */
463	RTGID gid;
464	/** The group name.
465	* Empty if not available or not supported, truncated if too long. */
466	char szName[GSTCTLFSOBJATTRUNION_MAX_SIZE - sizeof(RTGID)];
467	} GSTCTLFSOBJATTRUNIXGROUP;
468	AssertCompileSize(GSTCTLFSOBJATTRUNIXGROUP, 128);
469
470	/**
471	* Guest filesystem object attributes.
472	*/
473	typedef struct GSTCTLFSOBJATTR
474	{
475	/** Mode flags (st_mode). RTFS_UNIX_, RTFS_TYPE_, and RTFS_DOS_. /
476	RTFMODE fMode;
477
478	/** The additional attributes available. */
479	GSTCTLFSOBJATTRADD enmAdditional;
480
481	/**
482	* Additional attributes.
483	*
484	* Unless explicitly specified to an API, the API can provide additional
485	* data as it is provided by the underlying OS.
486	*/
487	union GSTCTLFSOBJATTRUNION
488	{
489	/** Additional Unix Attributes - GUEST_FSOBJATTRADD_UNIX. */
490	GSTCTLFSOBJATTRUNIX Unix;
491	/** Additional Unix Owner Attributes - GUEST_FSOBJATTRADD_UNIX_OWNER. */
492	GSTCTLFSOBJATTRUNIXOWNER UnixOwner;
493	/** Additional Unix Group Attributes - GUEST_FSOBJATTRADD_UNIX_GROUP. */
494	GSTCTLFSOBJATTRUNIXGROUP UnixGroup;
495
496	/**
497	* Extended attribute size is available when RTFS_DOS_HAVE_EA_SIZE is set.
498	*/
499	struct GSTCTLFSOBJATTREASIZE
500	{
501	/** Size of EAs. */
502	RTFOFF cb;
503	} EASize;
504	/** Reserved space. */
505	uint8_t abReserveSpace[128];
506	} u;
507	} GSTCTLFSOBJATTR;
508	AssertCompileSize(GSTCTLFSOBJATTR /* 136 */, sizeof(RTFMODE) + sizeof(GSTCTLFSOBJATTRADD) + 128);
509	/** Pointer to a guest filesystem object attributes structure. */
510	typedef GSTCTLFSOBJATTR *PGSTCTLFSOBJATTR;
511	/** Pointer to a const guest filesystem object attributes structure. */
512	typedef const GSTCTLFSOBJATTR *PCGSTCTLFSOBJATTR;
513
514	/** @name GSTCTL_PATH_F_XXX - Generic flags for querying guest file system information.
515	* @{ */
516	/** No guest stat flags specified. */
517	#define GSTCTL_PATH_F_NONE UINT32_C(0)
518	/** Last component: Work on the link. */
519	#define GSTCTL_PATH_F_ON_LINK RT_BIT_32(0)
520	/** Last component: Follow if link. */
521	#define GSTCTL_PATH_F_FOLLOW_LINK RT_BIT_32(1)
522	/** Don't allow symbolic links as part of the path. */
523	#define GSTCTL_PATH_F_NO_SYMLINKS RT_BIT_32(2)
524	/** GSTCTL_PATH_F_XXX flag valid mask. */
525	#define GSTCTL_PATH_F_VALID_MASK UINT32_C(0x00000007)
526	/** @} */
527
528	/** @name GSTCTL_DIRLIST_F_XXX - Flags for guest directory listings.
529	* @{ */
530	/** No guest listing flags specified. */
531	#define GSTCTL_DIRLIST_F_NONE UINT32_C(0)
532	/** GSTCTL_DIRLIST_F_XXX valid mask. */
533	#define GSTCTL_DIRLIST_F_VALID_MASK UINT32_C(0x00000000)
534	/** @} */
535
536	/**
537	* Filter option for HOST_MSG_DIR_OPEN.
538	*/
539	typedef enum GSTCTLDIRFILTER
540	{
541	/** The usual invalid 0 entry. */
542	GSTCTLDIRFILTER_INVALID = 0,
543	/** No filter should be applied (and none was specified). */
544	GSTCTLDIRFILTER_NONE,
545	/** The Windows NT filter.
546	* The following wildcard chars: *, ?, <, > and "
547	* The matching is done on the uppercased strings. */
548	GSTCTLDIRFILTER_WINNT,
549	/** The UNIX filter.
550	* The following wildcard chars: *, ?, [..]
551	* The matching is done on exact case. */
552	GSTCTLDIRFILTER_UNIX,
553	/** The UNIX filter, uppercased matching.
554	* Same as GSTCTLDIRFILTER_UNIX except that the strings are uppercased before comparing. */
555	GSTCTLDIRFILTER_UNIX_UPCASED,
556
557	/** The usual full 32-bit value. */
558	GSTCTLDIRFILTER_32BIT_HACK = 0x7fffffff
559	} GSTCTLDIRFILTER;
560
561	/** @name GSTCTLDIR_F_XXX - Directory flags for HOST_MSG_DIR_OPEN.
562	* @{ */
563	/** No directory open flags specified. */
564	#define GSTCTLDIR_F_NONE UINT32_C(0)
565	/** Don't allow symbolic links as part of the path.
566	* @remarks this flag is currently not implemented and will be ignored. */
567	#define GSTCTLDIR_F_NO_SYMLINKS RT_BIT_32(0)
568	/** Deny relative opening of anything above this directory. */
569	#define GSTCTLDIR_F_DENY_ASCENT RT_BIT_32(1)
570	/** Don't follow symbolic links in the final component. */
571	#define GSTCTLDIR_F_NO_FOLLOW RT_BIT_32(2)
572	/** Long path hack: Don't apply RTPathAbs to the path. */
573	#define GSTCTLDIR_F_NO_ABS_PATH RT_BIT_32(3)
574	/** Valid flag mask. */
575	#define GSTCTLDIR_F_VALID_MASK UINT32_C(0x0000000f)
576
577	/**
578	* Guest filesystem object information structure.
579	*
580	* This is returned by
581	* - GUEST_FS_NOTIFYTYPE_QUERY_INFO
582	* - GUEST_DIR_NOTIFYTYPE_READ
583	*/
584	typedef struct GSTCTLFSOBJINFO
585	{
586	/** Logical size (st_size).
587	* For normal files this is the size of the file.
588	* For symbolic links, this is the length of the path name contained
589	* in the symbolic link.
590	* For other objects this fields needs to be specified.
591	*/
592	RTFOFF cbObject;
593
594	/** Disk allocation size (st_blocks * DEV_BSIZE). */
595	RTFOFF cbAllocated;
596
597	/** Time of last access (st_atime). */
598	RTTIMESPEC AccessTime;
599
600	/** Time of last data modification (st_mtime). */
601	RTTIMESPEC ModificationTime;
602
603	/** Time of last status change (st_ctime).
604	* If not available this is set to ModificationTime.
605	*/
606	RTTIMESPEC ChangeTime;
607
608	/** Time of file birth (st_birthtime).
609	* If not available this is set to ChangeTime.
610	*/
611	RTTIMESPEC BirthTime;
612
613	/** Attributes. */
614	GSTCTLFSOBJATTR Attr;
615
616	} GSTCTLFSOBJINFO;
617	AssertCompileSize(GSTCTLFSOBJINFO /* 184 */, 48 + sizeof(GSTCTLFSOBJATTR));
618	/** Pointer to a guest filesystem object information structure. */
619	typedef GSTCTLFSOBJINFO *PGSTCTLFSOBJINFO;
620	/** Pointer to a const guest filesystem object information structure. */
621	typedef const GSTCTLFSOBJINFO *PCGSTCTLFSOBJINFO;
622
623	/**
624	* Guest directory entry with extended information.
625	*
626	* This is inspired by IPRT + the PC interfaces.
627	*/
628	#pragma pack(1)
629	typedef struct GSTCTLDIRENTRYEX
630	{
631	/** Full information about the guest object. */
632	GSTCTLFSOBJINFO Info;
633	/** The length of the short field (number of RTUTF16 entries (not chars)).
634	* It is 16-bit for reasons of alignment. */
635	uint16_t cwcShortName;
636	/** The short name for 8.3 compatibility.
637	* Empty string if not available.
638	* Since the length is a bit tricky for a UTF-8 encoded name, and since this
639	* is practically speaking only a windows thing, it is encoded as UCS-2. */
640	RTUTF16 wszShortName[14];
641	/** The length of the filename. */
642	uint16_t cbName;
643	/** The filename. (no path)
644	* Using the pcbDirEntry parameter of RTDirReadEx makes this field variable in size. */
645	char szName[260];
646	} GSTCTLDIRENTRYEX;
647	#pragma pack()
648	AssertCompileSize(GSTCTLDIRENTRYEX, sizeof(GSTCTLFSOBJINFO) + 292);
649	/** Pointer to a guest directory entry. */
650	typedef GSTCTLDIRENTRYEX *PGSTCTLDIRENTRYEX;
651	/** Pointer to a const guest directory entry. */
652	typedef GSTCTLDIRENTRYEX const *PCGSTCTLDIRENTRYEX;
653
654	/** The maximum size (in bytes) of an entry file name (at least RT_UOFFSETOF(GSTCTLDIRENTRYEX, szName[2]). */
655	#define GSTCTL_DIRENTRY_MAX_SIZE 4096
656	/** Maximum characters of the resolved user name. Including terminator. */
657	#define GSTCTL_DIRENTRY_MAX_USER_NAME 255
658	/** Maximum characters of the resolved user groups list. Including terminator. */
659	#define GSTCTL_DIRENTRY_MAX_USER_GROUPS _1K
660	/** The resolved user groups delimiter as a string. */
661	#define GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR "\r\n"
662
663	/**
664	* Guest directory entry header.
665	*
666	* This is needed for (un-)packing multiple directory entries with its resolved user name + groups
667	* with the HOST_MSG_DIR_LIST command.
668	*
669	* The order of the attributes also mark their packed order, so be careful when changing this!
670	*
671	* @since 7.1
672	*/
673	#pragma pack(1)
674	typedef struct GSTCTLDIRENTRYLISTHDR
675	{
676	/** Size (in bytes) of the directory header). */
677	uint32_t cbDirEntryEx;
678	/** Size (in bytes) of the resolved user name as a string
679	* Includes terminator. */
680	uint32_t cbUser;
681	/** Size (in bytes) of the resolved user groups as a string.
682	* Delimited by GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR. Includes terminator. */
683	uint32_t cbGroups;
684	} GSTCTLDIRENTRYBLOCK;
685	/** Pointer to a guest directory header entry. */
686	typedef GSTCTLDIRENTRYLISTHDR *PGSTCTLDIRENTRYLISTHDR;
687	#pragma pack()
688	} /* namespace guestControl */
689
690	#endif /* !VBOX_INCLUDED_GuestHost_GuestControl_h */
691

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

source: vbox/trunk/include/VBox/GuestHost/GuestControl.h@ 103165

Download in other formats: