Receiver (Windows)

API Reference
Metadata Files
Download Libraries
Integration

Installer Metadata Files

Introduction

In order to help Citrix Receiver (and Citrix Receiver admins) configure the system for unattended install & ensure the appropriate set of installs (ie no unnecessary or conflicting installs) extra information is needed about the actual installers. To achieve this, every plug-in installer requires an associated XML metadata file which contains the information below. Schema for the MetaData can be found below.

Words in monospace below are references to schema element or attribute names. Note that schema element & attribute names are case sensitive.

It is strongly recommended that when preparing or changing a Metadata file that you validate it against the schema document. A file that is not valid, according to the schema, will not successfully upload into Citrix Receiver. There are many schema validation tools available for download.

All metadata files start with a header section that references the XML standards & schema used. This will be as follows:

<?xml version="1.0" ?>
<metadata
  xmlns="http://www.citrix.com/AppReceiver"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.citrix.com/AppReceiver MetaData.xsd">

This is followed by one or more plug-in entries. An installer can potentially contain multiple plug-ins. If this is the case then there should be multiple plug-in elements in the metadata file. Ideally the plug-ins will install separately.

Attributes and Elements

Citrix Receiver Version Annotations

Some items below are marked with CR1.1 or CR2.0. This notation indicates that this item was introduced in a specific version of Citrix Receiver to support new functionality and should not be used for Metadata files deployed to earlier versions of Citrix Receiver Merchandising Servers.

Each plug-in entry needs the following two mandatory attributes to be specified:

productName - This is the Product Name or friendly name of the plug-in that will be displayed within the Citrix Receiver system.

product - This is the GUID that uniquely identifies the particular plug-in within the Citrix Receiver system. The GUID used here should be used for all future releases of this plug-in. It must also match the GUID passed to the Citrix Receiver SDK ARRegister() API. The GUID should not be surrounded by curly braces {}.

Each plug-in element contains the following further elements:

version - The Product Version for the associated plug-in installer. This consists of (major / minor / build / custom) parts, being between 1 and 4 numeric entries, separated by dots. This should match the 'DisplayVersion' element of the plug-in once installed. Citrix Receiver will compare this information with any currently installed version of the product to determine whether an update is required. Mandatory element.

platforms - This specifies the list of platforms on which the installer is supported. The members of the list must come from the set specified within platformTypeList schema type. Mandatory element.

EULAlocation - If there is a fixed location where the EULA of the plug-in is available & you want the end user to be able to view it, populate this element with the appropriate URL. Optional element.

InstallerFilename This element should be set to the original filename envisioned when preparing the command line. Mandatory element.

READMElocation - Thus element should be set to a URL referencing the plug-in release README file (if available). If set, this will be made available as a link in the admin console. Optional element.CR1.1

installerTrueExitCodePath - Installer Alternative Exit Code location. Some executable meta-installers do not propagate the true exit code from the embedded installer out to be the exit code of the meta-installer. This element provides a means for Receiver to understand the true install state of running the installer. Set the element to be the full Registry path to a DWORD value created by your installer that contains the true exit code. HKLM paths only supported. Optional element. CR1.1

installerDetailExitMessagePath - Installer Alternative Exit Message location. Many installers contain Custom Actions that check some feature of the target machine and can cause the install to terminate if the conditions are not met. In this case, the only information that Receiver has about the installation failure is the installer exit code which normally corresponds to 'Fatal Installer Error'. To provide more useful information the installer can store a message providing more information about the failure in the Registry. The installerDetailExitMessagePath element is then set to the Registry path of this string. Receiver will pick up the message and include it in user and administrative logging to help diagnosis of the installation failure. Optional element. CR1.1

runningAllTheTime - Running all the time: provide an indicator whether it is normal that a plug-in is active & able to report status or is it OK that it may not be active all the time. Optional element. CR1.1

incompatiblePlugin - Incompatible Plugin: To cope with the case where multiple plugins perform the same role and should not be installed together. Would stop them being deployed together in same Delivery, or at least generate a warning. This is a list of guid entries. Optional element. CR1.1

deinstallPredecessorRange - DeInstallPredecessor ranges: If the plug-in installer can upgrade most, but not all previous versions then this element can automate the different handling. If the version of the currently installed plug-in is in the range specified then it's an indication that upgrade will not work and instead the plug-in will be reinstalled (uninstall / install). Optional element. CR1.1

Example Metadata. Note that if min is ommitted then the range is defined as ver 0 to the max value. If max is omitted then the range is defined as all versions greater than that min value.

<deinstallPredecessor>
    <range min="10.9" max="11.0"></range>
    <range max="6.3"></range>
  </deinstallPredecessor>

version - The main metadata element has a new string attribute version in Citrix Receiver release 1.1. This is declared as optional for backward compatibility with 1.0 (yes, we know) but to ensure correct operation if you depend upon features from a later version you should declare this and set it to the appropriate version number e.g. "1.1". CR1.1

Install Elements

Information elements for Install (autoInstall), Upgrade (autoUpgrade) and Uninstall (autoUninstall) all share the following details. The autoInstall element is mandatory, the autoUpgrade & autoUninstall elements are optional but it is best practice to provide them.

