diff options
Diffstat (limited to 'include/VBox/shflsvc.h')
| -rw-r--r-- | include/VBox/shflsvc.h | 2151 |
1 files changed, 2151 insertions, 0 deletions
diff --git a/include/VBox/shflsvc.h b/include/VBox/shflsvc.h new file mode 100644 index 00000000..5ebf0a34 --- /dev/null +++ b/include/VBox/shflsvc.h @@ -0,0 +1,2151 @@ +/** @file + * Shared Folders - Common header for host service and guest clients. + */ + +/* + * Copyright (C) 2006-2023 Oracle and/or its affiliates. + * + * Permission is hereby granted, free of charge, to any person + * obtaining a copy of this software and associated documentation + * files (the "Software"), to deal in the Software without + * restriction, including without limitation the rights to use, + * copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the + * Software is furnished to do so, subject to the following + * conditions: + * + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + * OTHER DEALINGS IN THE SOFTWARE. + */ + +#ifndef VBOX_INCLUDED_shflsvc_h +#define VBOX_INCLUDED_shflsvc_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#ifndef IN_MODULE +# include <VBox/VMMDevCoreTypes.h> +# include <VBox/VBoxGuestCoreTypes.h> +#endif +#include <iprt/string.h> +#include <VBox/cdefs.h> +#include <VBox/types.h> +#include <iprt/fs.h> +#include <iprt/assert.h> +#include <iprt/errcore.h> +#if defined(IN_RING3) || (defined(IN_RING0) && defined(RT_OS_DARWIN)) +# include <iprt/mem.h> +#endif +#include <iprt/utf16.h> + + + +/** @defgroup grp_vbox_shfl Shared Folder Interface Definition. + * + * Structures shared between guest and the service can be relocated and use + * offsets to point to variable length parts. + * + * Shared folders protocol works with handles. Before doing any action on a + * file system object, one have to obtain the object handle via a SHFL_FN_CREATE + * request. A handle must be closed with SHFL_FN_CLOSE. + * + * @{ + */ + +/** @name Some bit flag manipulation macros. + * @{ */ +#ifndef BIT_FLAG +#define BIT_FLAG(__Field,__Flag) ((__Field) & (__Flag)) +#endif + +#ifndef BIT_FLAG_SET +#define BIT_FLAG_SET(__Field,__Flag) ((__Field) |= (__Flag)) +#endif + +#ifndef BIT_FLAG_CLEAR +#define BIT_FLAG_CLEAR(__Field,__Flag) ((__Field) &= ~(__Flag)) +#endif +/** @} */ + + +/** @name Shared Folders service functions. (guest) + * @{ + */ +/** Query mappings changes. + * @note Description is currently misleading, it will always return all + * current mappings with SHFL_MS_NEW status. Only modification is the + * SHFL_MF_AUTOMOUNT flag that causes filtering out non-auto mounts. */ +#define SHFL_FN_QUERY_MAPPINGS (1) +/** Query the name of a map. */ +#define SHFL_FN_QUERY_MAP_NAME (2) +/** Open/create object. */ +#define SHFL_FN_CREATE (3) +/** Close object handle. */ +#define SHFL_FN_CLOSE (4) +/** Read object content. */ +#define SHFL_FN_READ (5) +/** Write new object content. */ +#define SHFL_FN_WRITE (6) +/** Lock/unlock a range in the object. */ +#define SHFL_FN_LOCK (7) +/** List object content. */ +#define SHFL_FN_LIST (8) +/** Query/set object information. */ +#define SHFL_FN_INFORMATION (9) +/** Remove object */ +#define SHFL_FN_REMOVE (11) +/** Map folder (legacy) */ +#define SHFL_FN_MAP_FOLDER_OLD (12) +/** Unmap folder */ +#define SHFL_FN_UNMAP_FOLDER (13) +/** Rename object (possibly moving it to another directory) */ +#define SHFL_FN_RENAME (14) +/** Flush file */ +#define SHFL_FN_FLUSH (15) +/** @todo macl, a description, please. */ +#define SHFL_FN_SET_UTF8 (16) +/** Map folder */ +#define SHFL_FN_MAP_FOLDER (17) +/** Read symlink destination. + * @since VBox 4.0 */ +#define SHFL_FN_READLINK (18) /**< @todo rename to SHFL_FN_READ_LINK (see struct capitalization) */ +/** Create symlink. + * @since VBox 4.0 */ +#define SHFL_FN_SYMLINK (19) +/** Ask host to show symlinks + * @since VBox 4.0 */ +#define SHFL_FN_SET_SYMLINKS (20) +/** Query information about a map. + * @since VBox 6.0 */ +#define SHFL_FN_QUERY_MAP_INFO (21) +/** Wait for changes to the mappings. + * @since VBox 6.0 */ +#define SHFL_FN_WAIT_FOR_MAPPINGS_CHANGES (22) +/** Cancel all waits for changes to the mappings for the calling client. + * The wait calls will return VERR_CANCELLED. + * @since VBox 6.0 */ +#define SHFL_FN_CANCEL_MAPPINGS_CHANGES_WAITS (23) +/** Sets the file size. + * @since VBox 6.0 */ +#define SHFL_FN_SET_FILE_SIZE (24) +/** Queries supported features. + * @since VBox 6.0.6 */ +#define SHFL_FN_QUERY_FEATURES (25) +/** Copies a file to another. + * @since VBox 6.0.6 */ +#define SHFL_FN_COPY_FILE (26) +/** Copies part of a file to another. + * @since VBox 6.0.6 */ +#define SHFL_FN_COPY_FILE_PART (27) +/** Close handle to (optional) and remove object by path. + * This function is tailored for Windows guests. + * @since VBox 6.0.8 */ +#define SHFL_FN_CLOSE_AND_REMOVE (28) +/** Set the host error code style. + * This is for more efficiently getting the correct error status when the host + * and guest OS types differs and it won't happen naturally. + * @since VBox 6.0.10 */ +#define SHFL_FN_SET_ERROR_STYLE (29) +/** The last function number. */ +#define SHFL_FN_LAST SHFL_FN_SET_ERROR_STYLE +/** @} */ + + +/** @name Shared Folders service functions. (host) + * @{ + */ +/** Add shared folder mapping. */ +#define SHFL_FN_ADD_MAPPING (1) +/** Remove shared folder mapping. */ +#define SHFL_FN_REMOVE_MAPPING (2) +/** Set the led status light address. */ +#define SHFL_FN_SET_STATUS_LED (3) +/** Allow the guest to create symbolic links + * @since VBox 4.0 */ +#define SHFL_FN_ALLOW_SYMLINKS_CREATE (4) +/** @} */ + + +/** Root handle for a mapping. Root handles are unique. + * + * @note Function parameters structures consider the root handle as 32 bit + * value. If the typedef will be changed, then function parameters must be + * changed accordingly. All those parameters are marked with SHFLROOT in + * comments. + */ +typedef uint32_t SHFLROOT; + +/** NIL shared folder root handle. */ +#define SHFL_ROOT_NIL ((SHFLROOT)~0) + + +/** A shared folders handle for an opened object. */ +typedef uint64_t SHFLHANDLE; + +#define SHFL_HANDLE_NIL ((SHFLHANDLE)~0LL) +#define SHFL_HANDLE_ROOT ((SHFLHANDLE)0LL) + +/** Hardcoded maximum length (in chars) of a shared folder name. */ +#define SHFL_MAX_LEN (256) +/** Hardcoded maximum number of shared folder mapping available to the guest. */ +#define SHFL_MAX_MAPPINGS (64) + + +/** @name Shared Folders strings. They can be either UTF-8 or UTF-16. + * @{ + */ + +/** + * Shared folder string buffer structure. + */ +typedef struct _SHFLSTRING +{ + /** Allocated size of the String member in bytes. */ + uint16_t u16Size; + + /** Length of string without trailing nul in bytes. */ + uint16_t u16Length; + + /** UTF-8 or UTF-16 string. Nul terminated. */ + union + { +#if 1 + char ach[1]; /**< UTF-8 but with a type that makes some more sense. */ + uint8_t utf8[1]; + RTUTF16 utf16[1]; + uint16_t ucs2[1]; /**< misnomer, use utf16. */ +#else + uint8_t utf8[RT_FLEXIBLE_ARRAY_IN_NESTED_UNION]; + RTUTF16 utf16[RT_FLEXIBLE_ARRAY_IN_NESTED_UNION]; + RTUTF16 ucs2[RT_FLEXIBLE_ARRAY_IN_NESTED_UNION]; /**< misnomer, use utf16. */ +#endif + } String; +} SHFLSTRING; +AssertCompileSize(RTUTF16, 2); +AssertCompileSize(SHFLSTRING, 6); +AssertCompileMemberOffset(SHFLSTRING, String, 4); +/** The size of SHFLSTRING w/o the string part. */ +#define SHFLSTRING_HEADER_SIZE 4 +AssertCompileMemberOffset(SHFLSTRING, String, SHFLSTRING_HEADER_SIZE); + +/** Pointer to a shared folder string buffer. */ +typedef SHFLSTRING *PSHFLSTRING; +/** Pointer to a const shared folder string buffer. */ +typedef const SHFLSTRING *PCSHFLSTRING; + +/** Calculate size of the string. */ +DECLINLINE(uint32_t) ShflStringSizeOfBuffer(PCSHFLSTRING pString) +{ + return pString ? (uint32_t)(SHFLSTRING_HEADER_SIZE + pString->u16Size) : 0; +} + +DECLINLINE(uint32_t) ShflStringLength(PCSHFLSTRING pString) +{ + return pString ? pString->u16Length : 0; +} + +DECLINLINE(PSHFLSTRING) ShflStringInitBuffer(void *pvBuffer, uint32_t u32Size) +{ + PSHFLSTRING pString = NULL; + const uint32_t u32HeaderSize = SHFLSTRING_HEADER_SIZE; + + /* + * Check that the buffer size is big enough to hold a zero sized string + * and is not too big to fit into 16 bit variables. + */ + if (u32Size >= u32HeaderSize && u32Size - u32HeaderSize <= 0xFFFF) + { + pString = (PSHFLSTRING)pvBuffer; + pString->u16Size = (uint16_t)(u32Size - u32HeaderSize); + pString->u16Length = 0; + if (pString->u16Size >= sizeof(pString->String.ucs2[0])) + pString->String.ucs2[0] = 0; + else if (pString->u16Size >= sizeof(pString->String.utf8[0])) + pString->String.utf8[0] = 0; + } + + return pString; +} + +/** + * Helper for copying one string into another. + * + * @returns IPRT status code. + * @retval VERR_BUFFER_OVERFLOW and pDst->u16Length set to source length. + * @param pDst The destination string. + * @param pSrc The source string. + * @param cbTerm The size of the string terminator. + */ +DECLINLINE(int) ShflStringCopy(PSHFLSTRING pDst, PCSHFLSTRING pSrc, size_t cbTerm) +{ + int rc = VINF_SUCCESS; + if (pDst->u16Size >= pSrc->u16Length + cbTerm) + { + memcpy(&pDst->String, &pSrc->String, pSrc->u16Length); + switch (cbTerm) + { + default: + case 2: pDst->String.ach[pSrc->u16Length + 1] = '\0'; RT_FALL_THROUGH(); + case 1: pDst->String.ach[pSrc->u16Length + 0] = '\0'; break; + case 0: break; + } + } + else + rc = VERR_BUFFER_OVERFLOW; + pDst->u16Length = pSrc->u16Length; + return rc; +} + +#if defined(IN_RING3) \ + || (defined(IN_RING0) && defined(RT_OS_DARWIN)) + +/** + * Duplicates a string using RTMemAlloc as allocator. + * + * @returns Copy, NULL if out of memory. + * @param pSrc The source string. + */ +DECLINLINE(PSHFLSTRING) ShflStringDup(PCSHFLSTRING pSrc) +{ + PSHFLSTRING pDst = (PSHFLSTRING)RTMemAlloc(SHFLSTRING_HEADER_SIZE + pSrc->u16Size); + if (pDst) + { + pDst->u16Length = pSrc->u16Length; + pDst->u16Size = pSrc->u16Size; + memcpy(&pDst->String, &pSrc->String, pSrc->u16Size); + } + return pDst; +} + +/** + * Duplicates a UTF-16 string using RTMemAlloc as allocator. + * + * The returned string will be using UTF-16 encoding too. + * + * @returns Pointer to copy on success - pass to RTMemFree to free. + * NULL if out of memory. + * @param pwszSrc The source string. Encoding is not checked. + */ +DECLINLINE(PSHFLSTRING) ShflStringDupUtf16(PCRTUTF16 pwszSrc) +{ + size_t cwcSrc = RTUtf16Len(pwszSrc); + if (cwcSrc < UINT16_MAX / sizeof(RTUTF16)) + { + PSHFLSTRING pDst = (PSHFLSTRING)RTMemAlloc(SHFLSTRING_HEADER_SIZE + (cwcSrc + 1) * sizeof(RTUTF16)); + if (pDst) + { + pDst->u16Length = (uint16_t)(cwcSrc * sizeof(RTUTF16)); + pDst->u16Size = (uint16_t)((cwcSrc + 1) * sizeof(RTUTF16)); + memcpy(&pDst->String, pwszSrc, (cwcSrc + 1) * sizeof(RTUTF16)); + return pDst; + } + } + AssertFailed(); + return NULL; +} + +/** + * Duplicates a UTF-8 string using RTMemAlloc as allocator. + * + * The returned string will be using UTF-8 encoding too. + * + * @returns Pointer to copy on success - pass to RTMemFree to free. + * NULL if out of memory. + * @param pszSrc The source string. Encoding is not checked. + */ +DECLINLINE(PSHFLSTRING) ShflStringDupUtf8(const char *pszSrc) +{ + size_t cchSrc = strlen(pszSrc); + if (cchSrc < UINT16_MAX) + { + PSHFLSTRING pDst = (PSHFLSTRING)RTMemAlloc(SHFLSTRING_HEADER_SIZE + cchSrc + 1); + if (pDst) + { + pDst->u16Length = (uint16_t)cchSrc; + pDst->u16Size = (uint16_t)(cchSrc + 1); + memcpy(&pDst->String, pszSrc, cchSrc + 1); + return pDst; + } + } + AssertFailed(); + return NULL; +} + +/** + * Creates a UTF-16 duplicate of the UTF-8 string @a pszSrc using RTMemAlloc as + * allocator. + * + * @returns Pointer to copy on success - pass to RTMemFree to free. + * NULL if out of memory or invalid UTF-8 encoding. + * @param pszSrc The source string. + */ +DECLINLINE(PSHFLSTRING) ShflStringDupUtf8AsUtf16(const char *pszSrc) +{ + size_t cwcConversion = 0; + int rc = RTStrCalcUtf16LenEx(pszSrc, RTSTR_MAX, &cwcConversion); + if ( RT_SUCCESS(rc) + && cwcConversion < UINT16_MAX / sizeof(RTUTF16)) + { + PSHFLSTRING pDst = (PSHFLSTRING)RTMemAlloc(SHFLSTRING_HEADER_SIZE + (cwcConversion + 1) * sizeof(RTUTF16)); + if (pDst) + { + PRTUTF16 pwszDst = pDst->String.ucs2; + pDst->u16Size = (uint16_t)((cwcConversion + 1) * sizeof(RTUTF16)); + rc = RTStrToUtf16Ex(pszSrc, RTSTR_MAX, &pwszDst, cwcConversion + 1, &cwcConversion); + AssertRC(rc); + if (RT_SUCCESS(rc)) + { + pDst->u16Length = (uint16_t)(cwcConversion * sizeof(RTUTF16)); + return pDst; + } + RTMemFree(pDst); + } + } + AssertMsgFailed(("rc=%Rrc cwcConversion=%#x\n", rc, cwcConversion)); + return NULL; +} + +/** + * Copies a UTF-8 string to a buffer as UTF-16. + * + * @returns IPRT status code. + * @param pDst The destination buffer. + * @param pszSrc The source string. + * @param cchSrc The source string length, or RTSTR_MAX. + */ +DECLINLINE(int) ShflStringCopyUtf8AsUtf16(PSHFLSTRING pDst, const char *pszSrc, size_t cchSrc) +{ + int rc; + size_t cwcDst = 0; + if (pDst->u16Size >= sizeof(RTUTF16)) + { + PRTUTF16 pwszDst = pDst->String.utf16; + rc = RTStrToUtf16Ex(pszSrc, cchSrc, &pwszDst, pDst->u16Size / sizeof(RTUTF16), &cwcDst); + } + else + { + RTStrCalcUtf16LenEx(pszSrc, cchSrc, &cwcDst); + rc = VERR_BUFFER_OVERFLOW; + } + pDst->u16Length = (uint16_t)(cwcDst * sizeof(RTUTF16)); + return rc != VERR_BUFFER_OVERFLOW || cwcDst < UINT16_MAX / sizeof(RTUTF16) ? rc : VERR_TOO_MUCH_DATA; +} + +/** + * Copies a UTF-8 string buffer to another buffer as UTF-16 + * + * @returns IPRT status code. + * @param pDst The destination buffer (UTF-16). + * @param pSrc The source buffer (UTF-8). + */ +DECLINLINE(int) ShflStringCopyUtf8BufAsUtf16(PSHFLSTRING pDst, PCSHFLSTRING pSrc) +{ + return ShflStringCopyUtf8AsUtf16(pDst, pSrc->String.ach, pSrc->u16Length); +} + +/** + * Copies a UTF-16 string to a buffer as UTF-8 + * + * @returns IPRT status code. + * @param pDst The destination buffer. + * @param pwszSrc The source string. + * @param cwcSrc The source string length, or RTSTR_MAX. + */ +DECLINLINE(int) ShflStringCopyUtf16AsUtf8(PSHFLSTRING pDst, PCRTUTF16 pwszSrc, size_t cwcSrc) +{ + int rc; + size_t cchDst = 0; + if (pDst->u16Size > 0) + { + char *pszDst = pDst->String.ach; + rc = RTUtf16ToUtf8Ex(pwszSrc, cwcSrc, &pszDst, pDst->u16Size, &cchDst); + } + else + { + RTUtf16CalcUtf8LenEx(pwszSrc, cwcSrc, &cchDst); + rc = VERR_BUFFER_OVERFLOW; + } + pDst->u16Length = (uint16_t)cchDst; + return rc != VERR_BUFFER_OVERFLOW || cchDst < UINT16_MAX ? rc : VERR_TOO_MUCH_DATA; +} + +/** + * Copies a UTF-16 string buffer to another buffer as UTF-8 + * + * @returns IPRT status code. + * @param pDst The destination buffer (UTF-8). + * @param pSrc The source buffer (UTF-16). + */ +DECLINLINE(int) ShflStringCopyUtf16BufAsUtf8(PSHFLSTRING pDst, PCSHFLSTRING pSrc) +{ + return ShflStringCopyUtf16AsUtf8(pDst, pSrc->String.utf16, pSrc->u16Length / sizeof(RTUTF16)); +} + +#endif /* IN_RING3 */ + +/** + * Validates a HGCM string output parameter. + * + * @returns true if valid, false if not. + * + * @param pString The string buffer pointer. + * @param cbBuf The buffer size from the parameter. + */ +DECLINLINE(bool) ShflStringIsValidOut(PCSHFLSTRING pString, uint32_t cbBuf) +{ + if (RT_LIKELY(cbBuf > RT_UOFFSETOF(SHFLSTRING, String))) + if (RT_LIKELY((uint32_t)pString->u16Size + RT_UOFFSETOF(SHFLSTRING, String) <= cbBuf)) + if (RT_LIKELY(pString->u16Length < pString->u16Size)) + return true; + return false; +} + +/** + * Validates a HGCM string input parameter. + * + * @returns true if valid, false if not. + * + * @param pString The string buffer pointer. + * @param cbBuf The buffer size from the parameter. + * @param fUtf8Not16 Set if UTF-8 encoding, clear if UTF-16 encoding. + */ +DECLINLINE(bool) ShflStringIsValidIn(PCSHFLSTRING pString, uint32_t cbBuf, bool fUtf8Not16) +{ + int rc; + if (RT_LIKELY(cbBuf > RT_UOFFSETOF(SHFLSTRING, String))) + { + if (RT_LIKELY((uint32_t)pString->u16Size + RT_UOFFSETOF(SHFLSTRING, String) <= cbBuf)) + { + if (fUtf8Not16) + { + /* UTF-8: */ + if (RT_LIKELY(pString->u16Length < pString->u16Size)) + { + rc = RTStrValidateEncodingEx((const char *)&pString->String.utf8[0], pString->u16Length + 1, + RTSTR_VALIDATE_ENCODING_EXACT_LENGTH | RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED); + if (RT_SUCCESS(rc)) + return true; + } + } + else + { + /* UTF-16: */ + if (RT_LIKELY(!(pString->u16Length & 1))) + { + if (RT_LIKELY((uint32_t)sizeof(RTUTF16) + pString->u16Length <= pString->u16Size)) + { + rc = RTUtf16ValidateEncodingEx(&pString->String.ucs2[0], pString->u16Length / 2 + 1, + RTSTR_VALIDATE_ENCODING_EXACT_LENGTH + | RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED); + if (RT_SUCCESS(rc)) + return true; + } + } + } + } + } + return false; +} + +/** + * Validates an optional HGCM string input parameter. + * + * @returns true if valid, false if not. + * + * @param pString The string buffer pointer. Can be NULL. + * @param cbBuf The buffer size from the parameter. + * @param fUtf8Not16 Set if UTF-8 encoding, clear if UTF-16 encoding. + */ +DECLINLINE(bool) ShflStringIsValidOrNullIn(PCSHFLSTRING pString, uint32_t cbBuf, bool fUtf8Not16) +{ + if (pString) + return ShflStringIsValidIn(pString, cbBuf, fUtf8Not16); + if (RT_LIKELY(cbBuf == 0)) + return true; + return false; +} + +/** Macro for passing as string as a HGCM parmeter (pointer) */ +#define SHFLSTRING_TO_HGMC_PARAM(a_pParam, a_pString) \ + do { \ + (a_pParam)->type = VBOX_HGCM_SVC_PARM_PTR; \ + (a_pParam)->u.pointer.addr = (a_pString); \ + (a_pParam)->u.pointer.size = ShflStringSizeOfBuffer(a_pString); \ + } while (0) + +/** @} */ + + +/** + * The available additional information in a SHFLFSOBJATTR object. + */ +typedef enum SHFLFSOBJATTRADD +{ + /** No additional information is available / requested. */ + SHFLFSOBJATTRADD_NOTHING = 1, + /** The additional unix attributes (SHFLFSOBJATTR::u::Unix) are + * available / requested. */ + SHFLFSOBJATTRADD_UNIX, + /** The additional extended attribute size (SHFLFSOBJATTR::u::EASize) is + * available / requested. */ + SHFLFSOBJATTRADD_EASIZE, + /** The last valid item (inclusive). + * The valid range is SHFLFSOBJATTRADD_NOTHING thru + * SHFLFSOBJATTRADD_LAST. */ + SHFLFSOBJATTRADD_LAST = SHFLFSOBJATTRADD_EASIZE, + + /** The usual 32-bit hack. */ + SHFLFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff +} SHFLFSOBJATTRADD; + + +/* Assert sizes of the IRPT types we're using below. */ +AssertCompileSize(RTFMODE, 4); +AssertCompileSize(RTFOFF, 8); +AssertCompileSize(RTINODE, 8); +AssertCompileSize(RTTIMESPEC, 8); +AssertCompileSize(RTDEV, 4); +AssertCompileSize(RTUID, 4); + +/** + * Shared folder filesystem object attributes. + */ +#pragma pack(1) +typedef struct SHFLFSOBJATTR +{ + /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*. + * @remarks We depend on a number of RTFS_ defines to remain unchanged. + * Fortuntately, these are depending on windows, dos and unix + * standard values, so this shouldn't be much of a pain. */ + RTFMODE fMode; + + /** The additional attributes available. */ + SHFLFSOBJATTRADD enmAdditional; + + /** + * Additional attributes. + * + * Unless explicitly specified to an API, the API can provide additional + * data as it is provided by the underlying OS. + */ + union SHFLFSOBJATTRUNION + { + /** Additional Unix Attributes + * These are available when SHFLFSOBJATTRADD is set in fUnix. + */ + struct SHFLFSOBJATTRUNIX + { + /** The user owning the filesystem object (st_uid). + * This field is ~0U if not supported. */ + RTUID uid; + + /** The group the filesystem object is assigned (st_gid). + * This field is ~0U if not supported. */ + RTGID gid; + + /** Number of hard links to this filesystem object (st_nlink). + * This field is 1 if the filesystem doesn't support hardlinking or + * the information isn't available. + */ + uint32_t cHardlinks; + + /** The device number of the device which this filesystem object resides on (st_dev). + * This field is 0 if this information is not available. */ + RTDEV INodeIdDevice; + + /** The unique identifier (within the filesystem) of this filesystem object (st_ino). + * Together with INodeIdDevice, this field can be used as a OS wide unique id + * when both their values are not 0. + * This field is 0 if the information is not available. */ + RTINODE INodeId; + + /** User flags (st_flags). + * This field is 0 if this information is not available. */ + uint32_t fFlags; + + /** The current generation number (st_gen). + * This field is 0 if this information is not available. */ + uint32_t GenerationId; + + /** The device number of a character or block device type object (st_rdev). + * This field is 0 if the file isn't of a character or block device type and + * when the OS doesn't subscribe to the major+minor device idenfication scheme. */ + RTDEV Device; + } Unix; + + /** + * Extended attribute size. + */ + struct SHFLFSOBJATTREASIZE + { + /** Size of EAs. */ + RTFOFF cb; + } EASize; + } u; +} SHFLFSOBJATTR; +#pragma pack() +AssertCompileSize(SHFLFSOBJATTR, 44); +/** Pointer to a shared folder filesystem object attributes structure. */ +typedef SHFLFSOBJATTR *PSHFLFSOBJATTR; +/** Pointer to a const shared folder filesystem object attributes structure. */ +typedef const SHFLFSOBJATTR *PCSHFLFSOBJATTR; + + +/** + * Filesystem object information structure. + */ +#pragma pack(1) +typedef struct SHFLFSOBJINFO +{ + /** Logical size (st_size). + * For normal files this is the size of the file. + * For symbolic links, this is the length of the path name contained + * in the symbolic link. + * For other objects this fields needs to be specified. + */ + RTFOFF cbObject; + + /** Disk allocation size (st_blocks * DEV_BSIZE). */ + RTFOFF cbAllocated; + + /** Time of last access (st_atime). + * @remarks Here (and other places) we depend on the IPRT timespec to + * remain unchanged. */ + RTTIMESPEC AccessTime; + + /** Time of last data modification (st_mtime). */ + RTTIMESPEC ModificationTime; + + /** Time of last status change (st_ctime). + * If not available this is set to ModificationTime. + */ + RTTIMESPEC ChangeTime; + + /** Time of file birth (st_birthtime). + * If not available this is set to ChangeTime. + */ + RTTIMESPEC BirthTime; + + /** Attributes. */ + SHFLFSOBJATTR Attr; + +} SHFLFSOBJINFO; +#pragma pack() +AssertCompileSize(SHFLFSOBJINFO, 92); +/** Pointer to a shared folder filesystem object information structure. */ +typedef SHFLFSOBJINFO *PSHFLFSOBJINFO; +/** Pointer to a const shared folder filesystem object information + * structure. */ +typedef const SHFLFSOBJINFO *PCSHFLFSOBJINFO; + + +/** + * Copy file system objinfo from IPRT to shared folder format. + * + * @param pDst The shared folder structure. + * @param pSrc The IPRT structure. + */ +DECLINLINE(void) vbfsCopyFsObjInfoFromIprt(PSHFLFSOBJINFO pDst, PCRTFSOBJINFO pSrc) +{ + pDst->cbObject = pSrc->cbObject; + pDst->cbAllocated = pSrc->cbAllocated; + pDst->AccessTime = pSrc->AccessTime; + pDst->ModificationTime = pSrc->ModificationTime; + pDst->ChangeTime = pSrc->ChangeTime; + pDst->BirthTime = pSrc->BirthTime; + pDst->Attr.fMode = pSrc->Attr.fMode; + /* Clear bits which we don't pass through for security reasons. */ + pDst->Attr.fMode &= ~(RTFS_UNIX_ISUID | RTFS_UNIX_ISGID | RTFS_UNIX_ISTXT); + RT_ZERO(pDst->Attr.u); + switch (pSrc->Attr.enmAdditional) + { + default: + case RTFSOBJATTRADD_NOTHING: + pDst->Attr.enmAdditional = SHFLFSOBJATTRADD_NOTHING; + break; + + case RTFSOBJATTRADD_UNIX: + pDst->Attr.enmAdditional = SHFLFSOBJATTRADD_UNIX; + pDst->Attr.u.Unix.uid = pSrc->Attr.u.Unix.uid; + pDst->Attr.u.Unix.gid = pSrc->Attr.u.Unix.gid; + pDst->Attr.u.Unix.cHardlinks = pSrc->Attr.u.Unix.cHardlinks; + pDst->Attr.u.Unix.INodeIdDevice = pSrc->Attr.u.Unix.INodeIdDevice; + pDst->Attr.u.Unix.INodeId = pSrc->Attr.u.Unix.INodeId; + pDst->Attr.u.Unix.fFlags = pSrc->Attr.u.Unix.fFlags; + pDst->Attr.u.Unix.GenerationId = pSrc->Attr.u.Unix.GenerationId; + pDst->Attr.u.Unix.Device = pSrc->Attr.u.Unix.Device; + break; + + case RTFSOBJATTRADD_EASIZE: + pDst->Attr.enmAdditional = SHFLFSOBJATTRADD_EASIZE; + pDst->Attr.u.EASize.cb = pSrc->Attr.u.EASize.cb; + break; + } +} + + +/** Result of an open/create request. + * Along with handle value the result code + * identifies what has happened while + * trying to open the object. + */ +typedef enum _SHFLCREATERESULT +{ + SHFL_NO_RESULT, + /** Specified path does not exist. */ + SHFL_PATH_NOT_FOUND, + /** Path to file exists, but the last component does not. */ + SHFL_FILE_NOT_FOUND, + /** File already exists and either has been opened or not. */ + SHFL_FILE_EXISTS, + /** New file was created. */ + SHFL_FILE_CREATED, + /** Existing file was replaced or overwritten. */ + SHFL_FILE_REPLACED, + /** Blow the type up to 32-bit. */ + SHFL_32BIT_HACK = 0x7fffffff +} SHFLCREATERESULT; +AssertCompile(SHFL_NO_RESULT == 0); +AssertCompileSize(SHFLCREATERESULT, 4); + + +/** @name Open/create flags. + * @{ + */ + +/** No flags. Initialization value. */ +#define SHFL_CF_NONE (0x00000000) + +/** Lookup only the object, do not return a handle. All other flags are ignored. */ +#define SHFL_CF_LOOKUP (0x00000001) + +/** Open parent directory of specified object. + * Useful for the corresponding Windows FSD flag + * and for opening paths like \\dir\\*.* to search the 'dir'. + * @todo possibly not needed??? + */ +#define SHFL_CF_OPEN_TARGET_DIRECTORY (0x00000002) + +/** Create/open a directory. */ +#define SHFL_CF_DIRECTORY (0x00000004) + +/** Open/create action to do if object exists + * and if the object does not exists. + * REPLACE file means atomically DELETE and CREATE. + * OVERWRITE file means truncating the file to 0 and + * setting new size. + * When opening an existing directory REPLACE and OVERWRITE + * actions are considered invalid, and cause returning + * FILE_EXISTS with NIL handle. + */ +#define SHFL_CF_ACT_MASK_IF_EXISTS (0x000000F0) +#define SHFL_CF_ACT_MASK_IF_NEW (0x00000F00) + +/** What to do if object exists. */ +#define SHFL_CF_ACT_OPEN_IF_EXISTS (0x00000000) +#define SHFL_CF_ACT_FAIL_IF_EXISTS (0x00000010) +#define SHFL_CF_ACT_REPLACE_IF_EXISTS (0x00000020) +#define SHFL_CF_ACT_OVERWRITE_IF_EXISTS (0x00000030) + +/** What to do if object does not exist. */ +#define SHFL_CF_ACT_CREATE_IF_NEW (0x00000000) +#define SHFL_CF_ACT_FAIL_IF_NEW (0x00000100) + +/** Read/write requested access for the object. */ +#define SHFL_CF_ACCESS_MASK_RW (0x00003000) + +/** No access requested. */ +#define SHFL_CF_ACCESS_NONE (0x00000000) +/** Read access requested. */ +#define SHFL_CF_ACCESS_READ (0x00001000) +/** Write access requested. */ +#define SHFL_CF_ACCESS_WRITE (0x00002000) +/** Read/Write access requested. */ +#define SHFL_CF_ACCESS_READWRITE (SHFL_CF_ACCESS_READ | SHFL_CF_ACCESS_WRITE) + +/** Requested share access for the object. */ +#define SHFL_CF_ACCESS_MASK_DENY (0x0000C000) + +/** Allow any access. */ +#define SHFL_CF_ACCESS_DENYNONE (0x00000000) +/** Do not allow read. */ +#define SHFL_CF_ACCESS_DENYREAD (0x00004000) +/** Do not allow write. */ +#define SHFL_CF_ACCESS_DENYWRITE (0x00008000) +/** Do not allow access. */ +#define SHFL_CF_ACCESS_DENYALL (SHFL_CF_ACCESS_DENYREAD | SHFL_CF_ACCESS_DENYWRITE) + +/** Requested access to attributes of the object. */ +#define SHFL_CF_ACCESS_MASK_ATTR (0x00030000) + +/** No access requested. */ +#define SHFL_CF_ACCESS_ATTR_NONE (0x00000000) +/** Read access requested. */ +#define SHFL_CF_ACCESS_ATTR_READ (0x00010000) +/** Write access requested. */ +#define SHFL_CF_ACCESS_ATTR_WRITE (0x00020000) +/** Read/Write access requested. */ +#define SHFL_CF_ACCESS_ATTR_READWRITE (SHFL_CF_ACCESS_ATTR_READ | SHFL_CF_ACCESS_ATTR_WRITE) + +/** The file is opened in append mode. Ignored if SHFL_CF_ACCESS_WRITE is not set. */ +#define SHFL_CF_ACCESS_APPEND (0x00040000) + +/** @} */ + +#pragma pack(1) +typedef struct _SHFLCREATEPARMS +{ + /* Returned handle of opened object. */ + SHFLHANDLE Handle; + + /* Returned result of the operation */ + SHFLCREATERESULT Result; + + /* SHFL_CF_* */ + uint32_t CreateFlags; + + /* Attributes of object to create and + * returned actual attributes of opened/created object. + */ + SHFLFSOBJINFO Info; + +} SHFLCREATEPARMS; +#pragma pack() + +typedef SHFLCREATEPARMS *PSHFLCREATEPARMS; + + +/** @name Shared Folders mappings. + * @{ + */ + +/** The mapping has been added since last query. */ +#define SHFL_MS_NEW (1) +/** The mapping has been deleted since last query. */ +#define SHFL_MS_DELETED (2) + +typedef struct _SHFLMAPPING +{ + /** Mapping status. + * @note Currently always set to SHFL_MS_NEW. */ + uint32_t u32Status; + /** Root handle. */ + SHFLROOT root; +} SHFLMAPPING; +/** Pointer to a SHFLMAPPING structure. */ +typedef SHFLMAPPING *PSHFLMAPPING; + +/** @} */ + + +/** @name Shared Folder directory information + * @{ + */ + +typedef struct _SHFLDIRINFO +{ + /** Full information about the object. */ + SHFLFSOBJINFO Info; + /** The length of the short field (number of RTUTF16 chars). + * It is 16-bit for reasons of alignment. */ + uint16_t cucShortName; + /** The short name for 8.3 compatibility. + * Empty string if not available. + */ + RTUTF16 uszShortName[14]; + /** @todo malc, a description, please. */ + SHFLSTRING name; +} SHFLDIRINFO, *PSHFLDIRINFO; + + +/** + * Shared folder filesystem properties. + */ +typedef struct SHFLFSPROPERTIES +{ + /** The maximum size of a filesystem object name. + * This does not include the '\\0'. */ + uint32_t cbMaxComponent; + + /** True if the filesystem is remote. + * False if the filesystem is local. */ + bool fRemote; + + /** True if the filesystem is case sensitive. + * False if the filesystem is case insensitive. */ + bool fCaseSensitive; + + /** True if the filesystem is mounted read only. + * False if the filesystem is mounted read write. */ + bool fReadOnly; + + /** True if the filesystem can encode unicode object names. + * False if it can't. */ + bool fSupportsUnicode; + + /** True if the filesystem is compresses. + * False if it isn't or we don't know. */ + bool fCompressed; + + /** True if the filesystem compresses of individual files. + * False if it doesn't or we don't know. */ + bool fFileCompression; + + /** @todo more? */ +} SHFLFSPROPERTIES; +AssertCompileSize(SHFLFSPROPERTIES, 12); +/** Pointer to a shared folder filesystem properties structure. */ +typedef SHFLFSPROPERTIES *PSHFLFSPROPERTIES; +/** Pointer to a const shared folder filesystem properties structure. */ +typedef SHFLFSPROPERTIES const *PCSHFLFSPROPERTIES; + + +/** + * Copy file system properties from IPRT to shared folder format. + * + * @param pDst The shared folder structure. + * @param pSrc The IPRT structure. + */ +DECLINLINE(void) vbfsCopyFsPropertiesFromIprt(PSHFLFSPROPERTIES pDst, PCRTFSPROPERTIES pSrc) +{ + RT_ZERO(*pDst); /* zap the implicit padding. */ + pDst->cbMaxComponent = pSrc->cbMaxComponent; + pDst->fRemote = pSrc->fRemote; + pDst->fCaseSensitive = pSrc->fCaseSensitive; + pDst->fReadOnly = pSrc->fReadOnly; + pDst->fSupportsUnicode = pSrc->fSupportsUnicode; + pDst->fCompressed = pSrc->fCompressed; + pDst->fFileCompression = pSrc->fFileCompression; +} + + +typedef struct _SHFLVOLINFO +{ + RTFOFF ullTotalAllocationBytes; + RTFOFF ullAvailableAllocationBytes; + uint32_t ulBytesPerAllocationUnit; + uint32_t ulBytesPerSector; + uint32_t ulSerial; + SHFLFSPROPERTIES fsProperties; +} SHFLVOLINFO, *PSHFLVOLINFO; + +/** @} */ + + +/** @defgroup grp_vbox_shfl_params Function parameter structures. + * @{ + */ + +/** @name SHFL_FN_QUERY_MAPPINGS + * @{ + */ +/** Validation mask. Needs to be adjusted + * whenever a new SHFL_MF_ flag is added. */ +#define SHFL_MF_MASK (0x00000011) +/** UTF-16 enconded strings. */ +#define SHFL_MF_UCS2 (0x00000000) +/** Guest uses UTF8 strings, if not set then the strings are unicode (UCS2). */ +#define SHFL_MF_UTF8 (0x00000001) +/** Just handle the auto-mounted folders. */ +#define SHFL_MF_AUTOMOUNT (0x00000010) + +/** Parameters structure. */ +typedef struct _VBoxSFQueryMappings +{ + VBGLIOCHGCMCALL callInfo; + + /** 32bit, in: + * Flags describing various client needs. + */ + HGCMFunctionParameter flags; + + /** 32bit, in/out: + * Number of mappings the client expects. + * This is the number of elements in the + * mappings array. + */ + HGCMFunctionParameter numberOfMappings; + + /** pointer, in/out: + * Points to array of SHFLMAPPING structures. + */ + HGCMFunctionParameter mappings; + +} VBoxSFQueryMappings; + +/** Number of parameters */ +#define SHFL_CPARMS_QUERY_MAPPINGS (3) +/** @} */ + + +/** @name SHFL_FN_QUERY_MAP_NAME + * @{ + */ + +/** Parameters structure. */ +typedef struct _VBoxSFQueryMapName +{ + VBGLIOCHGCMCALL callInfo; + + /** 32bit, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in/out: + * Points to SHFLSTRING buffer. + */ + HGCMFunctionParameter name; + +} VBoxSFQueryMapName; + +/** Number of parameters */ +#define SHFL_CPARMS_QUERY_MAP_NAME (2) +/** @} */ + + +/** @name SHFL_FN_MAP_FOLDER_OLD + * @{ + */ + +/** Parameters structure. */ +typedef struct _VBoxSFMapFolder_Old +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: + * Points to SHFLSTRING buffer. + */ + HGCMFunctionParameter path; + + /** pointer, out: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: RTUTF16 + * Path delimiter + */ + HGCMFunctionParameter delimiter; + +} VBoxSFMapFolder_Old; + +/** Number of parameters */ +#define SHFL_CPARMS_MAP_FOLDER_OLD (3) +/** @} */ + + +/** @name SHFL_FN_MAP_FOLDER + * @{ + */ + +/** SHFL_FN_MAP_FOLDER parameters. */ +typedef struct VBoxSFParmMapFolder +{ + /** pointer, in: SHFLSTRING with the name of the folder to map. */ + HGCMFunctionParameter pStrName; + /** value32, out: The root ID (SHFLROOT) of the mapping. */ + HGCMFunctionParameter id32Root; + /** value32, in: Path delimiter code point. */ + HGCMFunctionParameter uc32Delimiter; + /** value32, in: case senstive flag */ + HGCMFunctionParameter fCaseSensitive; +} VBoxSFParmMapFolder; + +/** Parameters structure. */ +typedef struct _VBoxSFMapFolder +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: + * Points to SHFLSTRING buffer. + */ + HGCMFunctionParameter path; + + /** pointer, out: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: RTUTF16 + * Path delimiter + */ + HGCMFunctionParameter delimiter; + + /** pointer, in: SHFLROOT + * Case senstive flag + */ + HGCMFunctionParameter fCaseSensitive; + +} VBoxSFMapFolder; + +/** Number of parameters */ +#define SHFL_CPARMS_MAP_FOLDER (4) +/** @} */ + + +/** @name SHFL_FN_UNMAP_FOLDER + * @{ + */ + +/** SHFL_FN_UNMAP_FOLDER parameters. */ +typedef struct VBoxSFParmUnmapFolder +{ + /** value32, in: SHFLROOT of the mapping to unmap */ + HGCMFunctionParameter id32Root; +} VBoxSFParmUnmapFolder; + +/** Parameters structure. */ +typedef struct _VBoxSFUnmapFolder +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + +} VBoxSFUnmapFolder; + +/** Number of parameters */ +#define SHFL_CPARMS_UNMAP_FOLDER (1) +/** @} */ + + +/** @name SHFL_FN_CREATE + * @{ + */ + +/** SHFL_FN_CREATE parameters. */ +typedef struct VBoxSFParmCreate +{ + /** value32, in: SHFLROOT + * Root handle of the mapping which name is queried. */ + HGCMFunctionParameter id32Root; + /** pointer, in: Points to SHFLSTRING buffer. */ + HGCMFunctionParameter pStrPath; + /** pointer, in/out: Points to SHFLCREATEPARMS buffer. */ + HGCMFunctionParameter pCreateParms; +} VBoxSFParmCreate; + +/** Parameters structure. */ +typedef struct _VBoxSFCreate +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: + * Points to SHFLSTRING buffer. + */ + HGCMFunctionParameter path; + + /** pointer, in/out: + * Points to SHFLCREATEPARMS buffer. + */ + HGCMFunctionParameter parms; + +} VBoxSFCreate; + +/** Number of parameters */ +#define SHFL_CPARMS_CREATE (3) +/** @} */ + + +/** @name SHFL_FN_CLOSE + * @{ + */ + +/** SHFL_FN_CLOSE parameters. */ +typedef struct VBoxSFParmClose +{ + /** value32, in: SHFLROOT of the mapping with the handle. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of object to close. */ + HGCMFunctionParameter u64Handle; +} VBoxSFParmClose; + +/** Parameters structure. */ +typedef struct _VBoxSFClose +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + + /** value64, in: + * SHFLHANDLE of object to close. + */ + HGCMFunctionParameter handle; + +} VBoxSFClose; + +/** Number of parameters */ +#define SHFL_CPARMS_CLOSE (2) +/** @} */ + + +/** @name SHFL_FN_READ + * @{ + */ + +/** SHFL_FN_READ parameters. */ +typedef struct VBoxSFParmRead +{ + /** value32, in: SHFLROOT of the mapping with the handle. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of object to read from . */ + HGCMFunctionParameter u64Handle; + /** value64, in: Offset to start reading from. */ + HGCMFunctionParameter off64Read; + /** value32, in/out: How much to try read / Actually read. */ + HGCMFunctionParameter cb32Read; + /** pointer, out: Buffer to return the data in. */ + HGCMFunctionParameter pBuf; +} VBoxSFParmRead; + +/** Parameters structure. */ +typedef struct _VBoxSFRead +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to read from. + */ + HGCMFunctionParameter handle; + + /** value64, in: + * Offset to read from. + */ + HGCMFunctionParameter offset; + + /** value64, in/out: + * Bytes to read/How many were read. + */ + HGCMFunctionParameter cb; + + /** pointer, out: + * Buffer to place data to. + */ + HGCMFunctionParameter buffer; + +} VBoxSFRead; + +/** Number of parameters */ +#define SHFL_CPARMS_READ (5) +/** @} */ + + +/** @name SHFL_FN_WRITE + * @{ + */ + +/** SHFL_FN_WRITE parameters. */ +typedef struct VBoxSFParmWrite +{ + /** value32, in: SHFLROOT of the mapping with the handle. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of object to write to. */ + HGCMFunctionParameter u64Handle; + /** value64, in/out: Offset to start writing at / New offset. + * @note The new offset isn't necessarily off + cb for files opened with + * SHFL_CF_ACCESS_APPEND since other parties (host programs, other VMs, + * other computers) could have extended the file since the last time the + * guest got a fresh size statistic. So, this helps the guest avoiding + * a stat call to check the actual size. */ + HGCMFunctionParameter off64Write; + /** value32, in/out: How much to try write / Actually written. */ + HGCMFunctionParameter cb32Write; + /** pointer, out: Buffer to return the data in. */ + HGCMFunctionParameter pBuf; +} VBoxSFParmWrite; + +/** Parameters structure. */ +typedef struct _VBoxSFWrite +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to write to. + */ + HGCMFunctionParameter handle; + + /** value64, in/out: + * Offset to write to/New offset. + * @note The new offset isn't necessarily off + cb for files opened with + * SHFL_CF_ACCESS_APPEND since other parties (host programs, other VMs, + * other computers) could have extended the file since the last time the + * guest got a fresh size statistic. So, this helps the guest avoiding + * a stat call to check the actual size. + */ + HGCMFunctionParameter offset; + + /** value64, in/out: + * Bytes to write/How many were written. + */ + HGCMFunctionParameter cb; + + /** pointer, in: + * Data to write. + */ + HGCMFunctionParameter buffer; + +} VBoxSFWrite; + +/** Number of parameters */ +#define SHFL_CPARMS_WRITE (5) +/** @} */ + + +/** @name SHFL_FN_LOCK + * @remarks Lock owner is the HGCM client. + * @{ + */ + +/** Lock mode bit mask. */ +#define SHFL_LOCK_MODE_MASK (0x3) +/** Cancel lock on the given range. */ +#define SHFL_LOCK_CANCEL (0x0) +/** Acquire read only lock. Prevent write to the range. */ +#define SHFL_LOCK_SHARED (0x1) +/** Acquire write lock. Prevent both write and read to the range. */ +#define SHFL_LOCK_EXCLUSIVE (0x2) + +/** Do not wait for lock if it can not be acquired at the time. */ +#define SHFL_LOCK_NOWAIT (0x0) +/** Wait and acquire lock. */ +#define SHFL_LOCK_WAIT (0x4) + +/** Lock the specified range. */ +#define SHFL_LOCK_PARTIAL (0x0) +/** Lock entire object. */ +#define SHFL_LOCK_ENTIRE (0x8) + +/** Parameters structure. */ +typedef struct _VBoxSFLock +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to be locked. + */ + HGCMFunctionParameter handle; + + /** value64, in: + * Starting offset of lock range. + */ + HGCMFunctionParameter offset; + + /** value64, in: + * Length of range. + */ + HGCMFunctionParameter length; + + /** value32, in: + * Lock flags SHFL_LOCK_*. + */ + HGCMFunctionParameter flags; + +} VBoxSFLock; + +/** Number of parameters */ +#define SHFL_CPARMS_LOCK (5) +/** @} */ + + +/** @name SHFL_FN_FLUSH + * @{ + */ + +/** SHFL_FN_FLUSH parameters. */ +typedef struct VBoxSFParmFlush +{ + /** value32, in: SHFLROOT of the mapping with the handle. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of object to flush. */ + HGCMFunctionParameter u64Handle; +} VBoxSFParmFlush; + +/** Parameters structure. */ +typedef struct _VBoxSFFlush +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to be locked. + */ + HGCMFunctionParameter handle; + +} VBoxSFFlush; + +/** Number of parameters */ +#define SHFL_CPARMS_FLUSH (2) +/** @} */ + + +/** @name SHFL_FN_SET_UTF8 + * @{ */ +/** NUmber of parameters for SHFL_FN_SET_UTF8. */ +#define SHFL_CPARMS_SET_UTF8 (0) +/** @} */ + + +/** @name SHFL_FN_LIST + * @remarks Listing information includes variable length RTDIRENTRY[EX] + * structures. + * @{ + */ + +/** @todo might be necessary for future. */ +#define SHFL_LIST_NONE 0 +#define SHFL_LIST_RETURN_ONE 1 +#define SHFL_LIST_RESTART 2 + +/** SHFL_FN_LIST parameters. */ +typedef struct VBoxSFParmList +{ + /** value32, in: SHFLROOT of the mapping the handle belongs to. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of the directory. */ + HGCMFunctionParameter u64Handle; + /** value32, in: List flags SHFL_LIST_XXX. */ + HGCMFunctionParameter f32Flags; + /** value32, in/out: Input buffer size / Returned bytes count. */ + HGCMFunctionParameter cb32Buffer; + /** pointer, in[optional]: SHFLSTRING filter string (full path). */ + HGCMFunctionParameter pStrFilter; + /** pointer, out: Buffer to return listing information in (SHFLDIRINFO). + * When SHFL_LIST_RETURN_ONE is not specfied, multiple record may be + * returned, deriving the entry size using SHFLDIRINFO::name.u16Size. */ + HGCMFunctionParameter pBuffer; + /** value32, out: Set to 0 if the listing is done, 1 if there are more entries. + * @note Must be set to zero on call as it was declared in/out parameter and + * may be used as such again. */ + HGCMFunctionParameter f32More; + /** value32, out: Number of entries returned. */ + HGCMFunctionParameter c32Entries; +} VBoxSFParmList; + + +/** Parameters structure. */ +typedef struct _VBoxSFList +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to be listed. + */ + HGCMFunctionParameter handle; + + /** value32, in: + * List flags SHFL_LIST_*. + */ + HGCMFunctionParameter flags; + + /** value32, in/out: + * Bytes to be used for listing information/How many bytes were used. + */ + HGCMFunctionParameter cb; + + /** pointer, in/optional + * Points to SHFLSTRING buffer that specifies a search path. + */ + HGCMFunctionParameter path; + + /** pointer, out: + * Buffer to place listing information to. (SHFLDIRINFO) + */ + HGCMFunctionParameter buffer; + + /** value32, in/out: + * Indicates a key where the listing must be resumed. + * in: 0 means start from begin of object. + * out: 0 means listing completed. + */ + HGCMFunctionParameter resumePoint; + + /** pointer, out: + * Number of files returned + */ + HGCMFunctionParameter cFiles; + +} VBoxSFList; + +/** Number of parameters */ +#define SHFL_CPARMS_LIST (8) +/** @} */ + + +/** @name SHFL_FN_READLINK + * @{ + */ + +/** SHFL_FN_READLINK parameters. */ +typedef struct VBoxSFParmReadLink +{ + /** value32, in: SHFLROOT of the mapping which the symlink is read. */ + HGCMFunctionParameter id32Root; + /** pointer, in: SHFLSTRING full path to the symlink. */ + HGCMFunctionParameter pStrPath; + /** pointer, out: Buffer to place the symlink target into. + * @note Buffer contains UTF-8 characters on success, regardless of the + * UTF-8/UTF-16 setting of the connection. Will be zero terminated. + * + * @todo r=bird: This should've been a string! + * @todo r=bird: There should've been a byte count returned! */ + HGCMFunctionParameter pBuffer; +} VBoxSFParmReadLink; + +/** Parameters structure. */ +typedef struct _VBoxSFReadLink +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: + * Points to SHFLSTRING buffer. + */ + HGCMFunctionParameter path; + + /** pointer, out: + * Buffer to place data to. + * @note Buffer contains UTF-8 characters on success, regardless of the + * UTF-8/UTF-16 setting of the connection. Will be zero terminated. + */ + HGCMFunctionParameter buffer; + +} VBoxSFReadLink; + +/** Number of parameters */ +#define SHFL_CPARMS_READLINK (3) +/** @} */ + + +/** @name SHFL_FN_INFORMATION + * @{ + */ + +/** Mask of Set/Get bit. */ +#define SHFL_INFO_MODE_MASK (0x1) +/** Get information */ +#define SHFL_INFO_GET (0x0) +/** Set information */ +#define SHFL_INFO_SET (0x1) + +/** Get name of the object. */ +#define SHFL_INFO_NAME (0x2) +/** Set size of object (extend/trucate); only applies to file objects */ +#define SHFL_INFO_SIZE (0x4) +/** Get/Set file object info. */ +#define SHFL_INFO_FILE (0x8) +/** Get volume information. */ +#define SHFL_INFO_VOLUME (0x10) + +/** @todo different file info structures */ + +/** SHFL_FN_INFORMATION parameters. */ +typedef struct VBoxSFParmInformation +{ + /** value32, in: SHFLROOT of the mapping the handle belongs to. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of object to be queried/set. */ + HGCMFunctionParameter u64Handle; + /** value32, in: SHFL_INFO_XXX */ + HGCMFunctionParameter f32Flags; + /** value32, in/out: Bytes to be used for information/How many bytes were used. */ + HGCMFunctionParameter cb32; + /** pointer, in/out: Information to be set/get (SHFLFSOBJINFO, SHFLVOLINFO, or SHFLSTRING). + * Do not forget to set the SHFLFSOBJINFO::Attr::enmAdditional for Get operation as well. */ + HGCMFunctionParameter pInfo; +} VBoxSFParmInformation; + + +/** Parameters structure. */ +typedef struct _VBoxSFInformation +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to be listed. + */ + HGCMFunctionParameter handle; + + /** value32, in: + * SHFL_INFO_* + */ + HGCMFunctionParameter flags; + + /** value32, in/out: + * Bytes to be used for information/How many bytes were used. + */ + HGCMFunctionParameter cb; + + /** pointer, in/out: + * Information to be set/get (SHFLFSOBJINFO or SHFLSTRING). Do not forget + * to set the SHFLFSOBJINFO::Attr::enmAdditional for Get operation as well. + */ + HGCMFunctionParameter info; + +} VBoxSFInformation; + +/** Number of parameters */ +#define SHFL_CPARMS_INFORMATION (5) +/** @} */ + + +/** @name SHFL_FN_REMOVE + * @{ + */ + +#define SHFL_REMOVE_FILE (0x1) +#define SHFL_REMOVE_DIR (0x2) +#define SHFL_REMOVE_SYMLINK (0x4) + +/** SHFL_FN_REMOVE parameters. */ +typedef struct VBoxSFParmRemove +{ + /** value32, in: SHFLROOT of the mapping the path is relative to. */ + HGCMFunctionParameter id32Root; + /** pointer, in: Points to SHFLSTRING buffer. */ + HGCMFunctionParameter pStrPath; + /** value32, in: SHFL_REMOVE_XXX */ + HGCMFunctionParameter f32Flags; +} VBoxSFParmRemove; + +/** Parameters structure. */ +typedef struct _VBoxSFRemove +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: + * Points to SHFLSTRING buffer. + */ + HGCMFunctionParameter path; + + /** value32, in: + * remove flags (file/directory) + */ + HGCMFunctionParameter flags; + +} VBoxSFRemove; + +#define SHFL_CPARMS_REMOVE (3) +/** @} */ + + +/** @name SHFL_FN_CLOSE_AND_REMOVE + * Extends SHFL_FN_REMOVE with a 4th handle parameter that can be nil. + * @{ + */ +/** SHFL_FN_CLOSE_AND_REMOVE parameters. */ +typedef struct VBoxSFParmCloseAndRemove +{ + /** value32, in: SHFLROOT of the mapping the path is relative to. */ + HGCMFunctionParameter id32Root; + /** pointer, in: Points to SHFLSTRING buffer. */ + HGCMFunctionParameter pStrPath; + /** value32, in: SHFL_REMOVE_XXX */ + HGCMFunctionParameter f32Flags; + /** value64, in: SHFLHANDLE to the object to be removed & close, optional. */ + HGCMFunctionParameter u64Handle; +} VBoxSFParmCloseAndRemove; +/** Number of parameters */ +#define SHFL_CPARMS_CLOSE_AND_REMOVE (4) +AssertCompileSize(VBoxSFParmCloseAndRemove, SHFL_CPARMS_CLOSE_AND_REMOVE * sizeof(HGCMFunctionParameter)); +/** @} */ + + +/** @name SHFL_FN_RENAME + * @{ + */ + +#define SHFL_RENAME_FILE (0x1) +#define SHFL_RENAME_DIR (0x2) +#define SHFL_RENAME_REPLACE_IF_EXISTS (0x4) + +/** SHFL_FN_RENAME parameters. */ +typedef struct VBoxSFParmRename +{ + /** value32, in: SHFLROOT of the mapping the paths are relative to. */ + HGCMFunctionParameter id32Root; + /** pointer, in: SHFLSTRING giving the source (old) path. */ + HGCMFunctionParameter pStrSrcPath; + /** pointer, in: SHFLSTRING giving the destination (new) path. */ + HGCMFunctionParameter pStrDstPath; + /** value32, in: SHFL_RENAME_XXX */ + HGCMFunctionParameter f32Flags; +} VBoxSFParmRename; + +/** Parameters structure. */ +typedef struct _VBoxSFRename +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: + * Points to SHFLSTRING src. + */ + HGCMFunctionParameter src; + + /** pointer, in: + * Points to SHFLSTRING dest. + */ + HGCMFunctionParameter dest; + + /** value32, in: + * rename flags (file/directory) + */ + HGCMFunctionParameter flags; + +} VBoxSFRename; + +#define SHFL_CPARMS_RENAME (4) +/** @} */ + + +/** @name SHFL_FN_SYMLINK + * @{ + */ + +/** Parameters structure. */ +typedef struct VBoxSFParmCreateSymlink +{ + /** value32, in: SHFLROOT of the mapping the symlink should be created on. */ + HGCMFunctionParameter id32Root; + /** pointer, in: SHFLSTRING giving the path to the symlink. */ + HGCMFunctionParameter pStrSymlink; + /** pointer, in: SHFLSTRING giving the target. */ + HGCMFunctionParameter pStrTarget; + /** pointer, out: SHFLFSOBJINFO buffer to be filled with info about the created symlink. */ + HGCMFunctionParameter pInfo; +} VBoxSFParmCreateSymlink; + +/** Parameters structure. */ +typedef struct _VBoxSFSymlink +{ + VBGLIOCHGCMCALL callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** pointer, in: + * Points to SHFLSTRING of path for the new symlink. + */ + HGCMFunctionParameter newPath; + + /** pointer, in: + * Points to SHFLSTRING of destination for symlink. + */ + HGCMFunctionParameter oldPath; + + /** pointer, out: + * Information about created symlink. + */ + HGCMFunctionParameter info; + +} VBoxSFSymlink; + +#define SHFL_CPARMS_SYMLINK (4) +/** @} */ + + +/** @name SHFL_FN_SET_SYMLINKS + * @{ */ +/** NUmber of parameters for SHFL_FN_SET_SYMLINKS. */ +#define SHFL_CPARMS_SET_SYMLINKS (0) +/** @} */ + + +/** @name SHFL_FN_QUERY_MAP_INFO + * @{ + */ +/** Query flag: Guest prefers drive letters as mount points. */ +#define SHFL_MIQF_DRIVE_LETTER RT_BIT_64(0) +/** Query flag: Guest prefers paths as mount points. */ +#define SHFL_MIQF_PATH RT_BIT_64(1) + +/** Set if writable. */ +#define SHFL_MIF_WRITABLE RT_BIT_64(0) +/** Indicates that the mapping should be auto-mounted. */ +#define SHFL_MIF_AUTO_MOUNT RT_BIT_64(1) +/** Set if host is case insensitive. */ +#define SHFL_MIF_HOST_ICASE RT_BIT_64(2) +/** Set if guest is case insensitive. */ +#define SHFL_MIF_GUEST_ICASE RT_BIT_64(3) +/** Symbolic link creation is allowed. */ +#define SHFL_MIF_SYMLINK_CREATION RT_BIT_64(4) + +/** Parameters structure. */ +typedef struct VBoxSFQueryMapInfo +{ + /** Common header. */ + VBGLIOCHGCMCALL callInfo; + /** 32-bit, in: SHFLROOT - root handle of the mapping to query. */ + HGCMFunctionParameter root; + /** pointer, in/out: SHFLSTRING buffer for the name. */ + HGCMFunctionParameter name; + /** pointer, in/out: SHFLSTRING buffer for the auto mount point. */ + HGCMFunctionParameter mountPoint; + /** 64-bit, in: SHFL_MIQF_XXX; out: SHFL_MIF_XXX. */ + HGCMFunctionParameter flags; + /** 32-bit, out: Root ID version number - root handle reuse guard. */ + HGCMFunctionParameter rootIdVersion; +} VBoxSFQueryMapInfo; +/** Number of parameters */ +#define SHFL_CPARMS_QUERY_MAP_INFO (5) +/** @} */ + + +/** @name SHFL_FN_WAIT_FOR_MAPPINGS_CHANGES + * + * Returns VINF_SUCCESS on change and VINF_TRY_AGAIN when restored from saved + * state. If the guest makes too many calls (max 64) VERR_OUT_OF_RESOURCES will + * be returned. + * + * @{ + */ +/** Parameters structure. */ +typedef struct VBoxSFWaitForMappingsChanges +{ + /** Common header. */ + VBGLIOCHGCMCALL callInfo; + /** 32-bit, in/out: The mappings configuration version. + * On input the client sets it to the last config it knows about, on return + * it holds the current version. */ + HGCMFunctionParameter version; +} VBoxSFWaitForMappingsChanges; +/** Number of parameters */ +#define SHFL_CPARMS_WAIT_FOR_MAPPINGS_CHANGES (1) +/** @} */ + + +/** @name SHFL_FN_CANCEL_MAPPINGS_CHANGES_WAITS + * @{ + */ +/** Number of parameters */ +#define SHFL_CPARMS_CANCEL_MAPPINGS_CHANGES_WAITS (0) +/** @} */ + + +/** @name SHFL_FN_SET_FILE_SIZE + * @{ + */ +/** SHFL_FN_SET_FILE_SIZE parameters. */ +typedef struct VBoxSFParmSetFileSize +{ + /** value32, in: SHFLROOT of the mapping the handle belongs to. */ + HGCMFunctionParameter id32Root; + /** value64, in: SHFLHANDLE of the file to change the size of. */ + HGCMFunctionParameter u64Handle; + /** value64, in: The new file size. */ + HGCMFunctionParameter cb64NewSize; +} VBoxSFParmSetFileSize; +/** Number of parameters */ +#define SHFL_CPARMS_SET_FILE_SIZE (3) +/** @} */ + + +/** @name SHFL_FN_QUERY_FEATURES + * @{ */ +/** SHFL_FN_QUERY_FEATURES parameters. */ +typedef struct VBoxSFParmQueryFeatures +{ + /** value64, out: Feature flags, SHFL_FEATURE_XXX. */ + HGCMFunctionParameter f64Features; + /** value32, out: The ordinal of the last valid function */ + HGCMFunctionParameter u32LastFunction; +} VBoxSFParmQueryFeatures; +/** Number of parameters for SHFL_FN_QUERY_FEATURES. */ +#define SHFL_CPARMS_QUERY_FEATURES (2) + +/** The write functions updates the file offset upon return. + * This can be helpful for files open in append mode. */ +#define SHFL_FEATURE_WRITE_UPDATES_OFFSET RT_BIT_64(0) +/** @} */ + + +/** @name SHFL_FN_COPY_FILE + * @{ */ +/** SHFL_FN_COPY_FILE parameters. */ +typedef struct VBoxSFParmCopyFile +{ + /** value32, in: SHFLROOT of the mapping the source handle belongs to. */ + HGCMFunctionParameter id32RootSrc; + /** pointer, in: SHFLSTRING giving the source file path. */ + HGCMFunctionParameter pStrPathSrc; + + /** value32, in: SHFLROOT of the mapping the destination handle belongs to. */ + HGCMFunctionParameter id32RootDst; + /** pointer, in: SHFLSTRING giving the destination file path. */ + HGCMFunctionParameter pStrPathDst; + + /** value32, in: Reserved for the future, must be zero. */ + HGCMFunctionParameter f32Flags; +} VBoxSFParmCopyFile; +/** Number of parameters for SHFL_FN_COPY_FILE. */ +#define SHFL_CPARMS_COPY_FILE (5) +/** @} */ + + +/** @name SHFL_FN_COPY_FILE_PART + * @{ */ +/** SHFL_FN_COPY_FILE_PART parameters. */ +typedef struct VBoxSFParmCopyFilePart +{ + /** value32, in: SHFLROOT of the mapping the source handle belongs to. */ + HGCMFunctionParameter id32RootSrc; + /** value64, in: SHFLHANDLE of the source file. */ + HGCMFunctionParameter u64HandleSrc; + /** value64, in: The source file offset. */ + HGCMFunctionParameter off64Src; + + /** value32, in: SHFLROOT of the mapping the destination handle belongs to. */ + HGCMFunctionParameter id32RootDst; + /** value64, in: SHFLHANDLE of the destination file. */ + HGCMFunctionParameter u64HandleDst; + /** value64, in: The destination file offset. */ + HGCMFunctionParameter off64Dst; + + /** value64, in/out: The number of bytes to copy on input / bytes actually copied. */ + HGCMFunctionParameter cb64ToCopy; + /** value32, in: Reserved for the future, must be zero. */ + HGCMFunctionParameter f32Flags; +} VBoxSFParmCopyFilePart; +/** Number of parameters for SHFL_FN_COPY_FILE_PART. */ +#define SHFL_CPARMS_COPY_FILE_PART (8) +/** @} */ + + +/** @name SHFL_FN_SET_ERROR_STYLE + * @{ */ +/** The defined error styles. */ +typedef enum SHFLERRORSTYLE +{ + kShflErrorStyle_Invalid = 0, + kShflErrorStyle_Windows, + kShflErrorStyle_Linux, + kShflErrorStyle_End, + kShflErrorStyle_32BitHack = 0x7fffffff +} SHFLERRORSTYLE; +/** The native error style. */ +#if defined(RT_OS_WINDOWS) || defined(RT_OS_OS2) +# define SHFLERRORSTYLE_NATIVE kShflErrorStyle_Windows +#else +# define SHFLERRORSTYLE_NATIVE kShflErrorStyle_Linux +#endif + +/** SHFL_FN_SET_ERROR_STYLE parameters. */ +typedef struct VBoxSFParmSetErrorStyle +{ + /** value32, in: The style, SHFLERRORSTYLE. */ + HGCMFunctionParameter u32Style; + /** value32, in: Reserved for the future, must be zero. */ + HGCMFunctionParameter u32Reserved; +} VBoxSFParmSetErrorStyle; +/** Number of parameters for SHFL_FN_SET_ERROR_STYLE. */ +#define SHFL_CPARMS_SET_ERROR_STYLE (2) +/** @} */ + + +/** @name SHFL_FN_ADD_MAPPING + * @note Host call, no guest structure is used. + * @{ + */ + +/** mapping is writable */ +#define SHFL_ADD_MAPPING_F_WRITABLE (RT_BIT_32(0)) +/** mapping is automounted by the guest */ +#define SHFL_ADD_MAPPING_F_AUTOMOUNT (RT_BIT_32(1)) +/** allow the guest to create symlinks */ +#define SHFL_ADD_MAPPING_F_CREATE_SYMLINKS (RT_BIT_32(2)) +/** mapping is actually missing on the host */ +#define SHFL_ADD_MAPPING_F_MISSING (RT_BIT_32(3)) + +#define SHFL_CPARMS_ADD_MAPPING (4) +/** @} */ + + +/** @name SHFL_FN_REMOVE_MAPPING + * @note Host call, no guest structure is used. + * @{ + */ + +#define SHFL_CPARMS_REMOVE_MAPPING (1) +/** @} */ + + +/** @name SHFL_FN_SET_STATUS_LED + * @note Host call, no guest structure is used. + * @{ + */ + +#define SHFL_CPARMS_SET_STATUS_LED (1) +/** @} */ + + +/** @} */ +/** @} */ + +#endif /* !VBOX_INCLUDED_shflsvc_h */ + |