Implementing and Using a File Filter (Windows CE 5.0)

  • Article

Send Feedback

Windows 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 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 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 ICeFileFilter interface and methods.

  3. ActiveSync calls the QueryInterface method for the file filter's ICeFileFilterOptions interface.

    If this interface is available, Windows CE then calls ICeFileFilterOptions::SetFilterOptions with a correctly initialized CFF_CONVERTOPTIONS structure. The bNoModalUI member 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::FilterOptions to 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 CE Explorer on the Windows CE-based device.
  2. ActiveSync displays the File Conversion Properties dialog box to prompt the user for a conversion type.
  3. ActiveSync calls ICeFileFilter::NextConvertFile for 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_SOURCEFILE structures.

Within the ICeFileFilter::NextConvertFile method

  1. Call ICeFileFilterSite::OpenSourceFile to open the source file.

  2. Call ICeFileFilterSite::OpenDestinationFile to open the destination file.

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

  4. Convert the data.

    Conversion can include independent software vendor (ISV) developed code and RAPI calls.

  5. Check the status of the NextConvertFilepbCancel parameter 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 OpenDestinationFile to write the converted data to the stream file that was opened.

  7. Call ICeFileFilterSite::ReportProgress occasionally 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::ReportLoss to 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::FormatMessage for the file filter, in order to properly format the message.

  9. Call ICeFileFilterSite::CloseSourceFile to close the source file, then call ICeFileFilterSite::CloseDestinationFile to close the destination file.

See Also

Converting File Formats

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.