command This command line sets out the basic structure of the appropriate unattended install action command with the relevant parameters and switches to control UI. To help Citrix Receiver select the relevant portions required for different install contexts the structure should include the following tokens:
- $INSTALLERFILENAME - will be replaced by the installer name once downloaded to the client.
- $SILENTSWITCH - placeholder to be replaced by a switch to suppress installer UI.
- $PARAMETERS - used to specify local environment specific parameters to the install action.
  Therefore, the most basic form of the command line would be:
  $INSTALLERFILENAME $SILENTSWITCH $PARAMETERS
  or for MSI installs:
  msiexec /i $INSTALLERFILENAME $SILENTSWITCH $PARAMETERS

commandParameters - This is where any parameters to the unattended install are set. Where a parameter needs defining for the delivery environment with a piece of configuration information (eg a Server URL), Citrix Receiver can generate GUI within the admin tool to prompt for that information and provide it to the install process. For example an installer may accept a SERVER_URL property. Within the commandParameters element this could be expressed as SERVER_URL=$ServerLoc. The specification of ServerLoc would come from the installerOptGUI or configuration elements. See the Plug-in Configuration section below for more details.
Citrix Receiver admins
If you want to specify one of the less common installer options not specified in the initial metadata, add it to the commandParameters element.
silentSwitch - Use this element to specify the switch to suppress installer UI (eg /qn for msiexec).

reboot - If the action is likely to require a reboot after install then set the reboot attribute and suppress the reboot using whatever command flag is required (Citrix Receiver will coordinate all required reboots from installers).

autoUninstall - This element contains the information required to perform an uninstall of the plug-in. It contains only the above details. If it is not possible to specify a command line that will uninstall an arbitrary version of the plug-in (if for example the product guid varies with every version) then specify an empty command string. In that case Citrix Receiver will do its best to detect the relevant uninstall command for the currently installed plug-in.

Important:
For MSI based installs, it may seem tempting to use the form msiexec /x $INSTALLERFILENAME as the uninstall command. This will not work as this command has to support uninstalling older versions of your plug-in. Newer installers are not applicable to uninstall old versions and the original installer file may not be available. Receiver (from ver 1.1) will detect & reject this command form. Instead you should use the msiexec /x your-product-guid form (assuming product guid is fixed), if not revert to the detected version as above.

autoInstall and autoUpgrade- The elements to describe install actions (autoInstall) and upgrade actions (autoUpgrade) for plug-ins include additional details (below). If the autoUpgrade section is absent then the autoInstall information will be used to attempt to perform upgrades but you must ensure any default settings will be appropriate for upgrades to be performed successfully.

- canUpgradeWhilePluginRunning - Should the Upgrade not be suitable to be performed whilst a plug-in is active then set the canUpgradeWhilePluginRunning attribute on the upgrade section. If this is set, Citrix Receiver will defer the upgrade until the next login or boot.

- deinstallPredecessors - If this installer is not backwardly compatible with previous version for upgrades, set the deinstallPredecessors attribute. This will cause any previous instance of the plug-in to be uninstalled before the upgrade is applied rather than an upgrade run on the install.

- lessSilentswitch - Upgrade can also take a lessSilentswitch element which is used in case an upgrade needs to, for example, prompt the user to close down running apps (and/or the plug-in itself). If the fully silent form returns a failure, Citrix Receiver will then run the 'less silent' form of the upgrade.

- startAfterInstall - It is preferable for Citrix Receiver operation if the installer does not startup the plug-in after the install action is complete. If there is an installer switch that suppresses a start then it's good practice to set it. If Citrix Receiver should startup the plug-in immediately after the install has finished and this will be an effective operation (i.e., the plug-in doesn't require reboot to operate correctly) then set the startAfterInstall element to be true. This will inform Citrix Receiver to startup the plug-in.

- autoStart, startupRunKey and startupMenu - Citrix Receiver learns how to start the plug-in by looking at the way the plug-in is configured to start at login time. Citrix Receiver will repurpose that information for its own coordination of plug-in startup. The autoStart element informs Citrix Receiver where to look for that information. Login startup is either achieved by adding an entry to the Run key in the registry or the Startup key in the All Programs menu. If the former is used, add a startupRunKey element otherwise add a startupMenu element. These contain just the relevant name of the Run value or shortcut file respectively, Citrix Receiver will look in both user local & machine wide locations for these settings.

From CR 1.1, multiple autoStart entries can be configured for a plug-in.

As an example:

<autoStart>
    <startupMenu>Citrix XenApp.lnk</startupMenu>
</autoStart>

Optional Elements

adminOptions - The adminOptions element is set to one of demand, prefer or none depending on the level of Admin privilege required to install correctly. demand implies the installer always requires admin privilege, prefer that it has value without admin privilege (eg will install with reduced function) and none that it does not require admin privilege.

pluginLanguages - The pluginLanguages element should contain the list of languages that the plug-in supports (standard locale encodings).

pluginDescriptions - The pluginDescriptions element contains information about the plug-in that will be presented to the user. Both full and abbreviated descriptions should be given, in the relevant set of languages. The descriptions should state what the plug-in is used for and any relevant disclosure information that may be important to a user (eg. Installs kernel components). Specify a new descriptions element for each new language entry. 'Note that Version 1.0 & 1.1 of Citrix Receiver will only display English descriptions' in gthe admin console.

Example:

<!-- Informed Consent / Plug-in Description  -->
  <pluginDescriptions>
    <descriptions language="en" >
      <description>Citrix XenApp plug-in for Hosted Applications integrates hosted applications into your desktop.
      </description>
      <shortdescription>XenApp Client for accessing Hosted Applications.</shortdescription>
    </descriptions>
  </pluginDescriptions>

