WFAPI SDK programmer’s guide

The Citrix WinFrame API (WFAPI) functions enable application programs to perform tasks that are unique to Citrix Virtual Apps and Desktops.. Appropriate hotfixes and service packs may be needed for the functions defined here to execute properly.

Citrix Virtual Apps and Desktops server will be referred to as Citrix VDA in the Citrix WinFrame API documentation. Citrix Virtual Apps and Desktops (RDS VDA) runs on server OSs,Microsoft Windows 2019, Microsoft Windows 2022. Citrix Virtual Apps and Desktops (WS VDA) runs on workstation OSs,Windows 10, and Windows 11.

This SDK allows software developers to programmatically access features specific to Citrix VDAs. For example:

• Enumerating servers, sessions, and processes

• Managing servers, sessions, and processes

• Accessing Citrix-specific user data

• Sending messages to a session

• Using virtual channels

• Waiting on system events

The WFAPI SDK comprises a set of function calls to the Wfapi.dll dynamic link library (DLL) for 32-bit applications and Wfapi64.dll for 64-bit applications. These DLLs are available on servers and Windows Workstation platforms running Citrix Virtual Apps and Desktops. Example programs are included to assist developers.

Using the WFAPI SDK

The WFAPI SDK is intended for use by OEMs and customers who need to write applications that directly call WFAPI functions, using Microsoft Version 14.0 (Visual Studio 2015-2022).

System requirements

The WFAPI SDK must be installed and built on a Windows 10, Windows 11, Windows Servers 2019 and 2022 computer with sufficient disk space. The SDK does not need more than a few megabytes of disk space. However, third-party development tools (for example, Microsoft Visual C++) may require a substantial amount of disk space. When considering system requirements for using this SDK, plan to have enough disk space for all of the necessary software components to install and function properly.

The WFAPI SDK is supported on 32-bit and 64-bit operating systems. The descriptions in this guide are primarily based on 64-bit operating systems and differences for 32-bit operating systems are noted.

Generally, wfapi64.lib and wfapi64.dll are needed if you intend to develop a genuine 64-bit application. If you do not intend to develop genuine 64-bit applications, you do not need to use the wfapi64.lib and wfapi64.dll files.

The WFAPI SDK has been upgraded to work with Microsoft Visual C++ Version 14.0. This SDK was built and tested with earlier versions of MS Visual Studio compilers (i.e. Visual Studio 8) for backward compatibility. Install Visual C++ before installing the WFAPI SDK.

Execution environment

Required hotfixes, service packs, and clients are available from http://www.citrix.com/support.

Directory layout

The following folders are created in the WFAPI SDK installation directory:

• DOCS – WFAPI SDK guide and readme

• EXAMPLES – C examples

• INCLUDE – C header file Wfapi.h

• LIB – C library files Wfapi.lib (for 32-bit applications) and Wfapi64.lib (for 64-bit applications)

Install the WFAPI SDK

1. Download SDK.
2. Run WFApiSDK.msi.
3. Follow the installation dialogs. The default installation directory is %SystemDrive%\Program Files(x86)\Citrix\WFApiSDK.

Finding documentation

The Citrix Virtual Apps and Desktop Server WFAPI SDK Guide is automatically installed when you install the WFAPI SDK (default location: %[SystemDrive]{.SpellE}%\Program Files (x86)\Citrix\WfApiSDK\Docs). To open this document, double-click the Wfapi.pdf file.

Getting support

Citrix provides technical support primarily through the Citrix Solutions Network (CSN) channel partners. Contact your supplier for first-line support or use Citrix Online Technical Support to find the nearest CSN partner.

Citrix offers online technical support services on the Citrix Web site. The Support page includes links to downloads, the Citrix Knowledge Center, Citrix Consulting Services, and other useful support pages.

The Citrix Developer Center is the home for all technical resources and discussions involving the use of Citrix SDKs. You can find access to SDKs, sample code and scripts, extensions and plug-ins, and SDK documentation. Also included are the Citrix Developer Network forums, where technical discussions take place around each of the Citrix SDKs.

Uninstall the WFAPI SDK

Use the Add or Remove Programs utility in the Windows Control Panel.

Example rograms

