VMware Vdpservice SDK 3.2.0

VMware Horizon 7 Session
Enhancement SDK Programming Guide

VMware Horizon 7 Session Enhancement SDK 3.2
VMware Horizon 7
VMware Horizon 7 Session Enhancement SDK Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
https://docs.vmware.com/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2014–2017 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
Contents
VMware Horizon 7 Session Enhancement SDK Programming Guide 7
1 Overview of the VMware Horizon 7 Session Enhancement SDK 9

Introduction to the VMware Horizon 7 Session Enhancement API 9
About VMware Horizon 7 Session Enhancement Key Concepts 10
VMware Horizon 7 Session Enhancement Program Flow 11
Query Interface 13
RPC API 15
Overlay API 16
Installation 17
Sample Code 17
2 Data Types and Error Codes 19

Data Types 19
Error Codes 20
3 Channel Interaction Functions 23

ThreadInitialize 24
ThreadUninitialize 24
v1.Poll 25
v3.Poll 25
RegisterChannelNotifySink 26
UnregisterChannelNotifySink 26
Connect 27
Disconnect 27
GetConnectionState 28
GetChannelState 28
SwitchToStreamDataMode 29
GetSessionType 29
RegisterObserver 30
UnregisterObserver 30
Broadcast 30
4 RPC Functions 33
VariantInit 34
VariantCopy 35
VariantClear 35
VariantFromChar 36
VariantFromShort 36
VariantFromUShort 36
VariantFromInt32 37
VMware, Inc. 3
VariantFromUInt32 37
VariantFromInt64 38
VariantFromUInt64 38
VariantFromFloat 39
VariantFromDouble 39
VariantFromStr 40
VariantFromBlob 40
CreateChannelObject 41
DestroyChannelObject 41
GetObjectState 42
GetObjectName 42
v1.CreateContext 43
DestroyContext 43
Invoke 44
IsSideChannelAvailable 44
RequestSideChannel 45
GetObjectOptions 45
v3.CreateContext 45
GetId 46
GetCommand 46
SetCommand 47
GetNamedCommand 47
SetNamedCommand 48
GetParamCount 48
AppendParam 49
GetParam 49
AppendNamedParam 50
GetNamedParam 50
GetReturnCode 51
SetReturnCode 51
GetReturnValCount 52
AppendReturnVal 52
GetReturnVal 53
AppendNamedReturnVal 53
GetNamedReturnVal 54
SetOps 54
GetStreamDataHeaderTailSize 55
GetStreamDataHeaderTail 55
GetMinimalStreamDataSize 56
GetStreamDataSize 56
v1.GetStreamDataInfo 57
GetStreamData 57
FreeStreamDataPayload 58
v2.GetStreamDataInfo 58
5 Overlay Functions 61
VDPOverlayGuest_Interface Functions 61
v1.Init for the Guest-Side Library 61
v1.Exit for the Guest-Side Library 62
4 VMware, Inc.
Contents
v1.RegisterWindow 62
v1.UnregisterWindow 63
v1.IsWindowRegistered 63
v1.EnableOverlay 63
v1.DisableOverlay 64
v1.IsOverlayEnabled 65
v1.SetLayoutMode 65
v1.GetLayoutMode 66
v1.SendMsg for the Guest-Side Library 67
v2.GetColorkey 67
VDPOverlayClient_Interface Functions 68
v1.Init for the Client-Side Library 68
v1.Exit for the Client-Side Library 69
v1.Update 69
v1.GetInfo 70
v1.SendMsg for the Client-Side Library 70
v2.InitLocal 71
v2.CreateOverlay 71
v2.DestroyOverlay 72
v2.SetPosition 73
v2.SetSize 73
v2.SetClipRegion 74
v2.SetLayer 75
v2.SetColorkey 75
v2.EnableOverlay 76
v2.DisableOverlay 77
v2.SetLayoutMode 77
v2.Update 78
v2.GetInfo 79
6 Channel Sinks 81
OnConnectionStateChanged 81
OnChannelStateChanged 81
OnPeerObjectCreated 82
7 RPC Sinks 83
OnInvoke 83
OnObjectStateChanged 83
OnDone 84
OnAbort 84
8 Overlay Sinks 87
OnOverlayReady 87
OnOverlayRejected 88
OnOverlayCreateError 88
OnUserMsg (Guest Sink) 89
OnWindowRegistered 89
OnWindowUnregistered 90
VMware, Inc. 5
OnOverlayEnabled 90
OnOverlayDisabled 91
OnWindowPositionChanged 91
OnWindowSizeChanged 92
OnWindowObscured 92
OnWindowVisible 93
OnLayoutModeChanged 93
OnUserMsg (Client Sink) 93
Index 95
6 VMware, Inc.
VMware Horizon 7 Session Enhancement SDK
Programming Guide
This document, VMware Horizon 7 Session Enhancement SDK Programming Guide, provides information about
®
developing applications using the VMware Horizon 7 Session Enhancement Application Programming
Interface (API). VMware provides several software development kit (SDK) products, each of which targets
different developer communities and platforms.
Intended Audience
This guide is intended for software developers who want to create applications that are used remotely over
a VMware Horizon™ 7 connection.
VMware Technical Publications Glossary

VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions
of terms as they are used in VMware technical documentation, go to
http://www.vmware.com/support/pubs.
VMware, Inc. 7
8 VMware, Inc.
Overview of the VMware Horizon 7
Session Enhancement SDK 1
With the VMware Horizon 7 Session Enhancement Software Development Kit (SDK), you can develop
applications that communicate between a client and a remote desktop over a Horizon 7 connection using
Blast Extreme or PCoIP display protocol.
The SDK contains resources such as documentation, binaries, library files, include files, and code samples, to
help you develop applications that use the VMware Horizon 7 Session Enhancement API.
This chapter includes the following topics:
n “Introduction to the VMware Horizon 7 Session Enhancement API,” on page 9
n “About VMware Horizon 7 Session Enhancement Key Concepts,” on page 10
n “VMware Horizon 7 Session Enhancement Program Flow,” on page 11
n “Query Interface,” on page 13
n “RPC API,” on page 15
n “Overlay API,” on page 16
n “Installation,” on page 17
n “Sample Code,” on page 17
Introduction to the VMware Horizon 7 Session Enhancement API

The VMware Horizon 7 Session Enhancement API specifies how the client side and the desktop side of an
application can communicate over a VMware Horizon 7 connection. All interactions with the API are
asynchronous.
Any software that uses the Horizon 7 Session Enhancement API must have two components:
n Application
This is the code that runs on a remote desktop.
n Plug-In
This is the code that is installed on a client.
The Horizon 7 Session Enhancement API consists of two distinct APIs:
n Remote Procedure Call (RPC) API
The RPC API provides an asynchronous, callback-driven communication channel between applications
that run on a remote desktop and a plug-in that runs on a client. The RPC API also handles the
marshaling and un-marshaling of parameters.
VMware, Inc. 9
n Overlay API
The Overlay API solves the problem of displaying rendered images on the client. Images appear to a
user as a local window on the remote desktop.
OpenSSL Issue
The Horizon 7 Session Enhancement API dynamically loads the OpenSSL library to implement its security
features. If a software's application and plug-in components also dynamically load the OpenSSL library in
the same process as the Horizon 7 Session Enhancement API, you must adhere to the following rules to
prevent crashes or exceptions.
1 Plug-in components must not call the CRYPTO_set_locking_callback(), CRYPTO_set_id_callback(), and

CRYPTO_set_add_lock_callback() functions since vmware-remotemks already call these functions.
2 Application components must set up the above callbacks before loading the Horizon 7 Session
Enhancement API library. They must also ensure those callbacks are valid before unloading the
Horizon 7 Session Enhancement API library.
3 If the code is shared by both the plug-in and application components, you must call the above three
callback functions if CRYPTO_get_locking_callback() returns NULL. You must call those three functions
to set callbacks at the same time.
Supported Operating Systems

The Horizon 7 Session Enhancement API supports all Windows, Linux, and Mac operating systems that
Horizon 7 supports. For information about supported operating systems, see the View Installation document.
About VMware Horizon 7 Session Enhancement Key Concepts

To effectively use the VMware Horizon 7 Session Enhancement API, it is important to be familiar with the
key concepts in Horizon 7 Session Enhancement.
Connection
A connection refers to a VMware Horizon 7 session over Blast Extreme or PCoIP protocol. You cannot alter a
connection through the Horizon 7 Session Enhancement API, but you can determine the current state of a
connection. If a connection is not in the connected state, no action can be taken with the API. You can receive
notification of a change in a connection's state using VDPService_ChannelNotifySink through the
OnConnectionStateChanged callback. You can also retrieve the current state of a connection using the
GetConnectionState method that is found in VDPService_ChannelInterface API.
Channel
A channel represents the link between a remote application and a local plug-in. The state of a channel is not
necessarily the same as the state of a connection.
You can receive notification of a change in the state of a channel through the VDPService_ChannelNotifySink
function that you register with the channel. The OnChannelStateChanged callback delivers the state change.
You can query the current state of a channel using the GetChannelState method in
VDPService_ChannelInterface.
10 VMware, Inc.
Chapter 1 Overview of the VMware Horizon 7 Session Enhancement SDK
Side Channel
A side channel represents an additional link between a remote application and a local plug-in. A side
channel belongs to a channel object and is set up via channel. A side channel can only be established after a
channel object is connected. A side channel is designed to reduce application response time when there is
network congestion in the main channel. For example, an application can use the main channel to transfer
real-time control messages and use the side channel to transfer large amounts of user data.
Channel Context
A channel context is a wrapper for the parameters and return values of a remote call. A channel context
holds all of the information for the receiver of a remote call to determine which method is requested.
Interaction with the channel context is done using VDPRPC_ChannelContextInterface.
Overlay
An overlay is a window or image that is displayed over another so that the overlayed image or window
appears to be part of the underlying UI. This is typically done for video that plays locally, but needs to
appear as if it is playing on the remote machine.
Remote Procedure Call

A remote procedure call (RPC) is an invocation of a method on a non-local machine. Typically, the remote
machine publishes a set of methods that it responds to, and the client invokes the methods through some
channel. A call to Invoke initiates an RPC.
Sink
A sink is a structure of function pointers and is used to communicate asynchronously with user code. Each
API call has one or more sets of sinks. The user must register the sinks to receive the necessary callbacks that
give the user important information.
Variant
To ease cross-platform communication, all parameters that are used with the VDP RPC API are wrapped in
the VDP_RPC_VARIANT data type. This data type contains an identifier that indicates the type of data in the
structure and the data itself. The use of variants is done through VDPRPC_VariantInterface.
VMware Horizon 7 Session Enhancement Program Flow

A typical Horizon 7 session enhancement program flow involves the initialization of an application, a plug-
in, threads, and a channel, sink registration, and the calling of RPC and Overlay API methods, and shutting
down.
Application Initialization
The user controls the starting up of the remote side of the Horizon 7 session enhancement system. Upon
application launch, the user code calls the VDPServer_Init method and gets the
VDP_SERVICE_QUERY_INTERFACE structure. The user code then calls the QueryInterface method to fetch all the
interfaces that it needs to do its work.
VMware, Inc. 11
Plug-In Initialization
On the local side, it is the Horizon 7 session enhancement system that initializes the plug-in code. In the
VDPService_PluginInit call, the user code must store the passed-in reference to the
VDP_SERVICE_QUERY_INTERFACE structure and use it to request all the interfaces that it needs. At this point the
user code is only loaded. Once the matching application for the loaded plugin starts,
VDPService_PluginCreateInstance is called. In this callback, the user may return a pointer that is returned in
each callback, so that the user code can maintain its state. To match a plug-in and an application, call the
VDPService_PluginGetTokenName method, and compare the string that is returned with the string that is
given by the application.
Before returning from the VDPService_PluginCreateInstance callback, the user code must call Connect from
VDPService_ChannelInterface.
Note Due to a limitation in the underlying protocol used, the TokenName variable must be less than 16 bytes
in length.
Sink Registration
To receive callbacks from the Horizon 7 session enhancement system, you must register sinks for different
notifications. The first sink to register is VDPService_ChannelNotifySink. This sink notifies you of changes to
the connection state, the channel state, and when the application has created an object. For more information
about object creation, see the ChannelObject section below. To register the sink, use the
RegisterChannelNotifySink method in VDPService_ChannelInterface. After the sink is registered, you
receive a handle for that sink that you can use to unregister the sink. You must register
DPService_ChannelNotifySink before you call Connect to ensure that you receive a notification when the
channel is available.
After you register DPService_ChannelNotifySink be, you most likely will not receive a callback for a
connection state change. This is because by the time the application or plug-in is started, the connection is
likely to be in the connected state. To confirm that the connection is in the proper state prior to any actions,
use the GetConnectionState method.
In addition to VDPService_ChannelNotifySink, the following sinks exist:
n VDPRPC_ObjectNotifySink
This is for individual channel objects.
n VDPRPC_RequestCallback
This is for callbacks for each RPC call.
n VDPOverlayGuest_Sink
This is for important overlay notifications for the guest.
n VDPOverlayClient_Sink
This is for important overlay notifications for the client.
Thread Initialization
On the application side, the main thread is the one that the user calls VDPService_ServerInit on. On the
plug-in side, the main thread is the one that the VDPService_PluginCreateInstance callback is received on.
For other threads, you must call ThreadInitialize before you call any other method in the RPC APIs or the
Overlay APIs.
If a thread is no longer needed, you must uninitialize it by calling the ThreadUninitialize method.
12 VMware, Inc.
Channel
For communication to occur, the channel between the application and the plug-in must be active. To
initialize the channel connection, call the Connect method. It must be called on both sides of the connection
for each channel. To shut down a channel, call the Disconnect method.
After you call Disconnect, or whenever the channel is in a disconnected state, you must free all your channel
objects using the DestroyChannelObject method. If the channel is connected again, you must recreate any
required objects.
Query Interface
The query interface is a data type that both the Application and the Plug-in must interact with.
The query interface data type VDP_SERVICE_QUERY_INTERFACE is a struct that is defined in vdpService.h. The
Application and the Plug-in receive a reference to this struct differently. The struct has two members: a
version attribute, and a function pointer. The version attribute notifies the user's application which version
of the APIs are available. The function pointer is how the user's code will access the other APIs in the
system. The function pointer has the following definition.
Bool (*QueryInterface) (const GUID *iid, void *iface);
The QueryInterface() function fetches the functions that the user needs to interact with the Horizon 7
Session Enhancement API. The following table lists the GUIDs that are defined by Horizon 7 Session
Enhancement the the function lists that the GUIDs return.
Table 1‑1. Horizon 7 Session Enhancement GUIDs

