LEADTOOLS WIA (Leadtools.Wia assembly) Send comments on this topic. | Back to Introduction - All Topics | Help Version 17.0.3.30
AcquireSimple Method
See Also 
Leadtools.Wia Namespace > WiaSession Class : AcquireSimple Method



version
The WIA version to be used. Possible values are:

Value

Meaning

WiaVersion.Version1 Use WIA version 1.0.
WiaVersion.Version2 Use WIA version 2.0.
owner
Window handle of your application window.
item

This parameter is only used when acquiring from a scanner device while 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 desired scanner item.

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

deviceType
Specifies which type of WIA device to use. Possible values are:

Value

Meaning

WiaDeviceType.Default Generic WIA device. During device enumerations, this constant is used to enumerate all WIA devices. This is the default value.
WiaDeviceType.Scanner The device is a scanner.
WiaDeviceType.DigitalCamera The device is a camera. Note that this type of device is not supported by Windows Vista and later.
WiaDeviceType.StreamingVideo The device contains streaming video. Note that this type of device is not supported by Windows Server 2003, Windows Vista, or later.
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.NoDefault Force displaying the Select Device dialog box even if there is only one device available.
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.
version
The WIA version to be used. Possible values are:

Value

Meaning

WiaVersion.Version1 Use WIA version 1.0.
WiaVersion.Version2 Use WIA version 2.0.
owner
Window handle of your application window.
item

This parameter is only used when acquiring from a scanner device while 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 desired scanner item.

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

deviceType
Specifies which type of WIA device to use. Possible values are:

Value

Meaning

WiaDeviceType.Default Generic WIA device. During device enumerations, this constant is used to enumerate all WIA devices. This is the default value.
WiaDeviceType.Scanner The device is a scanner.
WiaDeviceType.DigitalCamera The device is a camera. Note that this type of device is not supported by Windows Vista and later.
WiaDeviceType.StreamingVideo The device contains streaming video. Note that this type of device is not supported by Windows Server 2003, Windows Vista, or later.
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.NoDefault Force displaying the Select Device dialog box even if there is only one device available.
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.
Acquires one or more images from a WIA source.

Syntax

Visual Basic (Declaration) 
Public Function AcquireSimple( _
   ByVal version As WiaVersion, _
   ByVal owner As IWin32Window, _
   ByVal item As Object, _
   ByVal deviceType As WiaDeviceType, _
   ByVal flags As WiaAcquireFlags _
) As DialogResult
Visual Basic (Usage)Copy Code
Dim instance As WiaSession
Dim version As WiaVersion
Dim owner As IWin32Window
Dim item As Object
Dim deviceType As WiaDeviceType
Dim flags As WiaAcquireFlags
Dim value As DialogResult
 
value = instance.AcquireSimple(version, owner, item, deviceType, flags)
C# 
public DialogResult AcquireSimple( 
   WiaVersion version,
   IWin32Window owner,
   object item,
   WiaDeviceType deviceType,
   WiaAcquireFlags flags
)
C++/CLI 
public:
DialogResult AcquireSimple( 
   WiaVersion version,
   IWin32Window^ owner,
   Object^ item,
   WiaDeviceType deviceType,
   WiaAcquireFlags flags
) 

Parameters

version
The WIA version to be used. Possible values are:

Value

Meaning

WiaVersion.Version1 Use WIA version 1.0.
WiaVersion.Version2 Use WIA version 2.0.
owner
Window handle of your application window.
item

This parameter is only used when acquiring from a scanner device while 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 desired scanner item.

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

deviceType
Specifies which type of WIA device to use. Possible values are:

Value

Meaning

WiaDeviceType.Default Generic WIA device. During device enumerations, this constant is used to enumerate all WIA devices. This is the default value.
WiaDeviceType.Scanner The device is a scanner.
WiaDeviceType.DigitalCamera The device is a camera. Note that this type of device is not supported by Windows Vista and later.
WiaDeviceType.StreamingVideo The device contains streaming video. Note that this type of device is not supported by Windows Server 2003, Windows Vista, or later.
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.NoDefault Force displaying the Select Device dialog box even if there is only one device available.
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.