The WFAPI SDK includes C example programs that demonstrate how to use the WFAPI functions.

There are two C example programs: TESTALL and SMCCONSOLE. Both ANSI (Testall.exe) and Unicode (Testallw.exe and SmcConsole.exe) versions of the programs are supplied with each located in its own sub-directory. The makefile that is supplied with the example programs builds both the ANSI and Unicode versions of the executables. The Unicode version is made by defining the Unicode macros. You may modify these makefiles for your system as needed.

These example programs are written to run on 32-bit machines. To run these examples on a 64-bit machine, modify the makefiles so they link to wfapi64.lib instead of wfapi.lib.

The Testall and SMCConsole sample programs have been tested for use with Servers running RDS VDAs and Workstations running WS VDAs.

C example Programs

The following instructions apply to Microsoft Visual Studio 2019. Adapt the instructions as needed for other environments.

To build the C example programs from a command prompt

1. If the INCLUDE and LIB environment variables are not set (type set at a command prompt to view them), open the developer command prompt by going to Start menu search for Visual Studio 2019 and then open x86 Native Tools Command Prompt for VS2019 or x64 Native Tools Command Prompt for VS2019 as administrator depending on the type of build you want.

2. Set the environment variables LIB and INCLUDE using the below commands.

3. Set LIB=%LIB%;C:\Program Files (x86)\Citrix\WfApiSDK\lib

4. Set INCLUDE=%INCLUDE%;C:\Program Files (x86)\Citrix\WfApiSDK\include;C:\Program Files (x86)\Citrix\WfApiSDK\lib

   Here C:\Program Files (x86)\Citrix\WfApiSDK is the path of the installed WfApi Sdk on your computer.

5. Run NMAKE on the desired directory.

Note: With the files as shipped, running NMAKE with no parameters doesn’t rebuild the source files. To force rebuilding all files, run NMAKE CLEAN ALL.

To build the C example programs from within Microsoft Visual Studio 2019

1. Create a new project.

   a. Open a new project. Select New from the File menu and select Project. Alternatively, press Ctrl+N or click New Project on the Start page.

   b. In the New Project window, select Visual C++ Projects in the left pane under Project Types.

   c. Select Empty Project under Templates in the right pane.

   d. Type a project name in the Name text box (for example, wfapi).

   e. Enter the location of the project in the Location box or browse to a location.

   f. Select Application Settings to display the application settings window and configure the project.

   g. Select an option under Application type.

   h. Select Empty Project under Additional options.

   i. Click Finish.

2. Add the source file (Testall.c) to the project.

   a. Select Add Existing Item from the Project menu or press Ctrl+Shift+D.

   b. In the Add Existing Item - wfapi window, enter a file name in the File name box. Alternatively, you can use the tool bar to find a file that you want to add.

   c. Select the file. Click Open.

3. Configure the build environment.

   a. Select Properties from theProject menu. The wfapi Property Pages window appears.

   b. Select All Configurations from the Configurations list. A tree of configuration settings appears in the left pane.

   c. Expand the C/C++ node.

   d. Select the General node.

   e. Enter the path for the Wfapi.h file in the Additional Include Directories box in the right pane.

   f. Expand the Linker node in the left pane.

   g. Select the General node.

   h. Select the Additional Library Directories box in the right pane. Enter the path for the Wfapi.lib/Wfapi64.lib file.

   i. Select Input tab and then in the Additional Dependencies, add the libraries ‘netapi32.lib’ and ‘wfapi.lib’ for 32 bit applications or ‘wfapi64.lib’ for 64-bit applications.

   j. Click OK.

4. To build the Unicode version:

   a. Select Properties from the Project menu.

   b. Select All Configurations from the Configurations list.

   c. Expand the C/C++ node on the left.

   d. Select the General category.

   e. In the Preprocessor Definitions text box, type /DUNICODE and /D_UNICODE.

5. Build the executable. Select Build Project from the Build menu, where Project is the name of your project (for example, wfapi).

TESTALL

This example program uses a text menu interface to call most of the WFAPI functions. To retrieve information, specify the user name, server, and domain. These values affect the results of the WFQueryUserConfig() and WFSetUserConfig() functions.