In This Topic ▼

Acquire Method

Summary

Acquires one or more images from a WIA source.

Syntax

C++

public DialogResult Acquire( 
   IntPtr owner, 
   object item, 
   WiaAcquireFlags flags 
)

  
Public Function Acquire( _ 
   ByVal owner As IntPtr, _ 
   ByVal item As Object, _ 
   ByVal flags As WiaAcquireFlags _ 
) As DialogResult

public: 
DialogResult Acquire(  
   IntPtr owner, 
   Object^ item, 
   WiaAcquireFlags flags 
)

Parameters

owner
Window handle of your application window.

item
This parameter is only used when acquiring from scanner device and the ShowUserInterface flag is NOT set. Use this parameter to specify the scanner's paper source (Feeder or Flatbed).

This flag is optional. If you are using WIA 1.0 you can change the paper source by changing the WiaPropertyId.ScannerDeviceDocumentHandlingSelect property value for the root item or by enumerating the available scanner items and passing the item to be used for scanning.

If you are using WIA 2.0 either enumerate the available scanner items and pass the item to be used for scanning, or pass null (Nothing in VB), in which case the enumeration will be performed internally and the first enumerated item will be used as the source item.

flags
Flag that determines certain actions of the WIA image acquisition selection dialog box. Possible values are:

Value	Meaning
WiaAcquireFlags.None	Default behavior for the device image acquisition dialog box.
WiaAcquireFlags.SingleImage	Restrict image selection to a single image in the device image acquisition dialog box. This flag is not available if you are using WIA version 2.0.
WiaAcquireFlags.ShowUserInterface	Show the manufacturer's image acquisition dialog box.
WiaAcquireFlags.UseCommonUI	Use the system user interface (UI), if available, rather than the vendor-supplied UI. If the system UI is not available, the vendor UI is used.

Return Value

One of the DialogResult values. If an error occurs, an exception is thrown.

Remarks

This function will acquire single or multiple images from the selected WIA device.

Make sure to call WiaSession.Startup and then call any of the WiaSession.SelectDeviceDlg or WiaSession.SelectDevice functions before calling this function.

You can change the AcquireOptions property members before calling this method to control some options while acquiring from the WIA source.

Set this method for memory transfer or file transfer by performing one of the following:

Set the transfer mode you wish to use through the WiaSession.SetProperties method.
Set the transfer mode by setting the value parameter to any of the transfer modes available through the WiaTransferMode and then call the WiaSession.SetPropertyLong method passing WiaPropertyId.ItemTymed for the propertyId parameter of this method.

When performing memory transfer you need to add the AcquireEvent event to receive the acquired page(s). The event will also provide you with the percent completion of the page transfer progress.

When performing file transfer it is optional to add the AcquireEvent event since the event will only provide you with the saved file path and the percent completion of the file saving process.

When performing file transfer two properties within the WiaSession class will become available:

FilesCount - contains the count of the saved files.
FilesPaths - a collection that contains the saved file paths and filenames.

To cancel the acquire operation you need to add the AcquireEvent event and set the Cancel member of the WiaAcquireEventArgs to true.

Value	Meaning
WiaAcquireFlags.None	Default behavior for the device image acquisition dialog box.
WiaAcquireFlags.SingleImage	Restrict image selection to a single image in the device image acquisition dialog box. This flag is not available if you are using WIA version 2.0.
WiaAcquireFlags.ShowUserInterface	Show the manufacturer's image acquisition dialog box.
WiaAcquireFlags.UseCommonUI	Use the system user interface (UI), if available, rather than the vendor-supplied UI. If the system UI is not available, the vendor UI is used.

Note:	If the ShowUserInterface flag is set for any of the acquire methods, then be aware that some of the previously set/changed user properties (using any of the SetPropertyXxx or SetProperties methods) will be overwritten by the Microsoft's image acquisition dialog box. Microsoft's image acquisition dialog box sets its own initialization properties like the current intent (image type), selected area (left, top, width and height), paper source and duplex mode, ...etc. In order to suppress the manufacturer's image acquisition dialog and acquire directly from the specified source item through the item parameter using the values set through the SetPropertyXxx and SetProperties methods, do not set the ShowUserInterface flag.
Note:	While running a Win32 version application that calls this function on Windows VISTA 64-Bit we have noticed that the FilesCount and FilesPaths properties will not be updated with the required information. This is a known limitation of Microsoft's WIA toolkit.
Note:	If you are using WIA 2.0 and the ShowUserInterface flag is set it is not necessary to add the AcquireEvent event. Microsoft's WIA 2.0 acquire dialog does not provide an event but performs all the processing and returns with a count of the number of files saved and their paths through the FilesCount and FilesPaths properties.