Example

Visual BasicCopy Code
Public Sub AcquireSimpleExample(ByVal parent As IWin32Window)
   Dim session As WiaSession = New WiaSession()

   ' Initialize and fill the required fields from the WiaAcquireOptions structure
   Dim wiaAcquireOptions As WiaAcquireOptions = wiaAcquireOptions.Empty
   wiaAcquireOptions.MemoryBufferSize = 32 * 1024
   wiaAcquireOptions.DoubleBuffer = True
   session.AcquireOptions = wiaAcquireOptions

   AddHandler session.AcquireEvent, AddressOf session_AcquireSimpleEvent

   session.Acquire(parent, Nothing, WiaAcquireFlags.ShowUserInterface Or WiaAcquireFlags.UseCommonUI)

   RemoveHandler session.AcquireEvent, AddressOf session_AcquireSimpleEvent
   session.Shutdown()
End Sub

Public Sub session_AcquireSimpleEvent(ByVal sender As Object, ByVal e As WiaAcquireEventArgs)
   Application.DoEvents()

   If (e.Flags And WiaAcquiredPageFlags.StartOfPage) = WiaAcquiredPageFlags.StartOfPage Then
      Console.WriteLine("Beginning of data transfer.")
   ElseIf (e.Flags And WiaAcquiredPageFlags.EndOfPage) = WiaAcquiredPageFlags.EndOfPage Then
      Console.WriteLine("End of data transfer.")
   End If

   If Not e.Image Is Nothing Then
      ' You can load the image here.
   End If
End Sub
C#Copy Code
public void AcquireSimpleExample(IWin32Window parent)
{
   WiaSession wiaSession = new WiaSession();

   // Initialize and fill the required fields from the WiaAcquireOptions structure
   WiaAcquireOptions wiaAcquireOptions = WiaAcquireOptions.Empty;
   wiaAcquireOptions.MemoryBufferSize = 32 * 1024;
   wiaAcquireOptions.DoubleBuffer = true;
   wiaSession.AcquireOptions = wiaAcquireOptions;

   wiaSession.AcquireEvent += new EventHandler<WiaAcquireEventArgs>(wiaSession_AcquireSimpleEvent);

   wiaSession.Acquire(parent, null, WiaAcquireFlags.ShowUserInterface | WiaAcquireFlags.UseCommonUI);

   wiaSession.AcquireEvent -= new EventHandler<WiaAcquireEventArgs>(wiaSession_AcquireSimpleEvent);
   wiaSession.Shutdown();
}

public void wiaSession_AcquireSimpleEvent(object sender, WiaAcquireEventArgs e)
{
   Application.DoEvents();

   if ((e.Flags & WiaAcquiredPageFlags.StartOfPage) == WiaAcquiredPageFlags.StartOfPage)
      Console.WriteLine("Beginning of data transfer.");
   else if ((e.Flags & WiaAcquiredPageFlags.EndOfPage) == WiaAcquiredPageFlags.EndOfPage)
      Console.WriteLine("End of data transfer.");

   if (e.Image != null)
   {
      // You can load the image here.
   }
}

Remarks

This is a high level acquire function that you can call directly. When using this function, the following functions are called internally:

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

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

When performing memory transfer you need to add the WiaSession.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 WiaSession.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 become available:

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

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

Note:

Be aware that when the ShowUserInterface flag is set for any of the acquire methods, the values of any properties set by using 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.

Therefore, do not set the ShowUserInterface flag if you wish 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.

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 while the ShowUserInterface flag is set then it is not necessary to add the WiaSession.AcquireEvent event. Microsoft’s WIA 2.0 Acquire dialog does not provide an event but performs all the processing and returns with the number of files that were saved along with their paths through the FilesCount and FilesPaths properties.

For more information, refer to How to Acquire from the WIA Source.

Requirements

Target Platforms: Microsoft .NET Framework 2.0, Windows 2000, Windows XP, Windows Server 2003 family, Windows Server 2008 family, Windows Vista, Windows 7

See Also