GUID Returned Function List Version Header File
GUID_VDPRPC_VariantInterface_V1 VDPRPC_VariantInterface v1 vdprpc_interface.h
GUID_VDPRPC_ChannelObjectInterface_V3 VDPRPC_ChannelObjectInterface v3 vdprpc_interfaces.h
GUID_VDPRPC_ChannelContextInterface_V2 VDPRPC_ChannelContextInterfac v2 vdprpc_interfaces.h

e
GUID_VDPOverlay_GuestInterface_V2 VDPOverlay_GuestInterface v2 vdpOverlay.h
GUID_VDPOverlay_ClientInterface_V2 VDPOverlay_ClientInterface v2 vdpOverlay.h
GUID_VDPService_ChannelInterface_V2 VDPService_ChannelInterface v2 vdpService_interfaces.

h
GUID_VDPRPC_StreamDataInterface_V2 VDPRPC_StreamDataInterface v2 vdprpc_interfaces.h
GUID_VDPService_ObserverInterface_V1 VDPService_ObserverInterface v1 vdpService_interfaces.

h
The following sample code shows how to request an interface.
VDP_SERVICE_QUERY_INTERFACE qi;
VDPService_ChannelInterface ci;
qi.QueryInterface(GUID_VDPService_ChannelInterface_V1, &ci);
Application
The user launches the Application, which is the component that runs on the remote desktop. After the
Application starts and vdpService.dll is loaded, the Application calls VDPService_ServerInit() in the DLL.
When the Application exits, it must call VDPService_ServerExit(). The following table describes the two
server functions.
VMware, Inc. 13
Table 1‑2. Horizon 7 Session Enhancement Server Functions

Function Description
VDPService_ServerInit The Application calls this function when it starts. It must pass an identifying string (the
token) to the function. The function returns a pointer to VDP_SERVICE_QUERY_INTERFACE
and the channel handle for this Application, which uses the channel handle to initialize user
threads.
VDPService_ServerExit The Application calls this function when it closes down.
VDPService_ServerInit2 Same as VDPService_ServerInit but for a different session. Caller needs to have sufficient
privilege.
VDPService_ServerExit2 Same as VDPService_ServerExit but for a different session. Caller needs to have sufficient
privilege.
The following sample code shows how an Application initializes.
/* program startup (_tWinMain for example) */

VDP_SERVICE_QUERY_INTERFACE qi;
void *channelHandle;
VDPRPC_VariantInterface vi;
VDPOverlay_GuestInterface ogi;
/* other interfaces omitted */
VDPService_ServerInit("example" /* token */, &qi, &channelHandle);
qi.QueryInterface(GUID_VDPRPC_VariantInterface_V1, &vi);
qi.QueryInterface(GUID_VDPOverlay_GuestInterface_V1, &ogi);
/* ... */
Plug-In
The major difference between the Plug-in and the Application is that Horizon 7 loads the code on the client.
Therefore, the user-compiled code must be in a DLL or a shared object that the system loads. The Plug-in
must export the following functions.
Table 1‑3. Horizon 7 Session Enhancement Exported Plug-In Functions

Function Description
VDPService_PluginInit Invoked when the DLL or SO is loaded. The Plug-in receives its reference to
VDP_SERVICE_QUERY_INTERFACE.
VDPService_PluginInitWithP Similar to the VDPService_PluginInit function, but with an additional parameter

athFn for the absolute path to where the Plug-in is loaded from the disk.
VDPService_PluginExit Invoked when the DLL or SO is unloadedand the Horizon 7 session ends.
VDPService_PluginGetTokenN Horizon 7 Session Management uses this function to match the Plug-in with the
ame Application. The token that this function returns must match the token that the
matching Application passes to VDPService_ServerInit for communication to
occur.
VDPService_PluginCreateIns Invoked when a new channel's identifier matches the one that
tance VDPService_PlugingetTokenName returns. More than one instance of a plug-in may
exist. Horizon 7 Session management matches instances of the plug-in to the correct
channel.
VDPService_PluginDestroyIn Called when the channel this plug-in instance runs on closes.
stance
14 VMware, Inc.
RPC API
With the RPC API, applications and plug-ins can communicate across channels. You must perform all
VDPService initialization steps before you call the RPC API.
Channel Object
Before communication can occur, a channel object with the same name must exist on both sides of the
connection. To create a channel object, call the CreateChannelObject method. It does not matter whether the
channel object is created in the application or in the plug-in first. The initial state of the channel object is
disconnected.
When a channel object is created, a message is sent to the other side of the connection, where the callback
function OnPeerObjectCreated is called. To create a matching object, call the CreateChannelObject method.
After the matching object is created, the state of the object on both sides is connected and both sides receive
a state change notification.
After a channel object is connected, you can request a side channel for this object. There are two types of side
channels: virtual side channel and TCP side channel. A virtual side channel is an additional virtual channel.
A TCP side channel is a TCP socket connection between a client and an agent. When a side channel is
established and both sides receive a state change notification, the state of the channel object will change to
VDP_RPC_OBJ_SIDE_CHANNEL_CONNECTED. Once a side channel is connected, all RPCs (Invoke,
OnInvoke, and so on) will go through the side channel.
For a TCP side channel, an agent application can switch to stream data mode to save resources. In stream
data mode, all VDPService internal threads will be exited and an application has to use a TCP socket to send
data to and receive data from a plug-in. RPC packets can be created and parsed by stream data APIs.
Invoke
After you create a channel object, you cam invoke an RPC with the Invoke method. You must make the
Invoke call on the thread that you create the object on, unless the object is configured to allow invoke on any
thread.
The Invoke call requires a ChannelContext data structure, which is a wrapper for all the data for the RPC,
such as the command, parameters, and so on. You create a context with the CreateContext function. After
the context is created, add information for the RPC to the context with the VDPRPC_ChannelContextInterface
method and pass the context to Invoke. Even though you create the context, if the call to Invoke succeeds,
the API is responsible for freeing the context. This is because of the asynchronous nature of the API. When
the call to Invoke returns, the context might still be in use.
Each channel context has a unique ID that you can retrieve with the GetId method. The ID of a context that
is passed to an Invoke call is returned as a parameter in the OnDone and OnAbort handlers. You can use the ID
to map the callbacks to the Invoke call that they refer to. The ID of a context that is passed to the handlers
represents the return values from the other end of the connection and does not match the originating context
ID.
Variant
All data that you add to a channel context must be in a VDP_RPC_VARIANT data structure. The following code
sample shows how to add data to a variant and append it to a context.
VDP_RPC_VARIANT var;
VDPRPC_VariantInterface varIface;
VDPRPC_ChannelContextInterface ctxtIface;
void *contextHandle;
varIface.v1.VariantFromInt32(&var, 32);
ctxtIface.v1.AppendParam(contextHandle, &var);
VMware, Inc. 15
varIface.v1.VariantClear(&var);
varIface.v1.VariantFromString(&var, "sample string");
ctxtIface.v1.AppendNamedParam(contextHandle, "sample param", &var);
varIface.v1.VariantClear(&var);
After each use of a variant, call the VariantClear method to ensure that all resources are freed.
OnInvoke
On a successful Invoke call, the peer object receives an OnInvoke callback. In this callback you receive a
channel context. The context contains all of the information for the call. To respond, add the appropriate
return code and return values to the channel context, which is returned to the caller when the OnInvoke call
returns.
Application Shutdown
The application must call VDPService_ServerInit.
Plug-In Shutdown
If the channel that is associated with a plug-in is closed, the plug-in's VDPService_PluginDestroyInstance
method is called. The plug-in must free all resources and shut down.
Overlay API
With the Overlay API, you can overlay a window or an image on top of another windows or image. You
typically do this to make video that is playing locally appear as if it is playing on a remote machine.
Guest Setup
To use the Overlay API, the first step is to initialize the guest interface by calling the Init method. After a
successful initialization, register the window that you want to overlay by calling the RegisterWindow
method. The size and position of the registered window are tracked and sent to the client automatically. If
the client does not reject the registered window, you receive the OnOverolayReady callback. When you receive
this callback, you call the EnableOverlay function to display the overlay on the client.
When you are finished with the window, unregister it by calling UnregisterWindow.
Client Setup
On the client, the first step is to initialize the interface by calling Init, which returns a context ID. You use
the ID to identify the plug-in instance. When the guest registers a window, the client is notified through the
OnWindowRegistered sink callback, which gives you a window ID. You need both the context ID and the
window ID to update the overlay.
After you receive the OnOverlayReady callback, you can start displaying your image by calling the Update
method. The API does not keep a copy of the image unless the copyImage parameter is set to true. If you do
not own the image resource or you need to free it, you must set the copyImage parameter.
When you are finished with the overlay, call the Exit method.
16 VMware, Inc.
Installation
To use the Horizon 7 Session Enhancement API, you must install files on both the remote desktop and the
client.
Remote Desktop
The file vdpService.dll must exist on the remote desktop. When you install Horizon 7 Agent, this file is
automatically installed at %ProgramFiles%\common files\VMware\Remote Experience. The 64-bit version of
vdpService.dll is installed under x64 in the same directory.
Client
The file vdpService.dll (.so, .dylib) must exist on the client. It is highly recommended that you use the
one installed by the latest Horizon Client. If you have Horizon Client 4.0 or later, you do not need to install
vdpService.dll (.so, .dylib) from this SDK. If you have Horizon Client 3.5.x or earlier, install the file
from this SDK. If you want to install your own version of the library, make sure that you install the latest
openssl shared library, which is shipped with Horizon Client and also this SDK.
Windows Client
When you install Horizon Client, vdpService.dll is copied to the installation directory, for example,
C:\Program Files (x86)\VMware\VMware Horizon Client. If you have Horizon Client 3.5.x or earlier, replace
vdpService.dll with the one from this SDK and run the regsvr32 command to register the DLL.
Linux Client
Copy libvdpService.so to /usr/lib/pcoip/vchan_plugins. Copy the vdpService RPC plug-ins
to /usr/lib/vmware/view/vdpService. Make sure that the plu-ins have the execute permission. For overlay,
create the file /etc/vmware/vdp/host_overlay_plugins/config and add the following line to the file.
/usr/lib/pcoip/vchan_plugins/libvdpService.so
Mac Client
Copy libvdpService.dylib to /Applications/VMware\
Horizon/Client.app/Contents/Library/pcoip/vchan_plugins. Copy the vdpService RPC plug-ins
to /Applications/VMware\ Horizon/Client.app/Contents/Library/pcoip/vchan_plugins/vdpservice. Mac
client does not support overlay in this release.
Sample Code
In the Horizon 7 Session Enhancement SDK is a directory called samples that contains code samples of all
the methods in the SDK.
VMware, Inc. 17
18 VMware, Inc.
Data Types and Error Codes 2
The Horizon 7 Session Enhancement API has three groups of data types. The API also specifies error codes
for various error conditions.
n “Data Types,” on page 19
n “Error Codes,” on page 20
Data Types
The Horizon 7 Session Enhancement API uses the data types VDP Service, VDP RPC, and Overlay.
VDP Service Data Types

Table 2‑1. VDPService Data Types
Data Type Description
VDPService_ConnectionState This enum indicates the current state of the remote connection.
VDPService_ChannelState This enum indicates the current state of a particular channel.
VDPService_SessionType This enum indicates the type of the current session (Blast Extreme or PCoIP).
VDP RPC Data Types

The VDP RPC data types are for use with the VDP RPC API.
Table 2‑2. VDP RPC Data Types

VDP_RPC_VARENUM This enum indicates the type of data that is stored in a VDP_RPC_VARIANT.
VDP_RPC_BLOB Stores data that does not fit in any predefined VDP_RPC_VARENUM. Because VDP
Service sends the data as is, it cannot protect against changes in byte endianness.
Use care to avoid errors.
VDP_RPC_VARIANT Wraps the data for the RPC calls. Any data that is sent with the Invoke call must
be contained in a VDP_RPC_VARIANT.
VDPRPC_ObjectState Represents the state of an object. Only objects in the VDP_RPC_OBJ_CONNECTED

state can be used in the Invoke call.
VDPRPC_ObjectConfigurationFlag These flags configure new objects.

s
VMware, Inc. 19
Table 2‑2. VDP RPC Data Types (Continued)

VDPRPC_ChannelContectOps These flags configure options of a new context, for example, compression,
encryption, and so on.
VDPRPC_SideChannelType Virtual side channel or TCP side channel.
VDP Overlay Data Types

The VDP Overlay data types are for use with the Overlay API. They are found in vdpOverlay.h.
Table 2‑3. VDP Overlay Guest Data Types

VDPOverlay_WindowId An uint32 representation of the native OS window.
VDPOverlay_UserArgs Parameter that is passed through to the callback on the remote side.
VDPOverlay_LayoutMode This enum represents all of the different layouts that the VDP Overlay API
supports.
VDPOverlay_Error Returned by many of the Overlay functions. Indicates the results that may occur.
Table 2‑4. VDP Overlay Client Data Types

