Citrix Server Software Development Kit

(1)

Citrix

Server Software

Development Kit

MFCOM Component

June 2002

Version 2.2

(2)

transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Citrix Systems, Inc.

Citrix, ICA (Independent Computing Architecture), MetaFrame, MetaFrame XP, MultiWin, and Program Neighborhood are trademarks of Citrix Systems, Inc. in the United States and other countries.

Microsoft, Windows, Windows NT, Windows CE, MS-DOS, and ActiveX are registered trademarks of Microsoft Corporation.

All other trademarks and registered trademarks are the property of their respective owners.

(3)

Welcome

This manual describes the MetaFrame Component Object Model (MFCOM) application programming interface of Version 2.2 of the Citrix Server Software Development Kit (CSSDK). The MFCOM functions enable application programs to perform tasks unique to MetaFrame XP servers. Appropriate hotfixes and service packs may be needed for MetaFrame XP 1.0 for functions defined here to execute properly.

What Is MFCOM?

MFCOM is a COM server that exposes some of the MetaFrame control and monitoring functions through the objects and interfaces defined in this COM server. MFCOM is a COM object that meets the requirements defined in the Microsoft Component Object Model Specification.

MFCOM is a COM server, not a COM client. MFCOM exposes objects that can be accessed from a COM client. See “MetaFrame Object Architecture” in Chapter 2 for detailed information about the objects exposed by MFCOM.

MFCOM is a free threading COM server and supports automation. It is also a DCOM server; that is, a COM client can remotely connect to a server that hosts MFCOM just as if MFCOM was running locally on the client's system. Binary type information is available from the MFCOM type library.

MFCOM runs on Windows NT 4.0 Terminal Server Edition or Windows 2000 as a Windows NT service. It can be controlled using the Windows service control panel.

Who Should Use MFCOM?

• Software developers writing their own value-add software based on the Citrix MetaFrame XP platform.

(10)

Because MFCOM supports DCOM, you can remotely manage your MetaFrame farm and servers by developing a MFCOM client running on any Windows system capable of running a DCOM client.

Documentation Conventions

Citrix documentation uses the following typographic conventions for menus, commands, keyboard keys, and items in the program interface:

Convention Meaning

Boldface Commands, names of interface items such as text boxes and option buttons, and user input.

Italics Placeholders for information or parameters that you provide. For example, filename in a procedure means you type the actual name of a file. Italics also are used for new terms and the titles of books.

UPPERCASE Keyboard keys, such as CTRL for the Control key and F2 for the function key that is labeled F2.

Monospace Text displayed at a command prompt or in a text file.

%SystemRoot% The Windows system directory, which can be WTSRV, WINNT, WINDOWS, or other name specified when Windows is installed.

{ braces } A series of items, one of which is required in command statements. For example, { yes | no } means you must type yes or no. Do not type the braces themselves.

[ brackets ] Optional items in command statements. For example, [/ping] means that you can type /ping with the command. Do not type the brackets themselves.

| (vertical bar) A separator between items in braces or brackets in command statements. For example, { /hold | /release | /delete } means you type /hold or

/release or /delete.

… (ellipsis) You can repeat the previous item or items in command statements. For example, /route:devicename[,…] means you can type additional devicenames separated by commas.

(11)

Finding Information About Citrix Products

Sources of information about Citrix products include: Release Notes

Contain the very latest information, such as last-minute features and application notes, additional utilities, and resources available to help you get the most out of your Citrix product.

Windows NT Messages Database

Explains error and system information messages. This database is provided in the Microsoft Windows NT Server Resource Kit.

Books Online

Contains the Citrix server documentation as an online help file. The WINFRAME

Books Online are accessed from the WinFrame Books Online icon in the

Main group of Program Manager. The MetaFrame Readme is accessed from the MetaFrame Books Online icon in the MetaFrame Tools folder on the

