Reference

Source Object

The Source Object is used for all communcations with the data source.

Constructor

twain.SourceManager.OpenSource(Name)

The Source object is only created by a factory on the SourceManger object. The OpenSource method will create a connection to the data source.

Name Description Default Value
Name The name of the data source. Will present a dialog if this is not passed

This method will either return an object of type Source, or it will return None (which indicates that the user cancelled the open).

On failure it raises the following exceptions:

Exception Meaning
excDSOpenFailed The attempt to open the connect to the source failed. The name of the source is returned in the exc_value.

Methods

Source.DSM_Entry(datagroup, dataitem, messageid, message)

This method is used to make a call directly to the TWAIN Source. You can use it to implement any calls which have not been implemented in the DLL. Note that there is a separate method in the SourceManager object for sending messages to the Source Manager.

Be aware that there is a risk associated with using this method. Passing incorrect data may result in memory corruption.

Name Description Default Value
datagroup Data Group identifier. One of the DG_* constants. mandatory
dataitemid Data Item Type identifier. One of the DAT_* constants. mandatory
messageid The command to be performed. One of the MSG_* constants. mandatory
message The data for the operation. This should be built up using the struct python module. In many of the operations, the result is returned in this buffer. mandatory

This method returns the TWAIN Source Manager return value as an integer. This value is one of the TWRC_* values.

Source.RequestAcquire(ShowUI, ShowModal)

This method is ask the twain source to acquire an image.

Name	Description	Default Value
ShowUI	Boolean which tells Data Source to display its User Interface	mandatory
ShowUI	Boolean which tells Data Source that it's display should be modal/td>	mandatory

The method has no return value. On failure it will return one of the excTWCC exceptions.

Source.GetCapability(CapabilityCode)

This method is used to return the configuration for a capability. The configuration information may be a single value (e.g. CAP_FEEDERENABLED), or it may be a current value, a default value and a list of options. Use the twexplore program to see the capabilities of your device.

Name	Description	Default Value
CapabilityCode	One of the CAP_* (Generic Capabilities), ICAP_ (Image Capabilities), ACAP_* (Audio Capabilities) constants, representing the capability you are interested in.	mandatory

The method returns the configuration for a capability. See the section on capabilities for detailed information on these return values.

Source.GetCapabilityCurrent(CapabilityCode)

This method is used to return the current value for a capability. The current value is normally a single value. Use the twexplore program to see the capabilities of your device.

Name	Description	Default Value
CapabilityCode	One of the CAP_* (Generic Capabilities), ICAP_ (Image Capabilities), ACAP_* (Audio Capabilities) constants, representing the capability you are interested in.	mandatory

The method returns the current value for capability. See the section on capabilities for detailed information on these return values.

Source.GetCapabilityDefault(CapabilityCode)

This method is used to return the default value for a capability. The default value is normally a single value. Use the twexplore program to see the capabilities of your device.

Name	Description	Default Value
CapabilityCode	One of the CAP_* (Generic Capabilities), ICAP_ (Image Capabilities), ACAP_* (Audio Capabilities) constants, representing the capability you are interested in.	mandatory

The method returns the default value for capability. See the section on capabilities for detailed information on these return values.

Source.SetCapability(CapabilityCode)

This method is used to set the value for a capability.

Name	Description	Default Value
CapabilityCode	One of the CAP_* (Generic Capabilities), ICAP_ (Image Capabilities), ACAP_* (Audio Capabilities) constants, representing the capability you are interested in.	mandatory
Type	One of the TWTY_* constants. This value is returned by the GetCapability*() methods.	mandatory
Value	The value to which the capability is to be set. This value must be a single value at the moment. Its type depends on what the capability will support. Use the GetCapabilityCurrent() method to find the best type for the capability.	mandatory

There are no values returned.

Source.ResetCapability(CapabilityCode)

This method is used to reset the value ofr a capability to its default value.

Name	Description	Default Value
CapabilityCode	One of the CAP_* (Generic Capabilities), ICAP_ (Image Capabilities), ACAP_* (Audio Capabilities) constants, representing the capability you are interested in.	mandatory

There are no values returned.

Source.GetIdentity()

Returns a dictionary containing the configuration information for the Data Source.

Source.GetSourceName()

Returns the name of the source. This value can be used for re-connecting to the source at a later time.

Source.GetImageInfo()

This method returns information about the image. It can only be called in state 6, i.e. after the image is available in the Data Source. There is no matching 'Set' method for this call. These items have to be set using the Capabilities functionality.

The following items are returned in a dictionary:
XResolution, YResolution, ImageWidth, ImageLength, SamplesPerPixel, BitsPerSample, BitsPerPixel, Planar, PixelType, Compression

Source.GetImageLayout()

This method returns the layout about the image. It can only be called in state 4 or 6, i.e. before or after the image is available in the Data Source.

The values are returned as a tuple as follows:
((left, top, right, bottom) document_number, page_number, frame_number)

Source.SetImageLayout()

This method sets the layout about the image. In particular, it is used to select the image, when the Source user interface is not displayed. It can only be called in state 4, i.e. before the image is available in the Data Source.

Note, that the actual image may differ from the one you requested. Check the Layout again after the image is available.

Name	Description	Default Value
Frame	The frame of the image. This is a tuple of four floats, representing the (left, top, right, bottom) positions. The units are in the current units for the source.	mandatory
DocumentNumber	Integer Document Number.	mandatory
PageNumber	Integer Page Number.	mandatory
FrameNumber	Integer Frame Number	mandatory

Source.XferImageNatively()

This method is used to retrieve the image from the data source. The 'native' form of image transfer, is a windows specific mechanism where the data is placed in the Global Heap and a handle is passed back to our application.

This method returns two values, a Global Heap handle and a count of the number of items pending with the source. The data can be accessed using the GlobalHandle* methods in the twain module. The handle must be freed by your application using the twain.GlobalHandleFree() method. Otherwise it will remain unavailable to windows after your process exits.

Source.XferImageByFile()

This method is used to retrieve the image from the data source. This file name and format should have been previously defined by the SetXferFileName() method.

Source.GetXferFileName()

This call returns the name of the transfer file, which is currently configured in the data source. The call returns two values, the file name and the file format, which is one of the TWFF_* constants.

Source.SetXferFileName()

This call sets the name of the transfer file. If there is no path, the file should be created in the application current directory. , which is currently configured in the data source. The call returns two values, the file name and the file format, which is one of the TWFF_* constants.

Name	Description	Default Value
Filename	The name of the file. f there is no path, the file should be created in the application current directory.	mandatory
File Type	An integer describing the file format. One of the TWFF_* constants.	Current value is unchanged.

Source.CancelOnePendingXfer()

This method is used to cancel the current transfer. It may only be invoked when an image is available in the data source. The number of pending transfers is returned.

Source.CancelAllPendingXfers()

This method is used to cancel all transfer pending in the source. It may only be invoked when an image is available in the data source.

Source.HideUI()

This method is used to hide the user interface, which may have been displayed previously by a call to Source.RequestAquire(). This call may not be made while there are pending transfers in the data source. If there are pending images, call Source.CancelAllPendingXfers() first.

Source.destroy()

This method is used disconnect the Source object from the TWAIN source. This method is called automatically from the destructor. It is provided as a separate method to allow finer grained control over the disconnect process.

Reference

Exception	Meaning
excDSOpenFailed	The attempt to open the connect to the source failed. The name of the source is returned in the exc_value.