VDPOverlayClient_ContextId Returned from VDPOverlayClient_Init. This ID is used in every call to the

Client API.
VDPOverlayClient_OverlayInfo This structure is used in the call to VDPOverlayClient::GetInfo().

In V1 the first member of VDPOverlayClient_OverlayInfo was cbSize
which was set by the caller to determine the version of the struct. But doing
that was not backward compatible. For examle, a program written to V2
would return an error if it called GetInfo() because the size wouldn't be set
correctly.
Starting with V2 the first member of VDPOverlayClient_OverlayInfo is a
version and is set by GetInfo() to the version of the function that filled the
structure. For backward compatibility when calling v1.GetInfo() the caller
must set version = VDP_OVERLAY_INFO_V1_SIZE before calling
v1.GetInfo().
VDPOverlay_LayoutMode This enum represents all of the different layouts that the VDP Overlay API
supports.
VDPOverlay_Error Returned by many of the Overlay functions. Indicates the results that may
occur.
VDPOverlay_ImageFormat This enum defines the pixel format of an image passed to

VDPOverlayClient_Interface.v2.Update(). Note that
VDPOverlayClient_Interface.v1.Update() always assumes
VDP_OVERLAY_BGRX formated images.
Error Codes
The Horizon 7 Session Enhancement API specifies codes to indicate errors.
OnAbort Reason Error Codes

If the call to the VDPRPC_ChannelObjectInterface.v1.OnInvoke() method fails due to a Horizon 7 Session
Enhancement error, the supplied OnAbort method is called and the last parameter to this method contains
one of the following error codes.
20 VMware, Inc.
Chapter 2 Data Types and Error Codes
Table 2‑5. OnAbort Reason Error Codes

Code Description
VDP_RPC_E_APARTMENT_UNINITIALIZ This error occurs if the OnInvoke call is made on a thread that is not
ED initialized to be used with the Horizon 7 Session Management API.
VDP_RPC_E_APARTMENT_THREAD This error occurs if the OnInvoke call involves an object that was not
created on the calling thread and the object is not configured to allow
OnInvoke calls on different threads.
VDP_RPC_E_OBJECT_NOT_CONNECTED This error occurs if the object handle that is used for the OnInvoke call
points to an object that is not connected. This error indicates that the peer
object on the remote side is not yet created.
VDP_RPC_E_PARAMETER One of the required parameters that is passed to the OnInvoke call is
invalid.
VDP_RPC_E_MEMORY The system fails to allocate the required memory to send the request.
VDP Overlay Error Codes

If an error occurs, many of the methods that are defined in vdpOverlay.h return one of the following errors.
Table 2‑6. VDP Overlay Error Codes

Code Description
VDP_OVERLAY_ERROR_SUCCESS No error. The call is successful.
VDP_OVERLAY_ERROR_NOT_INITIALIZE The call fails because the VDP Overlay components are not properly
D loaded in the Horizon 7 environment.
VDP_OVERLAY_ERROR_ALREADY_INITI This error is only returned from the

ALIZED VDPOverlayGuest_Interface.v1.Init() call. The guest Overlay
system is already initialized.
VDP_OVERLAY_ERROR_INVALID_PARA One of the required parameters that is passed to the call is invalid.
METER
VDP_OVERLAY_ERROR_ALLOCATION_E The system fails to allocate the required memory or system resource to
RROR handle the call.
VDP_OVERLAY_ERROR_NO_MORE_OVE This error results from a failed attempt to register a window and may be
RLAYS received in the VDPOverlayGuest_Sink.v1.OnOverlayCreateError()
or VDPOverlayClient.v2.CreateOverlay() callback. This error may
be due to a client-side error. It can also occur if the call tries to register a
window that is already registered with a different plug-in.
VDP_OVERLAY_ERROR_OVERLAY_REJEC This error results from a failed attempt to register a window and is
TED returned in the reason field of the
VDPOverlayGuest_Sink.v1.OnOverlayRejected() callback. This error
occurs if the client does not accept the plug-in.
VDP_OVERLAY_ERROR_OVERLAY_NOT_ This error occurs when either

READY VDPOverlayGuest_Interface.v1.EnableOverlay or
VDPOverlayGuest_Interface.v1.DisableOverlay fails. It indicates
that the registered window is not ready, that is, the
VDPOverlayGuest_Sink.v1.OnOverlayReady() callback is not yet
received.
VDP_OVERLAY_ERROR_WINDOW_NOT_ The window ID that is specified in the call is not yet registered. Many
REGISTERED Overlay methods may return this error.
VDP_OVERLAY_ERROR_WINDOW_ALRE The window is already registered. This error can be returned fro the
ADY_REGISTERED VDPOverlayGuest_Interface.v1.RegisterWindow() method.
VMware, Inc. 21
Table 2‑6. VDP Overlay Error Codes (Continued)