isCritical - This boolean element indicates that this particular plugin should be installed before all others and will perform some critical task that must be completed before any further part of plug-in delivery is processed. The plug-in will indicate to Receiver that the critical task is complete by calling
```
ARUpdateStatus(AR_STATUS_PLUGIN_SET_STATE, AR_STATUS_PLUGIN_STATE_CRIT_TASK_SUCCESS, L"", L"");
```
CR2.0

disruptsDesktop - If a plug-in specifies this element it indicates that when an upgrade is in progress for the plug-in, it may disrupt the user from using the desktop (e.g. break an ICA connection to a XenDesktop). The user will be warned that disruption is likely and the desktop machine will be rebooted. CR2.0

Plug-in Dependencies

functionalDependencies and installationDependencies - Should the current plug-in rely on another plug-in being present before it will operate correctly then you can express that relationship by adding the GUID for the plug-in on which you will depend to the functionalDependencies list element. If that plug-in should be already present at install time for the current plug-in to successfully install then you can express that relationship by adding the GUID for the plug-in on which you will depend to the installationDependencies list element.

fullPlugin - The optional fullPlugin boolean element is used to help distinguish between plug-ins that have a cheifly autonomous role and those that mostly operate as dependent components for other plug-ins. It it used to help Citrix Receiver organise the Advanced portion of its Preferences control panel. If not specified the value defaults to true.

installOnce - Another optional boolean element is installOnce. This should be set to permit Citrix Receiver to help distribute a plug-in which will manage its own upgrades in normal operation. If Citrix Receiver detects that an existing install of the plug-in is present then no installation or upgrade will be attempted. If not specified the value defaults to false.

"Find Previous" Elements

detectCurrentVersionRulesList - This element is extremely important for successful operation of Citrix Receiver. The information provided is used to detect existing installations of plug-ins, determine their version and, in some cases, how to uninstall them. As installer identities and Displayed Names may not be consistent between releases, custom rules are required.

Maintainers
Beware editing this section. Make sure any changes are tested in a Pilot delivery to ensure the correct detection is achieved.
The detection rules can take the following form (as required).
UPGRADECODE:upgradecode. MSI Upgrade code GUID from installer. Note, this is not the same as the Citrix Receiver Plugin GUID from the product element. This form of the rule has the big advantage of remaining valid for a large set of releases. The upgradecode can be either in packed or unpacked GUID form. Unpacked form takes the following pattern {ABCDEFGH-IJKL-MNOP-QRST-UVWXYZ123456}. Note that packed form is not the same pattern with the decoration removed but takes the corresponding pattern: HGFEDCBALKJIPONMRQTSVUXWZY214365. It is recommended that you copy the original form from the location in which it is obtained. The Receiver determines which form is supplied by detecting the pattern so if you want to use the unpacked form include the {} braces and dashes. If you want to use the packed form then remove them.
The Upgrade Code can normally be obtained from:

- The source of the installer if you are a plug-in developer. Normally unpacked form.

- By examining the MSI installer binary using a tool like 'Orca'. In this case, open up the 'Upgrade' table and look at the UpgradeCode field entries.You'll need to check the ActionProperty to make sure the UpgradeCodes are relevant to this plug-in install case. Normally unpacked form.

- From the Windows registry where a plug-in is installed. Use 'regedit' to open up the HKEY_LOCAL_MACHINE\Software\Microsoft\CurrentVersion\Installer\UserData\S-1-5-18\Products key. Now search below that point for the plug-in install data (it will be in an 'InstallProperties' key under one of the list of GUIDs seen at that point). When you have located the appropriate entry, note the guid keyname under which the InstallProperties were found. Now open up the HKEY_LOCAL_MACHINE\Software\Microsoft\CurrentVersion\Installer\UpgradeCodes key. Look through the list of packed guids under that point until you find a key that contains the value you noted previously. When you locate it then the current keyname is the packed upgrade code. Be careful not to alter any data! Note that information for a per user install may not be under the S-1-5-18 key as above but under a user specific SID at the same level.

DISPLAYNAME:displaystring. This will look for the Display Name of the package inside the Windows Installer registry entries (corresponding to the 'DisplayName' registry string value). An exact match is expected.

Note that the first two forms are preferred as they will normally guide Citrix Receiver to appropriate areas of the Windows Installer database where information beyond the installed version can be found. This is particularly important if the Uninstall string for the product is difficult to predict in the metadata file.

REG:pathtoregistryvalue. Looks up the version in an arbitrary registry value. Pass in the full path to the registry value. Supported prefixes for the Reg path are:HKLM, HKCU, HKCR. If the value is a DWORD then the format is assumed to be Mmbb - 8 bits Major, 8 bits Minor, 16 bits Build. If the value is a string then it will be assumed to be numeric dot separated into up to 4 parts (major, minor, build, custom).

EXE:pathtoexefile. Looks up the version property of an executable file. Pass the full path to an exe file where version can be extracted. The path can include they following environment variables: ProgramFiles, ProgramFiles(x86), WinDir, SystemRoot.

As many of these as are necessary can be specified.

Examples:

<detectRule>UPGRADECODE:{C6F601FC-380A-4399-B1E9-7B881F70D1D2}</detectRule>
  <detectRule>UPGRADECODE:{07900A90-0794-46F5-AE12-24D86B365CA3}</detectRule>

