Implementing and Using a File Filter

The CD-ROM that accompanies this documentation includes a sample file filter named Copyfilt that imports a binary file (.bin) from a desktop computer to a binary file (.pbn) on a Windows CE–based device. The Copyfilt sample file filter demonstrates basic operations for implementing a file filter, which are described in the following procedure.

    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. Windows CE Services calls the QueryInterface method for the file filter's ICeFileFilterOptions interface.
   • If this interface is available, Windows CE then calls the ICeFileFilterOptions::SetFilterOptions method with a correctly initialized CFF_CONVERTOPTIONS structure. The bNoModalUI member specifies whether the converter is allowed to bring up modal UI while performing the conversion.

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

    To use 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 device.
2. Windows CE Services prompts the user for a conversion type, using the File Conversion Properties dialog box.
3. Windows CE Services calls the ICeFileFilter::NextConvertFile method for the file filter to perform the custom 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. Use the OpenSourceFile method to read data from the stream file that was opened.
4. Convert the data.

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

5. Check the status of the NextConvertFile pbCancel parameter occasionally to ensure that the user has not stopped the conversion process.

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

6. Use the OpenDestinationFile method to write the converted data to the stream file that was opened.
7. Call the ICeFileFilterSite::ReportProgress method occasionally to report the progress of the file conversion.

   Windows CE Services uses this information to update a status bar that shows the percentage of the conversion that is complete. You should limit your use of this method because it can add substantially to the conversion time.

8. Call the ICeFileFilterSite::ReportLoss method to report data that is intentionally discarded during conversion.

   Windows CE Services displays a message with this information when the file conversion is complete. Depending on the error format passed in the call, Windows CE Services may call the ICeFileFilter::FormatMessage method for the file filter, in order to properly format the message.

9. Use the ICeFileFilterSite::CloseSourceFile method to close the source file, and then use the ICeFileFilterSite::CloseDestinationFile method to close the destination file.