Catalog Item Properties (Windows Embedded CE 6.0)

1/6/2010

When you create a Catalog item for either a feature or a board support package (BSP), you must define that Catalog item by setting its properties.

When a new Catalog item is selected in Catalog Editor, Catalog item properties can be set either by using the Properties pane of Catalog Editor, or by typing directly in the XML source code.

When you edit a property in the Properties pane, the change is automatically applied to the XML source code of the .pbcxml file. When you edit an XML element in the source code, the change is automatically applied to the corresponding property in the Properties pane.

For more information, see Using the Catalog Editor to Edit an Existing Catalog File and Editing the XML Structure of a Catalog File.

Catalog Item Properties that You Can Set

The following table shows the properties that you can set in Catalog Editor for a new feature or for a new BSP, together with their associated XML elements in the XML source code.

Property (XML element or attribute) Description Catalog item category

Platform Directory

(<PlatformDirectory>)

Specifies the name of the BSP subdirectory that is located under %_WINCEROOT%\PLATFORM. For example, for the %_WINCEROOT%\PLATFORM\CEPC subdirectory, this value would be CEPC.

BSPs

Supported CPU

(<CpuId>)

Specifies the CPU that is supported by this BSP.

The format of the value in the XML source is the same format of the ID of a CPU Catalog record. For example, the CPU property value ARMV4I will be reflected in the XML source in the format Cpu:ARMV4I.

If a BSP supports multiple CPUs, you should have one BSP item for each CPU.

BSPs

Supported CPUs

(<SupportedCpuId>)

Specifies the CPU or CPUs that are supported by the Catalog item.

Feature Catalog items

Type

(<Type>)

Specifies the Catalog item type. It can be one of the following:

  • CoreOS-Specific - indicates that the Catalog item is associated with one or more CoreOSs. A CoreOS-specific Catalog item will appear in the CoreOS node in Catalog Items View and should only be specified by the vendor of a CoreOS. This value is typically used for Catalog items that are provided in Platform Builder.
  • BSP-Specific - indicates that the Catalog item is associated with one ore more specific BSPs. A BSP-specific catalog item will appear in its corresponding BSP node in Catalog Items View, and will only be visible in the Catalog if the BSP is selected for an OS design.
  • General - represents a Catalog item that will be displayed in Catalog Items View, typically in the Third Party node. This value is a good choice when you create a custom Catalog item.

Feature Catalog items

Help Link

(<HelpLink>)

Specifies the Help link for the Help page in a Help file to display if the developer requests Help for this Catalog item by selecting the Catalog item and pressing F1.

This property value is optional.

BSPs, Feature Catalog items

Sdk Help File Attribute

(<SdkHelpAttribute>)

Specifies a token that is used to filter Help pages in the Help collection created by the SDK roller in Platform Builder.

This property value is optional.

BSPs, Feature Catalog items

Sdk Help Files

(<SdkHelpFile>)

Specifies zero or more Help files that should be included in an SDK if the SDK includes the component or application represented by this Catalog item.

A Help file includes a collection of Help pages about a component or application. Each Help file is defined by an <SdkHelpFile> element.

This property value is optional.

BSPs, Feature Catalog items

Size

(<Size>)

Specifies an estimate of how much space, in bytes, that this Catalog item will require in a run-time image, excluding dependencies.

This property value is optional. The default value is 0.

BSPs, Feature Catalog items

Size Is Scaled

(<SizeIsScaled>)

Specifies whether this is a compiled component.

If set to true, the value of Size is an estimate for the x86 version of this Catalog item, and Size will vary based on the CPU type. The size estimate will be scaled for each CPU according to the CPU record's ScaleFactor.

If set to false, the value of Size is constant for all CPU types.

This property is optional. The default value is true.

BSPs, Feature Catalog items

Comment

(<Comment>)

Specifies comments about this Catalog item that are not used by Platform Builder. This property should be used instead of XML-style comments. These are lost when a Catalog file is edited by using the Catalog Editor.

This property value is optional.

BSPs, Feature Catalog items

Description

(<Description>)

Specifies a detailed description of the Catalog item.

This property value is optional.

BSPs, Feature Catalog items

Title

(<Title>)

Specifies the name of the Catalog item which will be displayed in the Catalog Items View.

This property value is required.

BSPs, Feature Catalog items

Unique Id

(Id attribute of <Item>, <Bsp>, or <FileInformation>)

Uniquely identifies the Catalog item. All root catalog records must have a unique ID. This ID is used when cross-referencing Catalog records.

For more information about the expected format, see Format of a Unique Id later in this topic. A GUID can be used instead of the expected format, although we do not recommend it.

BSPs, Feature Catalog items

Additional Variables

(<Variable>)

Specifies zero or more non-Sysgen variables associated with this Catalog item, such as environment variables. If this Catalog item is added to an operating-system (OS) design, these variables will be set to 1 in the build environment.

For possible values, see Environment Variables.

If no variables are specified and no <Project> elements (added when the Subprojects property is modified) are specified, this Catalog item is a display-only item that cannot be directly added or removed from an OS design.

If this Catalog item specifies <Module> elements (added when the Modules property is modified), the Catalog item is displayed as either present or excluded in an OS design, depending on whether the item's modules are listed in the filtered .bib file that is used for the OS configuration.

Feature Catalog items

Modules

(<Module>)

Specifies zero or more names of modules that implement the functionality represented by this Catalog item.

This information is used by Platform Builder to provide feedback on whether the modules associated with a Catalog item will be included in a run-time image after filtering the .bib file. For example, this property value can be set to uhci.dll.

You must specify a value for either Sysgen variable or Module. However, you typically would not set both properties.