and

<detectRule>REG:hklm\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\CitrixVpn\DisplayVersion</detectRule>
<detectRule>DISPLAYNAME:Citrix Secure Access Client</detectRule>
<detectRule>EXE:%programfiles%\Citrix\Receiver\Receiver.exe</detectRule>

Plug-in Configuration

In CR 1.0 only the installerOptGUI element was available to specify the UI for supplying the information that is to be subsituted into the commandParameters section. These values could only be applied at install time.

In CR 1.1 dynamic config updates were introduced such that if a plug-in subscribes to config updates via the SDK ARRegisterConfigurationHandler() API then any changes made to the configuration in the admin console are passed to the plug-in. The UI that supports this feature is specified by the configuration section. This is richer than that for installerOptGUI element and can be considered to supercede it. The configuration section can be used to create substitutions for the commandParameters section equivalently to the installerOptGUI element.

installerOptGUI element specifies; The Information Prompt (eg Server URL) and a 'variable' key which corresponds to part of the unattended install line. As an example, the unattended install line may contain SERVERURL=$ServerLoc. The UI for supplying this info is made up of a varname attribute (the substituted variable name) and prompts (supporting multiple languages) for that variable. Note the CR admin console currently only displays English (default) prompts.

As an example:

<installerOptGUI>
     <config varname="ServerLoc">
     	<InstallerOpt language="en">
        	<description>Address of the Broadcast Server</description>
        </InstallerOpt>
        <InstallerOpt language="fr">
        	<description>Adresse du serveur de Broadcast Serveur </description>
        </InstallerOpt>
     </config>
</installerOptGUI>

The configuration element describes the UI entries that are required. It describes one or more elements, to be shown in the order specified in the metadata file and consisting of either strings, bools, lists or uploads. For each of these config values, they have a name to distinguish entries once passed to the client and an admin facing prompt description which can be repeated in localised forms as appropriate (distinguished by lang attributes).
- string entries - Simple string entry. Takes the following attributes:
  - required - If true then data must be entered in this field. Default:false.
  - enforceType - Currently the valid enforcement types are http or https which will enforce the appropriate URL forms.
  - passwordField - Don't echo output.
  - defaultValue - A string used to pre-populate the config GUI. If the admin leaves the field untouched (or even if they clear the field for some reason), this value will be used. If the admin changes the value to a new one, the new value will be used.
  - example - The example text will be shown alongside the entry box.

- bool entries - Simple bool entry. Takes the following attribute.
  - initialValue - Default state of the bool.

- list entries - A repeated set of strings. Has the required, enforceType and example attributes as defined above.

- upload entries - A file upload box for advanced settings. Takes the required attribute.

As well as the values, you can also include a introText element that contains text that describes the configuration section helping the admin understand how to fill out the fields.

An example config section follows:

<configuration>
      <value name="SampleBool">
        <bool initialValue="false">
          <prompt lang="en">True or false</prompt>
          <prompt lang="fr">Vrai ou faux</prompt>
        </bool>
      </value>

      <value name="SampleString">
        <string enforce="true" enforceType="http"
                example="http://showcasesample.citrite.net" >
          <prompt>Please enter http URL</prompt>
        </string>
      </value>

      <value name="secondBool">
        <bool initialValue="true">
          <prompt>Enable very important feature</prompt>
          <prompt lang="de">Aktivieren Sie die Anweisungen auf irritierende Bell</prompt>
        </bool>
      </value>

      <value name="AdvancedSettingsFileUpload">
        <upload required="true">
          <prompt lang="en">Enter File Location</prompt>
          <prompt lang="it">Entri nella posizione della lima</prompt>
        </upload>
      </value>

      <value name="SampleList">
        <list  enforce="true" blankIsValid="true" enforceType="https">
          <prompt lang="en">Enter a set of https URLs</prompt>
          <prompt lang="fr">Entrez ensemble URL de https</prompt>
        </list>
      </value>

      <introText>
        <intro>Let me tell you here about the plugins and about these config settings and give some context that will help admins fill in the info correctly.</intro>
       </introText>

    </configuration>

Note that at the client end, this would result in data being passed to
the client callback in the following form:

<configuration>
      <bool name="SampleBool">true</bool>
      <string name="SampleString">the string entry</string>
      <bool name="secondBool">true</bool>
      <upload name="AdvancedSettingsFileUpload">
                    base 64 encoded file contents</upload>
      <list name="SampleList">
        <entry>list entry 1</entry>
        <entry>list entry 2</entry>
        <entry>list entry 3</entry>
      <list>
    </configuration>

Citrix Receiver 1.1 Localisation Element Additions

localisedProductNames - In the event of the plug-in product names being localised add a list of the localised names here.

localisedInstall - In the event that a localised install implies a different command line, command line parameter set or start menu shortcut name, you can now add these overrides under their default (en) entries.

Example section:

<autoInstall reboot="false">
    <command>msiexec /I $INSTALLERFILENAME $SILENTSWITCH $PARAMETERS</command>
    <command lang="fr">msiexec /I $INSTALLERFILENAME /leplumedematant</command>

    <commandParameters>ENABLE_SSON=Yes ALLOW_REBOOT=No SERVER_LOCATION=$ServerLo
       c REBOOT=ReallySuppress</commandParameters>
    <commandParameters lang="de">
         MeineHoseIstAbgereist=TRUE ALLOW_REBOOT=NO</commandParameters>

    <silentSwitch>/qn</silentSwitch>
    <startAfterInstall>false</startAfterInstall>
    <autoStart>
        <startupMenu>Citrix XenApp.lnk</startupMenu>
        <startupMenu lang="fr">Citrix XenFrappe.lnk</startupMenu>
    </autoStart>
    <lessSilentSwitch>/qb</lessSilentSwitch>
  </autoInstall>

