ICeFileFilter::NextConvertFile

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method is called by ActiveSync when the user selects a conversion type from the ActiveSync conversion selection dialog box.

Syntax

STDMETHODIMP ICeFileFilter::NextConvertFile(
  int nConversion,
  PFF_CONVERTINFO* pci,
  PFF_SOURCEFILE* psf,
  PFF_DESTINATIONFILE* pdf,
  volatile BOOL* pbCancel,
  PR_ERROR* perr
);

Parameters

• nConversion
  [in] Counter for converting a single source file into multiple destination files. This parameter is zero the first time NextConvertFile is called and is incremented for each successive call. A simple filter should return HRESULT_FROM_WIN32**(ERROR_NO_MORE_ITEMS)** if this parameter is not zero.

• pci
  [in] Pointer to a CFF_CONVERTINFO structure that contains a pointer to an ICeFileFilterSite object. A file filter uses this interface to create an IStream or IStorage object to read the contents of the source file or to write to the destination file. The type of interface object to create is determined by the nHowToOpen parameter in the ICeFileFilterSite::OpenSourceFile and ICeFileFilterSite::OpenDestinationFile methods. Any files opened in this way should be closed using the corresponding ICeFileFilterSite::CloseSourceFile or ICeFileFilterSite::CloseDestinationFile method.

• psf
  [in] Pointer to a CFF_SOURCEFILE structure that contains information about the source file.

• pdf
  [in] Pointer to a CFF_DESTINATIONFILE structure that contains information about the destination file.

• pbCancel
  [in] Pointer to a Boolean that is set TRUE if the user cancels the file conversion before it is completed, or set FALSE otherwise. Because this variable is updated asynchronously by another thread, its contents can change at any time. A file filter must check this variable regularly during the conversion process, and return ERROR_CANCELLED, after cleaning up, if it is ever set TRUE.

• perr
  [out] Pointer to a filter-defined error value that can be passed by the ActiveSync application to the ICeFileFilter::FormatMessage method. This error value is ignored unless the return value from NextConvertFile is E_FAIL.

Return Value

The following table shows the possible return values for this method.

Remarks

The Explorer window for the Windows Embedded CE–based device calls NextConvertFile repeatedly, incrementing the nConversion parameter, until the return value is ERROR_NO_MORE_ITEMS. A simple filter should return NOERROR the first time this method is called, and thereafter return HRESULT_FROM_WIN32**(ERROR_NO_MORE_ITEMS)**. Alternatively, a file filter can return E_FAIL and specify a filter-defined error value in the variable pointed to by perr.

As a file conversion progresses, a file filter should periodically call ICeFileFilterSite::ReportProgress to report its progress. ActiveSync uses the progress information to update a progress bar that shows the user how much of the conversion is complete.

If any important data is intentionally discarded by a file filter during the conversion process, the filter should call ICeFileFilterSite::ReportLoss to report the loss. When calling this ReportLoss, the filter specifies a message that explains the data loss, and ActiveSync formats and displays the message in a message box when the file conversion has completed.

Requirements

See Also

Reference

ICeFileFilter::FormatMessage
ICeFileFilterSite::CloseDestinationFile
ICeFileFilterSite::CloseSourceFile
ICeFileFilterSite::OpenDestinationFile
ICeFileFilterSite::OpenSourceFile
ICeFileFilterSite::ReportLoss
ICeFileFilterSite::ReportProgress
CFF_DESTINATIONFILE
CFF_CONVERTINFO
CFF_SOURCEFILE

Other Resources

IStream
IStorage