Code Description
VDP_OVERLAY_ERROR_NOT_LOCAL_OV The overlayId of a guest-side overlay was passed to a function that can
ERLAY only be called on a local overlay.
VDP_OVERLAY_ERROR_HOST_OVERLAY There is an error with a low level library. This error code should be
_ERROR treated as similar to INVALID_PARAMETER.
22 VMware, Inc.
Channel Interaction Functions 3
The Horizon 7 Session Enhancement SDK contains the header file vdpService_interfaces.h. This file
declares two structures of function pointers, VDPService_ChannelInterface and
VDPService_ObserverInterface.
You can use VDPService_ChannelInterface to interact with the remote connection or channel. With
VDPService_ObserverInterface two components within the same process can communicate
VDPService_ChannelInterface consists of the following functions:
n ThreadInitialize
n ThreadUninitualize
n Poll
n RegisterChannelNotifySink
n UnregisterChannelNotifySink
n Connect
n Disconnect
n GetConnectionState
n GetChannelState
n SwitchToStreamdataMode
n GetSessionType
VDPService_ObserverInterface consists of the following functions:
n RegisterObserver
n UnregisterObserver
n Broadcast
n “ThreadInitialize,” on page 24
n “ThreadUninitialize,” on page 24
n “v1.Poll,” on page 25
n “v3.Poll,” on page 25
n “RegisterChannelNotifySink,” on page 26
n “UnregisterChannelNotifySink,” on page 26
VMware, Inc. 23
n “Connect,” on page 27
n “Disconnect,” on page 27
n “GetConnectionState,” on page 28
n “GetChannelState,” on page 28
n “SwitchToStreamDataMode,” on page 29
n “GetSessionType,” on page 29
n “RegisterObserver,” on page 30
n “UnregisterObserver,” on page 30
n “Broadcast,” on page 30
ThreadInitialize
Initializes the thread for use with the Horizon 7 Session Enhancement APIs. This method must be called on
any thread that is not the main thread. Do not call this method on the thread that received the
VDPService_PluginCreateInstance callback or that the VDPService_ServerInit call was made from.
This function is a member of VDPService_ChannelInterface.
Method Signature
Bool (*ThreadInitialize)(void *channelHandle, uint32 unusedFlag);
Parameters
Parameter Description
channelHandle Represents the channel instance that this plug-in instance is running on. The channel handle is
returned from the VDPService_ServerInit call or passed from the
VDPService_PluginCreateInstance method.
unusedFlag Currently unused.
Return Values
Value Description
TRUE The thread was successfully initialized.
FALSE Thread initialization failed.
ThreadUninitialize
Uninitializes the calling thread, freeing all resources associated with Horizon 7 Session Enhancement. No
API calls must be made from this thread after this call. Only call this method on threads that had
ThreadInitialize invoked.
Method Signature
Bool (*ThreadUninitialize)(void);
Parameters
None
24 VMware, Inc.
Chapter 3 Channel Interaction Functions
Return Values
Value Description
TRUE The thread was successfully uninitialized.
FALSE Thread uninitialization failed.
v1.Poll
Allows the Horizon 7 Session Enhancement system to process any waiting events. This call is required on
any thread that the ThreadInitialize call was made to so that the Horizon 7 Session Enhancement system
can function. If there are no waiting events, this call will just return.
Note All waiting events will be processed, so control may not be returned to you for some time. Most
events will cause calls to registered sinks. Callbacks might be fired.
On Windows, if the thread uses its own message loop, using the method is not required.
Method Signature
void (*Poll)(void);
Parameters
None
Return Values
None
v3.Poll
Allows the Horizon 7 Session Enhancement system to process any waiting events. This call is required on
any thread that the ThreadInitialize call was made to so that the Horizon 7 Session Enhancement system
can function. If there are no waiting events, this call will be blocked until the next event or timeout is
reached.
Note All waiting events will be processed, so control may not be returned to you for some time. Most
events will cause calls to registered sinks. Callbacks might be fired.
On Windows, if the thread uses its own message loop, using the method is not required.
Method Signature
void (*Poll)(int timeout);
Parameters
timeout The time limit after which the Poll method will return.
VMware, Inc. 25
Return Values
None
RegisterChannelNotifySink
Registers the given VDPService_ChannelNotifySink with the channel associated with the calling thread. You
may register any number of sinks, and each will receive a callback when an event occurs.
The sinkHandle parameter will be set to the handle assigned to the given sink. This is used to unregister the
sink with the channel.
Method Signature
Bool (*RegisterChannelNotifySink)(const VDPService_ChannelNotifySink *sink, void *userData,
uint32 *sinkHandle);
Parameters
sink The sink to register with the channel.
userData Data that will be passed into any callbacks to this sink. Can be NULL.
sinkHandle Set to the handle assigned to this sink.
Return Values
Value Description
TRUE The sink was successfully registered.
FALSE Sink registration failed.
UnregisterChannelNotifySink
Removes the sink associated with the given handle from the list of sinks the channel associated with the
calling thread will notify of Horizon 7 Session Enhancement events.
Method Signature
(*UnregisterChannelNotifySink)(uint32 sinkHandle);
Parameters
sinkHandle The handle returned from RegisterChannelNotifySink of the sink to be unregistered.
26 VMware, Inc.
Return Values
Value Description
TRUE The sink that matches the given handle was successfully unregistered.
FALSE The sink is still registered with the handle.
Connect
Starts the channel connection. You must call Connect on both the application and the plug-in side, though
the order does not matter. Call this method prior to exiting the VDPService_PluginCreateInstance callback.
Method Signature
Bool (*Connect)(void);
Parameters
None
Return Values
Value Description
TRUE Call succeeded.
FALSE Call failed.
Disconnect
Closes the underlying channel connection. You can call this method on either the plug-in or the application
side.
Method Signature
Bool (*Disconnect)(void);
Parameters
None
Return Values
Value Description
TRUE Call succeeded.
FALSE Call failed.
VMware, Inc. 27
GetConnectionState
Used to query the state of the underlying Horizon 7 session. Note that depending on when a sink was
registered, you might not receive a callback noting that the connection state has changed. Use this method to
determine the state of the connection at any time.
Method Signature
VDPService_ConnectionState (*GetConnectionState)(void);
Parameters
None
Return Values
Value Description
VDP_SERVICE_CONN_UNINITIALIZED The Horizon 7 session cannot be found.
VDP_SERVICE_CONN_DISCONNECTED The Horizon 7 session is currently inactive.
VDP_SERVICE_CONN_PENDING The Horizon 7 session is not connected, but active on the calling end.
VDP_SERVICE_CONN_CONNECTED The Horizon 7 session is active.
GetChannelState
Queries the current state of the channel connection between application and plug-in instances. The channel
to query is determined by the ID of the calling thread.
Method Signature
VDPService_ChannelState (*GetChannelState)(void);
Parameters
None
Return Values
Value Description
VDP_SERVICE_CHAN_UNINITIALIZED The channel for this thread could not be found.
VDP_SERVICE_CHAN_DISCONNECTED The channel is inactive.
VDP_SERVICE_CHAN_PENDING The channel is open on the calling end, but not yet connected.
VDP_SERVICE_CHAN_CONNECTED The channel is active.
28 VMware, Inc.
SwitchToStreamDataMode
Switches vdpservice to TCP socket mode. This is an agent-only feature. In this mode, user can use output
socket handle to send and receive data via a TCP socket handler. All internal vdpservice threads are
terminated in order to save resources. Only VDPRPC_StreamDataInterface and VDPService_ServerExit APIs
can be called for the data process and final clean up.
Method Signature
BOOL (*SwitchToStreamDataMode)(const char *tcpObjName, void *channelHandle, int *fd);
Parameters
tcpObjName The name of the object which requested the TCP side channel.
channelHandle Represents the channel interface that this plug-in is running on. The channelHandle is returned from
the Vdpservice_ServerInit call or passed from the VDPService_PluginCreateInstance method.
fd Output TCP socket handle.
Return Values
Value Description
TRUE Switching to stream data mode succeeded.
FALSE Switching to stream data mode failed.
GetSessionType
Gets the current virtual channel type.
Method Signature
VDPService_SessionType (*GetSessionType)(void);
Parameters
None
Return Values
Value Description
VDP_SERVICE_NONE_SESSION Session type not determined yet.
VDP_SERVICE_PCOIP_SESSION vdpservice is running in a PCoIP session.
VDP_SERVICE_BLAST_SESSION vdpservice is running in a Blast Extreme session.
VMware, Inc. 29
RegisterObserver
Registers an observer with the given name and callbacks.
This function is a member of VDPService_ObserverInterface.
Method Signature
VDPService_ObserverId (*RegisterObserver)(* RegisterObserver) (const char *name, void *context,
VdpServiceObserverCallback cb);
Parameters
name The name of message caller is interested.
context Context pointer caller want to passed in callback.
cb Callback function when given name message is available.
Return Values
Value Description
uint32 The ID of the registered observer or 0 (failed).
UnregisterObserver
Unregisters an observer with the given name and callbacks.
Method Signature
BOOL (*UnregisterObserver)(VDPService_ObserverId id);
Parameters
id The observer id returned from RegisterObserver.
Return Values
Value Description
TRUE Unregister succeeded.
FALSE Unregister failed.
Broadcast
Broadcasts a given name's message to all observers. Basically, it will call all registered callbacks.
30 VMware, Inc.
Method Signature
BOOL (*Broadcast)(const char *name, const void *cookie, const void *data);
Parameters
name The name of the message.
cookie User-defined data. It can be as simple as request ID.
data Message data.
Return Values
Value Description
TRUE Success
FALSE Failure
VMware, Inc. 31
32 VMware, Inc.
RPC Functions 4
The vdprpc_interfaces.h header file included in the Horizon 7 Session Enhancement SDK contains a set of
structs of function pointers to send RPC messages.
n “VariantInit,” on page 34
n “VariantCopy,” on page 35
n “VariantClear,” on page 35
n “VariantFromChar,” on page 36
n “VariantFromShort,” on page 36
n “VariantFromUShort,” on page 36
n “VariantFromInt32,” on page 37
n “VariantFromUInt32,” on page 37
n “VariantFromInt64,” on page 38
n “VariantFromUInt64,” on page 38
n “VariantFromFloat,” on page 39
n “VariantFromDouble,” on page 39
n “VariantFromStr,” on page 40
n “VariantFromBlob,” on page 40
n “CreateChannelObject,” on page 41
n “DestroyChannelObject,” on page 41
n “GetObjectState,” on page 42
n “GetObjectName,” on page 42
n “v1.CreateContext,” on page 43
n “DestroyContext,” on page 43
n “Invoke,” on page 44
n “IsSideChannelAvailable,” on page 44
n “RequestSideChannel,” on page 45
n “GetObjectOptions,” on page 45
VMware, Inc. 33
n “v3.CreateContext,” on page 45
n “GetId,” on page 46
n “GetCommand,” on page 46
n “SetCommand,” on page 47
n “GetNamedCommand,” on page 47
n “SetNamedCommand,” on page 48
n “GetParamCount,” on page 48
n “AppendParam,” on page 49
n “GetParam,” on page 49
n “AppendNamedParam,” on page 50
n “GetNamedParam,” on page 50
n “GetReturnCode,” on page 51
n “SetReturnCode,” on page 51
n “GetReturnValCount,” on page 52
n “AppendReturnVal,” on page 52
n “GetReturnVal,” on page 53
n “AppendNamedReturnVal,” on page 53
n “GetNamedReturnVal,” on page 54
n “SetOps,” on page 54
n “GetStreamDataHeaderTailSize,” on page 55
n “GetStreamDataHeaderTail,” on page 55
n “GetMinimalStreamDataSize,” on page 56
n “GetStreamDataSize,” on page 56
n “v1.GetStreamDataInfo,” on page 57
n “GetStreamData,” on page 57
n “FreeStreamDataPayload,” on page 58
n “v2.GetStreamDataInfo,” on page 58
VariantInit
Initializes the given VDP_RPC_VARIANT.
This function is a member of VDPRPC_VariantInterface.
Method Signature
Bool (*VariantInit)(VDP_RPC_VARIANT *v);
Parameters
v The variant to be initialized.
34 VMware, Inc.
Chapter 4 RPC Functions
Return Values
Value Description
TRUE The variant was successfully initialized.
FALSE Initialization failed.
VariantCopy
Copies the data held from the Variant src to the Variant target. Any data held by target is overwritten. Any
data previously held in target is freed before being overwritten with the data in src.
Method Signature
Bool (*VariantCopy)(VDP_RPC_VARIANT *target, const VDP_RPC_VARIANT *src);
Parameters
target The variant to copy the data to.
src The variant to copy the data from.
Return Values
Value Description
TRUE Copy succeeded.
FALSE Copy failed. The target is unchanged.
VariantClear
Clears and frees any resources held by the given Variant. Call this method whenever you are finished with a
Variant, including after successfully adding a Variant to a context.
Method Signature
Bool (*VariantClear)(VDP_RPC_VARIANT *v);
Parameters
v The variant to clear.
Return Values
Value Description
TRUE The Variant is returned to initialized state.
FALSE The Variant is unchanged.
VMware, Inc. 35
VariantFromChar
Stores the given char in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromChar)(VDP_RPC_VARIANT *v, char c);
Parameters
v The variant to set.
c The char to store.
Return Values
Value Description
TRUE The char was successfully stored in the Variant.
FALSE Setting the Variant failed.
VariantFromShort
Stores the given short in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromShort)(VDP_RPC_VARIANT *v, short s);
Parameters
s The short to store.
Return Values
Value Description
TRUE The short was successfully stored in the Variant.
VariantFromUShort
Stores the given unsigned short in the given Variant and sets the internal type properly.
36 VMware, Inc.
Method Signature
Bool (*VariantFromUShort)(VDP_RPC_VARIANT *v, unsigned short us);
Parameters
us The unsigned short to store.
Return Values
Value Description
TRUE The unsigned short was successfully stored in the Variant.
VariantFromInt32
Stores the given int32 in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromInt32)(VDP_RPC_VARIANT *v, int32 i);
Parameters
i The int32 to store.
Return Values
Value Description
TRUE The int32 was successfully stored in the Variant.
VariantFromUInt32
Stores the given uint32 in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromUInt32)(VDP_RPC_VARIANT *v, uint32 ui);
VMware, Inc. 37
Parameters
ui The uint32 to store.
Return Values
Value Description
TRUE The uint32 was successfully stored in the Variant.
VariantFromInt64
Stores the given int64 in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromInt64)(VDP_RPC_VARIANT *v, int64 i);
Parameters
i The int64 to store.
Return Values
Value Description
TRUE The int64 was successfully stored in the Variant.
VariantFromUInt64
Stores the given uint64 in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromChar)(VDP_RPC_VARIANT *v, uint64 ui);
Parameters
ui The uint64 to store.
38 VMware, Inc.
Return Values
Value Description
TRUE The uint64 was successfully stored in the Variant.
VariantFromFloat
Stores the given float in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromFloat)(VDP_RPC_VARIANT *v, float f);
Parameters
f The float to store.
Return Values
Value Description
TRUE The float was successfully stored in the Variant.
VariantFromDouble
Stores the given double in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromDouble)(VDP_RPC_VARIANT *v, double d);
Parameters
d The double to store.
Return Values
Value Description
TRUE The double was successfully stored in the Variant.
VMware, Inc. 39
VariantFromStr
Stores a copy of the given const char * in the given Variant and sets the internal type properly.
Method Signature
Bool (*VariantFromStr)(VDP_RPC_VARIANT *v, const char *str);
Parameters
str The const char * to copy.
Return Values
Value Description
TRUE The const char * was successfully copied into the Variant.
VariantFromBlob
Stores a copy of the given VDP_RPC_BLOB in the given Variant. Use this method only for data that does not
fit any of the other types. Data is sent as is, so changes in architecture (such as sending from the Linux client
to the Windows guest) can wreak havoc on your data.
Method Signature
Bool (*VariantFromBlob)(VDP_RPC_VARIANT *v, VDP_RPC_BLOB *blob);
Parameters
blob The VDP_RPC_BLOB to copy.
Return Values
Value Description
TRUE The VDP_RPC_BLOB was successfully copied into the Variant.
40 VMware, Inc.
CreateChannelObject
Creates a channel object with the given name. This call, with the same object name, must be made on both
the plug-in and the application for communication to occur.
Objects begin in the VDP_RPC_OBJ_PENDING state. After the peer object is created, which might be prior
to the call, the state goes to VDP_RPC_OBJ_CONNECTED. The sink registered with the object receives
notifications of events involving the new object. A handle for the created object is returned in the
objectHandle parameter
Note Objects must be used on the thread on which the are created, unless configured with the
VDP_RPC_OBJ_CONFIG_INVOKE_ALLOW_ANY_THREAD flag. If this option is used, the user is
responsible for thread safety.
This function is a member of VDPRPC_ChannelObjectInterface.
Method Signature
Bool (*CreateChannelObject)(const char *name, const VDPRPC_ObjectNotifySink *sink, void
*userData, VDPRPC_ObjectConfigurationFlags configFlags, void **objectHandle);
Parameters
name Name for the created object.
sink Sink to be registered with the new object.
userData Data to be sent to all sink callbacks. Can be NULL.
configFlags Set of configuration options for the new object.
objectHandle Handle for the created object is stored here.
Return Values
Value Description
TRUE The object was successfully created.
FALSE Creation of the object failed failed.
DestroyChannelObject
Frees all resources associated with the given channel object.
Method Signature
Bool (*DestroyChannelObject)(void *objectHandle);
Parameters
objectHandle The handle, returned from CreateChannelObject, for the object to destroy.
VMware, Inc. 41
Return Values
Value Description
TRUE The object was successfully destroyed.
FALSE Destruction of the object failed.
GetObjectState
Queries the current state of the given object.
Method Signature
VDPRPC_ObjectState (*GetObjectState)(void *objectHandle);
Parameters
objectHandle The handle, returned from CreateChannelObject, for the object to query.
Return Values
Value Description
VDP_RPC_OBJ_UNINITIALIZED Object with the given handle could not be found.
VDP_RPC_OBJ_ DISCONNECTED Matching peer object was destroyed.
VDP_RPC_OBJ_ PENDING Object created locally, waiting for other end to create a peer object.
VDP_RPC_OBJ_ CONNECTED Given object is connected to its peer on the other side of the channel.
GetObjectName
Queries the given object for the name it was assigned at creation.
Method Signature
Bool (*GetObjectName)(void *objectHandle, char *buf, uint32 bufSize);
Parameters
objectHandle The handle, returned from CreateChannelObject, for the object to query.
buf The name of the object is stored in this parameter.
bufSize Size of the passed-in buf.
42 VMware, Inc.
Return Values
Value Description
TRUE The name was successfully returned.
FALSE An error occurred and the name was not returned.
v1.CreateContext
Allocates and returns a new channel context to be used for a RPC.
Method Signature
Bool (*CreateContext)(void *objectHandle, void **ppcontextHandle);
Parameters
objectHandle A handle for a valid channel object..
ppcontextHandle A handle for the new channel context is returned here.
Return Values
Value Description
TRUE The new context was successfully created and returned.
FALSE Context creation failed.
DestroyContext
Frees all resources associated with a given context. Call this method only on contexts that have not been sent
using the Invoke call. Only contexts that will not be used should be destroyed by the user.
Method Signature
Bool (*DestroyContext)(void *contextHandle);
Parameters
contextHandle The handle for the context to destroy.
Return Values
Value Description
TRUE The new context was successfully destroyed.
FALSE Destruction of the context failed.
VMware, Inc. 43
Invoke
Initiates a RPC between the given object and it's peer on the other end of the channel.
Method Signature
Bool (*Invoke)(void *objectHandle, void *contextHandle, const VDPRPC_RequestCallback *callback,
void *userData);
Parameters
objectHandle Handle for the object to send the RPC through.
contextHandle A handle for the context containing the data for this RPC. callback
callback User supplied callbacks to be used after the Invoke call.
userData User supplied data that will be passed to the callback methods. Can be NULL.
Return Values
Value Description
TRUE Invoke call succeeded and RPC was sent.
FALSE No RPC was sent due to an error.
IsSideChannelAvailable
Determines whether a side channel of the given type is available for use by any channel object. Currently,
only one object can use an available channel.
Method Signature
Bool (*IsSideChannelAvailable)(VDPRPC_SideChannelType type);
Parameters
type Side channel type. Either virtual side channel (VDP_RPC_SIDE_CHANNEL_TYPE_PCOIP) or TCP side
channel (VDP_RPC_SIDE_CHANNEL_TYPE_TCP)
Return Values
Value Description
TRUE Side channel of the given type is available.
FALSE Side channel of the given type is not available.
44 VMware, Inc.
RequestSideChannel
Requests a particular type of side channel for a given object.
Method Signature
Bool (*RequestSideChannel)(void *objectHandle, VDPRPC_SideChannelType type, const char *token);
Parameters
objectHandle Handle for the object.
type The type of side channel being requested.
token The name of the side channel to use. If NULL, the application token is used.
Return Values
Value Description
TRUE Request succeeded.
FALSE Request failed.
GetObjectOptions
Obtains the following object options after an object is created: (1) encryption and compression options which
both sides agree on; and (2) side channel types which peer does not support.
Method Signature
Bool (*GetObjectOptions)(void *objectHandle, uint32 *options);
Parameters
objectHandle Handle for the object.
options The supported options for the object are returned here.
Return Values
Value Description
TRUE Request succeeded.
FALSE Request failed.
v3.CreateContext
Same as v1.CreateContext but supports compression and encryption options.
VMware, Inc. 45
Method Signature
Bool (*CreateContext)(void *objectHandle, uint32 options, void **ppcontextHandle);
Parameters
objectHandle Handle for a valid channel object.
options Specifies whether compression and encryption will apply for this context.
ppcontextHandle A handle of a new channel context is returned here.
Return Values
Value Description
TRUE A new context was successfully created and returned.
FALSE Context creation failed.
GetId
Returns the unique ID for the given context. This ID can be used to map callbacks to the Invoke call that they
refer to.
This function is a member of VDPRPC_ChannelContextInterface.
Method Signature
uint32 (*GetId)(void *contextHandle);
Parameters
contextHandle The handle for the context to be queried.
Return Values
Value Description
uint32 The ID for the given context.
GetCommand
Queries the command code that was assigned to the given context. Use this method to determine the remote
method that was being called. Use the SetCommand method to set the command code. If 0 is returned, use
GetNamedCommand to fetch the command code.
Method Signature
uint32 (*GetCommand)(void *contextHandle);
46 VMware, Inc.
Parameters
contextHandle The handle for the context to query.
Return Values
Value Description
uint32 The uint32 command code set for this context. 0 indicates the command was not set as a uint32.
SetCommand
Sets the command code for the given context. The command code represents the remote method that the
context is meant to represent.
Note You can also store the command as a string (using SetNamedCommand . Only one can be used
though. If you call SetNamedCommand after this call, the uint32 command code is overwritten. Do not use 0 as
the command code because the Horizon 7 Session Enhancement system uses 0 to indicate an error.
Method Signature
Bool (*SetCommand)(void *contextHandle, uint32 command);
Parameters
contextHandle The handle for the context to set.
command The command code for the context.
Return Values
Value Description
TRUE Context command code was successfully set.
FALSE Unable to set the command code.
GetNamedCommand
Gets the command code assigned to the given context as a string. If the command was not stored as a string,
this method returns NULL, and you must use the GetCommand method instead to get the command code.
Method Signature
Bool (*GetNamedCommand)(void *contextHandle, char *buffer, int bufferSize);
VMware, Inc. 47
Parameters
buffer Out parameter that the name is to be stored in.
bufferSize Size of the buffer to store the name.
Return Values
Value Description
TRUE Named command successfully returned.
FALSE T he command was not stored as a string.
SetNamedCommand
Sets the command code for the given context with a name. You can either set the command as a uint32
(using SetCommand) or as a string, using this method. Use only one method. If you try to use both, the second
command used will overwrite the previous command.
Method Signature
Bool (*SetNamedCommand)(void *contextHandle, const char *command);
Parameters
command The command string to use.
Return Values
Value Description
TRUE Command string was successfully set.
FALSE Unable to set the command string.
GetParamCount
Returns the number of parameters appended to the given context.
Method Signature
int (*GetParamCount)(void *contextHandle);
48 VMware, Inc.
Parameters
Return Values
Value Description
int Number of parameters stored in the given context.
AppendParam
Adds the given Variant to the context as a parameter for the method. Appends the parameter to the end of
the list.
Method Signature
Bool (*AppendParam)(void *contextHandle, const VDP_RPC_VARIANT *v);
Parameters
contextHandle The handle for the context to add the parameter to.
v Variant to store in the context. A copy of the data is made.
Return Values
Value Description
TRUE Data was successfully stored.
FALSE Failed to append the Variant to the context.
GetParam
Fetches the parameter at the given index. The parameter list index begins at zero.
Method Signature
Bool (*GetParam)(void *contextHandle, int i, VDP_RPC_VARIANT *copy);
Parameters
contextHandle The context to query.
i Index of the parameter to fetch.
copy Variant into which the parameter is to be copied.
VMware, Inc. 49
Return Values
Value Description
TRUE Parameter at the given index was successfully returned.
FALSE Unable to find parameter at the given index.
AppendNamedParam
Append the given Variant as a parameter to the given context and assign it a name. Note that the parameter
is added to the end of the list with all parameters, even those without assigned names.
Method Signature
Bool (*AppendNamedParam)(void *contextHandle, const char *name, const VDP_RPC_VARIANT *v);
Parameters
contextHandle The context to append the parameter to.
name Name to assign to the parameter.
v The data for the new parameter.
Return Values
Value Description
TRUE Parameter successfully added.
FALSE Unable to append the parameter to the given context.
GetNamedParam
Fetch the parameter at the given index and return the name, if any, that was assigned to the parameter. If no
name was given, the name parameter remains untouched.
Method Signature
Bool (*GetNamedParam)(void *contextHandle, int index, char *name, int nameSize, VDP_RPC_VARIANT
*copy);
Parameters
contextHandle The context to fetch the parameter from.
index The index of the parameter to return.
name The buffer to store the assigned name in. Can be NULL if you are not interested in the
name.
nameSize Size of the passed-in buffer.
50 VMware, Inc.
copy Variant into which the parameter data is to be copied.
Return Values
Value Description
TRUE Parameter at the given index returned and name (if any) found.
FALSE Unable to fetch the parameter and name at the given index.
GetReturnCode
Queries the value assigned to the given index as a return code. The return code is meant to indicate the
success or failure of the remote method call, or as an error code.
Method Signature
uint32 (*GetReturnCode)(void *contextHandle);
Parameters
contextHandle The handle of the context to query.
Return Values
Value Description
uint32 Return code set for the given context.
SetReturnCode
Sets the return code for the given context. This should be done in the OnInvoke callback. This value
represents the success or failure of the remote call.
Method Signature
Bool (*SetReturnCode)(void *contextHandle, uint32 code);
Parameters
code Value for the return code.
VMware, Inc. 51
Return Values
Value Description
TRUE Return code of the context set
FALSE Unable to set the return code.
GetReturnValCount
Returns the number of Variants stored in the given context as return values.
Method Signature
int (*GetReturnValCount)(void *contextHandle);
Parameters
Return Values
Value Description
int Number of return values stored in the given context.
AppendReturnVal
Add the given Variant as a return value. The return values can be thought of as out parameters in a
procedure call. The user can return any data desired here. The Variant is added to the end of the return
value list.
Method Signature
Bool (*AppendReturnVal)(void *contextHandle, const VDP_RPC_VARIANT *v);
Parameters
contextHandle The handle for the context to append to.
v Data to append.
Return Values
Value Description
TRUE Return value was successfully added.
FALSE Failed to add the given Variant as a return value.
52 VMware, Inc.
GetReturnVal
Fetches the return value at the given index. Index of the return values begin at zero.
Method Signature
Bool (*GetReturnVal)(void *contextHandle, int i, const VDP_RPC_VARIANT *v);
Parameters
i Index of the return value to fetch.
v Variant into which the return value data is to be copied.
Return Values
Value Description
TRUE Return value successfully fetched.
FALSE Failed to locate return value at the given index.
AppendNamedReturnVal
Similar to AppendReturnVal but also assigns a name to the return value. The return value is added to the end
of the list of all return values, even those without assigned names.
Method Signature
Bool (*AppendNamedReturnVal)(void *contextHandle, const char *name, const VDP_RPC_VARIANT *v);
Parameters
contextHandle Context to add the return value to.
name Name for the given return value.
v Data for the return value.
Return Values
Value Description
TRUE Name and return value successfully added.
FALSE Failed to add return value.
VMware, Inc. 53
GetNamedReturnVal
Fetches the return value at the given index. Also returns the name assigned to the return value. This return
value might be NULL.
Method Signature
Bool (*GetNamedReturnVal)(void *contextHandle, int index, char *name, int nameSize, const
VDP_RPC_VARIANT *v);
Parameters
contextHandle Context to query.
index Index of the return value to fetch.
name Buffer to store the name into. Can be NULL.
nameSize Size of the name buffer.
v Variant to copy the return value data into.
Return Values
Value Description
TRUE Successfully fetched the return value and name at the given index.
FALSE Failed to find the return value or the name.
SetOps
Sets channel context options. The most common use is set RPC call in "post" mode, which does not expect
any response for this channel context.
Method Signature
Bool (*SetOps)(void *contextHandle, VDPRPC_ChannelContextOps op, const VDP_RPC_VARIANT *v);
Parameters
objectHandle Handle for a valid channel object.
options Channel context options.
v Option values in variant.
54 VMware, Inc.
Return Values
Value Description
TRUE Success
FALSE Failure
GetStreamDataHeaderTailSize
Obtains the size of the header and the tail for stream data mode (TCP socket) if neither compression nor
encryption is needed. Because stream data mode is an agent-only feature, data needs to be encapsulated in
RPC format to the client. This API is used to calculate the size of the header and the tail.
This function is a member of VDPRPC_StreamDataInterface.
Method Signature
Bool (*GetStreamDataHeaderTailSize)(int fd, int dataSize, int *headerLen, int *tailLen);
Parameters
fd A valid socket handle returned by SwitchToStreamDataMode.
dataSize The size of the data that the client intends to send.
headerLen The size of the header is returned here.
TailLen The size of the tail is returned here.
Return Values
Value Description
TRUE Successfully obtained the sizes.
FALSE Failure. Must be invalid socket handle.
GetStreamDataHeaderTail
Obtains the header and tail data for stream data mode to send via the TCP socket. This function is mainly
for optimization by eliminating a memcpy.
Method Signature
Bool (*GetStreamDataHeaderTail)(int fd, int *reqId, int reqCmd, VDP_RPC_BLOB *blob, char
*header, int headerBufLen, char *tail, int tailBufLen);
Parameters
fd A valid socket handle return by SwitchToStreamDataMode.
reqId RPC request ID is returned here for the caller to track each request.
reqCmd Request command.
VMware, Inc. 55
blob Blob data which will be sent using the TCP socket.
header Buffer to hold header data.
headerBufSize Header buffer size. Must be greater than or equal to the size returned by
GetStreamDataHeaderTailSize.
tail Buffer to hold header data.
tailBufLen Tail buffer size. Must be greater than or equal to the size returned by
GetStreamDataHeaderTailSize.
Return Values
Value Description
TRUE Successfully obtained the header and the tail.
FALSE Failure.
GetMinimalStreamDataSize
Gets the minimal stream data size before checking the RPC packet length.
Method Signature
int (*GetMinimalStreamDataSize)(int fd);
Parameters
Return Values
Value Description
uint32 The minimal size.
GetStreamDataSize
Gets the RPC packet length. The parameter recvData must have at least the minimal-size amount of data.
Method Signature
int (*GetStreamDataSize)(int fd, const char *recvData);
Parameters
recvData Data that needs to be parsed.
56 VMware, Inc.
Return Values
Value Description
uint32 The size of the whole RPC packet.
v1.GetStreamDataInfo
Parses stream data information from received binary data.
Method Signature
int (*GetStreamDataInfo)(int fd, const char *recvData, int *reqId, int *reqType, int *reqCmd,
VDP_RPC_BLOB *blob);
Parameters
reqId RPC request ID is returned here.
reqType RPC request type is returned here.
reqCmd RPC request command is returned here.
blob Blob data that is sent by client is returned here.
Return Values
Value Description
TRUE Successfully parsed recvData as an RPC packet.
FALSE Failure.
GetStreamData
Obtains the stream data to send via the TCP socket. This API is used when data needs either compression or
encryption. It also works if neither of them is needed, but it will involves one additional memory allocation
and memcpy. Be sure to call FreeStreamDataPayload to avoid memory leak.
Method Signature
int (*GetStreamData)(int fd, uint32 ctxOptions, int *reqId, int reqCmd, VDP_RPC_BLOB *blob,
VDP_RPC_BLOB *payload);
Parameters
ctxOptions Compression and encryption options.
VMware, Inc. 57
reqId RPC request ID is returned here for caller to track each request.
reqCmd Request command.
blob Blob data that needs to be sent.
payload Actual RPC packet data is returned in playload.
Return Values
Value Description
TRUE Payload creation succeeded.
FALSE Payload creation failed.
FreeStreamDataPayload
Frees payload memory for the blob data that is returned by GetStreamData or GetStreamDataInfo
Method Signature
int (*FreeStreamDataPayload)(VDP_RPC_BLOB *payload);
Parameters
payload Blob data that needs to be freed.
Return Values
Value Description
TRUE Payload successfully freed.
FALSE Failed to free payload data.
v2.GetStreamDataInfo
Same as v1.GetStreamDataInfo except for one more parameter, bNeedCleanup, to indicate whether the blob
data needs to be cleaned up. The size of recvData has to be greater than or equal to the size returned by
GetStreamDataSize().
Method Signature
int (*GetStreamDataInfo)(int fd, const char *recvData, int *reqId, int *reqType, int reqCmd,
Bool *bNeedCleanup, VDP_RPC_BLOB *blob);
58 VMware, Inc.
Parameters
reqId RPC request ID is returned here.
reqType RPC request type is returned here.
reqCmd RPC request command is returned here.
bNeedCleanup Boolean value is returned here to indicate if the blob data need to be freed by
FreeStreamDataPayload.
blob Blob data that is sent from the client is returned here.
Return Values
Value Description
TRUE RecvData is parsed as RPC packet successfully.
FALSE Otherwise.
VMware, Inc. 59
60 VMware, Inc.
Overlay Functions 5
The vdpOverlay.h header file defines the set of functions to use in order to support overlay functionality in
an application.
n “VDPOverlayGuest_Interface Functions,” on page 61
n “VDPOverlayClient_Interface Functions,” on page 68
VDPOverlayGuest_Interface Functions
With VDPOverlayGuest_Interface functions, you can work with windows; enable and disable the client-side
overlay; work with the layout mode for the overlay; send a message to the client-side plug-in; and release all
allocated resources.
v1.Init for the Guest-Side Library

Initializes the guest-side overlay library. This must be the first overlay API function called.
This function is a member of VDPOverlayGuest_Interface.
Method Signature
VDPOverlay_Error (*Init)(const VDPOverlayGuest_Sink* sink, void* userData);
Parameters
sink Function pointers called to notify users of overlay events.
userData Parameter that is passed to sink function callbacks.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Initialization succeeded.
VDP_OVERLAY_ERROR_ALREADY_INITIALIZED Init has already been called.
VDP_OVERLAY_ERROR_INVALID_PARAMETER NULL sink parameter, or invalid sink version.
VDP_OVERLAY_ERROR_ALLOCATION_ERROR Internal system error.
VMware, Inc. 61
v1.Exit for the Guest-Side Library

Frees all allocated resources held by the Horizon 7 Session Enhancement Overlay APIs and unregisters all
windows.
Method Signature
VDPOverlay_Error (*Exit)(void);
Parameters
None
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Overlay successfully shut down.
VDP_OVERLAY_ERROR_NOT_INITIALIZED Overlay was never initialized.
v1.RegisterWindow
Registers a window to be overlayed. The position, size, and so on of the window are sent to the client so that
a client-side plug-in can draw an area of the desktop UI that covers the window, giving the illusion that the
drawing is happening on the guest-side.
Method Signature
VDPOverlay_Error (*RegisterWindow)(VDPOverlay_WindowId windowId, VDPOverlay_UserArgs userArgs);
Parameters
windowId The operating system window identifier. A window can only be registered once.
userArgs Data that is to be passed to the client-side plug-in hwen the OnWindowRegistered() event handler is called.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Window was successfully registered.
VDP_OVERLAY_ERROR_NOT_INITIALIZED Overlay not initialized.
VDP_OVERLAY_ERROR_INVALID_PARAMETER Invalid window ID.
VDP_OVERLAY_ERROR_WINDOW_ALREADY_REGISTERED The given window ID has already been registered

with the Overlay system.
62 VMware, Inc.
Chapter 5 Overlay Functions
v1.UnregisterWindow
Unregisters a previously registered window. This method not only disables the client-side overlay, but also
releases any resources allocated to maintain the overlay.
Method Signature
VDPOverlay_Error (*UnregisterWindow)(VDPOverlay_WindowId windowId, VDPOverlay_UserArgs userArgs);
Parameters
windowId The operating system window identifier. The windowId must have been previously registered with
VDPOverlayGuest_RegisterWindow().
userArgs Data that is to be passed to the client-side plug-in when the VDPOverlayClient_WindowUnregistered event
is sent.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Window was successfully unregistered.
VDP_OVERLAY_ERROR_NOT_INITIALIZED Overlay has not been initialized.
VDP_OVERLAY_ERROR_WINDOW_NOT_REGISTERED The given window ID was never registered with the Overlay
system.
v1.IsWindowRegistered
Determines if a window is currently registered with the guest-side Overlay API.
Method Signature
Bool (*IsWindowRegistered)(VDPOverlay_WindowId windowId);
Parameters
windowId The operating system window identifier.
Return Values
Value Description
TRUE Window is currently registered.
FALSE The given window ID is not registered.
v1.EnableOverlay
Enables the client-side overlay. Once the window is registered, and ready, this function must be called to
display the client-side overlay.
VMware, Inc. 63
Method Signature
VDPOverlay_Error (*EnableOverlay)(VDPOverlay_WindowId windowId, VDPOverlay_UserArgs userArgs);
Parameters
windowId The operating system window identifier. It must be previously registered with
userArgs Data that is to be passed to the client-side plug-in when VDPOverlayClient_OverlayEnabled event is
sent.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS The message was sent.
VDP_OVERLAY_ERROR_NOT_INITIALIZED Overlay API was not initialized.
VDP_OVERLAY_ERROR_INVALID_PARAMETER The windowId or userArgs parameter was invalid, or there was

an error with msg.
VDP_OVERLAY_ERROR_HOST_OVERLAY_ERROR There is an error with a low-level library. This error code should
be treated as similar to INVALID_PARAMETER.
v1.DisableOverlay
Disables the client-side overlay. Disabling the overlay is a light-weight way to hide the client-side overlay.
Unlike VDPOverlayGuest_UnregisterWindow(), resources used to maintain the overlay are not released.
Method Signature
VDPOverlay_Error (*DisableOverlay)(VDPOverlay_WindowId windowId, VDPOverlay_UserArgs userArgs);
Parameters
windwId The operating system window identifier. It must be previously registered with
userArgs Data that is to be passed to the client-side plug-in when VDPOverlayClient_OverlayEnabled event is
sent.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The windowId or userArgs parameter was invalid, or there was

an error with msg.
64 VMware, Inc.
v1.IsOverlayEnabled
Queries whether the overlay associated with the given windowId is currently enabled.
Method Signature
Bool (*IsOverlayEnabled)(VDPOverlay_WindowId windowId);
Parameters
windowId The operating system window identifier. It must have been previously registered with
Return Values
Value Description
TRUE The overlay is enabled.
FALSE The overlay is disabled.
v1.SetLayoutMode
Sets the current layout mode for the overlay. The layout mode is used to determine how an image is drawn
(for example, scaled, cropped, and so on), when the size of the image doesn't match the size of the overlay.
Method Signature
VDPOverlay_Error (*SetLayoutMode)(VDPOverlay_WindowId windowId, VDPOverlay_LayoutMode
layoutMode);
VMware, Inc. 65
Parameters
layoutMode Determines how the image is drawn. This can be one of the following VDPOverlay_LayoutMode values:
Enum Values Description
DP_OVERLAY_LAYOUT_CENTER The image will be drawn centered in the

overlay and clipped to the size of the
overlay. No scaling will take place.
VDP_OVERLAY_LAYOUT_SCALE The image will be drawn to fill the entire

VDP_OVERLAY_LAYOUT_SCALE_SHRINK_ONLY overlay. No attempt at maintaining the
aspect ratio of the image is made.
VDP_OVERLAY_LAYOUT_CROP The image will be scaled to fill the entire

VDP_OVERLAY_LAYOUT_CROP_SHRINK_ONLY overlay while maintaining the aspect ratio.
Parts of the image will be clipped if
necessary.
VDP_OVERLAY_LAYOUT_LETTERBOX The image will be scaled such that either the

VDP_OVERLAY_LAYOUT_LETTERBOX_SHRINK_ONLY width or height of image will match the
width/height of the overlay. The other
dimension will be scaled to maintain the
aspect ratio. No part of the image will be
clipped but the image may not fill the entire
overlay.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The windowId or layoutMode parameter was invalid, or there

was an error with msg.
VDP_OVERLAY_ERROR_NOT_LOCAL_OVERLAY The overlayId of a guest-side overlay was passed to a function

that can only be called on a local overlay.
v1.GetLayoutMode
Gets the current layout mode for the overlay. The layout mode is used to determine how an image is drawn
(for example, scaled, cropped, and so on) when the size of the image does not match the size of the overlay.
Method Signature
VDPOverlay_Error (*GetLayoutMode)(VDPOverlay_WindowId windowId, VDPOverlay_LayoutMode
*pLayoutMode);
66 VMware, Inc.
Parameters
pLayoutMode Current layout mode is stored here.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Current layout mode was successfully retrieved.
VDP_OVERLAY_ERROR_INVALID_PARAMETER pLayoutMode is NULL.
VDP_OVERLAY_ERROR_WINDOW_NOT_REGISTERED The given windowId has not been registered with the
Overlay API.
v1.SendMsg for the Guest-Side Library

Sends a message to the client-side plug-in. The client's OnUserMsg event handler is called with the message.
Method Signature
VDPOverlay_Error (*SendMsg)(VDPOverlay_WindowId windowId, void *msg, uint32 msgLen);
Parameters
VDPOverlayGuest_RegisterWindow(). VDP_OVERLAY_WINDOW_ID_NONE can also be passed if the message
is not directed to a particular window.
msg Buffer that contains the message.
msgLen Size of the msg buffer.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS The message was sent to the client.
VDP_OVERLAY_ERROR_NOT_INITIALIZED Overlay API has not been initialized.
VDP_OVERLAY_ERROR_INVALID_PARAMETER Error occurred sending the supplied message.
Overlay API.
v2.GetColorkey
Retrieves the color key currently assigned to the windowId.
The color key is VDP_OVERLAY_HOST_COLORKEY_NONE until the windowId is assigned a color key by the overlay
services.
VMware, Inc. 67
Method Signature
VDPOverlay_Error (*GetColorkey)(VDPOverlay_WindowId windowId, uint32* colorkey);
Parameters
windowId The operating system window identifier, which must have been previously registered with
VDPOverlayGuest_RegisteredWindow(). VDP_OVERLAY_WINDOW_ID_NONE can be passed if the message is
not directed to a particular window.
colorkey A pointer to a uint32 that contains the color key.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Current information retrieved.
VDP_OVERLAY_ERROR_INVALID_PARAMETER The windowId or colorkey parameter was invalid, or there

was an error with msg.
Overlay API.
VDPOverlayClient_Interface Functions
With VDPOverlayClient_Interface functions, you can work with an overlay, send a message to the guest-side
plug-in, and release all allocated resources.
v1.Init for the Client-Side Library

This function initializes the client-side overlay library. This method must be the first method called in the
client-side Overlay API.
This function is a member of VDPOverlayClient_Interface.
Method Signature
VDPOverlay_Error (*Init)(const VDPOverlayClient_Sink* sink, void* userData,
VDPOverlayClient_ContextId* pContextId);
Parameters
sink Function pointers called when events are generated by the Overlay API.
userData Parameter that is passed to sink callbacks. Can be NULL.
pContextId Returns an ID that identifies the instance of the API for this plug-in
instance.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Overlay client API was initialized.
VDP_OVERLAY_ERROR_NOT_INITIALIZED Internal Horizon 7 Session Enhancement initialization error.
68 VMware, Inc.
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The sink or pContextId parameter is NULL or sink reported an

invalid version.
v1.Exit for the Client-Side Library

Performs cleanup operations and releases all allocated resources.
Method Signature
VDPOverlay_Error (*Exit)(VDPOverlayClient_ContextId contextId);
Parameters
contextId The ID returned from VDPOverlayClient_Init().
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Overlay API was properly shut down.
VDP_OVERLAY_ERROR_INVALID_PARAMETER contextId was invalid.
v1.Update
Updates the overlay with a new image. The updated image is displayed when the next frame is drawn.
Method Signature
VDPOverlay_Error (*Update)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId windowId,
void* pImage, int32 width, int32 height, int32 pitch, Bool copyImage);
Parameters
windowId Window ID that was received from a previous OnWindowRegistered() event.
pImage A pointer to the RGBX pixels to copy to the overlay.
width Width, in pixels, of the image pointed to by pImage. If the width of the image does not match the width of
the overlay, the given image is drawn according the layout mode of the overlay.
height Height, in pixels, of the image pointed to by pImage. If the height of the image does not match the height of
overlay, the given image is drawn according the layout mode of the overlay.
pitch Number of bytes that a single row of the image occupies. In the normal case, for BGRX images, this value is
width multiplied by 4.
copyImage If TRUE, a copy of the image data is made. If FALSE, no copy is made and the image data must remain valid
until another call to VDPOverlayClient_Update() is made.
VMware, Inc. 69
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Image was updated.
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId, windowID, or pImage parameter was invalid.
v1.GetInfo
Retrieves the current information about the overlay.
Method Signature
VDPOverlay_Error (*GetInfo)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId windowId,
VDPOverlayClient_OverlayInfo* pOverlayInfo);
Parameters
windowId Window ID that was cached from a previous OnWindowRegistered() event.
pOverlayInfo A pointer to a VDPOverlayClient_OverlayInfo structure which will be filled in with information

