Index: /trunk/include/VBox/shflsvc.h =================================================================== --- /trunk/include/VBox/shflsvc.h (revision 75382) +++ /trunk/include/VBox/shflsvc.h (revision 75383) @@ -1,4 +1,4 @@ /** @file - * Shared Folders: Common header for host service and guest clients. + * Shared Folders - Common header for host service and guest clients. */ @@ -45,4 +45,17 @@ + +/** @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. * @{ */ @@ -61,21 +74,7 @@ -/** - * 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. - */ - -/** Shared Folders service functions. (guest) - * @{ - */ - +/** @name Shared Folders service functions. (guest) + * @{ + */ /** Query mappings changes. */ #define SHFL_FN_QUERY_MAPPINGS (1) @@ -116,11 +115,10 @@ /** Ask host to show symlinks (as of VBox 4.0) */ #define SHFL_FN_SET_SYMLINKS (20) - -/** @} */ +/** @} */ + /** Shared Folders service functions. (host) - * @{ - */ - + * @{ + */ /** Add shared folder mapping. */ #define SHFL_FN_ADD_MAPPING (1) @@ -133,14 +131,15 @@ /** @} */ + /** 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. + * + * @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) @@ -156,4 +155,5 @@ /** 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. @@ -681,5 +681,5 @@ -/** Open/create flags. +/** @name Open/create flags. * @{ */ @@ -787,6 +787,6 @@ -/** Shared Folders mappings. - * @{ +/** @name Shared Folders mappings. + * @{ */ @@ -808,6 +808,7 @@ /** @} */ -/** Shared Folder directory information - * @{ + +/** @name Shared Folder directory information + * @{ */ @@ -901,15 +902,16 @@ /** @} */ -/** Function parameter structures. - * @{ - */ - -/** - * SHFL_FN_QUERY_MAPPINGS + +/** @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) -/** UC2 enconded strings. */ +/** UTF-16 enconded strings. */ #define SHFL_MF_UCS2 (0x00000000) /** Guest uses UTF8 strings, if not set then the strings are unicode (UCS2). */ @@ -918,10 +920,4 @@ #define SHFL_MF_AUTOMOUNT (0x00000010) -/** Type of guest system. For future system dependent features. */ -#define SHFL_MF_SYSTEM_MASK (0x0000FF00) -#define SHFL_MF_SYSTEM_NONE (0x00000000) -#define SHFL_MF_SYSTEM_WINDOWS (0x00000100) -#define SHFL_MF_SYSTEM_LINUX (0x00000200) - /** Parameters structure. */ typedef struct _VBoxSFQueryMappings @@ -950,9 +946,9 @@ /** Number of parameters */ #define SHFL_CPARMS_QUERY_MAPPINGS (3) - - - -/** - * SHFL_FN_QUERY_MAP_NAME +/** @} */ + + +/** @name SHFL_FN_QUERY_MAP_NAME + * @{ */ @@ -976,7 +972,9 @@ /** Number of parameters */ #define SHFL_CPARMS_QUERY_MAP_NAME (2) - -/** - * SHFL_FN_MAP_FOLDER_OLD +/** @} */ + + +/** @name SHFL_FN_MAP_FOLDER_OLD + * @{ */ @@ -1005,7 +1003,9 @@ /** Number of parameters */ #define SHFL_CPARMS_MAP_FOLDER_OLD (3) - -/** - * SHFL_FN_MAP_FOLDER +/** @} */ + + +/** @name SHFL_FN_MAP_FOLDER + * @{ */ @@ -1039,7 +1039,9 @@ /** Number of parameters */ #define SHFL_CPARMS_MAP_FOLDER (4) - -/** - * SHFL_FN_UNMAP_FOLDER +/** @} */ + + +/** @name SHFL_FN_UNMAP_FOLDER + * @{ */ @@ -1058,8 +1060,9 @@ /** Number of parameters */ #define SHFL_CPARMS_UNMAP_FOLDER (1) - - -/** - * SHFL_FN_CREATE +/** @} */ + + +/** @name SHFL_FN_CREATE + * @{ */ @@ -1088,8 +1091,9 @@ /** Number of parameters */ #define SHFL_CPARMS_CREATE (3) - - -/** - * SHFL_FN_CLOSE +/** @} */ + + +/** @name SHFL_FN_CLOSE + * @{ */ @@ -1114,8 +1118,9 @@ /** Number of parameters */ #define SHFL_CPARMS_CLOSE (2) - - -/** - * SHFL_FN_READ +/** @} */ + + +/** @name SHFL_FN_READ + * @{ */ @@ -1154,9 +1159,9 @@ /** Number of parameters */ #define SHFL_CPARMS_READ (5) - - - -/** - * SHFL_FN_WRITE +/** @} */ + + +/** @name SHFL_FN_WRITE + * @{ */ @@ -1195,12 +1200,11 @@ /** Number of parameters */ #define SHFL_CPARMS_WRITE (5) - - - -/** - * SHFL_FN_LOCK - */ - -/** Lock owner is the HGCM client. */ +/** @} */ + + +/** @name SHFL_FN_LOCK + * @remarks Lock owner is the HGCM client. + * @{ + */ /** Lock mode bit mask. */ @@ -1257,9 +1261,9 @@ /** Number of parameters */ #define SHFL_CPARMS_LOCK (5) - - - -/** - * SHFL_FN_FLUSH +/** @} */ + + +/** @name SHFL_FN_FLUSH + * @{ */ @@ -1283,14 +1287,16 @@ /** Number of parameters */ #define SHFL_CPARMS_FLUSH (2) - -/** - * SHFL_FN_LIST - */ - -/** Listing information includes variable length RTDIRENTRY[EX] structures. */ +/** @} */ + + +/** @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_RETURN_ONE 1 /** Parameters structure. */ @@ -1345,9 +1351,9 @@ /** Number of parameters */ #define SHFL_CPARMS_LIST (8) - - - -/** - * SHFL_FN_READLINK +/** @} */ + + +/** @name SHFL_FN_READLINK + * @{ */ @@ -1376,9 +1382,9 @@ /** Number of parameters */ #define SHFL_CPARMS_READLINK (3) - - - -/** - * SHFL_FN_INFORMATION +/** @} */ + + +/** @name SHFL_FN_INFORMATION + * @{ */ @@ -1437,8 +1443,9 @@ /** Number of parameters */ #define SHFL_CPARMS_INFORMATION (5) - - -/** - * SHFL_FN_REMOVE +/** @} */ + + +/** @name SHFL_FN_REMOVE + * @{ */ @@ -1470,8 +1477,9 @@ #define SHFL_CPARMS_REMOVE (3) - - -/** - * SHFL_FN_RENAME +/** @} */ + + +/** @name SHFL_FN_RENAME + * @{ */ @@ -1508,8 +1516,9 @@ #define SHFL_CPARMS_RENAME (4) - - -/** - * SHFL_FN_SYMLINK +/** @} */ + + +/** @name SHFL_FN_SYMLINK + * @{ */ @@ -1542,10 +1551,11 @@ #define SHFL_CPARMS_SYMLINK (4) - - - -/** - * SHFL_FN_ADD_MAPPING - * Host call, no guest structure is used. +/** @} */ + + + +/** @name SHFL_FN_ADD_MAPPING + * @note Host call, no guest structure is used. + * @{ */ @@ -1560,20 +1570,26 @@ #define SHFL_CPARMS_ADD_MAPPING (4) - -/** - * SHFL_FN_REMOVE_MAPPING - * Host call, no guest structure is used. +/** @} */ + + +/** @name SHFL_FN_REMOVE_MAPPING + * @note Host call, no guest structure is used. + * @{ */ #define SHFL_CPARMS_REMOVE_MAPPING (1) - - -/** - * SHFL_FN_SET_STATUS_LED - * Host call, no guest structure is used. +/** @} */ + + +/** @name SHFL_FN_SET_STATUS_LED + * @note Host call, no guest structure is used. + * @{ */ #define SHFL_CPARMS_SET_STATUS_LED (1) - +/** @} */ + + +/** @} */ /** @} */