Start menu. Updates are available from the Citrix Web site (http://www.citrix.com/support).

Online Help

Provides context-sensitive, step-by-step instructions and reference information from within Citrix utility programs.

MetaFrame Administrator’s Guide

Provides information about the concepts behind MetaFrame, installation and configuration instructions, and descriptions of the applications and tools provided in the MetaFrame package.

Citrix ICA Client Administrator’s Guides

Provide information and procedures for installing and using the Citrix ICA Client programs that provide remote access to Citrix servers.

All Microsoft Terminal Server compatibility guidelines can be applied to Citrix MetaFrame. For Terminal Server compatibility information, see the following Microsoft resources:

• The Microsoft Web site, http://www.microsoft.com • Microsoft Technet

MetaFrame XP Documentation

(12)

The documentation included with MetaFrame XP is available in the DOC directory on the MetaFrame XP CD-ROM. Documentation for ICA Client software is available on the ICA Client CD-ROM.

On a MetaFrame XP server, documentation is installed in a Documentation folder. You can display the contents of this folder by choosing Programs > Citrix > Documentation from the Start menu.

The following documentation is included with MetaFrame XP in Adobe PDF format:

• The MetaFrame XP Administrator’s Guide provides conceptual information and procedures for system administrators who install, configure, and maintain MetaFrame XP for Windows. To get the most out of theguide, review the table of contents to familiarize yourself with the topics included in the book.

• The MetaFrame_XP_Readme.txt file contains last minute updates, corrections to the documentation, and a list of known problems. This file is in the root directory of the MetaFrame XP CD-ROM.

• The Citrix NFuse Administrator’s Guide tells administrators how to install, configure, and customize NFuse.

• The Citrix ICA Client Administrator’s Guides provide instructions for system administrators who deploy ICA Clients to end-users on various computing platforms.

The MetaFrame XP Administrator’s Guide is available in the following locations: • In the \Doc directory of your MetaFrame XP CD-ROM

• Installed in the Documentation folder of your MetaFrame XP server. From the

Start menu, choose Programs > Citrix > Documentation.

• On the Citrix Web site at http://www.citrix.com/support, select the Product Documentation tab. You can check the Product Documentation area of the Web site at any time for the latest updates to Citrix technical manuals. Any updates to this manual published after the release of this product will be posted there.

Using PDF Documentation

To use the MetaFrame XP and ICA Client documentation that is provided in PDF files, you need to have the Adobe Acrobat Reader program. The Reader program lets you view, search, and print the documentation files.

(13)

Citrix on the World Wide Web

The Citrix Web site, at http://www.citrix.com, offers a variety of information and services for Citrix customers and users. From the Citrix home page, you can access Citrix online Technical Support Services and other information designed to assist MetaFrame XP administrators, including the following:

• Citrix Product Documentation Library containing the latest documentation for all Citrix products (at http://www.citrix.com/support, select Product

Documentation)

• Downloadable Citrix ICA Clients (at http://www.citrix.com/download) • Program information about Citrix Preferred Support Services options • An FTP server containing the latest service packs, hotfixes, utilities, and

product literature for download

• An online Solution Knowledgebase containing an extensive collection of application notes, technical articles, troubleshooting tips, and white papers • Interactive online Solution Forums for discussion of technical issues with other

users

• Frequently Asked Questions pages with answers to common technical and troubleshooting questions

• Information about programs and courseware for Citrix training and certifications

• Contact information for Citrix headquarters, including worldwide, European, Asia Pacific and Japan headquarters

• The Citrix Developer Network (CDN) at http://www.citrix.com/cdn. This new, open enrollment membership program provides access to developer tool kits, technical information, and test programs, for software and hardware vendors, system integrators, ICA licensees, and corporate IT developers who incorporate Citrix server-based computing solutions into their products.

Providing Feedback About This Guide

We strive to provide accurate, clear, complete, and usable documentation for Citrix products. If you have any comments, corrections, or suggestions for improving our documentation, we want to hear from you.

(14)

Disclaimer

The software (the “Software Development Kit”) and accompanying documentation included or described in this document are provided to you, the licensed user, by Citrix Systems, Inc. (“Citrix”) pursuant to the terms of the attached Software Development Kit License Agreement and may only be used and copied in accordance with the express terms of the Software Development Kit License Agreement. The licensed user may use the Software Development Kit and accompanying documentation solely to develop applications that access or utilize the Citrix Server Software. The licensed user may make one (1) copy of the Software Development Kit in machine-readable form solely for backup purposes, provided that the licensed user reproduces all proprietary notices on the copy. The licensed user may not reproduce, copy, modify, transfer or transmit by any means, electronic, mechanical or otherwise, the Software Development Kit or

accompanying documentation, in whole or in part, or grant any rights in the Software Development Kit or accompanying documentation except as expressly provided in the Software Development Kit License Agreement.

The Software Development Kit, including all accompanying documentation contained herein, is provided “AS IS” and Citrix and its suppliers make and the licensed user receives no warranties or conditions, express, implied, statutory, or otherwise. Citrix has made reasonable efforts to ensure the completeness and accuracy of all information contained in this Software Development Kit.

(15)

Introduction

MFCOM allows you to write code to access most of the MetaFrame XP server monitoring and management functions. For most users, these functions are available from the Citrix-provided Citrix Management Console (CMC). The interface properties and methods exposed in the MFCOM objects give third party developers the necessary accessing points to write their own programs to monitor and manage their MetaFrame servers.

Not all the functions existing in the CMC are exposed by MFCOM. We have identified the functions that are needed by most users and software integrators and expose them in MFCOM.

MFCOM is a service. MFCOM is auto-started when a user accesses any application that uses the MFCOM service.

Using MFCOM

(16)

System Requirements

The MFCOM component of the Citrix Server SDK must be installed on a Windows NT 4.0 or Windows 2000 computer with sufficient disk space for the SDK

installation. Although the SDK does not need more than a few megabytes of disk space, third-party development tools such as Microsoft Visual C++ or Visual Basic may require a substantial amount of disk space. When considering system

requirements for using the SDK, plan to have enough disk space for all the necessary software components to install and function properly.

Installation

Mfcom.exe is included in MetaFrame XP, Service Pack 2. This SDK, including documents, examples, and other information is available free of charge from the Citrix Developer Network’s Web site at http://www.citrix.com/cdn.

Directory Layout

• Bin.NET - Binaries compiled from the VisualStudio.NET example • CS - Examples written in C#

• CS\CSCMC - A simplified version of the Citrix Management Console written in C# and MFCOM; most of the object interfaces are exercised in this example • CS\LicTool - A handy license management tool that exercises the license

objects

• CS\PolicyAdm - A policy management tool • CS\PubApp - An application publishing utility • VB.NET - Examples written in Visual Basic 7

• VB.NET\FarmInfo - Example exercises some farm and session objects The following directories are created in the SDK installation directory: • DOCS - Contains this file (the MFCOM user’s manual)

• VB - Visual Basic examples

• VB\CINCOM - A comprehensive example that shows the usage of most of the exposed MFCOM objects and interfaces

• VB\EVENTS - Example to demonstrate how to receive MetaFrame server events using MFCOM

• VC - Visual C++ examples

(17)

• VC\CTXPING - An example that demonstrates the MetaFrame virtual channel object and interfaces; the Citrix Virtual Channel SDK is required for this example

• VC\FARM - An example that displays the farm name

• VC\GETAPP - A simple example that exercises some of the interfaces for accessing MetaFrame applications

• VC\INC - Directory that contains Mfcom.h • VC\LIB - Directory that contains Mfcom.lib

• VC\EVENTS - A multi-threaded Visual C++ program that demonstrates the usage of the MFCOM event interface properties and methods

• Utils - Directory that contains Mfreg.exe • Typelib - Directory that contains Mfcom.tlb

• Scripts - Simple Java and VB scripts using MFCOM

Execution Environment

The following list shows the requirements for the SDK to run properly on various Citrix server and client versions. The required hotfixes, service packs, and clients can be obtained from the Citrix Web site at http://www.citrix.com/support.

Citrix Product Requirements

ICA Clients Version 3.0 or higher

(18)

MFCOM Server and Client Configuration

Accessing an MFCOM Server

} To register MFCOM locally or remotely

• MFCOM is automatically registered and is ready to be used locally by any client code, including the SDK examples (provided MetaFrame XP for Windows, Service Pack 2, is installed).

• To register MFCOM for remote access to an MFCOM server, use the utility Mfreg.exe provided with this SDK package. Run mfreg.exe servername from a command prompt, where servername is the name of the server on which MFCOM will be running. When registration is complete, no additional configuration is required to allow the client system to access the remote server.

Warning If you have a previous version of MFCOM registered using MFREG for that version, you must first unregister it before registering the new version of MFCOM. Run MFREG /u at a command prompt using the old version of MFREG, then register the new MFCOM using the new MFREG

Important Before running Mfreg.exe, copy it from the Utils directory on the CSSDK CD to the %SystemRoot%\System32 folder.

You cannot register MFCOM locally and remotely simultaneously. If you want to change registration from local to remote or from remote to local, you must unregister the service.

} Unregistering your MFCOM server

