Registering a File Filter

An application registers a file filter by placing its CLSID in the following registry key locations:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services\Filters\.<file extension>\InstalledFilters. This registration associates the file filter with the file type that it converts.
HKEY_CLASSES_ROOT\CLSID. This registration provides information on the file filter's capabilities and its DLL.

Registering a file filter in two locations guarantees that your file filter is available for any new device partnership. Windows CE Services uses device partnerships to allow multiple Windows CE–based devices to be connected to the same desktop computer. If device partnerships exist when an application registers a file filter, an application must create a file filter extension key for each existing device partnership. Connecting a device to a desktop computer for the first time establishes a new device partnership with a unique identifier. Devices use the partnership identifier to store unique settings for synchronization, file conversions, and backup-and-restore information.

All filters registered under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services\Filters key are copied to the HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows CE Services\Partners\<partner identifier> key, where <partner identifier> is the identifier of the new device partnership.

A file type can have more than one file filter associated with it. The Windows CE Services user interface (UI) lists the registered filters as filter options. A file filter can be registered under the file type's InstalledFilters key in the DefaultImport or DefaultExport subkeys. As their names imply, these subkeys define the default file filters for the file type. The file filter specified under the extension key as the DefaultImport or DefaultExport value will be shown as the default.

Note Any filter defined as the DefaultImport or DefaultExport value must be an InstalledFilters value, also.

A file filter can also be registered for a particular device. For example, for the Palm-size PC device category, the file filter extension subkey needs to be created under the HKEY_LOCAL_MACHINE\SOFTWARE\Windows CE Services\SpecialDefaults\Palm PC\Filters key.

The following is the structure of the Filters key and the InstalledFilters subkey.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services\Filters

   \.<file extension>
      [DefaultImport = <default import filter CLSID>]
      [DefaultExport = <default export filter CLSID>]
      \InstalledFilters
         [<clsid1>]
         . . .
         [More CLSIDs for this extension.]
    . . .
    [More extensions.]

The HKEY_CLASSES_ROOT\CLSID key provides basic information about file filters. Each file filter that has been identified in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services\Filters key must be registered in this key. The following is the structure for this key and its subkeys.

HKEY_CLASSES_ROOT\CLSID

   \<clsid>
      \(Default) = <description in "Edit Conversion Settings" list>
      \DefaultIcon = <file name,index for the icon for this type>
      \InProcServer32 = <file name of the DLL that handles this type>
         ThreadingModel = Apartment
      \PegasusFilter
         [Import]
         [HasOptions]
         Description = <string to display in the conversion dialog box>
         NewExtension = <extension of the converted file>
   \. . . [More CLSIDs for filters.]

The <clsid> key is a named value that is the CLSID of the registered file filter. This key contains the following subkeys:

DefaultIcon, which defines the icon name string or icon resource identifier for the icon associated with the file filter DLL.
InProcServer32, which identifies the file filter DLL using the default value, and defines the apartment model capabilities of the file filter in the ThreadingModel named value.
PegasusFilter, which provides information on the specific capabilities of the file filer.
The following table shows possible named values for the PegasusFilter subkey.

Named value	Description
Import	If this named value exists, the conversion type is for importing files from the desktop computer to the device. Otherwise, the conversion type is for exporting files from the desktop computer to the device.
HasOptions	If this named value exists, the file filter supports the ICeFileFilter::FilterOptions method.
Description	The data for this named value is a string that describes the conversion. Windows CE Services displays this text on the property sheets that are displayed by selecting the DeviceDesktop or DesktopDevice tab control selections in the File Conversion Properties dialog box, and then choosing Edit to display the Edit Conversion Settings dialog box. For example, if the Import named value exists, then, on the DesktopDevice property sheet, the data value defined by the Description named value is displayed under the file conversions details Convert to HPC files of the type.
NewExtension	Defines the extension of the file that will be created on the destination device.

Registering a File Filter

Named value

Description