1. Initialize Imaging Toolkit. For more information, see Understanding Imaging Toolkit initialization.

2. Create a context. For more information, see Understanding context creation.

3. If applicable, set the port range. For more information, see Understanding the port range.

4. Set the scan settings. For more information, see Understanding scan settings specification.

5. Set the output directory and filename.

6. If applicable, register a callback function. For more information, see Registering a callback function.

7. Call one of the scan functions. For more information, see Calling the scan functions.

8. Uninitialize the Imaging Toolkit. For more information, see Uninitializing.

9. Retrieve the created scan context. For more information, see Understanding scan context retrieval.

Understanding Imaging Toolkit initialization

MFPSB_Initialize()

The MFPSB_Initialize() function lets the Imaging Toolkit library initialize internal data structures, read the Windows registry, and configure Imaging Toolkit. If SinglePort is set to TRUE, then the function also creates a receiving socket. We recommend calling this API when initializing the application, if SinglePort is set to TRUE.

Understanding context creation

MFPSB_CreateScanContext()

The MFPSB_CreateScanContext() function returns an MFPSB_HCTX value that is used as a handle to refer to a particular scan job.

To create a handle, provide the following:

• Printer IP address

• Profile name

• TCP port number

The function fails when it cannot communicate with the printer. If SinglePort is set to TRUE, then the port value is ignored.

Sample code

MFPSB_HCTX hCtx;
hCtx = MFPSB_CreateScanContext("myprinter.lexmark.com",
"mylabel", 9700);
if (hCtx == NULL)
{
   //There was an error creating the context.
}

Understanding the port range

The Set Port Range function designates the ports that Imaging Toolkit uses for receiving images. Lower and upper port range values are passed as a parameter, and must be set between 1024 and 65535. To disable the port range function and delete specified values, set the lower and upper port numbers to -1.

Sample code in Visual Basic

If isEmptyLowPort = True And isEmptyUpperPort = True Then
      //Disable the port range
        nLowerPort = -1
        nUpperPort = -1
        lError = MFPSB_SetPortRange(nLowerPort, nUpperPort)
        //Error code handling.
         .........
Else 
      ..............
      //Setting the port range.
        nLowerPort = Val(txtLowerPort)
        nUpperPort = Val(txtUpperPort)
        lError = MFPSB_SetPortRange(nLowerPort, nUpperPort)

Sample code in C++

int lowerport = 1024;
int upperport = 65535;
DWORD dwd = MFPSB_SetPortRange(lowerport,upperport);
if(dwd == 0)
      //Success
else
      //Show error message

Understanding scan settings specification

MFPSB_SetScanSetting()

Imaging Toolkit allows scan parameters for contexts. Each context has its own set of parameters. To query the parameters, use the MFPSB_QueryScanSetting() function.

Sample code

dwError = MFPSB_SetScanSetting(hCtx, “RESOLUTION”, “200”);
if (dwError != MFPSB_E_SUCCESS)
{
 	//Your code to handle this error 
}
Char sValue[32];

Long sValueLen = 32;
  //Get the value for the resolution parameter

dwError = MFPSB_QueryScanSetting(hCtx, “RESOLUTION”, sValue, 
&sValueLen);

if (dwError != MFPSB_E_SUCCESS)
{
 	//Your code to handle the error 
}

To retrieve a list of all scan settings for a specified context ID, use MFPSB_GetScanSettingsAsString.

Sample code

DWORD MFPSB_GetScanSettingsAsString(HANDLE hCtx, LPSTR sValue, LONG *sValueLen)

Where:

• hCtx [IN] is the handle or ID of the context.

• sValue [OUT] retrieves ScanSettings as a string delimited by Full Search and End of Transmission Block.

• sValueLen [OUT] is the number of context IDs.

Notes:

• If the function call is successful, then a zero value is returned. If the function call is not successful, then a nonzero value indicating the error code is returned. For more information on error codes, see Possible API-related error messages.
• Scan settings can be retrieved individually using MFPSB_QueryScanSetting, but this function should not be used to retrieve multiple scan settings.

Sample code for using the API to declare functions