• Type mfcom.exe /UnRegServer at a command prompt to remove current registration from a local server

• Type mfreg.exe /u at a command prompt to remove current registration from a remote server

Ensure the SNMP agents are enabled from the MFCOM-based Citrix Management Console if SNMP service is installed and started on the XP servers.

(19)

DCOM

The tool used to configure DCOM is Dcomcnfg.exe. For more information about using Dcomcnfg.exe, see the MSDN Web site.

There are many ways to configure DCOM. For more information about configuring DCOM, see Microsoft’s documentation.

DCOM Quick Start

Use the following procedure to configure MFCOM to specify MFCOM launch permissions for users:

1. Run Dcomcnfg.exe at a command prompt.

2. Click the Edit Default button under Default Launch Permissions. Change the

Type of Access by selecting Allow Launch from the drop-down box for the users who will need MFCOM object launching ability.

3. Click the Edit Default button under Default ConfigurationPermissions. Change the Type of Access by selecting Full Control from the drop-down box for the users who will need full control access.

4. Click the Default Properties tab. Under Default Impersonation Level,select

Impersonate from the drop-down list. Click OK to save this setting.

After you have properly configured your server, the users you have authorized will be able to access MFCOM.

(20)

MetaFrame Object Architecture

MetaFrame Farm Objects

In the MetaFrame XP environment, the top-most manageable object is a farm. A farm contains servers, applications, and other objects.

Objects exposed by MFCOM: • Farm

• Server • Application • Session

• License

• Account Authority • User

• Group • Process

• Virtual Channel • Zone

• Folder • License Set • License Number • Policy

• Printer • Printer Driver

• Printer Driver Mapping • Client Printers

(21)

Collection objects are returned by the enumeration calls provided by many MFCOM objects:

• Servers • Applications • Sessions

• Licenses

• Account Authorities • Users

• Groups • Processes • License Sets • License Numbers • Policies

• Printers • Printer Drivers

(22)

Special objects used to allow easier access to C++-like structures: • Time

• Client Module

• Application/Server Binding • Event Queue

• Credential

Note The folder object is used to organize servers and applications in tree structures, as well as organize account authorities that store user accounts in tree structures. Therefore, folder objects are further classified as server, application, and account folders. Server folder objects contain servers and other server folders. An

application folder contains applications and other application folders. An account folder contains user accounts and other account folders.

MetaFrame Object Properties And Methods

Objects exposed by MFCOM:

Farm Object

The farm object has the following properties:

Windows farm objects have the following properties:

Farm name (read-only)

Farm type (read-only)

Get license strings (read-only)

Get Windows farm interface pointer (read-only)

(23)

Session degradation bias (read/write) Enable SNMP Agent for session monitoring (read/write) Is current session user a Citrix administrator (read-only)

File types (read-only)

Enable auto client reconnect (read/write) Log auto client reconnect attempts (read/write) Enable DNS address resolution (read/write) NDS preferred tree (read/write) Per user connection limit (read/write) Log over the limit connection denials (read/write) Current user administrative privileges (read-only) Current user administrative privilege type (read-only) Enumerate policies in the farm (read-only) Enable auto created client printers on logon (read/write) Update auto created network printer properties on logon (read/write) Inherit auto created client printer settings for pending

jobs

(read/write)

Delete auto created client printer pending jobs on log off (read/write) Auto created client printer device setting (read/write) Auto created client printer device driver (read/write) Import network printers (method) Update network printers (method) Discard network printers (method) Auto replicated print drivers (read-only) Printer driver mappings for client printers (read-only) Auto created client printers for DOS and Windows CE

clients

(24)

SNMP Session Traps include:

The farm object supports enumeration of the following objects: • Servers

• Applications • Licenses • Sessions

• Account Authorities • Zones

• License Numbers • License Sets • Printers • Printer Drivers

The farm object supports the instantiation of the following objects: • Servers

• Applications • Licenses • Sessions

• Account Authorities • Zones

The farm object has the following methods: • Initialize

• Create an event queue • Add a new license • Publish a new application

Session logon Session logoff Session disconnect

(25)

• Return a special session collection object for logging off and disconnecting sessions more efficiently

Zone Object

The zone object has the following property:

The zone object supports enumeration of the following objects: • Servers in the zone

• Online servers in the zone

The zone object has the following method: • Initialize

Server Object

The server object supports many properties. To see all the server object properties, see the Visual Basic example, Cincom. Some of the server object properties include:

Zone Name (read-only)

Zone Data Collector (read-only)

Server name (read-only)

Server type (read-only)

Zone name (read-only)

Zone ranking (read/write)

IP address (read-only)

