Implementing and Using a File Filter

The Windows CE SDK 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.

    See Registering a File Filter.

  2. Implement the ICeFileFilter interface and methods.

    For a list of file filter interfaces, see Lists of Functions and Interfaces.

  3. Windows CE Services calls the QueryInterface method for the file filter's ICeFileFilterOptions interface. If this interface is available, it 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, the ICeFileFilter::FilterOptions method should be implemented. This allows a user to select among the conversion options supported by the file filter.

    To use a file filter
  1. The user uses the drag-and-drop method to transfer a file between Windows CE Explorer on the desktop and 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 file filter's ICeFileFilter::NextConvertFile method to perform the custom file conversion. 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. Read data from the stream file that was opened using the OpenSourceFile method.
    4. Convert the data. This can include ISV-developed code and remote application programming interface (RAPI) calls.
    5. Check on the status of the NextConvertFile pbCancel parameter occasionally to ensure that the user has not aborted the conversion process. If the conversion has been aborted, perform all cleanup operations and exit.
    6. Write the converted data to the stream file that was opened using the OpenDestinationFile method.
    7. Report the progress of the file conversion by occasionally calling the ICeFileFilterSite::ReportProgress method. Windows CE Services uses this information to update a status bar showing the percentage completion of the conversion. You should limit your use of this method because it can add substantially to the conversion time.
    8. Report data that is intentionally discarded during conversion by calling the ICeFileFilterSite::ReportLoss method. 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 file filter's ICeFileFilter::FormatMessage method, in order to properly format the message.
    9. Close the source file, using the ICeFileFilterSite::CloseSourceFile method, and then close the destination file, using the ICeFileFilterSite::CloseDestinationFile method.