Required functions

The Imaging Toolkit allows applications to perform the imaging process without any specific knowledge of how to communicate with a printer. With the Imaging Toolkit, you need only to create an instance of LITScan, and then call those APIs to complete the imaging process. The Imaging Toolkit API consists of public functions of the class LITScan, not all of which are needed for every application. This Imaging Toolkit supports profile names and file names that can contain ISO-8859-1/2/5 characters.

In order for the imaging process to take place, you must create a profile and receive the scanned image.

Creating a profile

A profile describes scan job parameters such as the contrast, depth, duplex, orientation, resolution, size, and type. The profile also determines where the scanned image is sent. This is specified by an IP address and a TCP port number.

As part of creating a profile, a socket must be created to listen for a connection on the TCP port that is specified by the profile.

Note: Make sure the socket is created before you send the profile to the printer. This way, the socket can be bound to the exact port number that was sent to the printer.

Receiving a scanned file

When you select the profile on the printer control panel, the printer connects to the socket and sends the image(s), along with metadata. Metadata is not part of the actual image data, but is rather information used as a communication tool between the printer and the computer.

For example, if you scan more than one page in a format the does not allow multiple pages, the printer sends each page as a separate file with metadata saying the file is complete, and another file is starting. When the printer is done sending the images, it closes the connection and the process is complete.

Basic API functions of LITScan

Basic API

What it does

public LITScan() throws Exception

This creates an instance of LITScan after initializing the Toolkit with the default configuration. The default configuration file, config.properties, should reside in the same location where the .jar file resides. If the Toolkit fails to load the file, then the Toolkit initializes with the default values.

During initialization, the Toolkit:

  • configures the library with the database connection and then connects to the library.

  • if used in a cluster environment, sets the Toolkit for cluster. If SinglePort=TRUE, then this API creates a receiving port using the port number specified in the configuration file. Since only a single socket can be opened with a specific port number, another instance of LITScan with the same port number cannot be created.

Exceptions:

  • SQLException, if the database connection fails

  • Socket-in-use exception, if a server socket cannot be created

public LITScan(String configFile)
throws Exception

This creates an instance of LITScan with a user-defined configuration. The user application can pass the user-defined path where the configuration file resides. If the Toolkit fails to load the file, then the Toolkit initializes with the default values.

public ScanInfo[] getInitScanContext()

This returns the context ID, MFP IP address, output location, and profile name of the scan contexts that where not released by the Toolkit. This API is generally used after creating an instance of the LITScan as it returns the scan contexts created at the previous instance. For more information, see Persistency and removing an unreachable profile.

public long createContext
(final String ipAdd,
final String profile,
final String filename)
throws Exception

This creates a data structure called a scan context, which contains information about the MFP, scan settings, and label name, among others, and returns a unique long integer value that identifies the scan context.

To use this API, the user has to send the following parameters:

ipAdd—This is the IP address of the MFP used to upload the scan profile.

profile—This is the name of the scan profile on the MFP.

filename—This is the full output file name for stored images.

Exceptions:

  • IllegalArgumentException, if the IP address of the MFP, profile name, or directory is not valid

  • “Illegal MFP” message, if the MFP is not found on the network

  • “Image acquisition failed. Unlicensed MFP” message, if the MFP is not licensed

public long createContext
(final String ipAdd,
final String profile
final int port) throws Exception

This creates a data structure called a scan context which contains information about the MFP, scan settings, and label name, among others, and returns a unique long integer value that identifies the scan context.

To use this API, the user has to send the following parameters:

ipAdd—This is the IP address of the MFP used to upload the scan profile.

profile—This is the name of the scan profile on the MFP.

port—This is the number of the port that receives the images.

Note: If zero is passed as a TCP port number, then the image is scanned on the first available port.

Exceptions:

  • IllegalArgumentException, if the IP address of the MFP, profile name, or directory is not valid.

  • “Illegal MFP” message, if the MFP is not found on the network.

  • “Image acquisition failed. Unlicensed MFP” message, if the MFP is not licensed.

public void
setObserver(final Observer observer)

This sets the user application as an observer that gets notifications of scans from the Toolkit.

public void
setSettings(final long contextID, 
Map sm)throws Exception