Declare Function MFPSB_GetScanSettingsAsString Lib "mfpsb.dll"_
(ByVal hContext As Long,_
ByVal IpSettingValue As String,_
ByRef IpLength As Long) As Long

Sample code for using the function in Visual Basic

hCtx = IbContexts.Text
		IStringLength = 400

		IErrorCode = MFPSB_GetScanSettingsAsString(hCtx, sValue, IStringLength)
		FS = Chr(28)
		For I = 0 To 14
			nStartPos = 0
			nEqualPos = 0
			nFSPos = 0

			sSetting = sScanSetting(i)
			nStartPos = InStr(1, sValue, sSetting, vbTextCompare)
			If nStartPos > 0 The
				nEqualPos = nStartPos + Len(sSetting)
				nFSPos = InStr(Right(sValue, Len(sValue) - nEqualPos), FS)
				If I = 14 Then
					sEdgeToEdgeVal = Mid$(sValue, nEqualPos +1, nFSPos - 1)
					If sEdgeToEdgeVal = True Then
						Check1.Value = 1
					Else
						Check.Value = 0
					End If
				Else
					tbScanSetting(i).Text = Mid$(sValue, nEqualPos + 1, nFSPos - 1)
				End If
			End If

Sample code for using the function in C++

CHAR value[10];
LONG valueLen = 10;
LONG* pValueLen = &vanlueLen;
dwd = MFPSB_GetScanSettingsAsString(contextid,value,pValueLen);
if(dwd==0)
{
      //Success
}
else
{
      //Show error message
}

Registering a callback function

MFPSB_RegisterCallback()

When registering the callback function, determine the events that must cause the Imaging Toolkit library to initiate the callback function. If a handle to a window is provided in the function, then the initialization of the callback occurs in the window procedure of this window. The imaging process runs on its own separate thread, and the calling application may require the callback to run in the same thread as the application. This process is the same for Visual Basic programs.

VOID_stdcall myCallback (MFPSB_HCTX hCtx, LONG lpId, LPVARIANT lpInfo)
{
   //Your own code representing what should be done
}
.
.
.
DWORD dwError;
dwError = MFPSB_RegisterCallBack(hCtx, (MFPSB_PFNCALLBACK)
myCallback, MFPSB_SBALLEVENTS, hWnd);

Calling the scan functions

MFPSB_StartScanBack()
MFPSB_StartScanBackNoBlock()

The two scan function options let you scan with or without a blocking function. The non-blocking versions allow the application to respond to your input. When you call the function, the profile is sent to the printer, and the Toolkit waits for the printer to connect back to it.

//Start the scan process.
dwError = MFPSB_StartScanBackNoBlock(hCtx); 
if (dwError != MFPSB_E_SUCCESS)
{
  	//The imaging process failed to start 
  	//handle the error
}

Uninitializing

MFPSB_Uninitialize()

This function releases all resources used by the library and deletes any remaining contexts.

Understanding scan context retrieval

We recommend calling these APIs when creating an instance of the application.

• MFPSB_GetInitContexts()—Determines the number of context IDs.

  Note: If the function call is successful, then a zero value is returned. If the function call is not successful, then a nonzero value indicating the error code is returned. For more information on error codes, see Possible API-related error messages.

• MFPSB_GetInitContextProfileInfo()—Retrieves the following details of each scan context and identified by a context ID:

  • Profile name

  • MFP IP address

  • Output directory

  • Output file name

  Note: If the function call is successful, then a zero value is returned. If the function call is not successful, then a nonzero value indicating the error code is returned. For more information on error codes, see Possible API-related error messages.

Sample code for using the APIs to declare functions in Visual Basic

Declare Function MFPSB_GetInitContexts Lib "mfpsb.dll"_
(ByRef address As Any,_
ByRef numContexts As Integer) As Long

Declare Function MFPSB_GetInitContextProfileInfo Lib "mfpsb.dll"_
(ByVal IContextID As Long,_
ByVal sProfileName As String,_
ByVal sMFPIP As String,_
ByVal sOutputFileDir As String,_
ByVal sOutputFileName as String,_
ByVal sIconFile as String) As Long

Sample code for using the functions in Visual Basic

