Catalog Item Properties

Article
03/24/2010

Other versions of this page are also available for the following:

Windows Embedded CE 6.0 R3

Windows Mobile Not Supported Windows Embedded CE Supported

8/27/2008

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

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 `<![CDATA[` and ends with `]]>`. To replace symbols with XML entities, use the entity instead of the symbol. For example, use `&amp;` instead of `&`. 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

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 <![CDATA[ and ends with ]]>. To replace symbols with XML entities, use the entity instead of the symbol. For example, use &amp; instead of &.

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

Format 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.

Catalog Item Properties

Catalog Item Properties that You Can Set

Format of a Unique ID

Property Settings Validation

See Also

Tasks

Concepts

Additional resources