Feature Catalog items

Notification Html

(<Html>, a child element of <Notification>)

Specifies the XML-escaped HTML code fragment that includes the contents of the notification. To change your HTML code to XML-escaped code, you must either make the HTML a CDATA section or replace all ampersands, > symbols, and < symbols with the corresponding XML entities.

A CDATA section starts with &lt;![CDATA[ and ends with ]]&gt;. To replace symbols with XML entities, use the entity instead of the symbol. For example, use &amp;amp; instead of &amp;.

This property value is optional.

Feature Catalog items

Notification Title

(<Title>, a child element of <Notification>)

Specifies the name displayed in the UI for the notification that is displayed when this Catalog item is included in an OS design.

This property value is optional.

Feature Catalog items

Sysgen variable

(<SysgenVariable>)

Specifies the Sysgen variable for the Catalog item.

This property value is required.

Feature Catalog items

Choose One Group

(<ChooseOneGroup>)

Specifies whether this item should have an option button in a "Choose one" folder instead of a check box. If set to true, this item is an option button. If set to false, this item is a check box. By default, this value is set to false.

Feature Catalog items

Locations

(<Location>)

Specifies one ore more paths to the folder in the Catalog Items View. This typically includes one location only, unless multiple locations are necessary. This path is a relative path from the CEBASE folder. For example, "Communication Services and Networking\Networking - General\My Catalog Item".

Feature Catalog items

Subproject Links

(<Project>)

Zero or more directory paths to a *.pbcxml file that should also be included in the run-time image if this Catalog item is included in an OS design.

A subproject link is created for display only.

Feature Catalog items

(<FileInformation>)

Specifies general information that applies to all Catalog items defined in the Catalog file. This is automatically added to the XML source code when you create a new Catalog item.

You can manually edit the values for following XML child elements: <Title>, <Description>, and <Vendor>.

BSPs, Feature Catalog items

(<Bsp>)

Specifies information that defines one BSP in the Catalog file. When you create a new Catalog item, this element is automatically added to the XML source code.

<Bsp> is a root catalog element that defines a BSP record (_TGTPLAT).

BSPs, Feature Catalog items

(<Item>)

Specifies information that represents one item in the Catalog file, such as a driver, a system component, or an application. When you create a new Catalog item, this element is automatically added to the XML source code.

Catalog files that contain BSP-specific Items should be saved in the Catalog folder under the BSP folder in the Platform directory (for example, %_WINCEROOT%\PLATFORM\CEPC\CATALOG).

Catalog files that contain Core OS-specific items should be saved in the Catalog file under CESBASE (%_WINCEROOT%\PUBLIC\CEBASE\CATALOG).

Catalog files that contain other items should be saved in the Catalog folder under the OS build tree in which the item is built (for example, %_WINCEROOT%\PUBLIC\SERVERS\CATALOG).

BSPs, Feature Catalog items

Ee482360.collapse(en-US,WinEmbedded.60).gifFormat of a Unique ID

Several kinds of XML elements have an Id attribute that uniquely identifies the entity represented by the XML element. The Id attribute contains the unique ID for the entity.

The following list shows the recommended format of the Id attribute for each kind of XML element that has this attribute:

XML element Type BSP Specific? Format of unique ID

<Bsp>

Not applicable

Yes

Bsp:VENDOR:BSPDIR:CPU

<Item>

CoreOSSpecific

No

Item:VENDOR:SYSGEN

<Item>

General

No

Item:VENDOR:SYSGEN

<Item>

BSPSpecific

No

Item:VENDOR:VARIABLE

<Item>

BSPSpecific

Yes

Item:VENDOR:MODULE:BSPDIR

<FileInformation>

Not applicable

No

FileInformation:VENDOR:CATALOGFILENAME

<FileInformation>

Not applicable

Yes

FileInformation:VENDOR:CATALOGFILENAME:BSPDIR

The format of the unique ID consists of a combination of the following kinds of variables:

Variable Description

VENDOR

Describes the name of the Catalog-item vendor (for example, MyCompany). When a Catalog item is a Windows Embedded CE OS component, this value is set to MS.

BSPDIR

Describes the platform directory name for the BSP (for example, CEPC).

CPU

Describes a CPU string (for example, ARMV4I).

SYSGEN

Describes a SYSGEN_VARIABLE (for example, SYSGEN_ATL).

VARIABLE

Describes the name of the associated environment variable.

MODULE

Describes the name of the primary DLL or EXE of a BSP-specific catalog item (for example, if the module is audio.dll, this variable is audio).

CATALOGFILENAME

Describes the name of the .pbcxml file (for example, if the file name is MyBsp.pbxml, this variable is MyBsp).

Note

We recommend that you do not modify Catalog items that have a unique ID that uses the format Item:MS:xxx unless you understand the results of modifying a Catalog item that is a part of the Windows Embedded CE operating system.

Property Settings Validation

After you add your new property settings, in Catalog Editor, choose Validate to validate the changes against the XSL schema. During Platform Builder installation, notice that the XSL schema is installed to the following locations:

  • <installation_drive>\Program Files\Microsoft Platform Builder\6.00\cepb\IdeVS
  • <installation_drive>\Program Files\Microsoft Visual Studio 8\Xml\Schemas

Note

If you have installed Visual Studio 2005 SP1, copy the XSL schema to the directory where you saved the .pbcxml file, or remove the xsi:schemaLocation attribute from the <CatalogFile> XML element, before you validate your .pbcxml file.

See Also

Tasks

How to Add a Device Driver to the Catalog

Concepts

Catalog Editor
How to Add an Application to the Catalog