Sample Metadata file

The following is an example Citrix Receiver Metadata file

<?xml version="1.0"?>
<metadata
  xmlns="http://www.citrix.com/AppReceiver"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.citrix.com/AppReceiver MetaData.xsd" version="1.1" >

<plugin product="61D54625-40B5-4175-A7E4-0CD657817445"
	productName="Test Plugin" >

  <platforms>XP XP64 Vista64 Win7 Win764</platforms>
  <version>1.3.5</version>
  <installerFilename>MyPlugin.msi</installerFilename>

  <fullPlugin>true</fullPlugin>

  <!-- Install string & Attributes -->
  <autoInstall reboot="false">
    <command>msiexec /i $INSTALLERFILENAME $PARAMETERS $SILENTSWITCH</command>
    <commandParameters>SERVER_LOCATION=$ServerLoc REBOOT=ReallySuppress</commandParameters>
    <silentSwitch>/qn</silentSwitch>
    <lessSilentSwitch>/qb</lessSilentSwitch>
  </autoInstall>

  <!-- Uninstall string & Attributes -->
  <autoUninstall reboot="false">
    <command>MsiExec.exe /X{0A920DF0-DF9E-4908-891D-716BC40C8F8E} $SILENTSWITCH</command>
    <silentSwitch>/qn</silentSwitch>
  </autoUninstall>

  <adminOptions>demand</adminOptions>

  <!-- Informed Consent / Plugin Description  -->
  <pluginDescriptions>
    <descriptions language="en" >
      <description>
        My Plug-in. I want to give the user an outline of what this plug-in does and what service it connects to.
      </description>
      <shortdescription>My Plug-in: Provides access to something</shortdescription>
    </descriptions>
  </pluginDescriptions>

 <!-- Admin console GUI generating information -->
    <configuration>

      <value name="ServerLoc">
        <string enforceType="http" required="true" defaultValue="http://demoacme.com/demoserver">
          <prompt lang="en">Enter Server Contact URL</prompt>
        </string>
      </value>

      <value name="EnableFeature">
        <bool initialValue="false">
          <prompt>Enable feature for user community</prompt>
        </bool>
      </value>

      <introText><intro>This text would inform the admin about appropriate usage for the Server Contact URL and Feature Enabling entries. It gets displayed in the admin console.</intro></introText>
    </configuration>

  <!-- List of Languages the plugin supports  -->
  <pluginLanguages>en de fr ja es ru zh-cn zh-tw</pluginLanguages>

  <!-- Rules use to detect currently installed version of plugin - see CR Client SDK doc for more details  -->
  <detectCurrentVersionRulesList>
    <detectRule>UPGRADECODE:C6E61359CF3D481CBD839809DC25A058</detectRule>
  </detectCurrentVersionRulesList>

  <installOnce>false</installOnce>

</plugin>

</metadata>

Metadata Schema

This is the schema for the CR 2.0 release. It is also available here.

<?xml version="1.0" encoding="utf-8"?>

<xs:schema
  xmlns="http://www.citrix.com/AppReceiver"
  elementFormDefault="qualified"
  targetNamespace="http://www.citrix.com/AppReceiver"
  id="metadata"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