Parent server folder (read/write)

Application-specific properties (read-only)

(26)

Windows server objects have the following properties:

TCP addresses (read-only)

IPX addresses (read-only)

NETBIOS address (read-only)

MetaFrame product code (read-only)

MetaFrame product name (read-only)

MetaFrame major and minor version numbers (read-only)

MetaFrame build number (read-only)

MetaFrame service pack information (read-only)

Windows NT major and minor version (read-only)

User farm’s ICA display settings (read/write)

Discard redundant graphics operations (read/write)

Use alternate caching method (read/write)

Supports legacy ICA display protocol (read/write)

ICA video buffer size (read/write)

ICA graphics degradation bias (read/write)

Notify user of ICA display degradation (read/write)

Use farm-wide SNMP settings (read/write)

Enable SNMP agent (read/write)

Enable SNMP session logon trap (read/write)

Enable SNMP session logoff trap (read/write)

Enable SNMP session disconnect trap (read/write)

Enable SNMP session threshold exceeded trap (read/write)

SNMP session threshold value (read/write)

Allow ICA browser listener on the UDP network (read/write)

Allow ICA browser listener on the IPX network (read/write)

Allow ICA browser listener on the NETBIOS network (read/write)

Respond to ICA client broadcast messages (read/write)

Enable logons to this server (read/write)

(27)

The server object supports enumeration of the following objects: • Sessions on the server

• Processes on the server

• Applications that are published on the server • Account authorities trusted by the server • Licenses assigned to or used by the server • Printers

• Printer Drivers

• Custom session collection for logging off and disconnecting sessions The server object supports instantiation of the following objects: • Session

• Process

The server object has the following methods: • Initialize

MetaFrame installation date (read-only)

MetaFrame Feature Release level (read/write)

Is shadowing console allowed? (read-only)

Installed hotfix count (read-only)

Installed hotfixes (read-only)

Use farm’s auto client reconnect setting (read/write)

Enable auto client reconnect (read/write)

Log auto client reconnect attempts (read/write)

NFuse XML service TCP/IP port number (read/write)

Printer virtual channel bandwith (read/write)

Load management system server load value (read-only)

(28)

Application Object

The application object supports the following properties:

The Windows application object supports the following properties:

Application name (read/write)

Application type (read-only)

Application distinguished name (read-only)

Application version (read-only)

Description (read/write)

Parent folder distinguished name (read/write)

Application enabled (read/write)

Server specific properties (read-only)

Get Windows application interface pointer (read-only)

Application name (read/write)

Application version (read-only)

Description (read/write)

Parent folder distinguished name (read/write)

Application enabled (read/write)

Server-specific properties (read-only)

Default encryption (read/write)

Default working directory (read/write)

Default initial program (read/write)

Default sound type (read/write)

Default window color (read/write)

Default window type (read/write)

Default window width (read/write)

Default window scale (read/write)

(29)

The application content object supports the following properties

The application object supports enumeration of the following objects: • Servers where the application is published

Desktop integrate flags (read/write)

MetaFrame publishing attributes (read/write)

Other publishing flags (read/write)

Program Neighborhood publishing flags (read/write)

Read-only flag (read/write)

Program Neighborhood folder (read/write)

CPU Priority level (read/write)

Application instance limit (read/write)

Allow multiple instances per user (read/write)

Enable SSL connections (read/write)

Application start menu folder (read/write)

File types associated with this application (read-only)

Add a file type to associate with this application (method)

Remove a file type to associate with this application (method)

Content name (read/write)

Content distinguished name (read-only)

Content publishing data version (read-only)

Content description (read/write)

Content parent folder distinguished name (read/write)

Enable content (read/write)

Content address (location) (read/write)

Add content to Start menu (read/write)

Add shortcut to client desktop (read/write)

Allow anonymous connections (read/write)

Program Neighborhood folder (read/write)

(30)

• Users who have permission to run the application • Sessions on which the application is running • Groups who have permission to run the application The application object supports the following methods: • Initialize

• Add a server to the application • Add a user to the application

• Remove a server from the application • Remove all servers from the application • Remove all users from the application • Remove a user from the application

• Load application data from persistent storage • Save data to the persistent storage

• Validate application settings

• Delete the application from persistent storage

Windows application objects support the following methods: • Add a server to the application

• Add a user to the application

• Remove a server from the application • Remove a user from the application • Remove all servers

• Remove all users

• Load application data from persistent storage • Save data to the persistent storage

• Validate application settings

• Delete the application from persistent storage • Read application icon from a file

(31)

Application content objects support the following methods: • Add a user to the published content

• Remove a user from the published content • Load content data from the persistent store • Save data to the persistent store

• Validate the content publishing setting • Delete the content from the persistent store • Read content icon from a file

• Write content icon to a file

Account Authority Object

The account authority object supports the following properties:

The account authority object supports enumeration of the following objects: • Users with the account authority

• Servers in the farm that trust the account authority • Groups with the account authority

• Folders (to display ADS/NDS notes in tree structure) The account authority object supports the following method: • Initialize

Session Object

The session object supports the following properties:

Account authority type (read-only)

Account authority name (read-only)

Credential (used to access this account authority) (read/write)

Session ID (read-only)

Server name on which the session resides (read-only)

Name of user owning the session (read-only)

(32)

Account authority type of the user (read-only)

Session name (read-only)

Session state (read-only)

Session connect time (read-only)

Session logon time (read-only)

Session last input time (read-only)

Session disconnect time (read-only)

Current time (read-only)

Client ICA buffer length (read-only)

Client name (read-only)

Client build (read-only)

Client directory (read-only)

Client product ID (read-only)

Client hardware ID (read-only)

Client address family (read-only)

Client address (read-only)

Client display horizontal resolution (read-only)

Client display vertical resolution (read-only)

Client display color depth (read-only)

Client ICA display cache sizes for small objects (read-only)

Client ICA display cache sizes for low/virtual memory (read-only)

