Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

Windows Embedded CE file filters are COM objects, usually compiled into DLLs, that reside on the desktop computer. ActiveSync uses these filters to convert file formats as files are transferred.

Because hand-held Windows Embedded CE-based devices generally have less storage space and RAM than desktop computers, their file formats are usually more compact than those for the same applications running on desktop computers. The size reduction is usually achieved by omitting functionality that is not as likely to be needed on a Windows Embedded CE-based device.

To implement a file filter

  1. Register the file filter DLL.

    For a description of how to register a file filter, see Registering a File Filter.

  2. Implement the ICeFileFilterinterface and methods.

  3. ActiveSync calls the QueryInterfacemethod for the file filter's ICeFileFilterOptionsinterface.

    If this interface is available, Windows Embedded CE then calls ICeFileFilterOptions::SetFilterOptionswith a correctly initialized CFF_CONVERTOPTIONSstructure. The bNoModalUImember specifies whether the converter is allowed to display a modal user interface while performing the conversion.

    For a file filter that includes selectable conversion options, implement ICeFileFilter::FilterOptionsto allow users to select among the conversion options supported by the file filter.
Using a file filter

  1. The user transfers a file by dragging it between Windows Explorer on the desktop computer and Windows Embedded CE Explorer on the Windows Embedded CE-based device.

  2. ActiveSync displays the File Conversion Propertiesdialog box to prompt the user for a conversion type.

  3. ActiveSync calls ICeFileFilter::NextConvertFilefor the file filter to perform the file conversion.

  4. Information about the file conversion and about the source and destination files is passed by pointers to the CFF_CONVERTINFO, CFF_DESTINATIONFILE, and CFF_SOURCEFILEstructures.

Within the ICeFileFilter::NextConvertFilemethod

  1. Call ICeFileFilterSite::OpenSourceFileto open the source file.

  2. Call ICeFileFilterSite::OpenDestinationFileto open the destination file.

  3. Call OpenSourceFileto read data from the stream file that was opened.

  4. Convert the data.

    Conversion can include custom code and RAPI calls.

  5. Check the status of the NextConvertFile  pbCancelparameter periodically to confirm that the user has not stopped the conversion process.

    If the conversion has been stopped, perform all cleanup operations, then exit.

  6. Use OpenDestinationFileto write the converted data to the stream file that was opened.

  7. Call ICeFileFilterSite::ReportProgressoccasionally to report the progress of the file conversion.

    ActiveSync uses this information to update a status bar that shows the percentage of the conversion completed. Repeated calls to this method can add substantially to the conversion time.

  8. Call ICeFileFilterSite::ReportLossto report data that is intentionally discarded during conversion.

    ActiveSync displays a message with this information when the file conversion is complete. Depending on the error format passed in the call, ActiveSync might call ICeFileFilter::FormatMessagefor the file filter, in order to properly format the message.

  9. Call ICeFileFilterSite::CloseSourceFileto close the source file, then call ICeFileFilterSite::CloseDestinationFileto close the destination file.

See Also