about the overlay.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or windowID parameter was invalid, or

pOverlayInfo was NULL.
v1.SendMsg for the Client-Side Library

Sends a message to the guest-side plug-in. The guest's OnUserMsg() event handler is called with the message.
Method Signature
VDPOverlay_Error (*SendMsg)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId windowId,
void* msg, uint32 msgLen);
Parameters
windowId The operating system window identifier that was cached from a previous OnWindowRegistered() event.
You may also pass VDP_OVERLAY_WINDOW_ID_NONE if the message is not directed to a particular window.
70 VMware, Inc.
msg A pointer to a buffer that contains the message.
msgLen Size of the msg buffer in bytes. The maximum message length is VDP_OVERLAY_USER_MSG_MAX_LEN bytes.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or windowID parameter was invalid, or there was

an error with msg.
v2.InitLocal
Initializes the client-side overlay library for use with just local overlays.
The overhead of creating an RPC connection to track guest side windows is not performed. You do not need
to call this function if you have already called v1.Init().
Method Signature
VDPOverlay_Error (*InitLocal)(const VDPOverlayClient_Sink* sink, void* userData,
VDPOverlayClient_ContextId* pContextId);
Parameters
sink Contains the function pointers that are called when events are generated by the Overlay library.
userData The parameter that is passed to event handler whenever an event is delivered.
pContextId Returns an ID that is used to identify the instance of the API. This ID must be passed to all other API
functions. This ID is also passed when calling the sink handlers.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The sink or userData parameter was invalid, or pContextId is