Client ICA display cache sizes for XMS memory (read-only)

Client ICA display disk cache size (read-only)

Client ICA display persistent cache size (read-only)

Client ICA display persistent cache minimum bitmap size (read-only)

Client ICA display persistent cache version (read-only)

Client modem name (read-only)

Connection encryption level (read-only)

Client license (read-only)

(33)

The session object supports enumeration of the following objects: • Processes for the session

• Virtual channels for the session • Applications sharing the session

The session object supports instantiation of the following objects: • Process

• Virtual channel

The session object supports the following methods: • Initialize

• Disconnect this session • Logoff this session

• Send a message to another session

Process Object

The process object supports the following properties:

Application name (for seamless sessions) (read-only)

Client product ID Value (read-only)

Client ID (can be used to identify the client) (read-only)

Process ID (read-only)

Process name (read-only)

User name (read-only)

Process state (read-only)

(34)

The Windows process object supports the following properties:

The process object supports the following methods: • Initialize

• Terminate process

Process ID (read-only)

Process name (read-only)

Process state (read-only)

Process creation time (read-only)

Process user time (read-only)

Process kernel time (read-only)

Process base priority (read-only)

Process peak virtual size (read-only)

Process current virtual size (read-only)

Process page fault count (read-only)

Process peak working set size (read-only)

Process current working set size (read-only)

Process peak paged pool usage quota (read-only)

Process current paged pool usage quota (read-only)

Process peak non-paged pool usage quota (read-only)

Process paged file usage (read-only)

(35)

User Object

The user object supports the following properties:

The user object supports enumeration of the following objects: • Groups that included the user

• Applications that a user has access to The user object supports the following method: • Initialize

Group Object

The group object supports the following properties:

User account type (read-only)

Policy associated with the user (read-only)

Allowed policies applied to the user (read-only)

User distinguished name (similar to application distinguished name)

(read-only)

Parent folder distinguished name (read-only)

Full name (dot-separated inverse representation of the user distinguished name)

(read-only)

Auto created printers (read-only)

Group name (read-only)

Group account type (read-only)

Policy associated with the group (read-only)

Allowed policies applied to the group (read-only)

(36)

The group object supports enumeration of the following objects: • Users that are included into the group

• Groups that are included into the group

• Applications that are available for members of the group The group object supports the following method:

• Initialize

Virtual Channel Object

The virtual channel object supports the following properties:

The virtual channel object supports the following methods: • Initialize

• Read client data

• Read virtual channel data • Write virtual channel data

• Purge virtual channel input/output buffer

License Object

The licence object contains the following properties:

Virtual channel name (read-only)

License ID (read-only)

License group (type) (read-only)

License number (read-only)

License description (read-only)

License status (read-only)

Grace days before activation (read-only)

User count (read-only)

(37)

The license object supports enumeration of the following object: • Servers that are using or assigned the license

The license object supports the following methods: • Initialize

• Activate this license. • Remove this license.

License Set Object

The license set object, together with the license number object, makes the license object obsolete.

The license set object contains the following properties:

The license set object supports the enumeration of the following objects: • License numbers (contributing to the license set)

• Servers assigned licenses from this set

The license set object supports the following methods: • Initialize the license set object

• Assign licenses to a server

Pooled count available (read-only)

Assigned count (read-only)

Assigned in use (read-only)

License ID (read-only)

License class (connection license or product license) (read-only)

License name (read-only)

Grace days before activation (read-only)

Total license count (read-only)

Pooled licenses in use (read-only)

Pooled licenses available (read-only)

(38)

License Number Object

The license number object, together with the license set object, makes the license object obsolete.

The license number object contains the following properties:

The license number object supports the following object: • License sets to which this license number can contribute The license number object supports the following methods: • Initialize the license number object

• Remove the license number • Activate the license number

License number (read-only)

License class (connection license or product license) (read-only)

License description (read-only)

(39)

Policy Object

The policy object contains the following properties:

The policy object supports the following method: • Initialize the object

The user policy object supports the following additional properties:

Policy name (read/write)

Policy description (read/write)

Policy priority (read/write)

Policy enabled (read/write)

Policy type (read-only)

User policy object (read-only)

Disable client drive mapping (read/write)

Disable client floppy drive mapping (read/write)

Disable client hard drive mapping (read/write)

Disable client network drive mapping (read/write)

Disable client printer mapping (read/write)

Disable client parallel port mapping (read/write)

Disable client serial port mapping (read/write)

Disable client clipboard mapping (read/write)

Disable client audio mapping (read/write)

Disable OEM virtual channels (read/write)

Connect client drives at logon (read/write)

Connect client printers at logon (read/write)

Default to main client printer (read/write)

Client security requirement (read/write)

Client security requirement list (read/write)

Disable auto client update (read/write)

Limit number of concurrent logon sessions (read/write)

(40)

The user policy object supports the following methods:

• Modify a user (add and remove from the allowed/denied list) • Modify a group (add and remove from the allowed/denied list) • Remove all users and groups in the policy

Printer Object

The printer object supports the following properties:

Limit on printer bandwith (read/write)

Printer bandwith limit (read/write)

Use local time of client (read/write)

Disable client local time estimation (read/write)

Configure shadowers (read/write)

Users allowed to shadow (other users) (read/write)

Groups allowed to shadow (other users) (read/write)

Users not allowed to shadow (other users) (read/write)

Groups not allowed to shadow (other users) (read/write)

Policy allowed user list (read-only)

Policy allowed group list (read-only)

Policy denied user list (read-only)

Policy denied group list (read-only)

Printer name (read-only)

Printer type (read-only)

Driver name (read-only)

