/** @file
* VBox Remote Desktop Extension (VRDE) - Public APIs.
*/
/*
* Copyright (C) 2006-2013 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* 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_RemoteDesktop_VRDE_h
#define ___VBox_RemoteDesktop_VRDE_h
/** @defgroup grp_vrdp VRDE
* VirtualBox Remote Desktop Extension (VRDE) interface that lets to use
* a Remote Desktop server like RDP.
* @{
*/
/* 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
#else
struct VRDEServer;
typedef struct VRDEServerType *HVRDESERVER;
#endif /* !__cplusplus */
/* Callback based VRDE server interface declarations. */
/** The color mouse pointer information. */
typedef struct _VRDECOLORPOINTER
{
/* The 1BPP mask and the 24BPP bitmap follow. */
/** Audio format information packed in a 32 bit value. */
/** 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. */
/** Decode number of channels. */
/** Decode number signess. */
/** Decode number of bits per sample. */
/** Decode number of bytes per sample. */
/*
* Audio input.
*/
/* Audio input notifications. */
typedef struct VRDEAUDIOINBEGIN
{
/*
* Remote USB protocol.
*/
/* The initial version 1. */
/* Version 2: look for VRDE_USB_VERSION_2 comments in the code. */
/* Version 3: look for VRDE_USB_VERSION_3 comments in the code. */
/* The default VRDE server version of Remote USB Protocol. */
/** USB backend operations. */
#define VRDE_USB_REQ_OPEN (0)
/** USB service operations. */
/** An operation completion status is a byte. */
/** USB device identifier is an 32 bit value. */
/** Status codes. */
/*
* 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. */
/* The operation code for which the reply was sent by the client. */
/* Common header for all return structures. */
typedef struct _VRDEUSBREQRETHDR
{
/* Device status. */
/* Device id. */
/* VRDE_USB_REQ_OPEN
*/
typedef struct _VRDE_USB_REQ_OPEN_PARM
{
typedef struct _VRDE_USB_REQ_OPEN_RET
{
/* VRDE_USB_REQ_CLOSE
*/
typedef struct _VRDE_USB_REQ_CLOSE_PARM
{
/* The close request has no returned data. */
/* VRDE_USB_REQ_RESET
*/
typedef struct _VRDE_USB_REQ_RESET_PARM
{
typedef struct _VRDE_USB_REQ_RESET_RET
{
/* VRDE_USB_REQ_SET_CONFIG
*/
typedef struct _VRDE_USB_REQ_SET_CONFIG_PARM
{
typedef struct _VRDE_USB_REQ_SET_CONFIG_RET
{
/* VRDE_USB_REQ_CLAIM_INTERFACE
*/
typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_PARM
{
typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_RET
{
/* VRDE_USB_REQ_RELEASE_INTERFACE
*/
typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_PARM
{
typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_RET
{
/* VRDE_USB_REQ_INTERFACE_SETTING
*/
typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_PARM
{
typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_RET
{
/* VRDE_USB_REQ_QUEUE_URB
*/
#define VRDE_USB_TRANSFER_TYPE_CTRL (0)
#define VRDE_USB_DIRECTION_SETUP (0)
typedef struct _VRDE_USB_REQ_QUEUE_URB_PARM
{
uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
/* 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
{
#define VRDE_USB_XFER_OK (0)
/* VRDE_USB_VERSION_2: New error codes. OHCI Completion Codes. */
/* VRDE_USB_VERSION_3: Fragmented URBs. */
/* VRDE_USB_VERSION_3: Fragmented URBs. */
typedef struct _VRDEUSBREQREAPURBBODY
{
/* 'len' bytes of data follow if direction of this URB was VRDE_USB_DIRECTION_IN. */
typedef struct _VRDE_USB_REQ_REAP_URB_RET
{
/* The REAP URB has no header, only completed URBs are returned. */
/* Another body may follow, depending on flags. */
/* VRDE_USB_REQ_CLEAR_HALTED_EP
*/
typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_PARM
{
typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_RET
{
/* VRDE_USB_REQ_CANCEL_URB
*/
typedef struct _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
{
/* Data is a list of the following variable length structures. */
typedef struct _VRDEUSBDEVICEDESC
{
/* Offset of the next structure. 0 if last. */
/* Identifier of the device assigned by client. */
/** USB version number. */
/** Device class. */
/** Device subclass. */
/** Device protocol */
/** Vendor ID. */
/** Product ID. */
/** Revision, integer part. */
/** Offset of the UTF8 manufacturer string relative to the structure start. */
/** Offset of the UTF8 product string relative to the structure start. */
/** Offset of the UTF8 serial number string relative to the structure start. */
/** Physical USB port the device is connected to. */
typedef struct _VRDEUSBDEVICEDESCEXT
{
/* Extended info.
*/
/** The USB device speed: VRDE_USBDEVICESPEED_*. */
typedef struct _VRDE_USB_REQ_DEVICE_LIST_RET
{
/* Other devices may follow.
* The list ends with (uint16_t)0,
* which means that an empty list consists of 2 zero bytes.
*/
typedef struct _VRDE_USB_REQ_DEVICE_LIST_EXT_RET
{
/* Other devices may follow.
* The list ends with (uint16_t)0,
* which means that an empty list consists of 2 zero bytes.
*/
/* The server requests the version of the port the device is attached to.
* The client must use VRDEUSBDEVICEDESCEXT structure.
*/
typedef struct _VRDEUSBREQNEGOTIATEPARM
{
/* 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.
*/
/* VRDEUSBREQNEGOTIATERET flags. */
/* VRDE_USB_VERSION_2: New flag. */
/* VRDE_USB_VERSION_3: New flag. */
* If this flag is set, then the VRDE_USB_CAPS2_FLAG_VERSION
* must also be set.
*/
/* VRDE_USB_VERSION_2: A set of valid flags. */
/* 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
{
typedef struct _VRDEUSBREQNEGOTIATERET_2
{
/* The server requests the version of the port the device is attached to.
* The client must use VRDEUSBDEVICEDESCEXT structure.
*/
typedef struct _VRDEUSBREQNEGOTIATERET_3
{
* VRDE_USB_CAPS2_FLAG_EXT flag are set.
* See VRDE_USB_CLIENT_CAPS_*
*/
#pragma pack()
#define VRDE_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
/** 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
*/
/** When last connection was established.
* int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
*/
/** 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
*/
/** How many bytes were sent in last (current) connection.
* uint64_t
*/
/** How many bytes were sent in all connections.
* uint64_t
*/
/** How many bytes were received in last (current) connection.
* uint64_t
*/
/** How many bytes were received in all connections.
* uint64_t
*/
/** Login user name supplied by the client.
* UTF8 nul terminated string.
*/
/** Login domain supplied by the client.
* UTF8 nul terminated string.
*/
/** The client name supplied by the client.
* UTF8 nul terminated string.
*/
/** IP address of the client.
* UTF8 nul terminated string.
*/
/** The client software version number.
* uint32_t.
*/
/** 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.
*/
/** TCP port where the server listens.
* Values: 0 - VRDE server failed to start.
* -1 - .
* int32_t.
*/
/** Hints what has been intercepted by the application. */
/** The version of the VRDE server interface. */
/** The header that does not change when the interface changes. */
typedef struct _VRDEINTERFACEHDR
{
/** The version of the interface. */
/** The size of the structure. */
/** The VRDE server entry points. Interface version 1. */
typedef struct _VRDEENTRYPOINTS_1
{
/** The header. */
/** Destroy the server instance.
*
* @param hServer The server instance handle.
*
* @return IPRT status code.
*/
/** 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.
*/
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.
*/
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.
*/
/**
* 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.
*/
unsigned uScreenId,
void *pvUpdate,
/**
* Set the mouse pointer shape.
*
* @param hServer Handle of VRDE server instance.
* @param pPointer The pointer shape information.
*/
const VRDECOLORPOINTER *pPointer));
/**
* Hide the mouse pointer.
*
* @param hServer Handle of VRDE server instance.
*/
/**
* 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.
*/
const void *pvSamples,
/**
* 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.
*/
/**
* 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.
*/
void *pvParm,
/**
* 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.
*/
void *pvData,
/**
* 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.
*/
void *pvBuffer,
/** 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. */
/** Destroy the server instance.
*
* @param hServer The server instance handle.
*
* @return IPRT status code.
*/
/** 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.
*/
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.
*/
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.
*/
/**
* 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.
*/
unsigned uScreenId,
void *pvUpdate,
/**
* Set the mouse pointer shape.
*
* @param hServer Handle of VRDE server instance.
* @param pPointer The pointer shape information.
*/
const VRDECOLORPOINTER *pPointer));
/**
* Hide the mouse pointer.
*
* @param hServer Handle of VRDE server instance.
*/
/**
* 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.
*/
const void *pvSamples,
/**
* 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.
*/
/**
* 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.
*/
void *pvParm,
/**
* 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.
*/
void *pvData,
/**
* 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.
*/
void *pvBuffer,
/**
* 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.
*/
const char *pszServer,
const char *pszUser,
const char *pszDomain,
const char *pszPassword,
const char *pszCookie));
/** 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. */
/*
* Same as version 2. See comment in VRDEENTRYPOINTS_2.
*/
bool fEnable));
bool fReconnect));
unsigned uScreenId,
void *pvUpdate,
const VRDECOLORPOINTER *pPointer));
const void *pvSamples,
void *pvParm,
void *pvData,
void *pvBuffer,
const char *pszServer,
const char *pszUser,
const char *pszDomain,
const char *pszPassword,
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.
*/
void *pvCtx,
/**
* 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.
*/
/* Indexes for VRDECallbackProperty.
* *_QP_* queries a property.
* *_SP_* sets a property.
*/
#define VRDE_QP_NETWORK_ADDRESS (2) /* UTF8 string. Host network interface IP address to bind to. */
#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_FEATURE (8) /* VRDEFEATURE structure. Generic interface to query named VRDE properties. */
#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
{
} VRDEFEATURE;
/* VRDE_SP_CLIENT_STATUS data. */
typedef struct VRDECLIENTSTATUS
{
/* A framebuffer description. */
typedef struct _VRDEFRAMEBUFFERINFO
{
int xOrigin;
int yOrigin;
unsigned cWidth;
unsigned cHeight;
unsigned cBitsPerPixel;
unsigned cbLine;
#define VRDE_INPUT_SCANCODE 0
typedef struct _VRDEINPUTSCANCODE
{
unsigned uScancode;
typedef struct _VRDEINPUTPOINT
{
int x;
int y;
unsigned uButtons;
typedef struct _VRDEINPUTSYNCH
{
unsigned uLockStatus;
#pragma pack()
/** The VRDE server callbacks. Interface version 1. */
typedef struct _VRDECALLBACKS_1
{
/** The 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.
*/
void *pvBuffer,
/* 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.
*/
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.
*/
/* 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_*).
*/
/* 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.
*/
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.
*/
void *pvIntercept,
const void *pvRet,
/**
* 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.
*/
void *pvIntercept,
const void *pvData,
/* 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.
*/
unsigned uScreenId,
/* 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.
*/
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.
*/
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.
*/
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.
*/
unsigned cWidth,
unsigned cHeight,
unsigned cBitsPerPixel,
unsigned uScreenId));
/* Callbacks are the same for the version 1 and version 2 interfaces. */
/** The VRDE server callbacks. Interface version 3. */
typedef struct _VRDECALLBACKS_3
{
/* The header. */
/*
* Same as in version 1 and 2. See comment in VRDECALLBACKS_1.
*/
void *pvBuffer,
const char *pszUser,
const char *pszPassword,
const char *pszDomain));
void **ppvIntercept));
void *pvIntercept,
const void *pvRet,
void *pvIntercept,
const void *pvData,
unsigned uScreenId,
unsigned uScreenId));
unsigned uScreenId));
int type,
const void *pvInput,
unsigned cbInput));
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.
*/
void *pvCtx,
const void *pvData,
/** 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. */
/*
* Same as version 3. See comment in VRDEENTRYPOINTS_3.
*/
DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect));
DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer));
DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples,
DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right));
DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format,
DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer,
DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer,
/**
* 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.
*/
const char *pszId,
const VRDEINTERFACEHDR *pCallbacks,
void *pvContext));
/* Callbacks are the same for the version 3 and version 4 interfaces. */
/**
* 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.
*/
void *pvCallback,
void *pvCallback,
/**
* 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[] =
* {
* NULL
* };
*
* @returns pointer to array of pointers to name strings (UTF8).
*/
DECLEXPORT(const char * const *) VRDESupportedProperties (void);
/** @} */
#endif