NULL.
VDP_OVERLAY_ERROR_ALLOCATION_ERROR The system fails to allocate the required memory or system

resource to handle the call.
v2.CreateOverlay
Creates a local overlay.
The overlay is not tied to a window on the guest (such an overlay is referred to as a "guest created overlay").
Locally created overlays give the client complete control over the overlay but also require the client to do
more of the work.
VMware, Inc. 71
Method Signature
VDPOverlay_Error (*CreateOverlay)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId*
pOverlayId);
Parameters
pOverlayId Returns a VDPOverlay_OverlayId that can be used to set properties on the overlay. This ID may also be
passed to functions that take a VDPOverlay_WindowId, for example, Update(), GetInfo(), and so on.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId parameter was invalid, or there pOverlayId is

NULL.
VDP_OVERLAY_ERROR_ALLOCATION_ERROR The system fails to allocate the required memory or system

resource to handle the call.
VDP_OVERLAY_ERROR_NO_MORE_OVERLAYS This error results from a failed attempt to register a window and
may be received in the
VDPOverlayGuest_Sink.v1.OnOverlayCreateError() callback.
This error may be due to a client-side error. It can also occurs if the
call tries to register a window that is already registered with a
different plug-in.
v2.DestroyOverlay
Destroys a local overlay.
All of the resources associated with the overlay are released. This function cannot be called on guest-created
overlays.
Method Signature
VDPOverlay_Error (*DestroyOverlay)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId
overlayId);
Parameters
overlayId An overlay ID that was returned from a previous call to CreateOverlay().
72 VMware, Inc.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or overlayId parameter was invalid.

