IWiaPreview::GetNewPreview method

Caches internally the unfiltered image returned from the driver.

Syntax

HRESULT GetNewPreview(
  [in] IWiaItem2            *pWiaItem2,
  [in] LONG                 lFlags,
  [in] IWiaTransferCallback *pWiaTransferCallback
);

Parameters

pWiaItem2 [in]

Type: IWiaItem2*

Specifies a pointer to the IWiaItem2 item for the image.

lFlags [in]

Type: LONG

Currently unused. Should be set to zero.

pWiaTransferCallback [in]

Type: IWiaTransferCallback*

Specifies a pointer to the calling application's IWiaTransferCallback interface.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

An application must call IWiaPreview::GetNewPreview before it calls IWiaPreview::DetectRegions.

IWiaPreview::GetNewPreview sets the WIA_DPS_PREVIEW property (and resets it before it returns, unless it was set before). This lets the driver and hardware, as well as the image processing filter, know that the item is a preview scan.

Internally, the Windows Image Acquisition (WIA) 2.0 preview component creates an instance of the driver's image processing filter by calling GetExtension on pWiaItem2. The WIA 2.0 preview component does this when the application calls IWiaPreview::GetNewPreview. The WIA 2.0 preview component also initializes the filter in IWiaPreview::GetNewPreview. The same filter instance is used by the WIA 2.0 preview component during a call to IWiaPreview::UpdatePreview.

Before calling into the WIA 2.0 preview component, an application should call CheckExtension to make sure that the driver comes with an image processing filter. It should call CheckExtension on the item that it would pass to IWiaPreview::GetNewPreview. It is useless to provide live previews without an image processing filter. If an application calls IWiaPreview::GetNewPreview for a driver without an image processing filter, the call will fail.

Examples

CheckImgFilter checks if the driver has an image processing filter. Before calling into the preview component, an application should ensure that the driver has an image processing filter.

HRESULT
CheckImgFilter(
   IN  IWiaItem2 *pWiaItem2,
   OUT BOOL      *pbHasImgFilter)
{
   HRESULT     hr = S_OK;

   if (!pWiaItem2 || !pbHasImgFilter)
   {
      hr = E_INVALIDARG;
   }

   if (SUCCEEDED(hr))
   {
     *pbHasImgFilter = FALSE;
   }

   if (SUCCEEDED(hr))
   {
      BSTR    bstrFilterString = SysAllocString(WIA_IMAGEPROC_FILTER_STR);

      if (bstrFilterString)
      {
         hr = pWiaItem2->CheckExtension(0,
                                        bstrFilterString,
                                        IID_IWiaSegmentationFilter,
                                        pbHasImgFilter);

         SysFreeString(bstrFilterString);
         bstrFilterString = NULL;
      }
      else
      {
         hr = E_OUTOFMEMORY;
      }
   }

   return hr;

}

DownloadPreviewImage downloads image data from the scanner by calling the preview component's IWiaPreview::GetNewPreview method. It then calls DetectSubregions if the application user wants to invoke the segmentation filter, which creates a child item under pWiaItem2 for each region it detects. See DetectRegions for the DetectSubregions method used in this example.

In this example, the application user sets m_bUseSegmentationFilter by clicking a check box. If the application supports this, it should first check that the driver has a segmentation filter by calling CheckExtension. See IWiaPreview::GetNewPreview for the CheckImgFilter method example that shows how this can be done.

HRESULT
DownloadPreviewImage(
   IN IWiaItem2 *pWiaFlatbedItem2)
{
   HRESULT hr              = S_OK;
   BOOL    bHasImgFilter   = FALSE;

   IWiaTransferCallback *pAppWiaTransferCallback = NULL;

   hr = CheckImgFilter(pWiaFlatbedItem2, &bHasImgFilter)

   if (SUCCEEDED(hr))
   {
      if (bHasImgFilter)
      {
         IWiaPreview *pWiaPreview = NULL;

         // In this example, the AppWiaTransferCallback class implements 
         // the IWiaTransferCallback interface.  
         // The constructor of AppWiaTransferCallback sets the reference count to 1.
         pAppWiaTransferCallback = new AppWiaTransferCallback();

         hr = pAppWiaTransferCallback ? S_OK : E_OUTOFMEMORY;

         if (SUCCEEDED(hr))
         {
            // Acquire image from scanner
            hr = m_pWiaPreview->GetNewPreview(pWiaFlatbedItem2,
                                              0,
                                              pAppWiaTransferCallback);    
         }

         //
         // Check the application UI for whether the user wants
         // to use the segmentation filter indicated by the value 
         // of m_bUseSegmentationFilter.
         //
         // m_FlatbedPreviewStream is the stream that
         // AppWiaTransferCallback::GetNextStream returned for the
         // flatbed item.
         // This stream is where the image data is stored after
         // the successful return of GetNewPreview.
         // The stream is passed into the segmentation filter
         // for region detection.
         if (SUCCEEDED(hr) && m_bUseSegmentationFilter)
         {
            DetectSubregions(m_FlatbedPreviewStream, pWiaFlatbedItem2);
         }

         if (pAppWiaTransferCallback)
         {
            // If the call to GetNewPreview was successful, the
            // preview component calls AddRef on the callback so
            // this call doesn't delete the object.

            pAppWiaTransferCallback->Release();
         }

      }
      else
      {
         // Do not create an instance of preview component if the driver does
         // not come with an image processing filter.
         // You can use segmentation filter, however, if the driver
         // comes with one (omitted here).
      }
   }

   return hr;
}

Requirements