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



owner
Window handle of your application window.
item

This parameter is only used if you are acquiring from a 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 since 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.

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.
owner
Window handle of your application window.
item

This parameter is only used if you are acquiring from a 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 since 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.

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.
Acquires one or more images from a WIA source directly to file(s).

Syntax

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

Parameters

owner
Window handle of your application window.
item

This parameter is only used if you are acquiring from a 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 since 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.

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.

Example

Visual BasicCopy Code
Public Sub AcquireToFileExample(ByVal parent As IWin32Window)
      If (Not WiaSession.IsAvailable(WiaVersion.Version1)) Then
         MessageBox.Show("WIA version 1.0 not installed.")
         Return
      End If

      Dim session As WiaSession = New WiaSession()
      session.Startup(WiaVersion.Version1)

      Dim res As DialogResult = session.SelectDeviceDlg(parent, WiaDeviceType.Default, WiaSelectSourceFlags.NoDefault)
      If res <> DialogResult.OK Then
         MessageBox.Show("Error selecting WIA device.")
         session.Shutdown()
         Return
      End If

      ' Initialize and fill the required fields from the WiaAcquireOptions structure
      Dim wiaAcquireOptions As WiaAcquireOptions = wiaAcquireOptions.Empty
      wiaAcquireOptions.FileName = Path.Combine(LEAD_VARS.ImagesDir, "WiaTest.bmp")
      wiaAcquireOptions.OverwriteExisting = True
      wiaAcquireOptions.Append = False
      wiaAcquireOptions.SaveToOneFile = False
      session.AcquireOptions = wiaAcquireOptions

      AddHandler session.AcquireFileEvent, AddressOf session_AcquireFileEvent

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

      ' Display listing of all paths and filenames for the saved files(s).
      If session.FilesCount > 0 Then
         Dim strMsg As String = "Acquired page(s) were saved to:" & Constants.vbLf + Constants.vbLf
         Dim i As Integer = 0
         Do While i < session.FilesCount
            Dim strTemp As String = String.Format("{0}" & Constants.vbLf, session.FilesPaths(i))
            strMsg &= strTemp
            i += 1
         Loop
         MessageBox.Show(strMsg)
      End If

      RemoveHandler session.AcquireFileEvent, AddressOf session_AcquireFileEvent
      session.Shutdown()
   End Sub

   Public Sub session_AcquireFileEvent(ByVal sender As Object, ByVal e As WiaAcquireFileEventArgs)
      Console.WriteLine(e.Percent)
   End Sub


Public NotInheritable Class LEAD_VARS
   Public Const ImagesDir As String = "C:\Users\Public\Documents\LEADTOOLS Images"
End Class
C#Copy Code
public void AcquireToFileExample(IWin32Window parent)
   {
      if (!WiaSession.IsAvailable(WiaVersion.Version1))
      {
         MessageBox.Show("WIA version 1.0 not installed.");
         return;
      }

      WiaSession wiaSession = new WiaSession();
      wiaSession.Startup(WiaVersion.Version1);

      DialogResult res = wiaSession.SelectDeviceDlg(parent, WiaDeviceType.Default, WiaSelectSourceFlags.NoDefault);
      if (res != DialogResult.OK)
      {
         MessageBox.Show("Error selecting WIA device.");
         wiaSession.Shutdown();
         return;
      }

      // Initialize and fill the required fields from the WiaAcquireOptions structure
      WiaAcquireOptions wiaAcquireOptions = WiaAcquireOptions.Empty;
      wiaAcquireOptions.FileName = Path.Combine(LEAD_VARS.ImagesDir, "WiaTest.bmp");
      wiaAcquireOptions.OverwriteExisting = true;
      wiaAcquireOptions.Append = false;
      wiaAcquireOptions.SaveToOneFile = false;
      wiaSession.AcquireOptions = wiaAcquireOptions;

      wiaSession.AcquireFileEvent += new EventHandler<WiaAcquireFileEventArgs>(wiaSession_AcquireFileEvent);

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

      // Display a listing of all paths and filenames for the saved files(s).
      if(wiaSession.FilesCount > 0)
      {
         string strMsg = "Acquired page(s) were saved to:\n\n";
         for (int i = 0; i < wiaSession.FilesCount; i++)
         {
            string strTemp = string.Format("{0}\n", wiaSession.FilesPaths[i]);
            strMsg += strTemp;
         }
         MessageBox.Show(strMsg);
      }

      wiaSession.AcquireFileEvent -= new EventHandler<WiaAcquireFileEventArgs>(wiaSession_AcquireFileEvent);
      wiaSession.Shutdown();
   }

   public void wiaSession_AcquireFileEvent(object sender, WiaAcquireFileEventArgs e)
   {
      Console.WriteLine(e.Percent);
   }


static class LEAD_VARS
{
   public const string ImagesDir = @"C:\Users\Public\Documents\LEADTOOLS Images";
}

Remarks

This function will acquire single or multiple images from the selected WIA device and save them directly to file(s).

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

Change the Leadtools.Wia.WiaSession.AcquireOptions property members before calling this method to control the saved filenames and paths, along with other options while acquiring from the WIA source.

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 name and the percent completion of the file saving process.

Two properties within the WiaSession class will become available when using this function:

  • 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:

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.

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 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 of 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