IPegasusFileFilter::NextConvertFile

When the user selects a conversion type from the H/PC Explorer File Conversion Properties dialog box, H/PC Explorer calls the IPegasusFileFilter::NextConvertFile method of the file filter that supports the selected conversion.

Syntax

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

At a Glance

Header file:	Replfilt.h
Platforms:	H/PC
Windows CE versions:	1.0 and later

Parameters

nConversion: A counter for converting a single source file into multiple destination files. This parameter will be zero the first time NextConvertFile is called and will be incremented for each successive call. A simple filter should return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) if this parameter is not zero.
pci: Pointer to a PFF_CONVERTINFO structure that contains a pointer to an IPegasusFileFilterSite 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 the nHowToOpen parameter in the IPegasusFileFilterSite::OpenSourceFile and IPegasusFileFilterSite::OpenDestinationFile methods. Any files opened in this way should be closed using the corresponding IPegasusFileFilterSite::CloseSourceFile or IPegasusFileFilterSite::CloseDestinationFile methods.
psf: Pointer to a PFF_SOURCEFILE structure that contains information about the source file.
pdf: Pointer to a PFF_DESTINATIONFILE structure that contains information about the destination file.
pbCancel: Pointer to a variable that receives TRUE if the user cancels the file conversion before it is completed. Otherwise, the variable is set to FALSE. 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 to TRUE.
perr: Address of a filter-defined error value that can be passed (by the H/PC Explorer application) to the IPegasusFileFilter::FormatMessage method. This error value will be ignored unless the return value from NextConvertFile is E_FAIL.

Return Values

NOERROR: The subconversion was successful; proceed to the next subconversion.
HRESULT_FROM_WIN32 (ERROR_CANCELLED): The user canceled the conversion.
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS): The conversion (or last subconversion) was successful. End calls to IPegasusFileFilter::NextConvertFile.
E_FAIL: The perr parameter contained an error value that should be passed to IPegasusFileFilter::FormatMessage.

Remarks

H/PC Explorer calls the IPegasusFileFilter::NextConvertFile method 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 code in the variable pointed to by perr. For more information about filter-defined error codes, see Filter Defined Error Values.

As a file conversion progresses, a file filter should periodically call IPegasusFileFilterSite::ReportProgress to report its progress. H/PC Explorer uses the progress information to update a progress bar that shows the user how much of the conversion has been completed.