source: vbox/trunk/include/VBox/shflsvc.h@ 78570

/** @file
 * Shared Folders - Common header for host service and guest clients.
 */

/*
 * Copyright (C) 2006-2019 Oracle Corporation
 *
 * 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)
/** The last function number. */
#define SHFL_FN_LAST                SHFL_FN_CLOSE_AND_REMOVE
/** @} */


/** @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 VBoxSFParmCopyFilePar
{
    /** 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_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 */