v2.SetPosition
Sets the position of a local overlay.
This function cannot be called on guest-created overlays.
Method Signature
VDPOverlay_Error (*SetPosition)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId
overlayId, int32 x, int32 y);
Parameters
x,y The position of the overlay. The position is specified as the upper-left corner of the overlay in guest UI
coordinates.
Return Values
Value Description

v2.SetSize
Sets the size of a local overlay.
Method Signature
VDPOverlay_Error (*SetSize)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId
overlayId, int32 width, int32 height);
VMware, Inc. 73
Parameters
Paramater Description
width, height The size of the overlay in pixels. If the size of the image specified in Update() does not match the size
of the overlay, the image is drawn as specified by the layout mode.
Return Values
Value Description

v2.SetClipRegion
Sets the clipping region on the overlay.
Method Signature
VDPOverlay_Error (*SetClipRegion)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId
overlayId, VMRect* pClipRects, int32 nClipRects);
Parameters
pClipRects An array of VMRect's that describe the visible area of the overlay. The clipping information is relative to
the screen. For example, 0,0 is the top-left corner of the screen. This means that the clipping information
describes a specific area of the screen that does not change when the overlay is moved. A copy of the
VMRect array is made so that the caller does not have to maintain the memory.
nClipRects The number of VMRect's in the pClipRects array. Passing the value of 0 for nClipRects removes the clip
region.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or overlayId parameter was invalid, or

pClipRects is NULL.
74 VMware, Inc.
Value Description

v2.SetLayer
Sets the layer on a local overlay.
Method Signature
VDPOverlay_Error (*SetLayer)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId
overlayId, uint32 layer);
Parameters
layer The layer of the overlay. Overlays with a higher layer value will be on top of overlays with a lower layer
value. If two overlays have the same layer value the overlay created last will be on top.
Return Values
Value Description

v2.SetColorkey
Sets the color key on a local overlay.
Method Signature
VDPOverlay_Error (*SetColorkey)(VDPOverlayClient_ContextId contextId, VDPOverlay_OverlayId
overlayId, uint32 colorkey);
VMware, Inc. 75
Parameters
colorkey An RGB value that will limit the area of the guest UI where the overlay is drawn. When a color key is set on
an overlay only the pixels on the guest's UI that match the color key value will be updated. It is the caller's
responsibility to draw the color key to an area on the guest's desktop that corresponds to the position of the
overlay as set by SetPosition(). Passing VDP_OVERLAY_COLORKEY_NONE will remove the color key from
the overlay.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId, overlayId or colorkey parameter was invalid.

v2.EnableOverlay
Enables an overlay that has been previously disabled.
An overlay can be disabled if either the guest or client calls DisableOverlay() for the given window ID.
Method Signature
VDPOverlay_Error (*EnableOverlay)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId
windowId);
Parameters
windowId A window ID that was cached from a previous OnWindowRegistered() event.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or windowId parameter was invalid.
76 VMware, Inc.
v2.DisableOverlay
Disables an overlay.
Disabling an overlay is a light-weight way to hide an overlay. Unlike DestroyOverlay(), resources used to
maintain the overlay are not released.
Method Signature
VDPOverlay_Error (*DisableOverlay)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId
windowId);
Parameters
contextId the ID returned from VDPOverlayClient_Init().
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or windowID parameter was invalid.
v2.SetLayoutMode
Sets the current layout mode for the overlay.
The layout mode is used to determine how an image is drawn, for example, scaled, cropped, and so on,
when the size of the image doesn't match the size of the overlay.
Method Signature
VDPOverlay_Error (*SetLayoutMode)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId
windowId, VDPOverlay_LayoutMode layoutMode);
VMware, Inc. 77
Parameters
layoutMode Determines how the image is drawn. This can be one of the following VDPOverlay_LayoutMode values:
Enum Values Description
DP_OVERLAY_LAYOUT_CENTER The image will be drawn centered in the

overlay and clipped to the size of the
overlay. No scaling will take place.
VDP_OVERLAY_LAYOUT_SCALE The image will be drawn to fill the entire

VDP_OVERLAY_LAYOUT_SCALE_SHRINK_ONLY overlay. No attempt at maintaining the
aspect ratio of the image is made.
VDP_OVERLAY_LAYOUT_CROP The image will be scaled to fill the entire

VDP_OVERLAY_LAYOUT_CROP_SHRINK_ONLY overlay while maintaining the aspect ratio.
Parts of the image will be clipped if
necessary.
VDP_OVERLAY_LAYOUT_LETTERBOX The image will be scaled such that either the

VDP_OVERLAY_LAYOUT_LETTERBOX_SHRINK_ONLY width or height of image will match the
width/height of the overlay. The other
dimension will be scaled to maintain the
aspect ratio. No part of the image will be
clipped but the image may not fill the entire
overlay.
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or windowID parameter was invalid.

v2.Update
Updates the overlay with a new image.
The updated image is displayed when the next frame is drawn.
Method Signature
VDPOverlay_Error (*Update)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId windowId,
void* pImage, int32 width, int32 height, int32 pitch, VDPOverlay_ImageFormat format, uint32
flags);
78 VMware, Inc.
Parameters
windowId Window ID that was received from a previous OnWindowRegistered() event.
pImage A pointer to the RGBX pixels to copy to the overlay.
width Width, in pixels, of the image pointed to by pImage. If the width of the image does not match the width of
the overlay, the given image is drawn according the layout mode of the overlay.
height Height, in pixels, of the image pointed to by pImage. If the height of the image does not match the height of
overlay, the given image is drawn according the layout mode of the overlay.
pitch Number of bytes that a single row of the image occupies. In the normal case, for BGRX images, this value is
width multiplied by 4.
format The pixel format of the image. This is one of the values in VDPOverlay_ImageFormat.
flags n VDP_OVERLAY_UPDATE_FLAG_NONE - Place holder denoting that no flags are being passed.
n VDP_OVERLAY_UPDATE_FLAG_COPY_IMAGE - If set a copy of the image data is made. If FALSE no copy is
made and the image data must remain valid until another call to Update() is made.
n VDP_OVERLAY_UPDATE_FLAG_SHARED_SURFACE - Allows a DirectX surface handle to be passed in place
of a pointer to the image. Shared surfaces are not supported on all video cards or with all image
formats, so the application must be prepared to fall back to not using this flag and passing a pointer to
the image in system memory.
Return Values
Value Description
VDP_OVERLAY_ERROR_SUCCESS Image was updated.
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId, windowID, or pImage parameter was invalid.
v2.GetInfo
Retrieves current information about the overlay
Method Signature
VDPOverlay_Error (*GetInfo)(VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId windowId,
VDPOverlayClient_OverlayInfo* pOverlayInfo);
Parameters
windowId Window ID that was cached from a previous OnWindowRegistered() event.
pOverlayInfo A pointer to a VDPOverlayClient_OverlayInfo structure which will be filled in with information

about the overlay.
VMware, Inc. 79
Return Values
Value Description
VDP_OVERLAY_ERROR_INVALID_PARAMETER The contextId or windowID parameter was invalid, or

pOverlayInfo was NULL.
80 VMware, Inc.
Channel Sinks 6
In order to interact and receive notifications of changes, you must register sinks with the Horizon 7 Session
Enhancement APIs. Channel sinks are common sinks.
These functions are members of VDPService_ChannelNotifySink.
n “OnConnectionStateChanged,” on page 81
n “OnChannelStateChanged,” on page 81
n “OnPeerObjectCreated,” on page 82
OnConnectionStateChanged
This method is invoked when a change in the underlying Horizon 7 session has changed its state.
This function is a member of VDPService_ChannelNotifySink.
Method Signature
void (*OnConnectionStateChanged)(void *userData, VDPService_ConnectionState currentState,
VDPService_ConnectionState transientState, void *reserved);
Parameters
userData Parameter passed in to the RegisterChannelNotifySink method. May be NULL.
currentState The current state of the connection.
transientState The state change that caused the callback. This can be different from currentState if other state
changes have already taken place and are waiting to be processed.
reserved Unused parameter.
Return Values
None
OnChannelStateChanged
This method is invoked when there is a change in the channel connection that this plug-in instance uses.
VMware, Inc. 81
Method Signature
void (*OnChannelStateChanged)(void *userData, VDPService_ChannelState currentState,
VDPService_ChannelState transientState, void *reserved);
Parameters
currentState The current state of the connection.
transientState The state change that caused the callback. This can be different from currentState if other state
changes have already taken place and are waiting to be processed.
Return Values
None
OnPeerObjectCreated
This method is invoked when an object was created on the other side of the channel connection, and no
object with the same name exists locally.
Method Signature
void (*OnPeerObjectCreated)(void *userData, const char *objName, void *reserved);
Parameters
objName The name of the object created by the peer.
Return Values
None
82 VMware, Inc.
RPC Sinks 7
You must register RPC sinks in order to interact with and receive notifications of changes to RPC-specific
Horizon 7 Session Enhancement APIs.
n “OnInvoke,” on page 83
n “OnObjectStateChanged,” on page 83
n “OnDone,” on page 84
n “OnAbort,” on page 84
OnInvoke
This method is invoked when the peer on the other end of the channel calls Invoke. The contextHandle
parameter is used to retrieve the data given by the peer, using VDPService_ChannelContextInterface. This
same context should be altered to hold the return values, and the context will be returned to the caller when
this method returns.
This function is a member of VDPRPC_ObjectNotifySink.
Method Signature
void (*OnInvoke)(void *userData, void *contextHandle, void *reserved);
Parameters
userData The userData parameter passed in to the CreateChannelObject method. May be NULL.
contextHandle Handle for the context that will contain the data for the call, and to hold the return values.
Return Values
None
OnObjectStateChanged
Called when the state of the object this sink was registered with has changed.
This function is a member of VDPRPC_ObjectNotifySink.
VMware, Inc. 83
Method Signature
void (*OnObjectStateChanged)(void *userData, void *reserved);
Parameters
userData The userData parameter passed in to the CreateChannelObject method. May be NULL.
Return Values
None
OnDone
This method is invoked when the Invoke call that this sink is registered with returns from the peer. The
contextId parameter maps to the ID of the context that is passed to the Invoke call. This ID does not match
the ID of the context that contextHandle points to. The contextHandle parameter holds all of the return
codes and values given by the peer.
This function is a member of VDPRPC_RequestCallback.
Method Signature
void (*OnDone)(void *userData, uint32 contextId, void *contextHandle);
Parameters
userData The userData parameter passed to the Invoke method.
contextId ID of the context that was passed to the Invoke method.
contextHandle Handle for the context that holds all of the return data from the peer.
Return Values
None
OnAbort
This method is called when the Invoke call that this sink is registered with fails due to a Horizon 7 Session
Enhancement error.
This function is a member of VDPRPC_RequestCallback.
Method Signature
void (*OnAbort)(void *userData, uint32 contextId, Bool userCancelled, uint32 reason);
84 VMware, Inc.
Chapter 7 RPC Sinks
Parameters
userData The userData parameter passed to the Invoke method.
contextId ID of the context that was passed to the Invoke method.
userCancelled FALSE.
reason A VDP_RPC_E_* error code.
Return Values
None
VMware, Inc. 85
86 VMware, Inc.
Overlay Sinks 8
You must register overlay sinks in order to interact with and receive notifications of changes to overlay-
specific Horizon 7 Session Enhancement APIs.
n “OnOverlayReady,” on page 87
n “OnOverlayRejected,” on page 88
n “OnOverlayCreateError,” on page 88
n “OnUserMsg (Guest Sink),” on page 89
n “OnWindowRegistered,” on page 89
n “OnWindowUnregistered,” on page 90
n “OnOverlayEnabled,” on page 90
n “OnOverlayDisabled,” on page 91
n “OnWindowPositionChanged,” on page 91
n “OnWindowSizeChanged,” on page 92
n “OnWindowObscured,” on page 92
n “OnWindowVisible,” on page 93
n “OnLayoutModeChanged,” on page 93
n “OnUserMsg (Client Sink),” on page 93
OnOverlayReady
This event handler is called when the client-side overlay is ready to be displayed. It does not mean that the
overlay is enabled or even that the client-side has loaded an image into the overlay. It means only that the
overlay was properly created and is ready to display an image.
This function is a member of VDPOverlayGuest_Sink.
Method Signature
void (*OnOverlayReady)(void *userData, VDPOverlay_WindowId windowId, uint32 response);
VMware, Inc. 87
Parameters
userData The userData parameter that was passed to the Init call.
windowId The windowId this callback corresponds to.
response Client-side plug-in response.
Return Values
None
OnOverlayRejected
This event handler is called when the client-side overlay is not created because the client-side plug-in choose
to reject it. Note that the window that is associated with the overlay is automatically unregistered.
Method Signature
void (*OnOverlayRejected)(void *userData, VDPOverlay_WindowId windowId, uint32 reason);
Parameters
userData The userData parameter passed in to the Init call.
reason The client-side plug-in reason given for rejecting the overlay.
Return Values
None
OnOverlayCreateError
This event handler is called when the client-side overlay is not created due to an error. Note that the
window that is associated with the overlay is automatically unregistered.
Method Signature
void (*OnOverlayCreateError)(void *userData, VDPOverlay_WindowId windowId, VDPOverlay_Error
error);
Parameters
error The error that was encountered.
88 VMware, Inc.
Chapter 8 Overlay Sinks
Return Values
None
OnUserMsg (Guest Sink)

