/** @file * VBox Remote Desktop Extension (VRDE) - Public APIs. */ /* * Copyright (C) 2006-2019 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * General Public License (GPL) as published by the Free Software * Foundation, in version 2 as it comes in the "COPYING" file of the * VirtualBox OSE distribution. VirtualBox OSE is distributed in the * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. * * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the * VirtualBox OSE distribution, in which case the provisions of the * CDDL are applicable instead of those of the GPL. * * You may elect to license modified versions of this file under the * terms and conditions of either the GPL or the CDDL or both. */ #ifndef VBOX_INCLUDED_RemoteDesktop_VRDE_h #define VBOX_INCLUDED_RemoteDesktop_VRDE_h #ifndef RT_WITHOUT_PRAGMA_ONCE # pragma once #endif #include #include /** @defgroup grp_vrdp VRDE * VirtualBox Remote Desktop Extension (VRDE) interface that lets to use * a Remote Desktop server like RDP. * @{ */ RT_C_DECLS_BEGIN /* Forward declaration of the VRDE server instance handle. * This is an opaque pointer for VirtualBox. * The VRDE library uses it as a pointer to some internal data. */ #ifdef __cplusplus class VRDEServer; typedef class VRDEServerType *HVRDESERVER; #else struct VRDEServer; typedef struct VRDEServerType *HVRDESERVER; #endif /* !__cplusplus */ /* Callback based VRDE server interface declarations. */ /** The color mouse pointer information. */ typedef struct _VRDECOLORPOINTER { uint16_t u16HotX; uint16_t u16HotY; uint16_t u16Width; uint16_t u16Height; uint16_t u16MaskLen; uint16_t u16DataLen; /* The 1BPP mask and the 24BPP bitmap follow. */ } VRDECOLORPOINTER; /** Audio format information packed in a 32 bit value. */ typedef uint32_t VRDEAUDIOFORMAT; /** Constructs 32 bit value for given frequency, number of channel and bits per sample. */ #define VRDE_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF)) /** Decode frequency. */ #define VRDE_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF) /** Decode number of channels. */ #define VRDE_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF) /** Decode number signess. */ #define VRDE_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1) /** Decode number of bits per sample. */ #define VRDE_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF) /** Decode number of bytes per sample. */ #define VRDE_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDE_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8) /* * Audio input. */ /* Audio input notifications. */ #define VRDE_AUDIOIN_BEGIN 1 #define VRDE_AUDIOIN_DATA 2 #define VRDE_AUDIOIN_END 3 typedef struct VRDEAUDIOINBEGIN { VRDEAUDIOFORMAT fmt; /* Actual format of data, which will be sent in VRDE_AUDIOIN_DATA events. */ } VRDEAUDIOINBEGIN, *PVRDEAUDIOINBEGIN; /* * Remote USB protocol. */ /* The initial version 1. */ #define VRDE_USB_VERSION_1 (1) /* Version 2: look for VRDE_USB_VERSION_2 comments in the code. */ #define VRDE_USB_VERSION_2 (2) /* Version 3: look for VRDE_USB_VERSION_3 comments in the code. */ #define VRDE_USB_VERSION_3 (3) /* The default VRDE server version of Remote USB Protocol. */ #define VRDE_USB_VERSION VRDE_USB_VERSION_3 /** USB backend operations. */ #define VRDE_USB_REQ_OPEN (0) #define VRDE_USB_REQ_CLOSE (1) #define VRDE_USB_REQ_RESET (2) #define VRDE_USB_REQ_SET_CONFIG (3) #define VRDE_USB_REQ_CLAIM_INTERFACE (4) #define VRDE_USB_REQ_RELEASE_INTERFACE (5) #define VRDE_USB_REQ_INTERFACE_SETTING (6) #define VRDE_USB_REQ_QUEUE_URB (7) #define VRDE_USB_REQ_REAP_URB (8) #define VRDE_USB_REQ_CLEAR_HALTED_EP (9) #define VRDE_USB_REQ_CANCEL_URB (10) /** USB service operations. */ #define VRDE_USB_REQ_DEVICE_LIST (11) #define VRDE_USB_REQ_NEGOTIATE (12) /** An operation completion status is a byte. */ typedef uint8_t VRDEUSBSTATUS; /** USB device identifier is an 32 bit value. */ typedef uint32_t VRDEUSBDEVID; /** Status codes. */ #define VRDE_USB_STATUS_SUCCESS ((VRDEUSBSTATUS)0) #define VRDE_USB_STATUS_ACCESS_DENIED ((VRDEUSBSTATUS)1) #define VRDE_USB_STATUS_DEVICE_REMOVED ((VRDEUSBSTATUS)2) /* * Data structures to use with VRDEUSBRequest. * The *RET* structures always represent the layout of VRDE data. * The *PARM* structures normally the same as VRDE layout. * However the VRDE_USB_REQ_QUEUE_URB_PARM has a pointer to * URB data in place where actual data will be in VRDE layout. * * Since replies (*RET*) are asynchronous, the 'success' * replies are not required for operations which return * only the status code (VRDEUSBREQRETHDR only): * VRDE_USB_REQ_OPEN * VRDE_USB_REQ_RESET * VRDE_USB_REQ_SET_CONFIG * VRDE_USB_REQ_CLAIM_INTERFACE * VRDE_USB_REQ_RELEASE_INTERFACE * VRDE_USB_REQ_INTERFACE_SETTING * VRDE_USB_REQ_CLEAR_HALTED_EP * */ /* VRDE layout has no alignments. */ #pragma pack(1) /* Common header for all VRDE USB packets. After the reply hdr follows *PARM* or *RET* data. */ typedef struct _VRDEUSBPKTHDR { /* Total length of the reply NOT including the 'length' field. */ uint32_t length; /* The operation code for which the reply was sent by the client. */ uint8_t code; } VRDEUSBPKTHDR; /* Common header for all return structures. */ typedef struct _VRDEUSBREQRETHDR { /* Device status. */ VRDEUSBSTATUS status; /* Device id. */ VRDEUSBDEVID id; } VRDEUSBREQRETHDR; /* VRDE_USB_REQ_OPEN */ typedef struct _VRDE_USB_REQ_OPEN_PARM { uint8_t code; VRDEUSBDEVID id; } VRDE_USB_REQ_OPEN_PARM; typedef struct _VRDE_USB_REQ_OPEN_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_OPEN_RET; /* VRDE_USB_REQ_CLOSE */ typedef struct _VRDE_USB_REQ_CLOSE_PARM { uint8_t code; VRDEUSBDEVID id; } VRDE_USB_REQ_CLOSE_PARM; /* The close request has no returned data. */ /* VRDE_USB_REQ_RESET */ typedef struct _VRDE_USB_REQ_RESET_PARM { uint8_t code; VRDEUSBDEVID id; } VRDE_USB_REQ_RESET_PARM; typedef struct _VRDE_USB_REQ_RESET_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_RESET_RET; /* VRDE_USB_REQ_SET_CONFIG */ typedef struct _VRDE_USB_REQ_SET_CONFIG_PARM { uint8_t code; VRDEUSBDEVID id; uint8_t configuration; } VRDE_USB_REQ_SET_CONFIG_PARM; typedef struct _VRDE_USB_REQ_SET_CONFIG_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_SET_CONFIG_RET; /* VRDE_USB_REQ_CLAIM_INTERFACE */ typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_PARM { uint8_t code; VRDEUSBDEVID id; uint8_t iface; } VRDE_USB_REQ_CLAIM_INTERFACE_PARM; typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_CLAIM_INTERFACE_RET; /* VRDE_USB_REQ_RELEASE_INTERFACE */ typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_PARM { uint8_t code; VRDEUSBDEVID id; uint8_t iface; } VRDE_USB_REQ_RELEASE_INTERFACE_PARM; typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_RELEASE_INTERFACE_RET; /* VRDE_USB_REQ_INTERFACE_SETTING */ typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_PARM { uint8_t code; VRDEUSBDEVID id; uint8_t iface; uint8_t setting; } VRDE_USB_REQ_INTERFACE_SETTING_PARM; typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_INTERFACE_SETTING_RET; /* VRDE_USB_REQ_QUEUE_URB */ #define VRDE_USB_TRANSFER_TYPE_CTRL (0) #define VRDE_USB_TRANSFER_TYPE_ISOC (1) #define VRDE_USB_TRANSFER_TYPE_BULK (2) #define VRDE_USB_TRANSFER_TYPE_INTR (3) #define VRDE_USB_TRANSFER_TYPE_MSG (4) #define VRDE_USB_DIRECTION_SETUP (0) #define VRDE_USB_DIRECTION_IN (1) #define VRDE_USB_DIRECTION_OUT (2) typedef struct _VRDE_USB_REQ_QUEUE_URB_PARM { uint8_t code; VRDEUSBDEVID id; uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */ uint8_t type; uint8_t ep; uint8_t direction; uint32_t urblen; /* Length of the URB. */ uint32_t datalen; /* Length of the data. */ void *data; /* In RDP layout the data follow. */ } VRDE_USB_REQ_QUEUE_URB_PARM; /* The queue URB has no explicit return. The reap URB reply will be * eventually the indirect result. */ /* VRDE_USB_REQ_REAP_URB * Notificationg from server to client that server expects an URB * from any device. * Only sent if negotiated URB return method is polling. * Normally, the client will send URBs back as soon as they are ready. */ typedef struct _VRDE_USB_REQ_REAP_URB_PARM { uint8_t code; } VRDE_USB_REQ_REAP_URB_PARM; #define VRDE_USB_XFER_OK (0) #define VRDE_USB_XFER_STALL (1) #define VRDE_USB_XFER_DNR (2) #define VRDE_USB_XFER_CRC (3) /* VRDE_USB_VERSION_2: New error codes. OHCI Completion Codes. */ #define VRDE_USB_XFER_BS (4) /* BitStuffing */ #define VRDE_USB_XFER_DTM (5) /* DataToggleMismatch */ #define VRDE_USB_XFER_PCF (6) /* PIDCheckFailure */ #define VRDE_USB_XFER_UPID (7) /* UnexpectedPID */ #define VRDE_USB_XFER_DO (8) /* DataOverrun */ #define VRDE_USB_XFER_DU (9) /* DataUnderrun */ #define VRDE_USB_XFER_BO (10) /* BufferOverrun */ #define VRDE_USB_XFER_BU (11) /* BufferUnderrun */ #define VRDE_USB_XFER_ERR (12) /* VBox protocol error. */ #define VRDE_USB_REAP_FLAG_CONTINUED (0x0) #define VRDE_USB_REAP_FLAG_LAST (0x1) /* VRDE_USB_VERSION_3: Fragmented URBs. */ #define VRDE_USB_REAP_FLAG_FRAGMENT (0x2) #define VRDE_USB_REAP_VALID_FLAGS (VRDE_USB_REAP_FLAG_LAST) /* VRDE_USB_VERSION_3: Fragmented URBs. */ #define VRDE_USB_REAP_VALID_FLAGS_3 (VRDE_USB_REAP_FLAG_LAST | VRDE_USB_REAP_FLAG_FRAGMENT) typedef struct _VRDEUSBREQREAPURBBODY { VRDEUSBDEVID id; /* From which device the URB arrives. */ uint8_t flags; /* VRDE_USB_REAP_FLAG_* */ uint8_t error; /* VRDE_USB_XFER_* */ uint32_t handle; /* Handle of returned URB. Not 0. */ uint32_t len; /* Length of data actually transferred. */ /* 'len' bytes of data follow if direction of this URB was VRDE_USB_DIRECTION_IN. */ } VRDEUSBREQREAPURBBODY; typedef struct _VRDE_USB_REQ_REAP_URB_RET { /* The REAP URB has no header, only completed URBs are returned. */ VRDEUSBREQREAPURBBODY body; /* Another body may follow, depending on flags. */ } VRDE_USB_REQ_REAP_URB_RET; /* VRDE_USB_REQ_CLEAR_HALTED_EP */ typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_PARM { uint8_t code; VRDEUSBDEVID id; uint8_t ep; } VRDE_USB_REQ_CLEAR_HALTED_EP_PARM; typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_RET { VRDEUSBREQRETHDR hdr; } VRDE_USB_REQ_CLEAR_HALTED_EP_RET; /* VRDE_USB_REQ_CANCEL_URB */ typedef struct _VRDE_USB_REQ_CANCEL_URB_PARM { uint8_t code; VRDEUSBDEVID id; uint32_t handle; } VRDE_USB_REQ_CANCEL_URB_PARM; /* The cancel URB request has no return. */ /* VRDE_USB_REQ_DEVICE_LIST * * Server polls USB devices on client by sending this request * periodically. Client sends back a list of all devices * connected to it. Each device is assigned with an identifier, * that is used to distinguish the particular device. */ typedef struct _VRDE_USB_REQ_DEVICE_LIST_PARM { uint8_t code; } VRDE_USB_REQ_DEVICE_LIST_PARM; /* Data is a list of the following variable length structures. */ typedef struct _VRDEUSBDEVICEDESC { /* Offset of the next structure. 0 if last. */ uint16_t oNext; /* Identifier of the device assigned by client. */ VRDEUSBDEVID id; /** USB version number. */ uint16_t bcdUSB; /** Device class. */ uint8_t bDeviceClass; /** Device subclass. */ uint8_t bDeviceSubClass; /** Device protocol */ uint8_t bDeviceProtocol; /** Vendor ID. */ uint16_t idVendor; /** Product ID. */ uint16_t idProduct; /** Revision, integer part. */ uint16_t bcdRev; /** Offset of the UTF8 manufacturer string relative to the structure start. */ uint16_t oManufacturer; /** Offset of the UTF8 product string relative to the structure start. */ uint16_t oProduct; /** Offset of the UTF8 serial number string relative to the structure start. */ uint16_t oSerialNumber; /** Physical USB port the device is connected to. */ uint16_t idPort; } VRDEUSBDEVICEDESC; #define VRDE_USBDEVICESPEED_UNKNOWN 0 /* Unknown. */ #define VRDE_USBDEVICESPEED_LOW 1 /* Low speed (1.5 Mbit/s). */ #define VRDE_USBDEVICESPEED_FULL 2 /* Full speed (12 Mbit/s). */ #define VRDE_USBDEVICESPEED_HIGH 3 /* High speed (480 Mbit/s). */ #define VRDE_USBDEVICESPEED_VARIABLE 4 /* Variable speed - USB 2.5 / wireless. */ #define VRDE_USBDEVICESPEED_SUPERSPEED 5 /* Super Speed - USB 3.0 */ typedef struct _VRDEUSBDEVICEDESCEXT { VRDEUSBDEVICEDESC desc; /* Extended info. */ /** The USB device speed: VRDE_USBDEVICESPEED_*. */ uint16_t u16DeviceSpeed; } VRDEUSBDEVICEDESCEXT; typedef struct _VRDE_USB_REQ_DEVICE_LIST_RET { VRDEUSBDEVICEDESC body; /* Other devices may follow. * The list ends with (uint16_t)0, * which means that an empty list consists of 2 zero bytes. */ } VRDE_USB_REQ_DEVICE_LIST_RET; typedef struct _VRDE_USB_REQ_DEVICE_LIST_EXT_RET { VRDEUSBDEVICEDESCEXT body; /* Other devices may follow. * The list ends with (uint16_t)0, * which means that an empty list consists of 2 zero bytes. */ } VRDE_USB_REQ_DEVICE_LIST_EXT_RET; /* The server requests the version of the port the device is attached to. * The client must use VRDEUSBDEVICEDESCEXT structure. */ #define VRDE_USB_SERVER_CAPS_PORT_VERSION 0x0001 typedef struct _VRDEUSBREQNEGOTIATEPARM { uint8_t code; /* Remote USB Protocol version. */ /* VRDE_USB_VERSION_3: the 32 bit field is splitted to 16 bit version and 16 bit flags. * Version 1 and 2 servers therefore have 'flags' == 0. * Version 3+ servers can send some capabilities in this field, this way it is possible to add * a new capability without increasing the protocol version. */ uint16_t version; uint16_t flags; /* See VRDE_USB_SERVER_CAPS_* */ } VRDEUSBREQNEGOTIATEPARM; /* VRDEUSBREQNEGOTIATERET flags. */ #define VRDE_USB_CAPS_FLAG_ASYNC (0x0) #define VRDE_USB_CAPS_FLAG_POLL (0x1) /* VRDE_USB_VERSION_2: New flag. */ #define VRDE_USB_CAPS2_FLAG_VERSION (0x2) /* The client is negotiating the protocol version. */ /* VRDE_USB_VERSION_3: New flag. */ #define VRDE_USB_CAPS3_FLAG_EXT (0x4) /* The client is negotiating the extended flags. * If this flag is set, then the VRDE_USB_CAPS2_FLAG_VERSION * must also be set. */ #define VRDE_USB_CAPS_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL) /* VRDE_USB_VERSION_2: A set of valid flags. */ #define VRDE_USB_CAPS2_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL | VRDE_USB_CAPS2_FLAG_VERSION) /* VRDE_USB_VERSION_3: A set of valid flags. */ #define VRDE_USB_CAPS3_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL | VRDE_USB_CAPS2_FLAG_VERSION | VRDE_USB_CAPS3_FLAG_EXT) typedef struct _VRDEUSBREQNEGOTIATERET { uint8_t flags; } VRDEUSBREQNEGOTIATERET; typedef struct _VRDEUSBREQNEGOTIATERET_2 { uint8_t flags; uint32_t u32Version; /* This field presents only if the VRDE_USB_CAPS2_FLAG_VERSION flag is set. */ } VRDEUSBREQNEGOTIATERET_2; /* The server requests the version of the port the device is attached to. * The client must use VRDEUSBDEVICEDESCEXT structure. */ #define VRDE_USB_CLIENT_CAPS_PORT_VERSION 0x00000001 typedef struct _VRDEUSBREQNEGOTIATERET_3 { uint8_t flags; uint32_t u32Version; /* This field presents only if the VRDE_USB_CAPS2_FLAG_VERSION flag is set. */ uint32_t u32Flags; /* This field presents only if both VRDE_USB_CAPS2_FLAG_VERSION and * VRDE_USB_CAPS2_FLAG_EXT flag are set. * See VRDE_USB_CLIENT_CAPS_* */ } VRDEUSBREQNEGOTIATERET_3; #pragma pack() #define VRDE_CLIPBOARD_FORMAT_NULL (0x0) #define VRDE_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1) #define VRDE_CLIPBOARD_FORMAT_BITMAP (0x2) #define VRDE_CLIPBOARD_FORMAT_HTML (0x4) #define VRDE_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0) #define VRDE_CLIPBOARD_FUNCTION_DATA_READ (1) #define VRDE_CLIPBOARD_FUNCTION_DATA_WRITE (2) /** Indexes of information values. */ /** Whether a client is connected at the moment. * uint32_t */ #define VRDE_QI_ACTIVE (0) /** How many times a client connected up to current moment. * uint32_t */ #define VRDE_QI_NUMBER_OF_CLIENTS (1) /** When last connection was established. * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC */ #define VRDE_QI_BEGIN_TIME (2) /** When last connection was terminated or current time if connection still active. * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC */ #define VRDE_QI_END_TIME (3) /** How many bytes were sent in last (current) connection. * uint64_t */ #define VRDE_QI_BYTES_SENT (4) /** How many bytes were sent in all connections. * uint64_t */ #define VRDE_QI_BYTES_SENT_TOTAL (5) /** How many bytes were received in last (current) connection. * uint64_t */ #define VRDE_QI_BYTES_RECEIVED (6) /** How many bytes were received in all connections. * uint64_t */ #define VRDE_QI_BYTES_RECEIVED_TOTAL (7) /** Login user name supplied by the client. * UTF8 nul terminated string. */ #define VRDE_QI_USER (8) /** Login domain supplied by the client. * UTF8 nul terminated string. */ #define VRDE_QI_DOMAIN (9) /** The client name supplied by the client. * UTF8 nul terminated string. */ #define VRDE_QI_CLIENT_NAME (10) /** IP address of the client. * UTF8 nul terminated string. */ #define VRDE_QI_CLIENT_IP (11) /** The client software version number. * uint32_t. */ #define VRDE_QI_CLIENT_VERSION (12) /** Public key exchange method used when connection was established. * Values: 0 - RDP4 public key exchange scheme. * 1 - X509 sertificates were sent to client. * uint32_t. */ #define VRDE_QI_ENCRYPTION_STYLE (13) /** TCP port where the server listens. * Values: 0 - VRDE server failed to start. * -1 - . * int32_t. */ #define VRDE_QI_PORT (14) /** Hints what has been intercepted by the application. */ #define VRDE_CLIENT_INTERCEPT_AUDIO RT_BIT(0) #define VRDE_CLIENT_INTERCEPT_USB RT_BIT(1) #define VRDE_CLIENT_INTERCEPT_CLIPBOARD RT_BIT(2) #define VRDE_CLIENT_INTERCEPT_AUDIO_INPUT RT_BIT(3) /** The version of the VRDE server interface. */ #define VRDE_INTERFACE_VERSION_1 (1) #define VRDE_INTERFACE_VERSION_2 (2) #define VRDE_INTERFACE_VERSION_3 (3) #define VRDE_INTERFACE_VERSION_4 (4) /** The header that does not change when the interface changes. */ typedef struct _VRDEINTERFACEHDR { /** The version of the interface. */ uint64_t u64Version; /** The size of the structure. */ uint64_t u64Size; } VRDEINTERFACEHDR; /** The VRDE server entry points. Interface version 1. */ typedef struct _VRDEENTRYPOINTS_1 { /** The header. */ VRDEINTERFACEHDR header; /** Destroy the server instance. * * @param hServer The server instance handle. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer)); /** The server should start to accept clients connections. * * @param hServer The server instance handle. * @param fEnable Whether to enable or disable client connections. * When is false, all existing clients are disconnected. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable)); /** The server should disconnect the client. * * @param hServer The server instance handle. * @param u32ClientId The client identifier. * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the * client before disconnecting. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect)); /** * Inform the server that the display was resized. * The server will query information about display * from the application via callbacks. * * @param hServer Handle of VRDE server instance. */ DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer)); /** * Send a update. * * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called. * If the have to access the bitmap later or from another thread, then * it must used an intermediate buffer and copy the framebuffer data to the * intermediate buffer in VRDEUpdate. * * @param hServer Handle of VRDE server instance. * @param uScreenId The screen index. * @param pvUpdate Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data. * @param cbUpdate Size of the update data. */ DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate)); /** * Set the mouse pointer shape. * * @param hServer Handle of VRDE server instance. * @param pPointer The pointer shape information. */ DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer)); /** * Hide the mouse pointer. * * @param hServer Handle of VRDE server instance. */ DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer)); /** * Queues the samples to be sent to clients. * * @param hServer Handle of VRDE server instance. * @param pvSamples Address of samples to be sent. * @param cSamples Number of samples. * @param format Encoded audio format for these samples. * * @note Initialized to NULL when the application audio callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples, VRDEAUDIOFORMAT format)); /** * Sets the sound volume on clients. * * @param hServer Handle of VRDE server instance. * @param left 0..0xFFFF volume level for left channel. * @param right 0..0xFFFF volume level for right channel. * * @note Initialized to NULL when the application audio callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right)); /** * Sends a USB request. * * @param hServer Handle of VRDE server instance. * @param u32ClientId An identifier that allows the server to find the corresponding client. * The identifier is always passed by the server as a parameter * of the FNVRDEUSBCALLBACK. Note that the value is the same as * in the VRDESERVERCALLBACK functions. * @param pvParm Function specific parameters buffer. * @param cbParm Size of the buffer. * * @note Initialized to NULL when the application USB callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm, uint32_t cbParm)); /** * Called by the application when (VRDE_CLIPBOARD_FUNCTION_*): * - (0) guest announces available clipboard formats; * - (1) guest requests clipboard data; * - (2) guest responds to the client's request for clipboard data. * * @param hServer The VRDE server handle. * @param u32Function The cause of the call. * @param u32Format Bitmask of announced formats or the format of data. * @param pvData Points to: (1) buffer to be filled with clients data; * (2) data from the host. * @param cbData Size of 'pvData' buffer in bytes. * @param pcbActualRead Size of the copied data in bytes. * * @note Initialized to NULL when the application clipboard callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format, void *pvData, uint32_t cbData, uint32_t *pcbActualRead)); /** * Query various information from the VRDE server. * * @param hServer The VRDE server handle. * @param index VRDE_QI_* identifier of information to be returned. * @param pvBuffer Address of memory buffer to which the information must be written. * @param cbBuffer Size of the memory buffer in bytes. * @param pcbOut Size in bytes of returned information value. * * @remark The caller must check the *pcbOut. 0 there means no information was returned. * A value greater than cbBuffer means that information is too big to fit in the * buffer, in that case no information was placed to the buffer. */ DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut)); } VRDEENTRYPOINTS_1; /** The VRDE server entry points. Interface version 2. * A new entry point VRDERedirect has been added relative to version 1. */ typedef struct _VRDEENTRYPOINTS_2 { /** The header. */ VRDEINTERFACEHDR header; /** Destroy the server instance. * * @param hServer The server instance handle. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer)); /** The server should start to accept clients connections. * * @param hServer The server instance handle. * @param fEnable Whether to enable or disable client connections. * When is false, all existing clients are disconnected. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable)); /** The server should disconnect the client. * * @param hServer The server instance handle. * @param u32ClientId The client identifier. * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the * client before disconnecting. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect)); /** * Inform the server that the display was resized. * The server will query information about display * from the application via callbacks. * * @param hServer Handle of VRDE server instance. */ DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer)); /** * Send a update. * * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called. * If the have to access the bitmap later or from another thread, then * it must used an intermediate buffer and copy the framebuffer data to the * intermediate buffer in VRDEUpdate. * * @param hServer Handle of VRDE server instance. * @param uScreenId The screen index. * @param pvUpdate Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data. * @param cbUpdate Size of the update data. */ DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate)); /** * Set the mouse pointer shape. * * @param hServer Handle of VRDE server instance. * @param pPointer The pointer shape information. */ DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer)); /** * Hide the mouse pointer. * * @param hServer Handle of VRDE server instance. */ DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer)); /** * Queues the samples to be sent to clients. * * @param hServer Handle of VRDE server instance. * @param pvSamples Address of samples to be sent. * @param cSamples Number of samples. * @param format Encoded audio format for these samples. * * @note Initialized to NULL when the application audio callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples, VRDEAUDIOFORMAT format)); /** * Sets the sound volume on clients. * * @param hServer Handle of VRDE server instance. * @param left 0..0xFFFF volume level for left channel. * @param right 0..0xFFFF volume level for right channel. * * @note Initialized to NULL when the application audio callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right)); /** * Sends a USB request. * * @param hServer Handle of VRDE server instance. * @param u32ClientId An identifier that allows the server to find the corresponding client. * The identifier is always passed by the server as a parameter * of the FNVRDEUSBCALLBACK. Note that the value is the same as * in the VRDESERVERCALLBACK functions. * @param pvParm Function specific parameters buffer. * @param cbParm Size of the buffer. * * @note Initialized to NULL when the application USB callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm, uint32_t cbParm)); /** * Called by the application when (VRDE_CLIPBOARD_FUNCTION_*): * - (0) guest announces available clipboard formats; * - (1) guest requests clipboard data; * - (2) guest responds to the client's request for clipboard data. * * @param hServer The VRDE server handle. * @param u32Function The cause of the call. * @param u32Format Bitmask of announced formats or the format of data. * @param pvData Points to: (1) buffer to be filled with clients data; * (2) data from the host. * @param cbData Size of 'pvData' buffer in bytes. * @param pcbActualRead Size of the copied data in bytes. * * @note Initialized to NULL when the application clipboard callbacks are NULL. */ DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format, void *pvData, uint32_t cbData, uint32_t *pcbActualRead)); /** * Query various information from the VRDE server. * * @param hServer The VRDE server handle. * @param index VRDE_QI_* identifier of information to be returned. * @param pvBuffer Address of memory buffer to which the information must be written. * @param cbBuffer Size of the memory buffer in bytes. * @param pcbOut Size in bytes of returned information value. * * @remark The caller must check the *pcbOut. 0 there means no information was returned. * A value greater than cbBuffer means that information is too big to fit in the * buffer, in that case no information was placed to the buffer. */ DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut)); /** * The server should redirect the client to the specified server. * * @param hServer The server instance handle. * @param u32ClientId The client identifier. * @param pszServer The server to redirect the client to. * @param pszUser The username to use for the redirection. * Can be NULL. * @param pszDomain The domain. Can be NULL. * @param pszPassword The password. Can be NULL. * @param u32SessionId The ID of the session to redirect to. * @param pszCookie The routing token used by a load balancer to * route the redirection. Can be NULL. */ DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer, const char *pszUser, const char *pszDomain, const char *pszPassword, uint32_t u32SessionId, const char *pszCookie)); } VRDEENTRYPOINTS_2; /** The VRDE server entry points. Interface version 3. * New entry points VRDEAudioInOpen and VRDEAudioInClose has been added relative to version 2. */ typedef struct _VRDEENTRYPOINTS_3 { /* The header. */ VRDEINTERFACEHDR header; /* * Same as version 2. See comment in VRDEENTRYPOINTS_2. */ DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer)); DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable)); DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect)); DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer)); DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate)); DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer)); DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer)); DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples, VRDEAUDIOFORMAT format)); DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right)); DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm, uint32_t cbParm)); DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format, void *pvData, uint32_t cbData, uint32_t *pcbActualRead)); DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut)); DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer, const char *pszUser, const char *pszDomain, const char *pszPassword, uint32_t u32SessionId, const char *pszCookie)); /* * New for version 3. */ /** * Audio input open request. * * @param hServer Handle of VRDE server instance. * @param pvCtx To be used in VRDECallbackAudioIn. * @param u32ClientId An identifier that allows the server to find the corresponding client. * @param audioFormat Preferred format of audio data. * @param u32SamplesPerBlock Preferred number of samples in one block of audio input data. * * @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL. */ DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer, void *pvCtx, uint32_t u32ClientId, VRDEAUDIOFORMAT audioFormat, uint32_t u32SamplesPerBlock)); /** * Audio input close request. * * @param hServer Handle of VRDE server instance. * @param u32ClientId An identifier that allows the server to find the corresponding client. * * @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL. */ DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer, uint32_t u32ClientId)); } VRDEENTRYPOINTS_3; /* Indexes for VRDECallbackProperty. * *_QP_* queries a property. * *_SP_* sets a property. */ #define VRDE_QP_NETWORK_PORT (1) /* Obsolete. Use VRDE_QP_NETWORK_PORT_RANGE instead. */ #define VRDE_QP_NETWORK_ADDRESS (2) /* UTF8 string. Host network interface IP address to bind to. */ #define VRDE_QP_NUMBER_MONITORS (3) /* 32 bit. Number of monitors in the VM. */ #define VRDE_QP_NETWORK_PORT_RANGE (4) /* UTF8 string. List of ports. The server must bind to one of * free ports from the list. Example: "3000,3010-3012,4000", * which tells the server to bind to either of ports: * 3000, 3010, 3011, 3012, 4000. */ #define VRDE_QP_VIDEO_CHANNEL (5) #define VRDE_QP_VIDEO_CHANNEL_QUALITY (6) #define VRDE_QP_VIDEO_CHANNEL_SUNFLSH (7) #define VRDE_QP_FEATURE (8) /* VRDEFEATURE structure. Generic interface to query named VRDE properties. */ #define VRDE_QP_UNIX_SOCKET_PATH (9) /* Path to a UNIX Socket for incoming connections */ #define VRDE_SP_BASE 0x1000 #define VRDE_SP_NETWORK_BIND_PORT (VRDE_SP_BASE + 1) /* 32 bit. The port number actually used by the server. * If VRDECreateServer fails, it should set the port to 0. * If VRDECreateServer succeeds, then the port must be set * in VRDEEnableConnections to the actually used value. * VRDEDestroy must set the port to 0xFFFFFFFF. */ #define VRDE_SP_CLIENT_STATUS (VRDE_SP_BASE + 2) /* UTF8 string. The change of the generic client status: * "ATTACH" - the client is attached; * "DETACH" - the client is detached; * "NAME=..." - the client name changes. * Can be used for other notifications. */ #pragma pack(1) /* VRDE_QP_FEATURE data. */ typedef struct _VRDEFEATURE { uint32_t u32ClientId; char achInfo[1]; /* UTF8 property input name and output value. */ } VRDEFEATURE; /* VRDE_SP_CLIENT_STATUS data. */ typedef struct VRDECLIENTSTATUS { uint32_t u32ClientId; uint32_t cbStatus; char achStatus[1]; /* UTF8 status string. */ } VRDECLIENTSTATUS; /* A framebuffer description. */ typedef struct _VRDEFRAMEBUFFERINFO { const uint8_t *pu8Bits; int xOrigin; int yOrigin; unsigned cWidth; unsigned cHeight; unsigned cBitsPerPixel; unsigned cbLine; } VRDEFRAMEBUFFERINFO; #define VRDE_INPUT_SCANCODE 0 #define VRDE_INPUT_POINT 1 #define VRDE_INPUT_CAD 2 #define VRDE_INPUT_RESET 3 #define VRDE_INPUT_SYNCH 4 typedef struct _VRDEINPUTSCANCODE { unsigned uScancode; } VRDEINPUTSCANCODE; #define VRDE_INPUT_POINT_BUTTON1 0x01 #define VRDE_INPUT_POINT_BUTTON2 0x02 #define VRDE_INPUT_POINT_BUTTON3 0x04 #define VRDE_INPUT_POINT_WHEEL_UP 0x08 #define VRDE_INPUT_POINT_WHEEL_DOWN 0x10 typedef struct _VRDEINPUTPOINT { int x; int y; unsigned uButtons; } VRDEINPUTPOINT; #define VRDE_INPUT_SYNCH_SCROLL 0x01 #define VRDE_INPUT_SYNCH_NUMLOCK 0x02 #define VRDE_INPUT_SYNCH_CAPITAL 0x04 typedef struct _VRDEINPUTSYNCH { unsigned uLockStatus; } VRDEINPUTSYNCH; #pragma pack() /** The VRDE server callbacks. Interface version 1. */ typedef struct _VRDECALLBACKS_1 { /** The header. */ VRDEINTERFACEHDR header; /** * Query or set various information, on how the VRDE server operates, from or to the application. * Queries for properties will always return success, and if the key is not known or has no * value associated with it an empty string is returned. * * * @param pvCallback The callback specific pointer. * @param index VRDE_[Q|S]P_* identifier of information to be returned or set. * @param pvBuffer Address of memory buffer to which the information must be written or read. * @param cbBuffer Size of the memory buffer in bytes. * @param pcbOut Size in bytes of returned information value. * * @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value. */ DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut)); /* A client is logging in, the application must decide whether * to let to connect the client. The server will drop the connection, * when an error code is returned by the callback. * * @param pvCallback The callback specific pointer. * @param u32ClientId An unique client identifier generated by the server. * @param pszUser The username. * @param pszPassword The password. * @param pszDomain The domain. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback, uint32_t u32ClientId, const char *pszUser, const char *pszPassword, const char *pszDomain)); /* The client has been successfully connected. That is logon was successful and the * remote desktop protocol connection completely established. * * @param pvCallback The callback specific pointer. * @param u32ClientId An unique client identifier generated by the server. */ DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback, uint32_t u32ClientId)); /* The client has been disconnected. * * @param pvCallback The callback specific pointer. * @param u32ClientId An unique client identifier generated by the server. * @param fu32Intercepted What was intercepted by the client (VRDE_CLIENT_INTERCEPT_*). */ DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback, uint32_t u32ClientId, uint32_t fu32Intercepted)); /* The client supports one of RDP channels. * * @param pvCallback The callback specific pointer. * @param u32ClientId An unique client identifier generated by the server. * @param fu32Intercept What the client wants to intercept. One of VRDE_CLIENT_INTERCEPT_* flags. * @param ppvIntercept The value to be passed to the channel specific callback. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback, uint32_t u32ClientId, uint32_t fu32Intercept, void **ppvIntercept)); /** * Called by the server when a reply is received from a client. * * @param pvCallback The callback specific pointer. * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_USB. * @param u32ClientId Identifies the client that sent the reply. * @param u8Code The operation code VRDE_USB_REQ_*. * @param pvRet Points to data received from the client. * @param cbRet Size of the data in bytes. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback, void *pvIntercept, uint32_t u32ClientId, uint8_t u8Code, const void *pvRet, uint32_t cbRet)); /** * Called by the server when (VRDE_CLIPBOARD_FUNCTION_*): * - (0) client announces available clipboard formats; * - (1) client requests clipboard data. * * @param pvCallback The callback specific pointer. * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_CLIPBOARD. * @param u32ClientId Identifies the RDP client that sent the reply. * @param u32Function The cause of the callback. * @param u32Format Bitmask of reported formats or the format of received data. * @param pvData Reserved. * @param cbData Reserved. * * @return IPRT status code. */ DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback, void *pvIntercept, uint32_t u32ClientId, uint32_t u32Function, uint32_t u32Format, const void *pvData, uint32_t cbData)); /* The framebuffer information is queried. * * @param pvCallback The callback specific pointer. * @param uScreenId The framebuffer index. * @param pInfo The information structure to ber filled. * * @return Whether the framebuffer is available. */ DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback, unsigned uScreenId, VRDEFRAMEBUFFERINFO *pInfo)); /* Request the exclusive access to the framebuffer bitmap. * Currently not used because VirtualBox makes sure that the framebuffer is available * when VRDEUpdate is called. * * @param pvCallback The callback specific pointer. * @param uScreenId The framebuffer index. */ DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback, unsigned uScreenId)); /* Release the exclusive access to the framebuffer bitmap. * Currently not used because VirtualBox makes sure that the framebuffer is available * when VRDEUpdate is called. * * @param pvCallback The callback specific pointer. * @param uScreenId The framebuffer index. */ DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback, unsigned uScreenId)); /* Input from the client. * * @param pvCallback The callback specific pointer. * @param pvInput The input information. * @param cbInput The size of the input information. */ DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback, int type, const void *pvInput, unsigned cbInput)); /* Video mode hint from the client. * * @param pvCallback The callback specific pointer. * @param cWidth Requested width. * @param cHeight Requested height. * @param cBitsPerPixel Requested color depth. * @param uScreenId The framebuffer index. */ DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback, unsigned cWidth, unsigned cHeight, unsigned cBitsPerPixel, unsigned uScreenId)); } VRDECALLBACKS_1; /* Callbacks are the same for the version 1 and version 2 interfaces. */ typedef VRDECALLBACKS_1 VRDECALLBACKS_2; /** The VRDE server callbacks. Interface version 3. */ typedef struct _VRDECALLBACKS_3 { /* The header. */ VRDEINTERFACEHDR header; /* * Same as in version 1 and 2. See comment in VRDECALLBACKS_1. */ DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut)); DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback, uint32_t u32ClientId, const char *pszUser, const char *pszPassword, const char *pszDomain)); DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback, uint32_t u32ClientId)); DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback, uint32_t u32ClientId, uint32_t fu32Intercepted)); DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback, uint32_t u32ClientId, uint32_t fu32Intercept, void **ppvIntercept)); DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback, void *pvIntercept, uint32_t u32ClientId, uint8_t u8Code, const void *pvRet, uint32_t cbRet)); DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback, void *pvIntercept, uint32_t u32ClientId, uint32_t u32Function, uint32_t u32Format, const void *pvData, uint32_t cbData)); DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback, unsigned uScreenId, VRDEFRAMEBUFFERINFO *pInfo)); DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback, unsigned uScreenId)); DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback, unsigned uScreenId)); DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback, int type, const void *pvInput, unsigned cbInput)); DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback, unsigned cWidth, unsigned cHeight, unsigned cBitsPerPixel, unsigned uScreenId)); /* * New for version 3. */ /** * Called by the server when something happens with audio input. * * @param pvCallback The callback specific pointer. * @param pvCtx The value passed in VRDEAudioInOpen. * @param u32ClientId Identifies the client that sent the reply. * @param u32Event The event code VRDE_AUDIOIN_*. * @param pvData Points to data received from the client. * @param cbData Size of the data in bytes. */ DECLR3CALLBACKMEMBER(void, VRDECallbackAudioIn,(void *pvCallback, void *pvCtx, uint32_t u32ClientId, uint32_t u32Event, const void *pvData, uint32_t cbData)); } VRDECALLBACKS_3; /** The VRDE server entry points. Interface version 4. * New entry point VRDEGetInterface has been added relative to version 3. */ typedef struct _VRDEENTRYPOINTS_4 { /* The header. */ VRDEINTERFACEHDR header; /* * Same as version 3. See comment in VRDEENTRYPOINTS_3. */ DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer)); DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable)); DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect)); DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer)); DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate)); DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer)); DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer)); DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples, VRDEAUDIOFORMAT format)); DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right)); DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm, uint32_t cbParm)); DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format, void *pvData, uint32_t cbData, uint32_t *pcbActualRead)); DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut)); DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer, const char *pszUser, const char *pszDomain, const char *pszPassword, uint32_t u32SessionId, const char *pszCookie)); DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer, void *pvCtx, uint32_t u32ClientId, VRDEAUDIOFORMAT audioFormat, uint32_t u32SamplesPerBlock)); DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer, uint32_t u32ClientId)); /** * Generic interface query. An interface is a set of entry points and callbacks. * It is not a reference counted interface. * * @param hServer Handle of VRDE server instance. * @param pszId String identifier of the interface, like uuid. * @param pInterface The interface structure to be initialized by the VRDE server. * Only VRDEINTERFACEHDR is initialized by the caller. * @param pCallbacks Callbacks required by the interface. The server makes a local copy. * VRDEINTERFACEHDR version must correspond to the requested interface version. * @param pvContext The context to be used in callbacks. */ DECLR3CALLBACKMEMBER(int, VRDEGetInterface, (HVRDESERVER hServer, const char *pszId, VRDEINTERFACEHDR *pInterface, const VRDEINTERFACEHDR *pCallbacks, void *pvContext)); } VRDEENTRYPOINTS_4; /* Callbacks are the same for the version 3 and version 4 interfaces. */ typedef VRDECALLBACKS_3 VRDECALLBACKS_4; /** * Create a new VRDE server instance. The instance is fully functional but refuses * client connections until the entry point VRDEEnableConnections is called by the application. * * The caller prepares the VRDECALLBACKS_* structure. The header.u64Version field of the * structure must be initialized with the version of the interface to use. * The server will return pointer to VRDEENTRYPOINTS_* table in *ppEntryPoints * to match the requested interface. * That is if pCallbacks->header.u64Version == VRDE_INTERFACE_VERSION_1, then the server * expects pCallbacks to point to VRDECALLBACKS_1 and will return a pointer to VRDEENTRYPOINTS_1. * * @param pCallback Pointer to the application callbacks which let the server to fetch * the configuration data and to access the desktop. * @param pvCallback The callback specific pointer to be passed back to the application. * @param ppEntryPoints Where to store the pointer to the VRDE entry points structure. * @param phServer Pointer to the created server instance handle. * * @return IPRT status code. */ DECLEXPORT(int) VRDECreateServer (const VRDEINTERFACEHDR *pCallbacks, void *pvCallback, VRDEINTERFACEHDR **ppEntryPoints, HVRDESERVER *phServer); typedef DECLCALLBACK(int) FNVRDECREATESERVER (const VRDEINTERFACEHDR *pCallbacks, void *pvCallback, VRDEINTERFACEHDR **ppEntryPoints, HVRDESERVER *phServer); typedef FNVRDECREATESERVER *PFNVRDECREATESERVER; /** * List of names of the VRDE properties, which are recognized by the VRDE. * * For example VRDESupportedProperties should return gapszProperties declared as: * * static const char * const gapszProperties[] = * { * "TCP/Ports", * "TCP/Address", * NULL * }; * * @returns pointer to array of pointers to name strings (UTF8). */ DECLEXPORT(const char * const *) VRDESupportedProperties (void); typedef DECLCALLBACK(const char * const *) FNVRDESUPPORTEDPROPERTIES (void); typedef FNVRDESUPPORTEDPROPERTIES *PFNVRDESUPPORTEDPROPERTIES; RT_C_DECLS_END /** @} */ #endif /* !VBOX_INCLUDED_RemoteDesktop_VRDE_h */