sProfileName = Space$(35)
	sMFPIP = Space$(16)
	sOutputDir = Space$(225)
	sOutputFileName = Space$(35)
	sIconFile = Space$(260)
	IError = MFPSB_GetInitContexts(ByVal VarPtr(cList.ctx(oneIndex), sProfileName, sMFPIP,
sOutputFileDir, sOutputFileName, sIconFile)
		If IError = 0 Then
		IbContexts.AddItem (cList.ctx(oneIndex))
		Conexts(oneIndex, 0) = cList.ctx(oneIndex))
		Conexts(oneIndex, 1) = sMFPIP
		Conexts(oneIndex, 2) = sProfileName
		Conexts(oneIndex, 3) = sOutputFileDir
		Conexts(oneIndex, 4) = sOutputFileName
		Conexts(oneIndex, 5) = sIconFile
		numContexts = numContexts + 1
	End If
Next oneIndex

Sample code for using the functions in C++

LONG64 context[24];
MFPSB_HCTX initcontextPtr = context;
int numContexts = 24;
DWORD dwd = MFPSB_GetInitContexts(initcontextPtr, numContexts);
if(dwd == 0 )
{
      for(int iIndex=0 ; iIndex< numContexts; iIndex++)
      {
            //Show context ID
      }
}
else
{
      //Show error message
}
CHAR directory[32];
CHAR sIPAddress[32];
CHAR sOutputfilename[32];
CHAR sIconfile[32];
CHAR sProfileName[32];
dwd = MFPSB_GetInitContextProfileInfo(contextid,sProfileName,sIPAddress,directory,sOutputfilename,sIconfile);
if(dwd == 0)
{
      //Success
}
else
      //Show error message

Using the sample application

We recommend using a C# application from the <install-dir>\native\bin folder, where <install-dir> is the installation directory of the application.

The sample application sends scan profiles to a printer, and then receives the scanned images. To facilitate the imaging process, the MFPSB API exposed by the DLL consists of 16 functions. You can run the sample application from the bin folder of this package.

To copy the sample to another location, store all DLL files from the bin folder in the application folder. You can also copy the sample in the PATH environment variable.

If an icon is used when creating profiles, then the style sheets contained in the bin folder must be in the following:

• PATH environment

• Application directory

1. From the application, create a context.

   1. Enter the IP address or host name of the printer.

   2. Type the profile name.

   3. Click Create Context.

   An integer appears in the Contexts list box. The default values for the scan settings also appear. Create Context calls the MFPSB_CreateCallback function to create the context, and then calls the MFPSB_RegisterCallbackFunction when successful.

   The callback function for this application writes information in the output window.

2. Set the port range.

   1. Set the lower and upper port range. The value can be from 1024 to 65535.

   2. Click Set Port Range.

   The port range is set by calling MFPSB_SetPortRange().

   If port range settings are not specified, then the server attempts to open a socket on the first available port.

3. Enter the scan settings.

   1. Enter a value for each scan setting.

   2. Click Set Values.

   3. To test the value, click Get Values.

   MFPSB_SetScanSetting is called for each setting.

   Get Values calls the MFPSB_QueryScanSetting for each setting and updates the fields with the result.

4. Select a directory and file name for the output.

   Type the name of the directory and the output file. If these fields are not specified, then the directory used is the one where the application is running. The file name matches the profile name. These names can be entered at any time before Do Scan is selected, and files are overwritten without prompting.

   If you select Do Scan, then the MFPSB_SetOutputFile API function is called before MFPSB_StartScanBackNoBlock.

5. Type the full path of the icon file.

   If the printer has a control panel with a welcome screen, then send an icon to the printer, and then show it on the welcome screen. If the Icon field is not empty when Do Scan is selected, then the MFPSB_SetWelcomeScreenIcon function is called.

   Note: Icon images can be GIF, JPEG, or PNG, with dimensions of 120 x 75 pixels and not exceeding 11KB.

6. Perform the scan.

   Clicking Do Scan sends a profile to the printer by calling the MFPSB_StartScanBackNoBlock API function. This function is a non-blocking call. Updates on status come through the callback function which shows text into the output window. The scan job is initiated when the shortcut number or icon at the printer is used.

Other available options and their functions

Possible API-related error messages