This lets users change the multiple scan settings of a particular scan context specified by the context ID at any one call by passing the map of the key/value pair. "Key" is the setting name, and "value" is the supported scan value for that field. For more information about scan settings that the Toolkit supports and their supported values, see Scan settings.

Exception:

IllegalArgumentException exception is thrown, if the new Map fails to pass the scan settings verification.

public Map
getSettings(final long contextID)

This returns the map that holds the scan settings and its value in key/value pair of the scan context identified by the index. Index is the unique long integer value returned by the createContext API.

public void
cancelScan(final long contextID)

This cancels the scan job of the scan context identified by the context ID.

public void existScan()

This terminates the entire operation handled by the Toolkit.

public int
removeProfile(final long contextID) 
throws Exception

This removes the uploaded profile from the MFP that is specified in the scan context.

Parameter:

contextID—This is the ID of the scan context which is identified by a unique long integer value.

Exception:

ObjectStoreException, if the API fails to remove the profile from the MFP

public int
removeProfile (String profileName,
String mfpIPAddress)
throws Exception

This removes the uploaded profile from the MFP that is specified in the profile name and MFP IP address in the parameters.

Parameter:

profileName—This is the name of the scan profile on the MFP.

mfpIPAddress—This is the IP address of the MFP.

Exception:

ObjectStoreException, if the API fails to remove the profile from the MFP

public void
scanBlock(final long contextID) 
throws Exception

This creates and sends a scan profile to the printer, and saves the returned image after the profile is executed. Until the profile is executed or cancelled, this API does not return to the user application. This API cannot be used if SinglePort is set to TRUE.

Parameter:

contextID—This is the ID of the scan context which is identified by a unique long integer value.

Exception:

“Scan Context is in use” message, if the specified scan context is currently in operation

public void
scanNoBlock(final long contextID) 
throws Exception

This creates and sends a scan profile to the printer, and saves the returned image after the profile is executed. This is a non-blocking call.

Parameter:

contextID—This is the ID of the scan context which is identified by a unique long integer value.

Exception:

“Scan Context is in use” message, if the specified scan context is currently in operation

public void
releaseContext(final long contextID)

This deletes a specified scan context. If you are using the Toolkit with a database, then this deletes data from the database.

public void 
setOutputFile(final long contextID, 
final String directory, 
final String fileName)

This provides the output path of the directory where the scanned image file is stored.

public void
setPortRange (int lowerPort,
int upperPort)

This is used as an API to set lower and upper port range values (between 1024 and 65535).

If port range settings are left blank, then the server will attempt to open a socket on the first available port. If both the lower and upper port numbers are set to -1, then the port range function will be disabled, and any previously set port ranges will be deleted.

An IllegalArgumentException will occur with the message “Illegal port range” if:

  • The lower port number is less than 1024.

  • The upper port number is greater than 65535.

  • The lower port number is greater than the upper port number.


Receiving all images on the same port

You can set the Imaging Toolkit to receive all scanned images on a specific port using the SinglePort setting. To specify a particular port, change the following settings in config.properties:

Notes:

Persistency and removing an unreachable profile

Users can store the created scan context to the Firebird database. If ApplyDatabase is set to "true" in the configuration file and database connection is successful, then the scan context data will be stored in the database. It will remain in the database until you call the releaseContext API.

This stored information can be retrieved by the user using the ScanInfo[ ] getInitScanContext() API. This API returns all the scan context that has been created in the previous instance of the Imaging Toolkit as a list of ScanInfo objects. Each ScanInfo object contains the scan context ID, profile name, MFP IP address, and output directory of the previously created scan context. Use this API after creating an instance of LITScan during the initialization of the application.

The attributes of ScanInfo are contextID (long), mfpIpAddress (string), outputLocation (string), and ProfileName (string). Users can access them by using the following functions:

ScanInfo class function

What it does

public long getContextID()

Returns the scan context ID as a long integer

public String getMfpIPAddress()

Returns MFP IP address of the scan context

public String getOutputLocation()

Returns the output location of the scan context

public String getProfileName()

Returns the name of the profile


Profiles that are uploaded to the MFP and not removed if the Imaging Toolkit unexpectedly shuts down are no longer executable. These profiles are called steal or unreachable profiles. If ActivateUnreachableProfile is set to "true," then the API removes the profiles and resends them to be executed when launching the application again.