Driver platform (read-only

Paper size (read/write)

Paper width (read/write)

Paper height (read/write)

(41)

The printer object supports the following methods: • Initialize printer object

• Save print preferences

Printer Driver Object

The printer driver object supports the following properties:

The printer driver object supports the following method: • Unitize the printer driver object

Printer Driver Mapping Object

The printer driving mapping object supports the following properties:

The printer driver mapping method supports the following methods: • Save the printer driver mapping

• Delete the printer driver mapping

Print quality (read/write)

Paper orientation (read/write)

Collated (read/write)

User list of auto created printer (read-only)

Group list of auto created printer (read-only)

Driver name (read-only)

Driver platform (read-only)

Servers on which the driver is installed (read-only)

Server driver name (read/write)

Server driver platform (read/write)

(42)

Client Printer Object

This object is used to specify auto created client printers for the Windows CE and DOS clients. The client printer object has the following properties:

The client printer object supports the following methods: • Save auto created client printer

• Delete auto created client printer

Folder Object

The folder object contains the following properties:

The folder object supports enumeration of the following object: • Folders that are subfolders for the folder

The application folder object supports enumeration of the following object: • Applications that are published into the application folder

The server folder object supports enumeration of the following object: • Servers that are included into the server folder

Client name (read/write)

Client printer name (read/write)

Client printer driver name (read/write)

Client printer port type (read/write)

Client printer port number (read/write)

Auto creation status (read-only)

Folder type (read-only)

Folder name (read/write)

Folder distinguished name (read-only)

Get application folder interface pointer (read-only)

Get server folder interface pointer (read-only)

(43)

The account folder object supports enumeration of the following object: • Nodes of account authority (the nodes are considered as subfolders for the

account authority root folder)

The folder object supports the following methods: • Initialize

• Initialize application folder • Initialize server folder • Initialize account folder • Get subfolder interface pointer • Delete

• Move

• Create subfolder (excluding account folders)

The application folder object supports the following methods: • Get interface pointer to specific application object • Move specific application to another application folder The server folder object supports the following methods: • Get interface pointer to specific server object • Move specific server to another server folder

The account folder object supports the following method:

• Get interface pointer to an object of a user in the current folder

Collection Objects

MFCOM supports collections of all farm objects except the farm object itself, which is the top level object.

(44)

Custom Session Collection Object

The custom session object is MetaFrameMySession. Its collection object is

MetaFrameMySessions, which supports the following property:

The custom session object supports the following methods: • Add a custom session object to the collection

• Remove a custom session object from the collection • Remove object at a specified location

• Remove all objects in the collection

• Logoff all sessions specified by the objects in the collection • Disconnect all sessions specified by the objects in the collection

Custom Server Collection Object

The custom server collection object supports the following properties:

The custom server collection object supports the following methods: • Add a custom server object to the collection

• Remove a custom server object from the collection • Remove object at a specified location

• Remove all objects in the collection

• Apply smart card settings stored in each custom server object to the servers in the collection

• Query smart card settings stored in each custom server object from the servers in the collection

Count (number of objects in the collection) (read-only)

_NewEnum (start a new enumeration) (read-only)

Count (number of objects in a collection) (read-only)

Item (get a specific object at a location) (read-only)

(45)

String Collection Object

The MetaFrameMultiString object is a collection object of strings. This object supports the following properties:

This object supports the following methods: • Add a string to the collection

• Remove a string from the collection • Remove a string at a specified location • Remove all strings in the collection

Auxiliary Objects

MFCOM exposes the following special objects to aid in the access of some of the information returned by MFCOM interface methods.

Time Object

The time object supports the following properties:

_NewEnum (start a new enumeration) (read-only)

Count (number of objects in a collection) (read-only)

Item (get a specific object at a location) (read-only)

InList (test if an object is already in collection) (read-only)

Time type, Local or GMT (read/write)

Year of the time (read-only)

Month of the time (read-only)

Day of the time (read-only)

Day of the week (read-only)

Hour of the time (read-only)

Minute of the time (read-only)

(46)

Client Module Object

The client module object supports the following properties:

Application/Server Binding Object

The application/server binding object supports the following properties:

The application/server binding object supports the following method: • Initialize

Event Queue

The event queue object supports the following properties:

The event queue object supports the following methods: • Add event

Millisecond of the time (read-only)

Low part of the 64-bit time (read-only)

High part of the 64-bit time (read-only)

Client module file name (read-only)

Client module file last modified date (read-only)

Client module file size (read-only)

Client module file version (read-only)

Server type (read-only)

Initial command line (read/write)

Working directory (read/write)

Number of events in the queue (read-only)

First event in the queue (read-only)

(47)

• Remove event • Wait for event

• Get last object for event • Delete the event queue

User Credential Object

The user credential object is used to store the credential information required by various MFCOM calls that need such information. The user credential object supports the following properties:

The user credential object supports the following methods: • Initialize user credential object

SmartCard Setting Object

The SmartCard setting object is used to store information about configuring SmartCard on a MetaFrame server. It supports the following properties:

Custom Server Object

The MetaFrameMyServer object supports the following properties:

User Name (read/write)

User account type (read/write)

Account authority name (read/write)

Account authority type (read/write)

Password (write-only)

EnableLogon (Enable SmartCard logon) (read/write)

ProcessList (Processes that are SmartCard enabled) (read/write)

Server name (read/write)

Use farm’s SmartCard setting (read/write)

(48)

Determining the Citrix Server Version

If the Citrix server is a MetaFrame XP server, use the MFCOM server object interfaces to get the version information. If the Citrix server is not a MetaFrame XP server, the Citrix server version information is stored in predefined registry entries. The following is a sample output of the Citrix MetaFrame XP version information. Actual values may differ.

Citrix Product Version

MetaFrame XP 1.0 for Windows Terminal Server

Major 2, Minor 10, Build 1045

MetaFrame XP 1.0 for Windows 2000

(49)

Language Reference

This chapter presents the calling conventions of the MFCOM functions in Visual Basic 6.0, Visual Basic 7.0, C++, and C# syntax.

Organization Of This Chapter

This chapter begins with a brief introduction of MFCOM programming issues that apply to all languages. Next, issues that apply to an object are described under the heading of the interface, but before the method and property descriptions for the interface.

Function specification for C++, Visual Basic, and C# are all described together. While the use of MFCOM functions are not limited to these languages, the syntax for similar languages are often similar to those included here.

The term function is used here to refer to an object’s property or method from the C++ implementation perspective. Properties and methods are used when it is necessary to identify the category of a function or when objects are described from a COM (object-oriented) perspective.

Many interfaces have multiple versions; typically, an interface named

IMetaFrameXxx has the follow-up versions named IMetaFrameXxx2,

IMetaFrameXxx3, and so on. All versions of later MFCOM interfaces inherit from the previous interfaces. Only the functions that are new in a new version of an interface are listed in the section that describes the interface.

(50)

MetaFrameFarm Object

The MetaFrameFarm object supports functions that allow the callers to access and manage Citrix farm settings. Most of the properties defined in this object are available through the farm property page of the Citrix Management Console (CMC).

This object exposes functions for enumerating application, server, account

authority, session, zone, and license objects. In addition, it supports enumeration of server folders and application folders.

Functions are supported that create application, server, account authority, session, zone, and license objects, as well as server and application folder objects.

The interfaces supported by this object are: • IMetaFrameFarm

• IMetaFrameFarm2 • IMetaFrameFarm3 • IMetaFameWinFarm • IMetaFrameWinFarm2 • IMetaFrameWinFarm3

The default interface for the MetaFrameFarm object is IMetaFrameFarm2.

IMetaFrameFarm Interface

(51)

Initialize

Initialize the farm object.

C++ Syntax

Public: HRESULT Initialize( MetaFrameObjectType FarmType );

where

FarmType

Must be MetaFrameWinFarmObject.

Visual Basic Syntax

Public Sub Initialize (ByVal FarmType As MetaFrameObjectType)

C# Syntax

public void Initialize(

MetaFrameObjectType FarmType );

Remarks

Only the Windows farm type is supported. For more information about

(52)

FarmName

The name of the farm.

C++ Syntax

Public: HRESULT get_FarmName( BSTR* name

);

where

name

The address of a variable that will receive the name of the farm.

Visual Basic Syntax

Public Property FarmName As String

C# Syntax

public string FarmName {get;}

Remarks

(53)

FarmType

The type of the farm object.

C++ Syntax

Public: HRESULT get_FarmType( MetaFrameObjectType* type

);

where

type

Pointer to a variable that will receive the type of the farm object.

Visual Basic Syntax

Public Property FarmType As MetaFrameObjectType

C# Syntax

public MetaFrameObjectType FarmType {get;}

Remarks

(54)

Zones

Return an enumerator object that supports the IMetaFrameZones interface. Use this object to enumerate the MetaFrameZone objects.

C++ Syntax

Public: HRESULT get_Zones( IMetaFrameZones** pZones

);

where

pZones

The address of a variable that will receive the pointer to the zone collection object.

Visual Basic Syntax

Public Property Zones As IMetaFrameZones

C# Syntax

public IMetaFrameZones Zones {get;}

Remarks

(55)

Applications

Return an enumerator object that supports the IMetaFrameApplications

interface. Use this object to enumerate the MetaFrameApplication objects.

C++ Syntax

Public: HRESULT get_Applications( IMetaFrameApplications** pApps );

where

pApps

Pointer of a variable that will receive the pointer to the application collection object.

Visual Basic Syntax

Public Property Applications As IMetaFrameApplications

C# Syntax

public IMetaFrameApplications Applications {get;}

Remarks

This call returns a pointer to an enumerator object that can be used to enumerate all the published applications in the farm regardless of the application hierarchy, as displayed in Citrix Management Console.

(56)

Servers

Return an enumerator object that supports the IMetaFrameServers interface. Use this object to enumerate the MetaFrameServer objects.

C++ Syntax

Public: HRESULT get_Servers( IMetaFrameServers** pServers

);

where

pServers

The address of a variable that will receive the pointer to the server collection object.

Visual Basic Syntax

Public Property Servers As IMetaFrameServers

C# Syntax

public IMetaFrameServers Servers {get;}

Remarks

This call returns an enumerator object that can be used to enumerate all the servers in the farm regardless of the hierarchy as displayed in the Citrix Management Console for servers.

(57)

Licenses

Return an enumerator object that supports the IMetaFrameLicenses interface. Use this object to enumerate the MetaFrameLicense objects.

C++ Syntax

Public: HRESULT get_Licenses( MetaFrameLicenseGroup Group, IMetaFrameLicenses** pLicenses

);

where

Group

Type of the licenses to enumerate.

pLicenses

The license collection object.

Visual Basic Syntax

Public Property Licenses As IMetaFrameLicenses

C# Syntax

public IMetaFrameLicenses get_Licenses( MetaFrameLicenseGroup Group

);

Remarks

This call returns an enumerator object that can be used to enumerate all farm licenses, product licenses, or connection licenses.

For more information about using this object, see the IMetaFrameLicenses: License collection interface and Appendix A for more information about

MetaFrameLicenseGroup.

(58)

AccountAuthorities

Return an enumerator object that supports the IMetaFrameAcctAuths interface. Use this object to enumerate the MetaFrameAcctAuth objects.

C++ Syntax

Public: HRESULT get_AccountAuthorities( IMetaFrameAcctAuths** pAAs

);

where

pAAs

The address of a variable that will receive the pointer to the account authority collection object.

Visual Basic Syntax

Public Property AccountAuthorities As IMetaFrameAccountAuthorities

C# Syntax

public IMetaFrameAcctAuths AccountAuthorities {get;}

Remarks

This call returns an enumerator object that can be used to enumerate all the account authorities trusted by the servers in the farm.

The trust relationship among servers and account authorities can be complicated. The result returned by this enumeration contains all the account authorities trusted by all the servers in the farm. There may be conflicts among the trust relationships that may cause the enumerator to fail to return any results.

(59)

Sessions

Return an enumerator object that supports the IMetaFrameSessions interface. Use this object to enumerate the MetaFrameSession objects.

C++ Syntax

Public: HRESULT get_Sessions( IMetaFrameSessions** pSessions

);

where

pSessions

The address of a variable that will receive the pointer to the session collection object.

Visual Basic Syntax

Public Property Sessions As IMetaFrameSessions

C# Syntax

public IMetaFrameSessions Sessions {get;}

Remarks

This call returns an enumerator object that can be used to enumerate all the sessions on all the servers in the farm. For a large farm consisting of many servers and numerous sessions running on the servers, this enumeration result can be very large. The system that is running MFCOM must have sufficient memory for the session objects. An alternative is to use the session enumeration call for a server to get the sessions running on a particular server.

(60)

LicenseStrings

Return an array of license strings.

C++ Syntax

Public: HRESULT get_LicenseStrings( MetaFrameLicenseGroup Group, SAFEARRAY** IDList

);

where

Group

Specifies the type of the licenses to request.

IDList

The address of a variable that will receive the pointer to the license string array.

Visual Basic Syntax

Public Property LicenseStrings (ByVal Group As MetaFrameLicenseGroup) As String()

C# Syntax

public System.Array get_LicenseStrings( MetaFrameLicenseGroup Group

);

Remarks

This call returns an array of strings of which each contains a license string as displayed in the Citrix Management Console. This call can return the license strings for all the licenses, connection licenses, or product licenses.

(61)

WinFarmObject

Return an enumerator object that supports the IMetaFrameWinFarm interface.

C++ Syntax

Public: HRESULT get_WinFarmObject( IMetaFrameWinFarm** pObj

);

where

pObj

The address of a variable that will receive the pointer to the IMetaFrameWinFarm interface of the current object.

Visual Basic Syntax

Public Property WinFarmObject As IMetaFrameWinFarm

C# Syntax

public IMetaFrameWinFarm WinFarmObject {get;}

Remarks

Use this call to get a pointer to the IMetaFrameWinFarm interface, which can be

further used to call the functions supported by that interface. This function is primarily used by Visual Basic clients because they can’t call QueryInterface to

get the interface pointer. So, as an alternative, a C++ client can call

QueryInterface on the farm object pointer to get the interface pointer for the IMetaFrameWinFarm interface.

(62)

GetZone

Create an initialized MetaFrameZone object for a given zone name.

C++ Syntax

Public: HRESULT GetZone( BSTR ZoneName,

IMetaFrameZone** pZone

);

where

ZoneName

Name of a zone.

pZone

The address of a variable that will receive the pointer to the zone interface.

Visual Basic Syntax

Public Property GetZone (ByVal ZoneName As String) As IMetaFrameZone

C# Syntax

public IMetaFrameZone GetZone( string zoneName

);

Remarks

(63)

GetLicense

Create an initialized MetaFrameLicense object for a given license ID.

C++ Syntax

Public: HRESULT GetLicense( BSTR LicenseID,

IMetaFrameLicense** pLicense );

where

LicenseID

License ID.

pLicense

The address of a variable that will receive the pointer to the license interface.

Visual Basic Syntax

Public Property GetLicense (ByVal LicenseID As String) As IMetaFrameLicense

C# Syntax

public MetaFrameLicense GetLicense( string LicenseID

);

Remarks

Use this call to create a license object. Use the farm object’s license enumeration call to get the license ID or use the MetaFrame XP clicense utility to obtain the license ID.

(64)

GetAccountAuthority

Create an initialized MetaFrameAccountAuthority object.

C++ Syntax

Public: HRESULT GetAccountAuthority( MFAccountAuthorityType AAType, BSTR AAInstance,

IMetaFrameAccountAuthority** pAcctAuth

);

where

AAType

Account authority type.

AAInstance

Name of an account authority.

pAcctAuth

The address of a variable that will receive the pointer to the account authority interface.

Visual Basic Syntax

Public Property GetAccountAuthority (ByVal AAType As MFAccountAuthorityType, ByVal AAInstance As String) As IMetaFrameAccountAuthority

C# Syntax

public IMetaFrameAccountAuthority GetAccountAuthority( MFAccountAuthorityType AAType,

string AAInstance );

Remarks

Citrix Server Software Development Kit

Citrix

Contents

Chapter 1 Welcome . . . 9

Chapter 3 Language Reference . . . 49

Chapter 4 Example Programs. . . 681

Appendix A Type Definitions . . . 717

Appendix B GUIDs and Registry Entries . . . 737

Welcome

Who Should Use MFCOM?

Convention Meaning

/release or /delete.

Finding Information About Citrix Products

MetaFrame XP Documentation

Using PDF Documentation

Providing Feedback About This Guide

Introduction

System Requirements

Directory Layout

Execution Environment

Citrix Product Requirements

MFCOM Server and Client Configuration

DCOM Quick Start

MetaFrame Object Architecture

MetaFrame Object Properties And Methods

Zone Object

Application Object

Account Authority Object

Session Object

Process Object

User Object

Virtual Channel Object

License Set Object

License Number Object

Policy Object

Printer Object

Printer Driver Object

Client Printer Object

Collection Objects

Custom Server Collection Object

String Collection Object

Time Object

Client Module Object

User Credential Object

Custom Server Object

Citrix Product Version

Language Reference

MetaFrameFarm Object

IMetaFrameFarm Interface

FarmName

Remarks

Remarks

Visual Basic Syntax

Visual Basic Syntax

Servers

Visual Basic Syntax

C++ Syntax

Remarks

C++ Syntax

Remarks

C++ Syntax

LicenseStrings

Visual Basic Syntax

WinFarmObject

C# Syntax

GetZone

C# Syntax

Visual Basic Syntax

Visual Basic Syntax