Programming Reference
For function summaries, see:
AppendVdHeader (Deprecated)
Note
This function is deprecated. QueueVirtualWrite must be used in all
new virtual drivers.
Places an ICA virtual channel prefix on the output buffer prior to assembling and sending the buffer.
Calling Convention
INT WFCAPI AppendVdHeader (
PWD pWd,
USHORT Channel,
USHORT ByteCount);
Parameters
pWD
Pointer to a WinStation driver control structure.
Channel
Virtual channel number.
ByteCount
Actual size in bytes of the virtual channel packet data to be sent. Do not include additional bytes reservered for the buffer overhead.
Return Values
If the function succeeds, the return value is CLIENT_STATUS_SUCCESS.
If the function fails, the return value is the error code associated with the failure; use GetLastError to get the extended error information.
Remarks
Call this function to prefix the virtual channel packet with the appropriate header information. Normally the virtual driver sees only the private packet data. However, when a virtual driver sends a virtual channel packet to a server application, it must use this function to prefix the data with the ICA header.
Use OutBufReserve to reserve a buffer prior to making this call. The virtual driver must use this function immediately after a successful OutBufReserve and before any other data is placed in the packet. This action uses the additional four bytes requested in OutBufReserve, so do not include this overhead in ByteCount.
If an ICA header or virtual channel data is appended to the buffer, the buffer must be sent to the server before the control leaves the virtual driver.
A pointer to this function is obtained from the VDWRITEHOOK structure after hook registration in DriverOpen. The VDWRITEHOOK structure also provides pWd.
DriverClose
The WinStation driver calls this function prior to unloading the virtual driver, when the ICA connection is being terminated.
Calling Convention
INT Driverclose(
PVD pVD,
PDLLCLOSE pVdClose,
PUINT16 puiSize);
Parameters
pVD
Pointer to a virtual driver control structure.
pVdClose
Pointer to a standard driver close information structure.
puiSize
Pointer to the size of the driver close information structure. This is an input parameter.
Return Values
If the function succeeds the return value is CLIENT_STATUS_SUCCESS.
If the function fails, the return value is the CLIENT_ERROR_* value corresponding to the error condition; see clterr.h (in src/inc/) for a list of error values beginning with CLIENT_ERROR.
Remarks
When DriverClose is called, all private driver data is freed. The virtual driver does not need to deallocate the virtual channel or write hooks.
The pVdClose structure currently contains one element – NotUsed. This structure can be ignored.
DriverGetLastError
This function is not used but is available for linking with the common front end, VDAPI.
Calling Convention
INT DriverGetLastError(
PVD pVD,
PVDLASSTERROR pVdLastError);
Parameters
pVD
Pointer to a virtual driver control structure.
pVdLastError
Pointer to a structure that receives the last error information.
Return Value
The driver returns CLIENT_STATUS_SUCCESS.
Remarks
This function currently has no practical significance for virtual drivers; it is provided for compatibility with the loadable module interface.
DriverInfo
Gets information about the virtual driver, such as the version level of the driver.
Calling Convention
INT DriverInfo(
PVD pVD,
PDLLINFO pVdInfo,
PUINT16 puiSize);
Parameters
pVD
Pointer to a virtual driver control structure.
pVdInfo
Pointer to a standard driver information structure.
puiSize
Pointer to the size of the driver information structure. This is an output parameter.
Return Value
If the function succeeds, it returns CLIENT_STATUS_SUCCESS.
If the function fails because the buffer pointed to by pVdInfo is too small, it returns CLIENT_ERROR_BUFFER_TOO_SMALL. Normally, when a CLIENT_ERROR_* result code is returned, the ICA session is disconnected. CLIENT_ERROR_BUFFER_ TOO_SMALL is an exception and does not result in the ICA session being disconnected. Instead, the WinStation driver attempts to call DriverInfo again with the ByteCount of pVdInfo returned by the failed call.
Remarks
When the client starts, it calls this function to retrieve module-specific information for transmission to the host. This information is returned to the server side of the virtual channel by WFVirtualChannelQuery.
The virtual driver must support this call by returning a structure in the pVdInfo buffer. This structure can be a developer-defined virtual channel-specific structure, but it must begin with a VD_C2H structure, which in turn begins with a MODULE_C2H structure. All fields of the VD_C2H structure must be filled in except for the ChannelMask field. See ica-c2h.h (in src/inc/) for definitions of these structures.
The virtual driver must first check the size of the information buffer given against the size that the virtual driver requires (the VD_C2H structure). The size of the input buffer is given in pVdInfo->ByteCount.
If the buffer is too small to store the information that the driver needs to send, the correct size is filled into the ByteCount field and the driver returns CLIENT_ERROR_BUFFER_TOO_SMALL.
If the buffer is large enough, the driver must fill it with a module-defined structure. At a minimum, this structure must contain a VD_C2H structure. The VD_C2H structure must be the first data in the buffer; additional channel-specific data can follow. All relevant fields of this structure are filled in by this function. The flow control method is specified in the VDFLOW structure (an element of the VD_C2H structure). The Ping example contains a flow control selection.
The WinStation driver calls this function twice at initialization, after calling DriverOpen. The first call contains a NULL information buffer and a buffer size of zero. The driver is expected to fill in pVdInfo->ByteCount with the required buffer size and return CLIENT_ERROR_BUFFER_TOO_SMALL. The WinStation driver allocates a buffer of that size and retries the operation.
The data buffer pointed to by pVdinfo->pBuffer must not be changed by the virtual driver. The WinStation driver stores byte swap information in this buffer.
The parameter puiSize must be initialized to the size of the driver information structure.
DriverOpen
Initializes the virtual driver. The client engine calls this user-written function once when the client is loaded.
Calling Convention
INT DriverOpen(
PVD pVD, PVDOPEN pVdOpen)
PUINT16 puiSize);
Parameters
pVD
Pointer to the virtual driver control structure. This pointer is passed on every call to the virtual driver.
pVdOpen
Pointer to the virtual driver Open structure.
puiSize
Pointer to the size of the virtual driver Open structure. This is an output parameter.
Return Values
If the function succeeds, it returns CLIENT_STATUS_SUCCESS.
If the function fails, it returns the CLIENT_ERROR_* value corresponding to the error condition; see clterr.h (in src/inc/) for a list of error values beginning with CLIENT_ERROR
Remarks
The code fragments in this section are taken from the vdping example.
The DriverOpen function must:
1. Allocate a virtual channel.
Fill in a WDQUERYINFORMATION structure and call VdCallWd. The WinStation driver fills in the OpenVirtualChannel structure (including the channel number) and the data in pVd.
WDQUERYINFORMATION wdqi; OPENVIRTUALCHANNEL OpenVirtualChannel; UINT16 uiSize; wdqi.WdInformationClass = WdOpenVirtualChannel; wdqi.pWdInformation = &OpenVirtualChannel; wdqi.WdInformationLength = sizeof(OPENVIRTUALCHANNEL); OpenVirtualChannel.pVCName = CTXPING_VIRTUAL_CHANNEL_NAME; uiSize = sizeof(WDQUERYINFORMATION); rc = VdCallWd(pVd, WDxQUERYINFORMATION, &wdqi, &uiSize); /* do error processing here */
After the call to VdCallWd, the channel number is assigned in the OpenVirtualChannel structure's Channel element. Save the channel number and set the channel mask to indicate which channel this driver will handle.
For example:
g_usVirtualChannelNum = OpenVirtualChannel.Channel; pVdOpen->ChannelMask = (1L << g_usVirtualChannelNum);
2. Optionally specify a pointer to a private data structure.
If you want the virtual driver to allocate memory for state data, it can have a pointer to this data returned on each call by placing the pointer in the virtual driver structure, as follows:
pVd->pPrivate = pMyStructure;
3. Exchange entry point data with the WinStation driver.
The virtual driver must register a write hook with the client WinStation driver. The write hook is the entry point of the virtual driver to be called when data is received for this virtual channel. The WinStation driver returns pointers to functions that the driver must use to fill in output buffers and sends data to the WinStation driver for transmission to the server.
WDSETINFORMATION wdsi; VDWRITEHOOK vdwh; // Fill in a write hook structure vdwh.Type = g_usVirtualChannelNum; vdwh.pVdData = pVd; vdwh.pProc = (PVDWRITEPROCEDURE) ICADataArrival; // Fill in a set information structure wdsi.WdInformationClass = WdVirtualWriteHook; wdsi.pWdInformation = &vdwh; wdsi.WdInformationLength = sizeof(VDWRITEHOOK); uiSize = sizeof(WDSETINFORMATION); rc = VdCallWd( pVd, WDxSETINFORMATION, &wdsi, &uiSize); /* do error processing here */
During the registration of the write hook, the WinStation driver passes entry points for the deprecated output buffer virtual driver helper functions to the virtual driver in the VDWRITEHOOK structure. The DriverOpen function saves these in global variables so helper functions in the virtual driver can use them. The WinStation driver also passes a pointer to the WinStation driver data area, which the DriverOpen function also saves (because it is the first argument to the virtual driver helper functions).
// Record pointers to functions used // for sending data to the host. pWd = vdwh.pWdData; pOutBufReserve = vdwh.pOutBufReserveProc; pOutBufAppend = vdwh.pOutBufAppenProc; pOutBufWrite = vdwh.pOutBufWriteProc; pAppendVdHeader = vdwh.pAppendVdHeaderProc;
4. Allocate all memory needed by the driver and do any initialization. You can obtain the maximum ICA buffer size from the MaximumWriteSize element in the VDWRITEHOOK structure that is returned.
Note
vdwh.MaximumWriteSize is one byte greater than the actual
maximum that you can use because it also includes the channel number.
g_usMaxDataSize = vdwh.MaxiumWriteSize - 1;
if(NULL == (pMyData = malloc( g_usMaxDataSize )))
{
return(CLIENT_ERROR_NO_MEMORY);
}
5. Return the size of the VDOPEN structure in puiSize. This is used by the client engine to determine the version of the virtual channel driver.
DriverPoll
Allows the virtual driver to get periodic control to perform any action as required. With the Evt_ and Tmr_ APIs, a more event driven implementation is possible so you may find that the DriverPoll is empty.
Calling Convention
INT DriverPoll( PVD pVD, PVOID pVdPoll, PUINT16 puiSize);
Parameters
pVD
Pointer to a virtual driver control structure.
pVdPoll
Pointer to one of the driver poll information structures (DLLPOLL).
puiSize
Pointer to the size of the driver poll information structure. This is an output parameter.
Return Values
If the functionsucceeds, it returns CLIENT_STATUS_SUCCESS. If the driver has no data on this polling pass, it returns CLIENT_STATUS_NO_DATA.
If the virtual driver cannot allocate an output buffer, it returns CLIENT_STATUS_ERROR_RETRY so the WinStation driver does not slow polling. The virtual driver then attempts to get an output buffer the next time it is polled.
Return values that begin with CLIENT_ERROR_ are fatal errors; the ICA session is disconnected.
Remarks
Because the client engine is single threaded, a virtual driver is not allowed to block while waiting for a desired result (such as the availability of an output buffer) because this prevents the rest of the client from processing.
The Ping example includes examples of processing that can occur in DriverPoll.
DriverQueryInformation
Gets run-time information from the virtual driver.
Calling Convention
INT DriverQueryInformation( PVD pVD, PVDQUERYINFORMATION pVdQueryInformation, PUINT16 puiSize);
Parameters
pVD
Pointer to a virtual driver control structure.
pVdQueryInformation
Pointer to a structure that specifies the information to query and the results buffer.
puiSize
Pointer to the size of the query information and resolves structure. This is an output parameter.
Return Value
The function returns CLIENT_STATUS_SUCCESS.
Remarks
This function currently has no practical significance for virtual drivers; it is provided for compatibility with the loadable module interface. There are no general purpose query functions at this time other than LastError. The LastError query is accomplished through the DriverGetLastError function.
DriverSetInformation
Sets run-time information in the virtual driver.
Calling Convention
INT DriverSetInformation( PVD pVD, PVDSETINFORMATION pVdSetInformation, PUINT16 puiSize);
Parameters
pVD
Pointer to a virtual driver control structure.
pVdSetInformation
Pointer to a structure that specifies the information class, a pointer to any additional data, and the size in bytes of the additional data (if any).
puiSize
Pointer to the size of the information structure. This is an input parameter.
Return Value
The function returns CLIENT_STATUS_SUCCESS.
Remarks
This function can receive two information classes:
-
VdDisableModule: When the connection is being closed.
-
VdFlush: When WFPurgeInput or WFPurgeOutput is called by the server-side virtual channel application. The VdSetInformation structure contains a pointer to a VDFLUSH structure that specifies which purge function was called.
Evt_create
Allocates an event structure containing a callback that can be associated with the input or the output events of a particular file descriptor.
Calling Convention
VPSTATUS Evt_create ( void \*hTC, PFNDELIVER pDeliverFunc, void \*pSubscriberId, PEVT \*out);
Parameters
hTC
Pass NULL value as a dummy.
pDeliverFunc
The callback to call.
pSubscriberId
Data passed as an argument to the callback.
out
The event structure returned.
Return Value
The event structure created is returned with the out pointer argument. If the function succeeds, the return value is EVT_SUCCESS.
If the function fails because of insufficient memory, the return value is EVT_OBJ_CREATE_FAILED.
Remarks
The first argument of the callback pSubscriberId is the same as the pSubscriberId used to create the event structure.
The second argument nEvt is a pointer to the event structure responsible for the callback.
Evt_destroy
Destroys previously created event structure by freeing its memory and nulling the given pointer.
Calling Convention
VPSTATUS Evt_destroy ( PEVT \*phEvt);
Parameters
phEvt
Pointer to the event object to destroy.
Return Value
If the function succeeds, the return value is EVT_SUCCESS.
Remarks
The event object to destroy must be removed from the event loop using Evt_remove_triggers, before Evt_destroy is called.
Evt_remove_triggers
Removes the previously setup file descriptor selections from the given file descriptor.
Calling Convention
VPSTATUS Evt_remove_triggers ( Int fd);
Parameters
fd
The file descriptor to remove all selections from.
Return Value
If the function succeeds, the return value is EVT_SUCCESS.
Remarks
If both the input and output conditions are selected, both the conditions are removed.
Evt_signal
Calls the callback stored within the given event structure.
Calling Convention
VPSTATUS Evt_signal ( PEVT hEvt);
Parameters
hEvt
The event structure containing the callback to call.
Return Value
If the function succeeds, the return value is EVT_SUCCESS.
Remarks
Calls the callback function directly. No conditions must be met prior to this call.
Evt_trigger_for_input
Connects the callback of an event structure to trigger on the given file descriptor when it satisfies the input conditions.
Calling Convention
VPSTATUS Evt_trigger_for_input ( PEVT hEvt, int fd);
Parameters
hEvt
The event structure to associate with the input conditions of the given file descriptor.
fd
The file descriptor.Workspace app
Return Value
If the function succeeds, the return value is EVT_SUCCESS.
If the function fails because of insufficient memory, the return value is EVT_OBJ_CREATE_FAILED.
Remarks
The Glib implementation of the event loop used by Citrix Workspace app for Linux watches for the input conditions G_IO_IN and G_IO_HUP.
Evt_trigger_for_output
Connects the callback of an event structure to trigger on the given file descriptor when it satisfies the output conditions.
Calling Convention
VPSTATUS Evt_trigger_for_output ( PEVT hEvt, int fd);
Parameters
hEvt
The event structure to associate with the ouput conditions of the given file descriptor.
fd
The file descriptor.Workspace app
Return Value
If the function succeeds, the return value is EVT_SUCCESS.
If the function fails because of insufficient memory, the return value is EVT_OBJ_CREATE_FAILED.
Remarks
The Glib implementation of the event loop used by Citrix Workspace app for Linux watches for the ouput conditions G_IO_OUT.
ICADataArrival
The WinStation driver calls this function when data is received on a virtual channel being monitored by the driver. The address of this function is passed to the WinStation driver during DriverOpen.
Calling Convention
INT wfcapi ICADataArrival( PVD pVD, USHORT uChan, LPBYTE pBuf, USHORT Length);
Parameters
pVD
Pointer to a virtual driver control structure.
uChan
Virtual channel number.
pBuf
Pointer to the data buffer containing the virtual channel data as sent by the server-side application.
Length
Length in bytes of the data in the buffer.
Return Value
The driver returns CLIENT_STATUS_SUCCESS.
Remarks
This function name is a placeholder for a user-defined function; the actual function does not have to be called ICADataArrival, although it does have to match the function signature (parameters and return type). The address of this function is given to the WinStation driver during DriverOpen. Although ICA prefixes packet control data to the virtual channel data, this prefix is removed before this function is called.
After the virtual driver returns from this function, the WinStation driver considers the data delivered. The virtual driver must save whatever information it needs from this packet if later processing is required.
Do not allow this function to block. Use your own thread or the DriverPoll function (with polling enabled) for any required deferred processing.
The virtual driver can send data to the server on receipt of this data from within the ICADataArrival function, but be aware that the send operation may return an immediate error when buffers are not available to accommodate the send operation. The virtual driver may not block in this function waiting for the sending operation to complete.
If the virtual driver is handling multiple virtual channels, use the uChan parameter to determine the channel over which this data is to be sent. See DriverOpen for more information.
miGetPrivateProfileBool
Gets a Boolean value from a section of the Configuration Storage.
Calling Convention
INT miGetPrivateProfileBool( PCHAR lpszSection, PCHAR lpszEntry, BOOL bDefault);
Parameters
lpszSection
Name of section to query.
lpszEntry
Name of entry to query.
bDefault
Default value to use.
Return Values
If the requested entry is found, the entry value is returned; otherwise, bDefault is returned.
Remarks
A Boolean value of TRUE can be represented by on, yes, or true in the configuration files. All other strings are interpreted as FALSE.
miGetPrivateProfileInt
Gets an integer from a section of the Configuration Storage.
Calling Convention
INT miGetPrivateProfileInt( PCHAR lpszSection, PCHAR lpszEntry, INT iDefault);
Parameters
lpszSection
Name of section to query.
lpszEntry
Name of entry to query.
iDefault
Default value to use.
Return Values
If the requested entry is found, the entry value is returned; otherwise, iDefault is returned.
miGetPrivateProfileLong
Gets a long value from a section of the configuration files.
Calling Convention
INT miGetPrivateProfileLong( PCHAR lpszSection, PCHAR lpszEntry, LONG lDefault);
Parameters
lpszSection
Name of section to query.
lpszEntry
Name of entry to query.
lDefault
Default value to use.
Return Values
If the requested entry is found, the entry value is returned; otherwise, lDefault is returned.
miGetPrivateProfileString
Gets a string from a section of the configuration files.
Calling Convention
INT miGetPrivateProfileString( PCHAR lpszSection, PCHAR lpszEntry, PCHAR lpszDefault, PCHAR lpszReturnBuffer, INT cbSize);
Parameters
lpszSection
Name of section to query.
lpszEntry
Name of entry to query.
lpszDefault
Default value to use.
lpszReturnBuffer
Pointer to a buffer to hold results.
cbSize
Size of lpszReturnBuffer in bytes.
Return Values
This function returns the string length of the value returned in lpszReturnBuffer (not including the trailing NULL).
If the requested entry is found and the size of the entry string is less than or equal to cbSize, the entry value is copied to lpszReturnBuffer; otherwise, iDefault is copied to lpszReturnBuffer.
Remarks
lpszDefault must fit in lpszReturnBuffer. The caller is responsible for allocating and deallocating lpszReturnBuffer.
lpszReturnBuffer must be large enough to hold the maximum length entry string, plus a NULL termination character. If an entry string does not fit in lpszReturnBuffer, the lpszDefault value is used.
MM_clip
Sets the shape of the operating system window “xwin” from the list of sorted rectangles.
Calling Convention
void MM_clip ( UINT32 xwin, int count, struct tagTWI_RECT \*rects, BOOLEAN extended)
Parameters
xwin
Operating system session sub-window.
count
Number of rectangles.
rects
Array of rectangles sorted by Y and X.
extended
TRUE for any extensions; otherwise, FALSE.
Return Values
There are no return values.
Remarks
The structure has four long integers for left, top, right, and bottom. Rectangles are YXsorted.
The last argument must be FALSE to start a fresh clipping update, and TRUE to add any clipping updates to the current clipping list.
MM_destroy_window
Destroys a window created by MM_get_window().
Calling Convention
void MM_destroy_window ( UINT32 hwin, UINT32 xwin,
Parameters
hwin
Host (seamless) window identifiers, ignored for non-seamless sessions.
xwin
x sub-window of the session window.
Return Values
There are no return values.
Remarks
MM_destroy_window also removes any window deletion callbacks added with the low level MM_TWI_set_deletion_call.
MM_get_window
Creates an operating system window "xwinp" that is a sub-window of an existing session window with a server handle "hwin".
Calling Convention
BOOLEAN MM_get_window ( UINT32 hwin, UINT32 \*xwinp,
Parameters
hwin
Host (seamless) window identifiers, ignored for non-seamless sessions.
xwinp
Local operating system window identifier. Returns the sub-window identifier of the session window. In this case, the X Window System is the operating system windowing system.
Return Values
If the parent (hwin) exists, the return value is TRUE. If the parent does not exist, the return value is FALSE.
If the return value is FALSE, the function, including window creation, still works. The root window, however, is used as a temporary parent.
A call to MM_get_window() or MM_set_geometry() can be used to reparent to any existing seamless window.
Remarks
When "0" is passed as the server handle in a non-seamless (single window) session, there can be an existing window, *xwinp that is reparented. The sub-window, however, is unmapped.
If the parent is seamless, *xwinp is protected by unmapping and reparenting it to the root before the parent is deleted.
MM_set_geometry
Sets the size and position for an existing sub-window, "xwin" of a session window with the server handle, "hwin".
Calling Convention
BOOLEAN MM_set_geometry ( UINT32 hwin, UINT32 xwin, CTXMM_RECT \*rt);
Parameters
hwin
Host (seamless) window identifiers, ignored for non-seamless sessions.
xwin
Local operating system window identifier for the session sub-window. In this case, the X Window System is the operating system windowing system.
rt
CTXMM_RECT that describes the new window position and geometry.
Return Values
If the parent (hwin) exists, the return value is TRUE. If the parent does not exist, the return value is FALSE.
If the return value is TRUE, the sub-window is mapped on return.
Remarks
The CTXMM_RECT window rectangle is within the session coordinates which are not window relative and consist of four unsigned 32-bit integers for left, top, right, and bottom.
MM_show_window
Makes a sub-window visible.
Calling Convention
void MM_show_window ( UINT32 xwin)
Parameters
xwin
Local operating system window identifier for the session sub-window. In this case, the X Window System is the operating system windowing system.
Return Values
There are no return values.
Remarks
This function is called when the parent seamless window arrives after the geometry is set.
There must, however, be a successful call to MM_get_window() initially.
The function can be called with exactly the same window identifiers as the previous one. It cannot be used if MM_set_geometry() previously returned TRUE.
MM_TWI_clear_new_window_function
Clears the callback function set up using MM_TWI_set_new_window_function.
Calling Convention
void MM_TWI_clear_new_window_function ( void (\*) (UINT32))
Parameters
(*)(UINT32))
Callback function pointer to remove.
Return Values
There are no return values.
Remarks
Clears the callback for seamless window creation.
MM_TWI_set_new_window_function
Sets a callback function for seamless window creation.
Calling Convention
void MM_TWI_set_new_window_function ( void (*) (UINT32));
Parameters
(*)(UINT32)
Callback function pointer to remove.
Return Values
There are no return values.
Remarks
When MM_get_window() fails because the seamless window is not yet created, MM_TWI_set_new_window_function can be used to watch the creation. The handle must be established only when required and should be removed immediately. The callback argument is the server window handle of a newly created seamless window.
OutBufAppend (Deprecated)
Note
This function is deprecated. QueueVirtualWrite must be used in all
new virtual drivers.
Adds virtual channel packet data to the current output buffer.
Calling Convention
INT WFCAPI OutBufAppend( PWD pWd, LPBYTE pData, USHORT ByteCount);
Parameters
pWd
Pointer to a WinStation driver control structure.
pData
Pointer to the buffer containing the data to append.
ByteCount
Number of bytes to append to the buffer.
Return Values
If the function succeeds, it returns CLIENT_STATUS_SUCCESS.
If the function fails, it returns error code associated with the failure; use GetLastError to get the extended error information.
Remarks
This function adds virtual channel packet data to the end of the current output buffer. A buffer of appropriate size must be reserved before calling this function.
The address for this function is obtained from the VDWRITEHOOK structure after hook registration. The VDWRITEHOOK structure also provides pWd.
This function can be called multiple times to build up the content of the buffer. It is not written until OutBufWrite is called. Attempts to write more data than was specified in OutBufReserve cause unpredictable results.
The packet header information must be filled in before this function is called.
If an ICA header or virtual channel data is appended to the buffer, the buffer must be sent to the server before the control leaves the virtual driver.
OutBufReserve (Deprecated)
Note
This function is deprecated. QueueVirtualWrite must be used in all
new virtual drivers.
Checks if a buffer of the requested size is available. This function does not allocate buffers because they are already allocated by the WinStation driver.
Calling Convention
INT WFCAPI OutBufReserve( PWD pWd, USHORT ByteCount);
Parameters
pWd
Pointer to a WinStation driver control structure.
ByteCount
Size in bytes of the buffer needed. This must be four bytes larger than the data to be sent.
Return Values
If a buffer of the specified size is available, the return value is CLIENT_STATUS_SUCCESS.
If a buffer of the specified size is not available, the return value is CLIENT_ERROR_NO_OUTBUF.
Remarks
After this function is called to reserve an output buffer, use the other OutBuf* helper functions to append data and then send the buffer to the server.
If a buffer of the specified size is not available, attempt the operation in a later DriverPoll call.
The developer determines the ByteCount, which can be any length up to the maximum size supported by the ICA connection. This size is independent of size restrictions on the lower-layer transport.
-
If the server is running XenApp or a version of Presentation Server 3.0 Feature Release 2 or later, the maximum packet size is 5000 bytes (4996 bytes of data plus the 4-byte packet overhead generated by the ICA datastream manager)
-
If the server is running a version of Presentation Server earlier than 3.0 Feature Release 2, the maximum packet size is 2048 bytes (2044 bytes of data plus the 4- byte packet overhead generated by the ICA datastream manager)
The address for this function is obtained from the VDWRITEHOOK structure after hook registration. The VDWRITEHOOK structure also provides the pWd address.
OutBufWrite (Deprecated)
Note
This function is deprecated. QueueVirtualWrite must be used in all
new virtual drivers.
Sends a virtual channel packet to XenApp or XenDesktop.
Calling Convention
INT WFCAPI OutBufWrite( PWD pWd);
Parameters
pWd
Pointer to a WinStation driver control structure.
Return Values
If the function succeeds, it returns CLIENT_STATUS_SUCCESS.
If the function fails, it returns the error code associated with the failure; use GetLastError to get the extended error information.
Remarks
This function sends the current output buffer to the host. If a buffer was not reserved or no data was appended, this function does nothing.
If an ICA header or virtual channel data is appended to the buffer, the buffer must be sent to the server before DriverPoll returns.
The address for this function is obtained from the VDWRITEHOOK structure after hook registration. The VDWRITEHOOK structure also provides the pWd address.
QueueVirtualWrite
QueueVirtualWrite is an improved scatter gather interface. It queues a virtual write and stimulates packet output if required allowing data to be sent without having to wait for the poll.
Calling Convention
int WFCAPI QueueVirtualWrite ( PWD pWd, SHORT Channel, LPMEMORY_SECTION pMemorySections, USHORT NrOfMemorySections, USHORT Flag);
Parameters
pWd
Pointer to a WinStation driver control structure.
Channel
The virtual channel number
pMemorySections
Pointer to an array memory sections.
NrOfMemorySections
The number of memory sections.
Flag
This can be FLUSH_IMMEDIATELY if the data is required to be sent immediately or ! FLUSH_IMMEDIATELY for lower priority data.
Return Values
If the function succeeds, that is queued successfully, the return value is CLIENT_STATUS_SUCCESS.
If the function fails because of unsuccessful queue, the return value is CLIENT_ERROR_NO_OUTBUF.
Remarks
The interface is simpler as it reduces the call sequence OutBufReserve, AppendVdHeader, OutBufAppend, and OutBufWrite down to a single QueveVirtualWrite call.
The data to be written across the chosen virtual channel is described by an array of MEMORY_SECTION structures, each of which contains a length and data pointer pair. This allows multiple non-contiguous data segments to be combined and written with a single QueueVirtualWrite.
Tmr_create
Creates a timer object and returns its handle.
Calling Convention
VPSTATUS Tmr_create ( HND hTC, UINT32 uiPeriod, PVOID pvSubscriber, PFNDELIVER pfnDeliver. PTMR * phTimer);
Parameters
hTC
The value is NULL.
uiPeriod
The timeout for the timer in milliseconds.
pvSubscriber
Data passed as an argument to the callback.
pfnDeliver
The callback to call.
phTimer
The returned timer structure.
Return Values
If the function succeeds, the return value is TMR_SUCCESS.
If the function fails because of insufficient memory, the return value is TMR_OBJ_CREATE_FAILED.
Remarks
The default state of a newly created timer object is disabled. The "deliver" function is called when the timer fires.
Tmr_destroy
Destroys the timer object pointed to by the given handle and sets the handle to NULL.
Calling Convention
VPSTATUS Tmr_destroy ( PTMR \* phTimer);
Parameters
phTimer
The timer to destroy.
Return Values
If the function succeeds, the return value is TMR_SUCCESS.
Remarks
Tmr_destroy is called for all timer objects when they are not required.
Tmr_setEnabled
Enables or disables a timer object.
Calling Convention
VPSTATUS Tmr_setEnabled ( PTMR \* hTimer); BOOL fEnabled);
Parameters
hTimer
The timer to enable or disable.
fEnabled
Enables or disables the timer.
Return Values
If the function succeeds, the return value is TMR_SUCCESS.
Remarks
Enabling a disabled timer restarts the timing period. Re-enabling an enabled timer, however, does not perform any action.
Tmr_setPeriod
Sets the timeout period for a timer.
Calling Convention
VPSTATUS Tmr_setPeriod ( PTMR \* hTimer); UNIT32 uiPeriod);
Parameters
hTimer
The timer to change the timeout period for.
uiPeriod
The new timeout period in milliseconds.
Return Values
If the function succeeds, the return value is TMR_SUCCESS.
Remarks
If the timer is already running, the timer is reset and fires after the new period. If the timer is disabled, the timeout period is updated but the timer remains disabled.
VdCallWd
Calls the client WinStation driver to query and set information about the virtual channel. This is the main method for the virtual driver to access the WinStation driver. For general-purpose virtual channel drivers, this sets the virtual write hook.
Calling Convention
INT VdCallWd ( PVD pVd, USHORT ProcIndex, PVOID pParam, PUINT16 puiSize);
Parameters
pVd
Pointer to a virtual driver control structure.
ProcIndex
Index of the WinStation driver routine to call. For virtual drivers, this can be either WDxQUERYINFORMATION or WDxSETINFORMATION.
pParam
Pointer to a parameter structure, used for both input and output.
puiSize
Size of parameter structure, used for both input and output.
Return Values
If the function succeeds, it returns CLIENT_STATUS_SUCCESS.
If the function fails, it returns an error code associated with the failure; use DriverGetLastError to get the extended error information.
Remarks
This function is a general purpose mechanism to call routines in the WinStation driver. The only valid uses of this function for a virtual driver are:
-
To allocate the virtual channel using WDxQUERYINFORMATION
-
To exchange function pointers with the WinStation driver during DriverOpen using WDxSETINFORMATION
For more information, see DriverOpen or the Ping example.
On successful return, the VDWRITEHOOK structure contains pointers to the output buffer virtual driver helper functions, and a pointer to the WinStation driver control block (which is needed for buffer calls).