This event handler is called in response to a call to SendMsg from the client.
Method Signature
void (*OnUserMsg)(void *userData, VDPOverlay_WindowId windowId, void *msg, uint32 msgLen);
Parameters
windowId The windowId this message is sent to, or VDP_OVERLAY_WINDOW_ID_NONE if the message was not
sent to a particular window.
msg The message data. Not valid after the call returns.
msgLen Length of msg, in bytes.
Return Values
None
OnWindowRegistered
This event handler is called when the guest-side application registers a window using the RegisterWindow
method. You can reject the request by setting reject to TRUE. Use the response parameter to return a reason
to the guest. You can also use response to send a message to the guest in the non-reject case.
Note Cache the windowId parameter because it is required to identify the overlay to the Overlay API.
This function is a member of VDPOverlayClient_Sink.
Method Signature
void (*OnWindowRegistered)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId windowId, VDPOverlay_UserArgs userArgs, Bool *reject, uint32 *response);
Parameters
contextId The context ID returned from the Init call.
windowId The windowId representing the new overlay.
userArgs Value sent by the guest-side in the RegisterWindow call.
reject Set to TRUE to deny the request to create an overlay.
response Response sent back to the guest.
VMware, Inc. 89
Return Values
None
OnWindowUnregistered
This event handler is called when the guest-side unregisters a window using the UnregisterWindow method.
The window ID is no longer valid, and the overlay associated with the window ID is destroyed.
Method Signature
void (*OnWindowUnregistered)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId windowId, VDPOverlay_UserArgs userArgs);
Parameters
userData The userData parameter passed to the Init method.
windowId Window ID for the window that was unregistered.
userArgs Value sent by the guest-side application in the UnregisterWindow call.
Return Values
None
OnOverlayEnabled
This event handler is called when the guest-side enables the overlay using the EnableOverlay method. This
event handler causes the current image in the overlay to be displayed.
Method Signature
void (*OnOverlayEnabled)(void *userData, VDPOverlayClient_ContextId contextId,
Parameters
windowId Window ID that corresponds to the enabled overlay.
userArgs Value passed by the guest-side to the EnableOverlay call.
Return Values
None
90 VMware, Inc.
OnOverlayDisabled
This event handler is called when the guest-side disables the overlay using the DisableOverlay method,
causing the current image in the overlay to be hidden. The overlay image data is maintained and will be re-
displayed when the overlay is re-enabled.
Method Signature
void (*OnOverlayDisabled)(void *userData, VDPOverlayClient_ContextId contextId,
Parameters
windowId Window ID that corresponds to the disabled overlay.
userArgs Value passed by the guest-side to the DisableOverlay call.
Return Values
None
OnWindowPositionChanged
This event handler is called when the guest-side window that the overlay is tracking changes position. The
overlay is drawn at the new location. This event handler is for information only. No action is required by the
plug-in.
Method Signature
void (*OnWindowPositionChanged)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId int32 x, int32 y);
Parameters
windowId Window ID that corresponds to the repositioned overlay.
x New X position with the display.
y New Y position with the display.
Return Values
None
VMware, Inc. 91
OnWindowSizeChanged
This event handler is called when the guest-side window that the overlay is tracking changes size. The old
overlay image is redrawn according to the layout mode of the overlay. This event handler is for information
only. No action is required by the plug-in.
Method Signature
void (*OnWindowSizeChanged)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId windowId, int32 width, int32 height);
Parameters
windowId Window ID that corresponds to the resized overlay.
width New width of the window.
height New height of the window.
Return Values
None
OnWindowObscured
This event handler is called when the guest-side window that the overlay is tracking is completely obscured.
The client-side can use this event as a hint to scale back drawing to the overlay.
Method Signature
void (*OnWindowRegistered)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId windowId);
Parameters
windowId Window ID that corresponds to the obscured overlay.
Return Values
None
92 VMware, Inc.
OnWindowVisible
This event handler is called when the guest-side window that the overlay is tracking was obscured but now
is at least partially visible.
Method Signature
void (*OnWindowVisible)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId windowId);
Parameters
windowId Window ID that corresponds to the no longer obscured overlay.
Return Values
None
OnLayoutModeChanged
This event handler is called when the layout mode for the overlay is changed. This event handler is for
information only. No action is required by the plug-in.
Method Signature
void (*OnLayoutModeChanged)(void *userData, VDPOverlayClient_ContextId contextId,
VDPOverlay_WindowId windowId, VDPOverlay_LayoutMode layoutMode);
Parameters
windowId Window ID that corresponds to the referenced overlay.
layoutMode The new layout mode.
Return Values
None
OnUserMsg (Client Sink)

This event handler is when the guest-side application has called the SendMsg method.
VMware, Inc. 93
Method Signature
void (*OnUserMsg)(void *userData, VDPOverlayClient_ContextId contextId, VDPOverlay_WindowId
windowId, void *msg, uint32 msgLen);
Parameters
windowId The windowId this message is sent to, or VDP_OVERLAY_WINDOW_ID_NONE if the message was not
sent to a particular window.
msg The message data. Not valid after the call returns.
msgLen Length of msg, in bytes.
Return Values
None
94 VMware, Inc.
Index
A GetNamedParam method 50
AppendNamedParam method 50 GetNamedReturnVal method 54
AppendNamedReturnVal method 53 GetObjectName method 42
AppendParam method 49 GetObjectOptions method 45
AppendReturnVal method 52 GetObjectState method 42
GetParam method 49
B GetParamCount method 48
Broadcast method 30 GetReturnCode method 51
GetReturnVal method 53
C GetReturnValCount method 52
channel GetSessionType method 29
connect 11
GetStreamData method 57
disconnect 11
GetStreamDataHeaderTail method 55
channel sinks 81
GetStreamDataHeaderTailSize method 55
ChannelContext 10
GetStreamDataInfo method 57, 58
Connect method 27
GetStreamDataSize method 56
connection 10
glossary 7
CreateChannelObject method 41
CreateContext method 43, 45 H
Horizon 7 Session Enhancement, key
D concepts 10
data types Horizon 7 Session Enhancement SDK,
VDP Overlay 19 overview 9
VDP RPC 19
VDP Service 19 I
data typess 19 initialization
DestroyChannelObject method 41 application 11
DestroyContext method 43 plug-in 11
Disconnect method 27 thread 11
installation
download, SDK 17
remote desktop 17
Windows client 17
E
error codes intended audience 7
OnAbort reason 20 Invoke method 44
VDP overlay 20 IsSideChannelAvailable method 44
F O
FreeStreamDataPayload method 58 OnAbort method 84
OnChannelStateChanged method 81
G OnConnectionStateChanged method 81
GetChannelState method 28 OnDone method 84
GetCommand method 46 OnInvoke method 83
GetConnectionState method 28 OnLayoutModeChanged method 93
GetId method 46 OnObjectStateChanged method 83
GetMinimalStreamDataSize method 56 OnOverlayCreateError method 88
GetNamedCommand method 47 OnOverlayDisabled method 91
VMware, Inc. 95
OnOverlayEnabled method 90 UnregisterObserver method 30

OnOverlayReady method 87
OnOverlayRejected method 88 V
OnPeerObjectCreated method 82 v1.DisableOverlay method 64
OnUserMsg method 89, 93 v1.EnableOverlay method 63
OnWindowObscured method 92 v1.Exit method 62, 69
OnWindowPositionChanged method 91 v1.GetInfo method 70
OnWindowRegistered method 89 v1.GetLayoutMode method 66
OnWindowSizeChanged method 92 v1.Init method 61, 68
OnWindowUnregistered method 90 v1.IsOverlayEnabled method 65
OnWindowVisible method 93 v1.IsWindowRegistered method 63
operating system support 9 v1.Poll method 25
overlay 10 v1.RegisterWindow method 62
Overlay API v1.SendMsg method 67, 70
client setup 16 v1.SetLayoutMode method 65
guest setup 16 v1.UnregisterWindow method 63
overlay sinks 87 v1.Update method 69
v2.CreateOverlay method 71
R v2.DestroyOverlay method 72
RegisterChannelNotifySink method 26 v2.DisableOverlay method 77
RegisterObserver method 30 v2.EnableOverlay for the Guest-side Library
remote procedure call 10 method 76
RequestSideChannel method 45 v2.GetColorkey method 67
RPC API v2.GetInfo method 79
application shutdown 15 v2.InitLocal method 71
channel object 15 v2.SetClipRegion method 74
Invoke 15 v2.SetLayer method 75
OnInvoke 15 v2.SetLayoutMode method 77
plug-in shutdown 15 v2.SetPosition method 73
variant 15 v2.Update method 78
RPC sinks 83 v3.Poll method 25
variant 10
S VariantClear method 35
sample code 17 VariantCopy method 35
SetColorkey method 75 VariantFromBlob method 40
SetCommand method 47 VariantFromChar method 36
SetNamedCommand method 48 VariantFromDouble method 39
SetOps method 54 VariantFromFloat method 39
SetReturnCode method 51 VariantFromInt32 method 37
SetSize method 73 VariantFromInt64 method 38
side channel 10 VariantFromShort method 36
sink 10 VariantFromStr method 40
sink registration 11 VariantFromUInt32 method 37
SwitchToStreamDataMode method 29 VariantFromUInt64 method 38
VariantFromUShort method 36
T
VariantInit method 34
thread initialization 11
vdpOverlay.h file 61
ThreadInitialize method 24
VDPOverlayClient_Interface functions 68
ThreadUninitualize method 24
VDPOverlayGuest_Interface functions 61
vdprpc_interfaces.h file 33
U
vdpServices_interfaces.h file 23
UnregisterChannelNotifySink method 26
96 VMware, Inc.
Index
VMware Horizon 7 Session Enhancement API 9
VMware, Inc. 97
98 VMware, Inc.

VMware Vdpservice SDK 3.2.0

Uploaded by

Copyright:

VMware Vdpservice SDK 3.2.0

Uploaded by

Document Information

Original Title

Copyright

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

VMware Vdpservice SDK 3.2.0

Uploaded by

Copyright:

VMware Horizon 7 Session

Enhancement SDK Programming Guide

VMware Horizon 7 Session Enhancement SDK Programming Guide 7

1 Overview of the VMware Horizon 7 Session Enhancement SDK 9

2 Data Types and Error Codes 19

3 Channel Interaction Functions 23

VMware Technical Publications Glossary

This chapter includes the following topics:

n “Introduction to the VMware Horizon 7 Session Enhancement API,” on page 9

n “About VMware Horizon 7 Session Enhancement Key Concepts,” on page 10

n “VMware Horizon 7 Session Enhancement Program Flow,” on page 11

n “Query Interface,” on page 13

n “RPC API,” on page 15

n “Overlay API,” on page 16

n “Sample Code,” on page 17

Introduction to the VMware Horizon 7 Session Enhancement API

This is the code that is installed on a client.

The Horizon 7 Session Enhancement API consists of two distinct APIs:

n Remote Procedure Call (RPC) API

1 Plug-in components must not call the CRYPTO_set_locking_callback(), CRYPTO_set_id_callback(), and

Supported Operating Systems

About VMware Horizon 7 Session Enhancement Key Concepts

Remote Procedure Call

VMware Horizon 7 Session Enhancement Program Flow

In addition to VDPService_ChannelNotifySink, the following sinks exist:

This is for individual channel objects.

This is for callbacks for each RPC call.

This is for important overlay notifications for the guest.

This is for important overlay notifications for the client.

Bool (*QueryInterface) (const GUID *iid, void *iface);

Table 1‑1. Horizon 7 Session Enhancement GUIDs

GUID_VDPRPC_VariantInterface_V1 VDPRPC_VariantInterface v1 vdprpc_interface.h

GUID_VDPRPC_ChannelObjectInterface_V3 VDPRPC_ChannelObjectInterface v3 vdprpc_interfaces.h

GUID_VDPRPC_ChannelContextInterface_V2 VDPRPC_ChannelContextInterfac v2 vdprpc_interfaces.h

GUID_VDPOverlay_GuestInterface_V2 VDPOverlay_GuestInterface v2 vdpOverlay.h

GUID_VDPOverlay_ClientInterface_V2 VDPOverlay_ClientInterface v2 vdpOverlay.h

GUID_VDPService_ChannelInterface_V2 VDPService_ChannelInterface v2 vdpService_interfaces.

GUID_VDPRPC_StreamDataInterface_V2 VDPRPC_StreamDataInterface v2 vdprpc_interfaces.h

GUID_VDPService_ObserverInterface_V1 VDPService_ObserverInterface v1 vdpService_interfaces.

The following sample code shows how to request an interface.

Table 1‑2. Horizon 7 Session Enhancement Server Functions

VDPService_ServerExit The Application calls this function when it closes down.

The following sample code shows how an Application initializes.

/* program startup (_tWinMain for example) */

Table 1‑3. Horizon 7 Session Enhancement Exported Plug-In Functions

VDPService_PluginInitWithP Similar to the VDPService_PluginInit function, but with an additional parameter

This chapter includes the following topics:

n “Data Types,” on page 19

n “Error Codes,” on page 20

VDP Service Data Types

VDPService_ChannelState This enum indicates the current state of a particular channel.

VDP RPC Data Types

Table 2‑2. VDP RPC Data Types

VDPRPC_ObjectState Represents the state of an object. Only objects in the VDP_RPC_OBJ_CONNECTED

VDPRPC_ObjectConfigurationFlag These flags configure new objects.

Table 2‑2. VDP RPC Data Types (Continued)

VDPRPC_SideChannelType Virtual side channel or TCP side channel.

VDP Overlay Data Types

Table 2‑3. VDP Overlay Guest Data Types

VDPOverlay_WindowId An uint32 representation of the native OS window.

Table 2‑4. VDP Overlay Client Data Types

VDPOverlayClient_ContextId Returned from VDPOverlayClient_Init. This ID is used in every call to the

VDPOverlayClient_OverlayInfo This structure is used in the call to VDPOverlayClient::GetInfo().

Bool (QueryInterface) (const GUID iid, void *iface);