diff options
Diffstat (limited to 'include/VBox/VBoxGuestCoreTypes.h')
| -rw-r--r-- | include/VBox/VBoxGuestCoreTypes.h | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/include/VBox/VBoxGuestCoreTypes.h b/include/VBox/VBoxGuestCoreTypes.h new file mode 100644 index 00000000..0d820aab --- /dev/null +++ b/include/VBox/VBoxGuestCoreTypes.h @@ -0,0 +1,238 @@ +/** @file + * VBoxGuest - VirtualBox Guest Additions, Core Types. + * + * This contains types that are used both in the VBoxGuest I/O control interface + * and the VBoxGuestLib. The goal is to avoid having to include VBoxGuest.h + * everwhere VBoxGuestLib.h is used. + */ + +/* + * Copyright (C) 2006-2022 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_VBoxGuestCoreTypes_h +#define VBOX_INCLUDED_VBoxGuestCoreTypes_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <iprt/types.h> +#include <iprt/assertcompile.h> + +/** @addtogroup grp_vboxguest + * @{ */ + +/** + * Common in/out header. + * + * This is a copy/mirror of VMMDevRequestHeader to prevent duplicating data and + * needing to verify things multiple times. For that reason this differs a bit + * from SUPREQHDR. + * + * @sa VMMDevRequestHeader + */ +typedef struct VBGLREQHDR +{ + /** IN: The request input size, and output size if cbOut is zero. + * @sa VMMDevRequestHeader::size */ + uint32_t cbIn; + /** IN: Structure version (VBGLREQHDR_VERSION) + * @sa VMMDevRequestHeader::version */ + uint32_t uVersion; + /** IN: The VMMDev request type, set to VBGLREQHDR_TYPE_DEFAULT unless this is a + * kind of VMMDev request. + * @sa VMMDevRequestType, VMMDevRequestHeader::requestType */ + uint32_t uType; + /** OUT: The VBox status code of the operation, out direction only. */ + int32_t rc; + /** IN: The output size. This is optional - set to zero to use cbIn as the + * output size. */ + uint32_t cbOut; + /** Reserved / filled in by kernel, MBZ. + * @sa VMMDevRequestHeader::fRequestor */ + uint32_t uReserved; +} VBGLREQHDR; +AssertCompileSize(VBGLREQHDR, 24); +/** Pointer to a IOC header. */ +typedef VBGLREQHDR RT_FAR *PVBGLREQHDR; + +/** Version of VMMDevRequestHeader structure. */ +#define VBGLREQHDR_VERSION UINT32_C(0x10001) +/** Default request type. Use this for non-VMMDev requests. */ +#define VBGLREQHDR_TYPE_DEFAULT UINT32_C(0) + +/** Initialize a VBGLREQHDR structure for a fixed size I/O control call. + * @param a_pHdr Pointer to the header to initialize. + * @param a_IOCtl The base I/O control name, no VBGL_IOCTL_ prefix. We + * have to skip the prefix to avoid it getting expanded + * before we append _SIZE_IN and _SIZE_OUT to it. + */ +#define VBGLREQHDR_INIT(a_pHdr, a_IOCtl) \ + VBGLREQHDR_INIT_EX(a_pHdr, RT_CONCAT3(VBGL_IOCTL_,a_IOCtl,_SIZE_IN), RT_CONCAT3(VBGL_IOCTL_,a_IOCtl,_SIZE_OUT)) +/** Initialize a VBGLREQHDR structure, extended version. */ +#define VBGLREQHDR_INIT_EX(a_pHdr, a_cbIn, a_cbOut) \ + do { \ + (a_pHdr)->cbIn = (uint32_t)(a_cbIn); \ + (a_pHdr)->uVersion = VBGLREQHDR_VERSION; \ + (a_pHdr)->uType = VBGLREQHDR_TYPE_DEFAULT; \ + (a_pHdr)->rc = VERR_INTERNAL_ERROR; \ + (a_pHdr)->cbOut = (uint32_t)(a_cbOut); \ + (a_pHdr)->uReserved = 0; \ + } while (0) +/** Initialize a VBGLREQHDR structure for a VMMDev request. + * Same as VMMDEV_REQ_HDR_INIT(). */ +#define VBGLREQHDR_INIT_VMMDEV(a_pHdr, a_cb, a_enmType) \ + do { \ + (a_pHdr)->cbIn = (a_cb); \ + (a_pHdr)->uVersion = VBGLREQHDR_VERSION; \ + (a_pHdr)->uType = (a_enmType); \ + (a_pHdr)->rc = VERR_INTERNAL_ERROR; \ + (a_pHdr)->cbOut = 0; \ + (a_pHdr)->uReserved = 0; \ + } while (0) + + +/** + * For VBGL_IOCTL_HGCM_CALL and VBGL_IOCTL_HGCM_CALL_WITH_USER_DATA. + * + * @note This is used by alot of HGCM call structures. + */ +typedef struct VBGLIOCHGCMCALL +{ + /** Common header. */ + VBGLREQHDR Hdr; + /** Input: The id of the caller. */ + uint32_t u32ClientID; + /** Input: Function number. */ + uint32_t u32Function; + /** Input: How long to wait (milliseconds) for completion before cancelling the + * call. This is ignored if not a VBGL_IOCTL_HGCM_CALL_TIMED or + * VBGL_IOCTL_HGCM_CALL_TIMED_32 request. */ + uint32_t cMsTimeout; + /** Input: Whether a timed call is interruptible (ring-0 only). This is ignored + * if not a VBGL_IOCTL_HGCM_CALL_TIMED or VBGL_IOCTL_HGCM_CALL_TIMED_32 + * request, or if made from user land. */ + bool fInterruptible; + /** Explicit padding, MBZ. */ + uint8_t bReserved; + /** Input: How many parameters following this structure. + * + * The parameters are either HGCMFunctionParameter64 or HGCMFunctionParameter32, + * depending on whether we're receiving a 64-bit or 32-bit request. + * + * The current maximum is 61 parameters (given a 1KB max request size, + * and a 64-bit parameter size of 16 bytes). + * + * @note This information is duplicated by Hdr.cbIn, but it's currently too much + * work to eliminate this. */ + uint16_t cParms; + /* Parameters follow in form HGCMFunctionParameter aParms[cParms] */ +} VBGLIOCHGCMCALL, RT_FAR *PVBGLIOCHGCMCALL; +AssertCompileSize(VBGLIOCHGCMCALL, 24 + 16); +typedef VBGLIOCHGCMCALL const RT_FAR *PCVBGLIOCHGCMCALL; + +/** + * Initialize a HGCM header (VBGLIOCHGCMCALL) for a non-timed call. + * + * @param a_pHdr The header to initalize. + * @param a_idClient The client connection ID to call thru. + * @param a_idFunction The function we're calling + * @param a_cParameters Number of parameters. + */ +# define VBGL_HGCM_HDR_INIT(a_pHdr, a_idClient, a_idFunction, a_cParameters) \ + do { \ + VBGLREQHDR_INIT_EX(&(a_pHdr)->Hdr, \ + sizeof(VBGLIOCHGCMCALL) + (a_cParameters) * sizeof(HGCMFunctionParameter), \ + sizeof(VBGLIOCHGCMCALL) + (a_cParameters) * sizeof(HGCMFunctionParameter)); \ + (a_pHdr)->u32ClientID = (a_idClient); \ + (a_pHdr)->u32Function = (a_idFunction); \ + (a_pHdr)->cMsTimeout = RT_INDEFINITE_WAIT; \ + (a_pHdr)->fInterruptible = true; \ + (a_pHdr)->bReserved = 0; \ + (a_pHdr)->cParms = (a_cParameters); \ + } while (0) + +/** + * Initialize a HGCM header (VBGLIOCHGCMCALL) for a non-timed call, custom size. + * + * This is usually only needed when appending page lists to the call. + * + * @param a_pHdr The header to initalize. + * @param a_idClient The client connection ID to call thru. + * @param a_idFunction The function we're calling + * @param a_cParameters Number of parameters. + * @param a_cbReq The request size. + */ +# define VBGL_HGCM_HDR_INIT_EX(a_pHdr, a_idClient, a_idFunction, a_cParameters, a_cbReq) \ + do { \ + Assert((a_cbReq) >= sizeof(VBGLIOCHGCMCALL) + (a_cParameters) * sizeof(HGCMFunctionParameter)); \ + VBGLREQHDR_INIT_EX(&(a_pHdr)->Hdr, (a_cbReq), (a_cbReq)); \ + (a_pHdr)->u32ClientID = (a_idClient); \ + (a_pHdr)->u32Function = (a_idFunction); \ + (a_pHdr)->cMsTimeout = RT_INDEFINITE_WAIT; \ + (a_pHdr)->fInterruptible = true; \ + (a_pHdr)->bReserved = 0; \ + (a_pHdr)->cParms = (a_cParameters); \ + } while (0) + +/** + * Initialize a HGCM header (VBGLIOCHGCMCALL), with timeout (interruptible). + * + * @param a_pHdr The header to initalize. + * @param a_idClient The client connection ID to call thru. + * @param a_idFunction The function we're calling + * @param a_cParameters Number of parameters. + * @param a_cMsTimeout The timeout in milliseconds. + */ +# define VBGL_HGCM_HDR_INIT_TIMED(a_pHdr, a_idClient, a_idFunction, a_cParameters, a_cMsTimeout) \ + do { \ + VBGLREQHDR_INIT_EX(&(a_pHdr)->Hdr, \ + sizeof(VBGLIOCHGCMCALL) + (a_cParameters) * sizeof(HGCMFunctionParameter), \ + sizeof(VBGLIOCHGCMCALL) + (a_cParameters) * sizeof(HGCMFunctionParameter)); \ + (a_pHdr)->u32ClientID = (a_idClient); \ + (a_pHdr)->u32Function = (a_idFunction); \ + (a_pHdr)->cMsTimeout = (a_cMsTimeout); \ + (a_pHdr)->fInterruptible = true; \ + (a_pHdr)->bReserved = 0; \ + (a_pHdr)->cParms = (a_cParameters); \ + } while (0) + +/** Get the pointer to the first HGCM parameter. */ +# define VBGL_HGCM_GET_CALL_PARMS(a_pInfo) ( (HGCMFunctionParameter *)((uint8_t *)(a_pInfo) + sizeof(VBGLIOCHGCMCALL)) ) +/** Get the pointer to the first HGCM parameter in a 32-bit request. */ +# define VBGL_HGCM_GET_CALL_PARMS32(a_pInfo) ( (HGCMFunctionParameter32 *)((uint8_t *)(a_pInfo) + sizeof(VBGLIOCHGCMCALL)) ) + + +/** + * Mouse event noticification callback function. + * @param pvUser Argument given when setting the callback. + */ +typedef DECLCALLBACKTYPE(void, FNVBOXGUESTMOUSENOTIFY,(void *pvUser)); +/** Pointer to a mouse event notification callback function. */ +typedef FNVBOXGUESTMOUSENOTIFY *PFNVBOXGUESTMOUSENOTIFY; /**< @todo fix type prefix */ + +/** @} */ + +#endif /* !VBOX_INCLUDED_VBoxGuestCoreTypes_h */ + |