Programming reference
Unless otherwise specified, the following functions apply to Citrix VDAs. In the context of this reference a ‘server’ can be any supported Windows OS that is running a Citrix VDA.
WFOpenServer
This function opens a handle to a specified server.
C calling convention
HANDLE WINAPI WFOpenServer{W|A}(
IN LPWSTR pServerName
);
Parameters
| Parameter | Description |
|---|---|
| pServerName | A pointer to the name of a server that is running a VDA. Supply an ANSI string to WFOpenServerA() and a Unicode string to WFOpenServerW(). |
Returns
If the function succeeds, it returns a handle to the specified server. If the function fails, it returns NULL. Call the GetLastError() function to get extended error status.
Remarks
When you are finished with the handle, use the WFCloseServer() function to close all server handles opened using the WFOpenServer function, as part of you program's cleanup.
You do not need to open a handle for operations performed on the server where the program is running. Use the constant WF_CURRENT_SERVER_HANDLE instead.
WFCloseServer
Close a server handle that was opened by WFOpenServer.
C calling convention
VOID WINAPI WFCloseServer (
IN HANDLE hServerHandle
);
Parameters
| Parameter | Description |
|---|---|
| hServerHandle | A handle to a previously-opened server. Use the WFOpenServer() function to obtain a handle for a specific server. |
WFDisconnectSession
This function disconnects a specified session.
C calling convention
BOOL WINAPI WFDisconnectSession (
IN HANDLE hServer,
IN DWORD SessionId,
IN BOOL bWait
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a specific server or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| SessionId | The session ID of the target session. WF_CURRENT_SESSION identifies the current session. Use the WFEnumerateSessions() function to obtain session IDs. |
| bWait | If this value is TRUE, the function waits for the disconnect function to complete before it returns. |
Return values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFDisconnectSessionEx
This function forces an immediate disconnect of a specified session.
C calling convention
BOOL WINAPI WFDisconnectSessionEx(
IN HANDLE hServer,
IN DWORD SessionId,
IN ULONG Flags,
IN PVOID pBuffer,
IN ULONG BufferLength
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a specific server or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| SessionId | The session ID of the target session. WF_CURRENT_SESSION identifies the current session. Use the WFEnumerateSessions() function to obtain session IDs. |
| Flags | A combination of the following flags: WF_DISCON_WAIT. If this flag is set, the function waits for the disconnect to finish; if this flag is not set, the function does not wait for the disconnect to finish.WF_DISCON_NO_NOTIFY_CLIENT. If this flag is set, the function returns without notifying the client; if this flag is not set, the function waits for the client’s response to ensure that the client received the disconnect request. |
| pBuffer | This parameter is reserved for future use. |
| BufferLength | This parameter is reserved for future use. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function forces an immediate disconnect of the session. Use the WF_DISCON_NO_NOTIFY_CLIENT flag with caution because it does not notify the client of the disconnect.
WFEnumerateProcesses
This function retrieves a list of the active processes on a specified server.
C calling convention
BOOL WINAPI WFEnumerateProcesses{W|A}(
IN HANDLE hServer,
IN DWORD Reserved,
IN DWORD Version,
OUT PWF_PROCESS_INFO{W|A} * ppProcessInfo,
OUT DWORD * pCount
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a specific server or specify WF_CURRENT_SERVER_HANDLE to use the current server |
| Reserved | This value must be zero (0). |
| Version | The version of the enumeration request, this value must be 1. |
| ppProcessInfo | A pointer to the address of a variable that will receive the enumeration results that are returned as an array of WF_PROCESS_INFO structures (defined in Wfapi.h). The buffer is allocated by this function and is de-allocated using the WFFreeMemory() function. |
| pCount | A pointer to the variable that receives the number of returned WF_PROCESS_INFO structures. |
The name of the process pointed to by pProcessName contains an ANSI string if WFEnumerateProcessesA() is used, and a Unicode string if WFEnumerateProcessesW() is used.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function only applies to RDS VDAs.
WFEnumerateProcessesEx
This function retrieves a list of the active processes on a specified server. Detailed process information is also returned.
C calling convention
BOOL WINAPI WFEnumerateProcessesEx{W|A}(
IN HANDLE hServer,
IN DWORD Reserved,
IN DWORD Version,
OUT PWF_PROCESS_INFOEX{W|A} * ppProcessInfo,
OUT DWORD * pCount
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a specific server or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| Reserved | This value must be zero (0). |
| Version | The version of the enumeration request, this value must be 1. |
| ppProcessInfo | A pointer to the address of a variable that receives the enumeration results that are returned as an array of WF_PROCESS_INFOEX structures (defined in Wfapi.h). The buffer is allocated by this function and is de-allocated using the WFFreeMemory() function. |
| pCount | A pointer to the variable that receives the number of returned WF_PROCESS_INFOEX structures. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function only applies to RDS VDAs.
WFEnumerateSessions
This function retrieves a list of the sessions on a specified VDA.
C calling convention
BOOL WINAPI WFEnumerateSessions{W|A}(
IN HANDLE hServer,
IN DWORD Reserved,
IN DWORD Version,
OUT PWF_SESSION_INFO{W|A} * ppSessionInfo,
OUT DWORD * pCount
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a specific server or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| Reserved | This value must be zero (0). |
| Version | The version of the enumeration request, this value must be 1. |
| ppProcessInfo | A pointer to the address of a variable that receives the enumeration results that are returned as an array of WF_SESSION_INFO structures (defined in Wfapi.h). The buffer is allocated by this function and is de-allocated using the WFFreeMemory() function. |
| pCount | A pointer to the variable that receives the number of returned WF_SESSION_INFO structures. |
The session name pointed to by pWinStationName contains an ANSI string if WFEnumerateSessionsA() is used, and a Unicode string if WFEnumerateSessionssW() is used.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function applies to RDS VDAs. On WS VDAs, it shows only the console session.
WFFreeMemory
This function releases memory allocated by WFAPI functions.
C calling convention
VOID WINAPI WFFreeMemory(
IN PVOID pMemory
);
Parameters
| Parameter | Description |
|---|---|
| pMemory | A pointer to the memory to be freed. |
Remarks
Many functions allocate a data area to return information. Use this function to release these data areas.
WFLogoffSession
This function logs off a specified session.
C calling convention
BOOL WINAPI WFLogoffSession(
IN HANDLE hServer,
IN DWORD SessionId,
IN BOOL bWait
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| SessionId | The session ID of the target session. WF_CURRENT_SESSION specifies the current session. |
| bWait | Specify TRUE to instruct the server to wait for the operation to complete. Specify FALSE to log off the session in the background. To verify that the session is logged off, use the WFQuerySessionInformation() function to query the session ID and check for a FALSE return value. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFQuerySessionInformation
This function retrieves information about a specified session on a specified server.
C calling convention
BOOL WINAPI WFQuerySessionInformation{W|A}(
IN HANDLE hServer,
IN DWORD SessionId
IN WF_INCO_CLASS WFInfoClass,
OUT LPWSTR * ppBuffer,
OUT DWORD * pBytesReturned
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| SessionId | The session ID of the target session. WF_CURRENT_SESSION specifies the current session. |
| WFInfoClass | Type of information to be retrieved from the specified session. |
| ppBuffer | A pointer to the address of a variable that receives the information about the specified session. The format and contents of the data depend on the specified information class being queried; see the second column of the table above. The buffer is allocated by this function and is de-allocated using the WFFreeMemory() function. |
| pBytesReturned | A pointer to the variable that receives the number of returned bytes. If this value is NULL, the byte count is not returned. |
| WFInfoClass value | Data type | Note |
|---|---|---|
| WFVersion | OSVERSIONINFO | 1 |
| WFInitialProgram | NULL-terminated string | |
| WFWorkingDirectory | NULL-terminated string | |
| WFOEMId | NULL-terminated string | |
| WFSessionId | ULONG | |
| WFUserName | NULL-terminated string | |
| WFWinStationName | NULL-terminated string | 2 |
| WFDomainName | NULL-terminated string | |
| WFConnectState | INT | 2 |
| WFClientBuildNumber | USHORT | 3 |
| WFClientName | NULL-terminated string | 3 |
| WFClientDirectory | NULL-terminated string | 3 |
| WFClientProductId | USHORT | 3 |
| WFClientAddress | WF_CLIENT_ADDRESS | 2, 3 |
| WFClientDisplay | WF_CLIENT_DISPLAY | 2, 3 |
| WFClientCache | WF_CLIENT_CACHE | 2, 3 |
| WFClientDrives | WF_CLIENT_DRIVES | 2, 3 |
| WFICABufferLength | ULONG | 3 |
| WFApplicationName | NULL-terminated string | 3 |
| WFAppInfo | WF_APP_INFO | 2, 3 |
| WFClientInfo | WF_CLIENT_INFO | 2, 3 |
| WFUserInfo | WF_USER_INFO | 2, 3 |
| WFSessionTime | WF_SESSION_TIME | 2 |
-
1 - This is a standard Windows structure defined in Winbase.h. For more information, see the Windows programming documentation. This option returns information only for the current server; the server handle parameter is ignored for this option.
-
2 - These structures are defined in Wfapi.h.
-
3 - These parameters can be used only if the function is called from an ICA session. If run from the server console or a Direct ICA station, the function returns FALSE.
-
4 - The strings are in ANSI format if WFEnumerateSessionInformationA() is used, and Unicode format if WFEnumerateSessionInformationW() is used.
-
5 - Use an INTEGER or LONG to retrieve a SHORT.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
The WFSessionId WFInfoClass type returns zero (0) when running on the server console. This is the best method for determining if a program is being run from an ICA session or on the server console itself.
The WFVersion WFInfoClass type can be used only to retrieve operating system version information for the current server that is running Citrix Virtual Apps and Desktop Server. The server handle is ignored for this option.
On Workstation VDAs there is only one session, use WF_CURRENT_SESSION for the session Id.
WFQueryUserConfig
This function retrieves configuration information about a specified user on a server.
C calling convention
BOOL WINAPI WFQueryUserConfig{W|A}(
IN LPWSTR pServerName,
IN LPWSTR pUserName,
IN WF_CONFIG_CLASS WFConfigClass,
OUT LPWSTR * ppBuffer,
OUT DWORD * pBytesReturned
);
Parameters
| Parameter | Description |
|---|---|
| pServerName | A pointer to the name of a server or a domain controller. Use WF_CURRENT_SERVER_NAME to specify the current server. |
| pUserName | A pointer to the user name. |
| WFConfigClass | The type of user information to be retrieved. |
| ppBuffer | A pointer to the address of a variable that receives the query results. The buffer is allocated within this function and is de-allocated using the WFFreeMemory() function. |
| pBytesReturned | A pointer to the variable that receives the number of returned bytes. |
| WFConfigClass Value | (Data type) and data returned |
|---|---|
| WFUserConfigInitialProgram | (NULL-terminated string) User initial program |
| WFUserConfigWorkingDirectory | (NULL-terminated string) User working directory |
| WFUserConfigfInheritInitialProgram | (DWORD) Flag for inheriting initial program |
If WFQueryUserConfigA() is used, the supplied server name must be an ANSI string. If WFQueryUserConfigW() is used, the supplied server name must be a Unicode string.
The NetGetDCName() and NetGetAnyDCName() functions accept only Unicode strings as parameters.
The strings returned for the user initial program and user working directory are in ANSI format if WFQueryUserconfigA() is used, and in Unicode format if WFQueryUserConfigW() is used.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
The WFQueryUserConfig() and WFSetUserConfig() functions are passed a server name instead of a handle because user account information often resides on a domain controller. The domain controller can be a Windows server or a server. Any domain controller can be used to retrieve domain information, but you must use the primary domain controller to change domain information. Use the following standard Windows functions, which are in agreement with other Microsoft APIs.
-
Use NetGetDCName() to get the name of the primary domain controller for the WFSetUserConfig() function
-
Use NetGetAnyDCName() to get the name of any domain controller for the WFQueryUserConfig() function
This function applies to RDS VDAs.
WFSendMessage
This function sends a message box to a specified session.
C calling convention
BOOL WINAPI WFSendMessage{W|A}(
IN HANDLE hServer,
IN DWORD SessionId,
IN LPWSTR pTitle,
IN DWORD TitleLength,
IN LPWSTR pMessage,
IN DWORD MessageLength,
IN DWORD Style,
IN DWORD Timeout,
OUT DWORD * pResponse,
IN BOOL bWait
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| SessionId | The session ID of a session that is running a Citrix VDA. Use WF_CURRENT_SESSION to specify the current session. |
| pTittle | A pointer to the title that the message box will display. |
| TitleLength | The length (in bytes) of the title to be displayed. |
| pMessage | A pointer to the message to be displayed. |
| MessageLength | The length (in bytes) of the message to be displayed. |
| Style | A standard Windows MessageBox() style parameter. For more information,see the Microsoft documentation.Typically, this value is set to MB_OK for C++. |
| Timeout | The response time-out, in seconds. If the message does not receive a response within this time period and bWait is set to TRUE, pResponse contains IDTIMEOUT. |
| bWait | If TRUE, the function waits for the user to respond or the time-out to occur before returning control. If no Timeout value is specified, the user must respond before control is returned.If FALSE, control is returned immediately and pResponse contains IDASYNC. Use this method for simple information messages (such as print job notification messages) that do not need to return the user |
| pResponse | A pointer to a variable that indicates the location where the selected response will be returned. The response is one of: a MessageBox() return code, IDASYNC, or IDTIMEOUT. |
If WFSendMessageA() is used, the supplied title and message must be ANSI strings. If WFSendMessageW() is used, the title and message must be Unicode strings.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFSetUserConfig
This function modifies configuration information for a specified user on a server or domain controller.
C calling convention
BOOL WINAPI WFSetUserConfig{W|A}(
IN LPWSTR pServerName,
IN LPWSTR pUserName,
IN WF_CONFIG_CLASS WFConfigClass,
IN LPWSTR * pBuffer,
IN DWORD DataLength
);
Parameters
| Parameter | Description |
|---|---|
| pServerName | A pointer to the name of a server or a domain controller. Use WF_CURRENT_SERVER_NAME to specify the current server. |
| pUserName | A pointer to the user name. |
| WFConfigClass | The type of user information to be set |
| pBuffer | A pointer to the data that is used to modify the configuration of the specified user. |
| DataLength | The size (in bytes) of the buffer. The strings returned for the user initial program and user working directory are in ANSI format if WFQueryUserconfigA() is used, and Unicode format if WFQueryUserConfigW() is used. |
| WFConfigClass Values | (Data type) and data returned |
|---|---|
| WFUserConfigInitialProgram | (NULL-terminated string) User initial program. |
| WFUserConfigWorkingDirectory | (NULL-terminated string) User working director.y |
| WFUserConfigfInheritInitialProgram | (DWORD) Flag for inheriting initial program. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
The WFQueryUserConfig() and WFSetUserConfig() functions are passed a server name instead of a handle because user account information often resides on a domain controller. The domain controller can be a Windows server or a server that is running a Citrix VDA. Any domain controller can be used to retrieve domain information, but you must use the primary domain controller to change domain information. Use the following standard Windows functions, which are in agreement with other Microsoft APIs.
-
Use NetGetDCName() to get the name of the primary domain controller for the WFSetUserConfig() function
-
Use NetGetAnyDCName() to get the name of any domain controller for the WFQueryUserConfig() function You must have domain administrator privileges to use this function. This function applies to RDS VDAs.
WFShutdownSystem
This function shuts down (and optionally restarts) the current server.
C calling convention
BOOL WINAPI WFShutdownSystem(
IN HANDLE hServer,
IN DWORD ShutdownFlag
);
Parameters
| Parameter | Description |
|---|---|
| hServer | This parameter is ignored. |
| ShutdownFlag | One of the following flags. Flags cannot be combined. |
| Shutdown flag | Description |
|---|---|
| WF_WSD_LOGOFF | Forces all sessions except the console to log off and disables all further logons. Use this flag only on the server console. If the flag is used from another session, all sessions are logged off and no further logons are allowed. If a user is logged onto the console when the flag is used, the console is not logged off. |
| WF_WSD_SHUTDOWN | Shuts down the pc. This action is equivalent to selecting Shutdown from the Start menu or Program Manager. A dialog box appears on the server console, prompting the user to press a key to restart the pc. |
| WF_WSD_REBOOT | Shuts down and restarts the PC. This action is equivalent to selecting Shutdown and Reboot from the Start menu or Program Manager. |
| WF_WSD_FASTREBOOT | Restarts the server without shutting it down. This action is equivalent to running the SHUTDOWN / NOW command, which is typically not done. For more information, see the Remarks section. |
| WF_WSD_POWEROFF | Shuts down the pc and, on computers that support software control of power, powers it off. |
Returns
When this function is run on the server console, if the WF_WSD_LOGOFF flag is used and the function succeeds, the return value is TRUE. If this function is run on another session, or one of the other flags is used and the function succeeds, the program terminates and the pc is shut down.
If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
A system shutdown terminates all users and active programs. Users are not warned before they are logged off and they do not have the option of saving their work. The following steps occur during shutdown:
-
An exit command is issued to all active user applications. If an application does not exist within a specified interval, the application is terminated.
-
After all of the applications for a user terminate, the user is logged off.
-
After all users are logged off, an exit command is issued to all system services. If a system service does not terminate within a specified interval, the service is terminated.
-
After all system services are terminated, the file system cache is written to disk.
-
The disks are marked “Read Only.”
-
If the WF_WSD_REBOOT flag is specified, the system is restarted. If not, the System Can Be Turned Off message appears.
Caution: WF_WSD_FASTREBOOT forces an immediate shutdown, skipping Steps 1 through 3 in the preceding steps. Do not use WF_WSD_FASTREBOOT unless it is absolutely necessary because there is a possibility of severe data loss or file corruption.
Because there can be many users and processes in a large multiuser configuration, large system configurations may take some time to shut down properly. It is important to allow the system to shut down completely.
WFTerminateProcess
This function terminates a specified process on a server.
C calling convention
BOOL WINAPI WFTerminateProcess (
IN HANDLE hServer,
IN DWORD ProcessId,
IN DWORD ExitCode
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a PC that is running a VDA. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| ProcessId | The process ID of the process to be terminated. |
| ExitCode | The termination status for the process. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function applies to RDS VDAs.
A pointer to the variable that is updated with the length of the data that is returned in the allocated buffer upon a successful return.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFWaitSystemEvent
This function waits for an event (ICA session create/delete/connect, user logon/logoff, and so on) before it returns.
C calling convention
BOOL WINAPI WFWaitSystemEvent(
IN HANDLE hServer,
IN DWORD EventMask,
OUT DWORD * pEventFlags
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server |
| EventMask | The bit mask that specifies the event(s) for which the function waits. These values can be combined to wait for the first of multiple events. |
| pEventFlags | A pointer to a variable that receives a bit mask of events that occurred. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
Citrix VDA creates ICA connections dynamically as needed. The following table lists and describes the events (possible values for EventMask), and indicates the flags triggered by the event.
| Event | Description | Flags triggered |
|---|---|---|
| WF_EVENT_CREATE | New ICA session created | Create, State, Change, All |
| WF_EVENT_DELETE | Existing ICA session deleted | Delete, State, Change, All |
| WF_EVENT_LOGON | User logon to system (from console or WinStation) | Logon, State Change, All |
| WF_EVENT_LOGOFF | User logoff from system (from console or WinStation) | Delete, Logoff, State Change, All |
| WF_EVENT_CONNECT | ICA session connect from client | Connect, State, Change, All |
| WF_EVENT_DISCONNECT | ICA session disconnect from client | Disconnect, State Change, All |
| WF_EVENT_RENAME | Existing ICA session renamed | Rename, All |
| WF_EVENT_STATECHANGE | ICA session state change (this event is triggered when WF_CONNECTSTATE_CLASS (defined in Wfapi.h) changes) | |
| WF_EVENT_LICENSE | License state change (this event is License, All triggered when a license is added or deleted using License Manager) | License, All |
| WF_EVENT_ALL | Wait for any event type | |
| WF_EVENT_FLUSH | Unblock all waiting events (this event is used only as an EventMask) | |
| WF_EVENT_NONE | No event (this event is used only as a return value in pEventFlags) |
An ICA connection is created when a user connects. When a user signs off, the ICA session is deleted.
When a user signs on to a disconnected session, the existing session is deleted and the Delete flag is triggered. When users connect to a disconnected session from within a session, their session is disconnected and the Disconnect flag is triggered instead of the Delete flag.
**This API produces inconsistent results for WS VDA’s.
WFGetCtxSessionKeyList
Retrieve a list of Session keys.
C calling convention
DWORD WINAPI WFGetCtxSessionKeyList(
HANDLE hServer,
WCHAR **SessionKeys,
DWORD *KeyCount,
DWORD *dwKeyBufferLen,
DWORD *KeyStrLen
)
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer()function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server |
| SessionKeys | A pointer to a buffer that receives an array of session keys, which is allocated upon successful return. |
| KeyCount | A pointer to a DWORD that is set to the count of SessionKeys. |
| dwKeyBufferLen | Pointer to a DWORD which is updated with the length of the data returned in the allocated buffer upon successful return. |
| KeyStrLen | Length of the stings returned. The strings are GUIDS so their length is equal across all session keys. |
Returns
Return is ERROR_SUCCESS if successful otherwise an error code. If successful, the caller is responsible for deallocating the buffer returned.
Remarks
Shows 0 session keys for Workstation VDA’s.
WFIsThisDoubleHopSession
This function returns TRUE if the session is an ICA double hop else returns FALSE.
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server that is running Citrix Virtual Apps and Desktop Server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server.Currently WF_CURRENT_SERVER_HANDLE is supported |
| SessionId | A Citrix Virtual Apps and Desktop Server session ID. WF_CURRENT_SESSION identifies the current session. Currently current sessionId or WF_CURRENT_SESSION supported. |
Remarks
A double hop session is an ICA session running from an ICA session. This API must be called from the client.
WFWaitEndPointClientEventInDoubleHop
This function waits for an endpoint event (ICA session connect/disconnect) on a first-hop ICA session before it returns
C calling convention
BOOL WINAPI WFWaitEndPointClientEventInDoubleHop(
IN HANDLE hServer,
IN DWORD EventMask,
OUT DWORD * pEventFlags
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server that is running Citrix Virtual Apps and Desktop Server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server.Currently WF_CURRENT_SERVER_HANDLE is supported |
| EventMask | The bit mask that specifies the event(s) for which the function waits. These values can be combined to wait for the first of multiple events. |
| pEventFlags | A pointer to a variable that receives a bit mask of events that occurred. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
Remarks
Citrix Virtual Apps and Desktop Server creates ICA connections dynamically as needed. The following table lists and describes the events (possible values for EventMask), and indicates the flags triggered by the event.
| Event | Description | Flags triggered |
|---|---|---|
| WF_EVENT_CONNECT | ICA session connect from Endpoint to Connect first-hop | |
| WF_EVENT_DISCONNECT | ICA session connect from Endpoint to Disconnect first-hop | |
** API fails to wait if the second hop is WS-VDA
WFEndPointClientDataInDoubleHopW
Provides the Client name, ipaddress, productID and build number described in WF_CLIENT_INFOW structure if the session is running in a double-hop session.
BOOL WINAPI WFEndPointClientDataInDoubleHopW(
IN HANDLE hServer
IN DWORD SessionId,
IN PWF_CLIENT_INFOW* ppClientInfo,
DWORD* pDataSize);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server that is running Citrix Virtual Apps and Desktop Server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. Currently WF_CURRENT_SERVER_HANDLE is supported |
| SessionId | A Citrix Virtual Apps and Desktop Server session ID. WF_CURRENT_SESSION identifies the current session Currently current sessionId or WF_CURRENT_SESSION supported. |
| ppClientInfo | A pointer to the address of a variable type WF_CLIENT_INFOW that receives the information about the endpoint client data. The buffer is allocated by this function and is deallocated using the WFFreeMemory() function. |
| pDataSize | A pointer to the variable that receives the number of returned bytes. If this value is NULL, the byte count is not returned. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
WFCaptureAppDisplay
Captures the contents of an application window which can be consumed by virtual channels using the VC SDK.
BOOL WINAPI WFCaptureAppDisplay(
IN HWND hwnd
IN AppDisplayCallback cb
IN PVOID userdata
IN UINT32 flags);
Parameters
| Parameter | Description |
|---|---|
| hWnd | The window handle of the application whose display is to be captured. |
| cb | A callback to receive events. |
| userdata | A pointer to an application context or other user data that will be passed to the callback when it is invoked. |
| flags | One of the following flags. |
| flags | Description |
|---|---|
| WFAppDisplayBorder | Draws a red border around the captured application |
| WFAppDisplayCursor | Capture the display cursor |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
WFReleaseAppDisplay
Stops capturing the contents of an application window, which was previously initiated by calling WFCaptureAppDisplay.
VOID WINAPI WFReleaseAppDisplay(
IN HWND hwnd);
| Parameter | Description | |
|---|---|---|
| hWnd | The window handle of the application for which to stop capturing. | s response to the calling program. |
| pResponse | A pointer to a variable that indicates the location where the selected response will be returned. The response is one of: a MessageBox() return code, IDASYNC, or IDTIMEOUT. |
If WFSendMessageA() is used, the supplied title and message must be ANSI strings. If WFSendMessageW() is used, the title and message must be Unicode strings.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFSetUserConfig
This function modifies configuration information for a specified user on a server or domain controller.
C calling convention
BOOL WINAPI WFSetUserConfig{W|A}(
IN LPWSTR pServerName,
IN LPWSTR pUserName,
IN WF_CONFIG_CLASS WFConfigClass,
IN LPWSTR * pBuffer,
IN DWORD DataLength
);
Parameters
| Parameter | Description |
|---|---|
| pServerName | A pointer to the name of a server or a domain controller. Use WF_CURRENT_SERVER_NAME to specify the current server. |
| pUserName | A pointer to the user name. |
| WFConfigClass | The type of user information to be set |
| pBuffer | A pointer to the data that is used to modify the configuration of the specified user. |
| DataLength | The size (in bytes) of the buffer. The strings returned for the user initial program and user working directory are in ANSI format if WFQueryUserconfigA() is used, and Unicode format if WFQueryUserConfigW() is used. |
| WFConfigClass Values | (Data type) and data returned |
|---|---|
| WFUserConfigInitialProgram | (NULL-terminated string) User initial program. |
| WFUserConfigWorkingDirectory | (NULL-terminated string) User working director.y |
| WFUserConfigfInheritInitialProgram | (DWORD) Flag for inheriting initial program. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
The WFQueryUserConfig() and WFSetUserConfig() functions are passed a server name instead of a handle because user account information often resides on a domain controller. The domain controller can be a Windows server or a server that is running a Citrix VDA. Any domain controller can be used to retrieve domain information, but you must use the primary domain controller to change domain information. Use the following standard Windows functions, which are in agreement with other Microsoft APIs.
-
Use NetGetDCName() to get the name of the primary domain controller for the WFSetUserConfig() function
-
Use NetGetAnyDCName() to get the name of any domain controller for the WFQueryUserConfig() function You must have domain administrator privileges to use this function. This function applies to RDS VDAs.
WFShutdownSystem
This function shuts down (and optionally restarts) the current server.
C calling convention
BOOL WINAPI WFShutdownSystem(
IN HANDLE hServer,
IN DWORD ShutdownFlag
);
Parameters
| Parameter | Description |
|---|---|
| hServer | This parameter is ignored. |
| ShutdownFlag | One of the following flags. Flags cannot be combined. |
| Shutdown flag | Description |
|---|---|
| WF_WSD_LOGOFF | Forces all sessions except the console to log off and disables all further logons. Use this flag only on the server console. If the flag is used from another session, all sessions are logged off and no further logons are allowed. If a user is logged onto the console when the flag is used, the console is not logged off. |
| WF_WSD_SHUTDOWN | Shuts down the pc. This action is equivalent to selecting Shutdown from the Start menu or Program Manager. A dialog box appears on the server console, prompting the user to press a key to restart the pc. |
| WF_WSD_REBOOT | Shuts down and restarts the PC. This action is equivalent to selecting Shutdown and Reboot from the Start menu or Program Manager. |
| WF_WSD_FASTREBOOT | Restarts the server without shutting it down. This action is equivalent to running the SHUTDOWN / NOW command, which is typically not done. For more information, see the Remarks section. |
| WF_WSD_POWEROFF | Shuts down the pc and, on computers that support software control of power, powers it off. |
Returns
When this function is run on the server console, if the WF_WSD_LOGOFF flag is used and the function succeeds, the return value is TRUE. If this function is run on another session, or one of the other flags is used and the function succeeds, the program terminates and the pc is shut down.
If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
A system shutdown terminates all users and active programs. Users are not warned before they are logged off and they do not have the option of saving their work. The following steps occur during shutdown:
-
An exit command is issued to all active user applications. If an application does not exist within a specified interval, the application is terminated.
-
After all of the applications for a user terminate, the user is logged off.
-
After all users are logged off, an exit command is issued to all system services. If a system service does not terminate within a specified interval, the service is terminated.
-
After all system services are terminated, the file system cache is written to disk.
-
The disks are marked “Read Only.”
-
If the WF_WSD_REBOOT flag is specified, the system is restarted. If not, the System Can Be Turned Off message appears.
Caution: WF_WSD_FASTREBOOT forces an immediate shutdown, skipping Steps 1 through 3 in the preceding steps. Do not use WF_WSD_FASTREBOOT unless it is absolutely necessary because there is a possibility of severe data loss or file corruption.
Because there can be many users and processes in a large multiuser configuration, large system configurations may take some time to shut down properly. It is important to allow the system to shut down completely.
WFTerminateProcess
This function terminates a specified process on a server.
C calling convention
BOOL WINAPI WFTerminateProcess (
IN HANDLE hServer,
IN DWORD ProcessId,
IN DWORD ExitCode
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a PC that is running a VDA. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| ProcessId | The process ID of the process to be terminated. |
| ExitCode | The termination status for the process. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function applies to RDS VDAs.
A pointer to the variable that is updated with the length of the data that is returned in the allocated buffer upon a successful return.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFWaitSystemEvent
This function waits for an event (ICA session create/delete/connect, user logon/logoff, and so on) before it returns.
C calling convention
BOOL WINAPI WFWaitSystemEvent(
IN HANDLE hServer,
IN DWORD EventMask,
OUT DWORD * pEventFlags
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server |
| EventMask | The bit mask that specifies the event(s) for which the function waits. These values can be combined to wait for the first of multiple events. |
| pEventFlags | A pointer to a variable that receives a bit mask of events that occurred. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
Citrix VDA creates ICA connections dynamically as needed. The following table lists and describes the events (possible values for EventMask), and indicates the flags triggered by the event.
| Event | Description | Flags triggered |
|---|---|---|
| WF_EVENT_CREATE | New ICA session created | Create, State, Change, All |
| WF_EVENT_DELETE | Existing ICA session deleted | Delete, State, Change, All |
| WF_EVENT_LOGON | User logon to system (from console or WinStation) | Logon, State Change, All |
| WF_EVENT_LOGOFF | User logoff from system (from console or WinStation) | Delete, Logoff, State Change, All |
| WF_EVENT_CONNECT | ICA session connect from client | Connect, State, Change, All |
| WF_EVENT_DISCONNECT | ICA session disconnect from client | Disconnect, State Change, All |
| WF_EVENT_RENAME | Existing ICA session renamed | Rename, All |
| WF_EVENT_STATECHANGE | ICA session state change (this event is triggered when WF_CONNECTSTATE_CLASS (defined in Wfapi.h) changes) | |
| WF_EVENT_LICENSE | License state change (this event is License, All triggered when a license is added or deleted using License Manager) | License, All |
| WF_EVENT_ALL | Wait for any event type | |
| WF_EVENT_FLUSH | Unblock all waiting events (this event is used only as an EventMask) | |
| WF_EVENT_NONE | No event (this event is used only as a return value in pEventFlags) |
An ICA connection is created when a user connects. When a user signs off, the ICA session is deleted.
When a user signs on to a disconnected session, the existing session is deleted and the Delete flag is triggered. When users connect to a disconnected session from within a session, their session is disconnected and the Disconnect flag is triggered instead of the Delete flag.
**This API produces inconsistent results for WS VDA’s.
WFGetCtxSessionKeyList
Retrieve a list of Session keys.
C calling convention
DWORD WINAPI WFGetCtxSessionKeyList(
HANDLE hServer,
WCHAR **SessionKeys,
DWORD *KeyCount,
DWORD *dwKeyBufferLen,
DWORD *KeyStrLen
)
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer()function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server |
| SessionKeys | A pointer to a buffer that receives an array of session keys, which is allocated upon successful return. |
| KeyCount | A pointer to a DWORD that is set to the count of SessionKeys. |
| dwKeyBufferLen | Pointer to a DWORD which is updated with the length of the data returned in the allocated buffer upon successful return. |
| KeyStrLen | Length of the stings returned. The strings are GUIDS so their length is equal across all session keys. |
Returns
Return is ERROR_SUCCESS if successful otherwise an error code. If successful, the caller is responsible for deallocating the buffer returned.
Remarks
Shows 0 session keys for Workstation VDA’s.
WFIsThisDoubleHopSession
This function returns TRUE if the session is an ICA double hop else returns FALSE.
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server that is running Citrix Virtual Apps and Desktop Server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server.Currently WF_CURRENT_SERVER_HANDLE is supported |
| SessionId | A Citrix Virtual Apps and Desktop Server session ID. WF_CURRENT_SESSION identifies the current session. Currently current sessionId or WF_CURRENT_SESSION supported. |
Remarks
A double hop session is an ICA session running from an ICA session. This API must be called from the client.
WFWaitEndPointClientEventInDoubleHop
This function waits for an endpoint event (ICA session connect/disconnect) on a first-hop ICA session before it returns
C calling convention
BOOL WINAPI WFWaitEndPointClientEventInDoubleHop(
IN HANDLE hServer,
IN DWORD EventMask,
OUT DWORD * pEventFlags
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server that is running Citrix Virtual Apps and Desktop Server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server.Currently WF_CURRENT_SERVER_HANDLE is supported |
| EventMask | The bit mask that specifies the event(s) for which the function waits. These values can be combined to wait for the first of multiple events. |
| pEventFlags | A pointer to a variable that receives a bit mask of events that occurred. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
Remarks
Citrix Virtual Apps and Desktop Server creates ICA connections dynamically as needed. The following table lists and describes the events (possible values for EventMask), and indicates the flags triggered by the event.
| Event | Description | Flags triggered |
|---|---|---|
| WF_EVENT_CONNECT | ICA session connect from Endpoint to Connect first-hop | |
| WF_EVENT_DISCONNECT | ICA session connect from Endpoint to Disconnect first-hop | |
** API fails to wait if the second hop is WS-VDA
WFEndPointClientDataInDoubleHopW
Provides the Client name, ipaddress, productID and build number described in WF_CLIENT_INFOW structure if the session is running in a double-hop session.
BOOL WINAPI WFEndPointClientDataInDoubleHopW(
IN HANDLE hServer
IN DWORD SessionId,
IN PWF_CLIENT_INFOW* ppClientInfo,
DWORD* pDataSize);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server that is running Citrix Virtual Apps and Desktop Server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. Currently WF_CURRENT_SERVER_HANDLE is supported |
| SessionId | A Citrix Virtual Apps and Desktop Server session ID. WF_CURRENT_SESSION identifies the current session Currently current sessionId or WF_CURRENT_SESSION supported. |
| ppClientInfo | A pointer to the address of a variable type WF_CLIENT_INFOW that receives the information about the endpoint client data. The buffer is allocated by this function and is deallocated using the WFFreeMemory() function. |
| pDataSize | A pointer to the variable that receives the number of returned bytes. If this value is NULL, the byte count is not returned. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
WFCaptureAppDisplay
Captures the contents of an application window which can be consumed by virtual channels using the VC SDK.
BOOL WINAPI WFCaptureAppDisplay(
IN HWND hwnd
IN AppDisplayCallback cb
IN PVOID userdata
IN UINT32 flags);
Parameters
| Parameter | Description |
|---|---|
| hWnd | The window handle of the application whose display is to be captured. |
| cb | A callback to receive events. |
| userdata | A pointer to an application context or other user data that will be passed to the callback when it is invoked. |
| flags | One of the following flags. |
| flags | Description |
|---|---|
| WFAppDisplayBorder | Draws a red border around the captured application |
| WFAppDisplayCursor | Capture the display cursor |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
WFReleaseAppDisplay
Stops capturing the contents of an application window, which was previously initiated by calling WFCaptureAppDisplay.
VOID WINAPI WFReleaseAppDisplay(
IN HWND hwnd);
| Parameter | Description |
|---|---|
| hWnd | The window handle of the application for which to stop capturing. |
In this article
- WFOpenServer
- WFCloseServer
- WFDisconnectSession
- WFDisconnectSessionEx
- WFEnumerateProcesses
- WFEnumerateProcessesEx
- WFEnumerateSessions
- WFFreeMemory
- WFLogoffSession
- WFQuerySessionInformation
- WFQueryUserConfig
- WFSendMessage
- WFSetUserConfig
- WFShutdownSystem
- WFTerminateProcess
- WFWaitSystemEvent
- WFGetCtxSessionKeyList
- WFIsThisDoubleHopSession
- WFWaitEndPointClientEventInDoubleHop
- WFEndPointClientDataInDoubleHopW
- WFCaptureAppDisplay
- WFReleaseAppDisplay
- WFSetUserConfig
- WFShutdownSystem
- WFTerminateProcess
- WFWaitSystemEvent
- WFGetCtxSessionKeyList
- WFIsThisDoubleHopSession
- WFWaitEndPointClientEventInDoubleHop
- WFEndPointClientDataInDoubleHopW
- WFCaptureAppDisplay
- WFReleaseAppDisplay