>

  <annotation xmlns="http://www.w3.org/2001/XMLSchema">
    <documentation>
      Copyright 2008-2010 Citrix Systems, Inc. All Rights Reserved.
    </documentation>
  </annotation>

  <xs:element name="metadata">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="1" maxOccurs="100" name="plugin" type="pluginListType" />
      </xs:sequence>

      <!-- This attribute is listed as optional for backward compatibility, but plugins adopting 2.0 schema elements
                 *MUST* set this to "2.0" to ensure correct operation
            -->
      <xs:attribute default="1.0" name="version" type="xs:token" use="optional" />
    </xs:complexType>
  </xs:element>

  <xs:complexType name="pluginListType">
    <xs:all>
      <!-- Supported platforms -->
      <xs:element name="platforms" type="platformTypeList" minOccurs="1" />

      <!-- Released Version of Plugin (Installer) -->
      <xs:element name="version" type="versionType" />

      <!-- URL to EULA text (if available) -->
      <xs:element name="EULAlocation" type="xs:anyURI" minOccurs="0" />

      <!-- Install string & Attributes -->
      <xs:element name="autoInstall" type="arUpdatingInstallType" />

      <!-- Uninstall string & Attributes -->
      <xs:element name="autoUninstall" type="arInstallType" minOccurs="0" />

      <!-- Upgrade string & Attributes -->
      <!-- If the upgrade string is omitted the install string will be used for upgrades. -->
      <xs:element name="autoUpgrade" type="arUpdatingInstallType" minOccurs="0" />

      <!-- Admin requirements -->
      <xs:element name="adminOptions" type="installationAdminPrivsType" default="none" />

      <!-- This plugin normally deployed if not present, it will be updated by itself in communication with its server component -->
      <xs:element name="installOnce" type="xs:boolean" default="false"  minOccurs="0" />

      <!-- Should it be important to maintain the filename of the installer, provide this element -->
      <xs:element name="installerFilename" type="xs:string" />

      <!-- Admin console GUI generating information -->
      <xs:element name="installerOptGUI" type="commonInstallerOptGUIListType" minOccurs="0" />

      <!-- Informed Consent / Plugin Description  -->
      <xs:element name="pluginDescriptions" type="pluginDescriptionListType" />

      <!-- List of Languages the plugin supports  -->
      <xs:element name="pluginLanguages" type="languageTypeList" minOccurs="1" />

      <!-- Rules use to detect currently installed version of plugin - see Receiever Client SDK doc for more details  -->
      <xs:element name="detectCurrentVersionRulesList" type="detectCurrentVersionType" minOccurs="0" />

      <!-- Other plugins on which this plugin depends at run time  -->
      <xs:element name="functionalDependencies" type="dependencyList" minOccurs="0" />

      <!-- Other plugins on which this plugin depends at install time  -->
      <xs:element name="installationDependencies" type="dependencyList" minOccurs="0" />

      <!-- Is this plugin a fully fledged, product level 'plugin' or a component associated with -->
      <!-- a plugin that we  might want to represent at a different (lesser) level   -->
      <xs:element name="fullPlugin" type="xs:boolean" default="true" minOccurs="0" />

      <!-- Elements introduced in version 1.1  -->
      <xs:element name="configuration" type="configType" minOccurs="0"  />

      <!-- URL to README file (if available) -->
      <xs:element name="READMElocation" type="xs:anyURI" minOccurs="0" />

      <!-- Sequence of Localised product names -->
      <xs:element name="localisedProductNames" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="1" maxOccurs="50" name="productName" type="localisedStringType" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <!-- Installer True Exit Code location. If set Receiver will look
             at a reg DWORD value of this path for the true exit code of the
             installer. Copes with MetaInstaller wrappers that throw away exit
             codes. HKLM paths only supported.
         -->
      <xs:element name="installerTrueExitCodePath" type="xs:string" minOccurs="0" />

      <!-- Installer Failure Details Message location. If set, Receiver will
             look at a reg string value of this path for any extra detail on
             the cause of an installer exiting with the opaque 'Fatal
             Installer Error' code. HKLM paths only supported.
         -->
      <xs:element name="installerDetailExitMessagePath" type="xs:string" minOccurs="0"  />

      <!--  pluginSupportsAdvancedMenuOptions: this plugin will mark some menu
              entries as being suitable for optional 'advanced' display. Option
              to enable such entries will only be shown in admin console if this
              is set.
         -->
      <xs:element name="pluginSupportsAdvancedMenuOptions" type="xs:boolean" default="false" minOccurs="0" />

      <!--  DeInstallPredecessor ranges: to meet the conditions like the Desktop Receiver upgrade failure case:
              Specify version ranges over which upgrade will not work & deinstallation prior to applying the new version
              is required. If a detected version does not fall into one of the specified ranges then it is assumed that
              upgrade will work.
         -->
      <xs:element name="deinstallPredecessor" minOccurs="0">
        <xs:complexType >
          <xs:sequence>
            <xs:element name="range" minOccurs="1" maxOccurs="100" >
              <xs:complexType>
                <xs:attribute name="min" type="xs:string" use="optional" />
                <xs:attribute name="max" type="xs:string" use="optional" />
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <!-- Running all the time: is it normal that a plug-in is active & able to report status
             (as say online / offline normally are) or is it OK that it may not be active all the time (eg ICA Engine).
         -->
      <xs:element name="runningAllTheTime" type="xs:boolean" minOccurs="0" />

      <!-- Incompatible Plugin: To cope with the case where multiple plugins
             perform the same role (eg PNA and Anthem). Would stop them being
             deployed together in same Delivery, or at least generate a warning.
             Does this need to be a list???
         -->
      <xs:element name="incompatiblePlugin" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="plugin" type="guid" minOccurs="1" maxOccurs="50" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <!-- Does this plug-in support Receiver communication links e.g., AG / Repeater? -->
      <xs:element name="supportsReceiverComms" type="xs:boolean" default="false" minOccurs="0" />

      <!-- Is this plug-in Dazzle? -->
      <xs:element name="isDazzle" type="xs:boolean" default="false" minOccurs="0" />

      <!-- Launch this plug-in after the completion dialog has been shown, on first time use. -->
      <xs:element name="launchAfterCompletionDialog" type="xs:boolean" default="false" minOccurs="0" />

      <!-- Elements new in CR 2.0 -->

      <!-- This plugin is critical and should be installed before any other plugins -->
      <xs:element name="isCritical" type="xs:boolean" default="false"  minOccurs="0" />

      <!-- Does this plug-in disrupt the desktop on install/upgrade? -->
      <xs:element name="disruptsDesktop" type="xs:boolean" default="false" minOccurs="0" />

    </xs:all>

    <xs:attribute name="product" use="required" type="guid" />
    <xs:attribute name="productName" use="required" type="xs:string" />

    <!-- If this is true then this is part of the Citrix Receiver itself (both main client or UE component) -->
    <xs:attribute name="appReceiverComponent" type="xs:boolean" default="false" use="optional" />
  </xs:complexType>


  <!-- Every plugin has a unique GUID. This is release invariant  -->
  <xs:simpleType name="guid">
    <xs:restriction base="xs:string" >

      <!-- This is the way it often appears in Windows. -->
      <xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />

      <!-- And this is a plain 32 character hex string. -->
      <xs:pattern value="[0-9a-fA-F]{32}" />

    </xs:restriction>
  </xs:simpleType>


  <!-- Version is normally a dotted string Major.Minor.BUild.Custom as applicable  -->
  <xs:simpleType name="versionType">
    <xs:restriction base="xs:token"/>
  </xs:simpleType>


  <!-- The relationship between the installer (action) and admin privilege  -->
  <xs:simpleType name="installationAdminPrivsType">
    <xs:restriction base="xs:normalizedString">
      <!-- Installation requires admin privs and should fail if they are not available. -->
      <xs:enumeration value="demand" />
      <!-- Installation should be done with admin privs if available.  If not available
      then proceed as non-admin user. -->
      <xs:enumeration value="prefer" />
      <!-- Install with non-privileged account.  Does not prevent installation if current user
      happens to be an admin. -->
      <xs:enumeration value="none" />
    </xs:restriction>
  </xs:simpleType>


  <!-- Possible Platforms for which this installer is valid (& platformType below)  -->
  <xs:simpleType name="platformTypeList" >
    <xs:list>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="XP"/>
          <xs:enumeration value="XP64"/>
          <xs:enumeration value="Vista"/>
          <xs:enumeration value="Vista64"/>
          <xs:enumeration value="2K3"/>
          <xs:enumeration value="2K364"/>
          <xs:enumeration value="WS08"/>
          <xs:enumeration value="WS08_64"/>
          <xs:enumeration value="Win7"/>
          <xs:enumeration value="Win764"/>
          <xs:enumeration value="WS08R2" />
          <xs:enumeration value="MacOS10.5"/>
          <xs:enumeration value="MacOS10.6"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>

  <!-- Possible Languages for which this installer is valid (& platformType below)  -->
  <xs:simpleType name="languageTypeList" >
    <xs:list itemType="xs:language" />
  </xs:simpleType>

  <!-- Details needed to perform an uninstall (& forms the basis of installs) -->
  <xs:complexType name="arInstallType" >
    <xs:sequence minOccurs="1" maxOccurs="1">

      <!-- Basic structure of Command eg INSTALLERFILENAME $SILENTSWITCH $PARAMETERS -->
      <xs:element name="command" type="localisedStringType" minOccurs="1" maxOccurs="50" />

      <!-- Name=$param(Param GUI Name) pairs -->
      <xs:element name="commandParameters" type="localisedStringType" minOccurs="0" maxOccurs="50" />

      <!-- Switch needed to make the install run silently eg /qn -->
      <xs:element name="silentSwitch" type="xs:string" minOccurs="1" maxOccurs="1"/>

    </xs:sequence>
    <xs:attribute name="reboot" type="xs:boolean" use="optional" />
  </xs:complexType>


  <!-- Type that supports Installs & Upgrades -->
  <xs:complexType name="arUpdatingInstallType" >
    <xs:complexContent >
      <xs:extension base="arInstallType" >
        <xs:sequence>

          <xs:element name="installer" type="xs:anyURI" minOccurs="0">
            <xs:annotation>
              <xs:documentation>
                Optional location of the installer.  There may be a list
                of these, although only the first may be used.
              </xs:documentation>
            </xs:annotation>
          </xs:element>

          <!-- Does AR need to start the plugin after install?  (We prefer the installer not to do so itself.) -->
          <xs:element name="startAfterInstall" type="xs:boolean" minOccurs="0" />

          <!-- Information on how the plugin (auto) starts on login -->
          <xs:element name="autoStart" type="autoStartType" minOccurs="0" maxOccurs="50" />

          <!-- Switch needed to make the install run with basic ui eg /qb -->
          <xs:element name="lessSilentSwitch" type="xs:string" minOccurs="0" maxOccurs="1" />

        </xs:sequence>

        <!-- In some cases an update (or an 'installation' that effects an update) require
        any earlier versions to be removed beforehand.  I.e. they can't handle it
        themselves. -->
        <xs:attribute name="deinstallPredecessors" type="xs:boolean" default="false" use="optional"/>

        <!-- Set this if the installer can detect & handle a running instance -->
        <xs:attribute name="canUpgradeWhilePluginRunning" type="xs:boolean" default="false"/>

      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <!-- If a plugin autostarts on login then it does so (on Windows!) via either a registry Run key or via a Startup menu entry -->
  <!-- Let the Receiver have that information so it can steal the info & use it to start the plugin at it's own convenience  -->
  <!-- Receiver will look in both per user & machine wide locations so this entry should be relative to these roots -->
  <xs:complexType name="autoStartType" >
    <xs:sequence>
      <xs:choice minOccurs="1" maxOccurs="1" >
        <xs:element name="startupMenu" type="localisedStringType" minOccurs="1" maxOccurs="50" />
        <xs:element name="startupRunKey" type="localisedStringType" minOccurs="1" maxOccurs="50" />
      </xs:choice>
    </xs:sequence>
  </xs:complexType>

  <!-- The Receiver admin console will want to prompt the admin for common install time params & fill them in on the installer -->
  <!-- command lines. This can be achieved by adding something of the form PARAM=$(VarName) to the command line; -->
  <!-- then below pass that variable name & it's description. -->
  <!-- e.g. Description="The Server URL for PNA" varname="PNAURL" -->
  <xs:complexType name="commonInstallerOptGUIListType" >
    <xs:sequence>
      <xs:element name="config" type="commonInstallerOptGUIConfigEntry" minOccurs="1" maxOccurs="100" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="commonInstallerOptGUIConfigEntry" >
    <xs:sequence>
      <xs:element name="InstallerOpt" type="commonInstallerOptGUIType" minOccurs="1" maxOccurs="100" />
    </xs:sequence>
    <xs:attribute name="varname" type="xs:string" use="required"/>
  </xs:complexType>

  <xs:complexType name="commonInstallerOptGUIType" >
    <xs:sequence>
      <xs:element name="description" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="language" type="xs:language" use="required"/>
  </xs:complexType>

  <!-- Include a description of the plugins function & any information pertinent to its activity (eg installs kernel -->
  <!-- components, such that a user can used that information for informed consent to an install  -->
  <xs:complexType name="pluginDescriptionListType" >
    <xs:sequence>
      <xs:element name="descriptions" type="pluginDescriptionType" minOccurs="1" maxOccurs="100" />
    </xs:sequence>
  </xs:complexType>

  <!-- Note that the description is required in all relevant languages -->
  <xs:complexType name="pluginDescriptionType" >
    <xs:sequence>
      <xs:element name="description" type="xs:string"/>
      <xs:element name="shortdescription" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="language" type="xs:language" use="required"/>
  </xs:complexType>

  <!-- GUID sequence for package & install dependencies -->
  <xs:complexType name="dependencyList" >
    <xs:sequence>
      <xs:element name="dependency" type="dependencyType"  minOccurs="1" maxOccurs="100" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="dependencyType">
    <xs:attribute name="id" type="guid" use="required" />
  </xs:complexType>

  <!-- Rules use to detect currently installed version of plugin - see Receiver Client SDK doc for more details  -->
  <xs:complexType name="detectCurrentVersionType" >
    <xs:sequence>
      <xs:element minOccurs="1" maxOccurs="100" name="detectRule">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="ignoreAfterVer" type="xs:string" use="optional" />
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <!-- Config types introduced in version 1.1. -->

  <!-- Core type for L10N -->
  <xs:complexType name="localisedStringType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute default="en" name="lang" type="xs:language" use="optional" />
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <!-- List of config elements -->
  <xs:complexType name="configType">
    <xs:sequence>
      <xs:element minOccurs="1" maxOccurs="100" name="value" type="configElementType" />
      <xs:element name="introText" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="1" maxOccurs="50" name="intro" type="localisedStringType" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>


  <!-- Construct as choice so the entries can be in any order -->
  <xs:complexType name="configElementType">
    <xs:choice minOccurs="1" maxOccurs="1">
      <xs:element name="string" type="valueStringType" />
      <xs:element name="bool" type="valueBoolType" />
      <xs:element name="list" type="valueListType" />
      <xs:element name="upload" type="valueFileUploadType" />
    </xs:choice>
    <xs:attribute name="name" type="xs:string" use="required" />
  </xs:complexType>

  <!-- Ensure enforcement types are correctly formed -->
  <xs:simpleType name="enforceTypesSet">
    <xs:list>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="http" />
          <xs:enumeration value="https" />
        </xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>


  <!-- Specifier for a single string entry
       Attr: required - data must be entered
       Attr: enforceType - http or https (URL types)
       Attr: passwordField - don't echo output
       Attr: defaultValue - start with this string, use it if no modification or field cleared.
  -->
  <xs:complexType name="valueStringType">
    <xs:sequence>
      <xs:element minOccurs="1" maxOccurs="50" name="prompt" type="localisedStringType" />
    </xs:sequence>
    <xs:attribute name="required" type="xs:boolean" use="optional" default="false" />
    <xs:attribute name="enforceType" type="enforceTypesSet" use="optional" />
    <xs:attribute name="passwordField" type="xs:boolean" use="optional" />
    <xs:attribute name="defaultValue" type="xs:string" use="optional" />
    <xs:attribute name="example" type="xs:string" use="optional" />
  </xs:complexType>

  <!-- Specifier for a boolean config entry
       Attr initialValue: is the value 'true' by default or not
  -->
  <xs:complexType name="valueBoolType">
    <xs:sequence>
      <xs:element minOccurs="1" maxOccurs="50" name="prompt" type="localisedStringType" />
    </xs:sequence>
    <xs:attribute name="initialValue" type="xs:boolean" use="optional" />
  </xs:complexType>

  <!-- Specifier for a list of config entries.
       Attr: required - data must be entered
       Attr: enforceType - http or https (URL types)
  -->
  <xs:complexType name="valueListType">
    <xs:sequence>
      <xs:element minOccurs="1" maxOccurs="50" name="prompt" type="localisedStringType" />
    </xs:sequence>
    <xs:attribute name="required" type="xs:boolean" use="optional" default="false" />
    <xs:attribute name="enforceType" type="enforceTypesSet" use="optional" />
    <xs:attribute name="example" type="xs:string" use="optional" />
  </xs:complexType>

  <!-- Specifier for an 'advanced settings' file upload entry
       Attr: required - data must be entered
  -->
  <xs:complexType name="valueFileUploadType">
    <xs:sequence>
      <xs:element minOccurs="1" maxOccurs="50" name="prompt" type="localisedStringType" />
    </xs:sequence>
    <xs:attribute name="required" type="xs:boolean" use="optional" default="false" />
  </xs:complexType>

</xs:schema>

Metadata windows