Developer Guide

Android Printing Framework 2.0
Developer Guide
Android Printing Framework
Developer Guide
® ISB Vietnam Co., Ltd. (IVC)
Page i
Android Printing Framework 2.0
Developer Guide
Table of Content
1
Introduction ........................................................................................................................................ 1
2
Terms and definitions........................................................................................................................ 1
3
Developer guide ................................................................................................................................. 1
3.1 Overview ..................................................................................................................................... 1
3.2 Configure development environment.......................................................................................... 1
3.2.1 Install APF Core module................................................................................................ 1
3.2.2 Install and configure APF SDK module ......................................................................... 1
3.3 Using APF SDK for proramming................................................................................................. 3
3.3.1 Create a connection to printing service ......................................................................... 3
3.3.2 Search the available devices connected to the system................................................. 5
3.3.2.1 Synchronously searching method ............................................................. 6
3.3.2.2 Asynchronously searching method ........................................................... 6
3.3.2.3 Combine searching modes ......................................................................... 7
3.3.2.4 Cancel searching method............................................................................ 8
3.3.3 Create new device object .............................................................................................. 8
3.3.4 Search printer driver ...................................................................................................... 8
3.3.5 Add a new printer to the system .................................................................................... 9
3.3.5.1 Add printer without driver ........................................................................... 9
3.3.5.2 Add printer with giving driver ................................................................... 10
3.3.6 Get printer from the system ......................................................................................... 10
3.3.7 Remove the printer ...................................................................................................... 11
3.3.8 Print a file (submit a print job) ...................................................................................... 12
3.3.9 Print an URL ................................................................................................................ 12
3.3.10 Print preview ................................................................................................................ 12
3.3.11 Cancel / Remove job ................................................................................................... 13
3.3.12 Get jobs ....................................................................................................................... 14
3.3.12.1 Get all jobs .................................................................................................. 14
3.3.12.2 Get job by id................................................................................................ 14
3.3.12.3 Get job by state........................................................................................... 14
3.3.12.4 Get job by printer........................................................................................ 14
3.3.12.5 Get job by printer and state....................................................................... 15
3.3.13 Using extend print options ........................................................................................... 15
4
Technical Support............................................................................................................................ 17
® ISB Vietnam Co., Ltd. (IVC)
Page ii
Android Printing Framework 2.0
Developer Guide
1 Introduction
This installation document guides you how to use APIs of APF Framework on Android project to
build applications which support printing.
2 Terms and definitions
This installation guideline has some definitions:
•
APF: Android Printing Framework.
•
ADT Plug-in: Android Development Tools, link: http://developer.android.com/sdk/index.html
3 Developer guide
3.1
Overview
APF Mobile included two modules:
3.2
•
APFCore: The core application of APF, was packed as Android package (APK)
•
APFSdk: The SDK provide printing APIs for building printing application using APF
Configure development environment
3.2.1 Install APF Core module
The APFCore module must be installed to Android terminal before using the APF
Framework.
This is an Android Application Package (APK) so it’s very easy to install. There is many ways
to deliver this module. We list some of them here for your reference:
•
Using ADB command from PC
•
Copy to SD Card then install using File manager application
•
Download from internet where you store this module, then install it
•
Your application will pack this module as an asset item (on assets folder), and install this
module when running.
•
Etc…
3.2.2 Install and configure APF SDK module
This APIs is provided under “libapf.jar” module, to use it, you must import it to your Android
project by Eclipse with these steps:
Copy the “libapf.jar” file to “libs” folder of your android project. If the “libs” folder does not
exist, create a new one.
If you’re using new version of ADT Plug-in, the “libapf.jar” (after copied to “libs” folder) will
be imported to your project automatically and the install step is finished. Otherwise, one more step
should be done to finish.
® ISB Vietnam Co., Ltd. (IVC)
Page 1/12
Android Printing Framework 2.0
Developer Guide
If you’re using the old version of ADT Plug-in, right-click on your Android project, choose
“Properties”, a dialog will appear like this:
After that, choose “Java Build Path” tab on the left panel:
® ISB Vietnam Co., Ltd. (IVC)
Page 2/12
Android Printing Framework 2.0
Developer Guide
Then press “Add External JARs…” button and specific a “libapf.jar” file location and press
“Open”, it will look like this:
Then press “OK” to finished installation steps.
3.3
Using APF SDK for proramming
The PrintingService class is designed to manage all operations of printing easily consist
of: connect or disconnect to or from printing service, search devices that connected to system, add
a new printer to system, remove or update a printer, set a printer as default printer of system, print /
pause / resume / cancel a job or many jobs, etc …
To use the those function, the first step is – get the instance of PrintingService by
getInstance() method:
PrintingService mPrintingService = PrintingService.getInstance();
…
3.3.1 Create a connection to printing service
The first thing need to do is creating a connection to printing service. This step is very
important to application since all methods need the connection must be initialized first.
To create a connection with printing service, you need a key which be provided by ISB
Vietnam Company Limited before (visit http://isb-vietnam.com.vn/ for more information). This key
will be valid with only your application, other applications cannot use it.
Once you got a key, we start the connection step. You should define the key and the printing
service instance as global variables like this:
® ISB Vietnam Co., Ltd. (IVC)
Page 3/12
Android Printing Framework 2.0
Developer Guide
private static final String YOUR_KEY =
"RTFCRDhERDc1ODI0OTZEOUE2OEQ1QjMwRkUyNTUzMjcz" +
"RTg5QUIxQ0JEMzE1RjgzQzJFNzcyMTNGNzQ5NDMzQ0Q0" +
"QUQwQTVFMjVFNTIwNzNFMDBBMjlFQTRFOTlGQTQ3NDRB" +
"QkY2OENEQjUyRDY1MjE5QjBCNjA1NTM1MDMzQUIyOEQ1" +
"QUI4NTkzM0RCMjE5QTVCQ0M3M0NEMTZEREUwNUU2QjBF" +
"MTEyNTMzNEE3QkI4NUIxQkYyQ0M3Qzc0MURCMDJDRjQw" +
"NUYwNTJGQkY0OTJFQzk0MUE0QjM3NzgwNDVBQkU2MDIx" +
"N0Q4QTJEQUQxRDM4MUEwNTJCQTFCQzE2QzY5M0M3MkU1" +
"REU0RkFFMDU0RkUxMEZBQUM3MTAwOUZGM0QxMDYwRUQ0" +
"QjhBNUJBRTlBN0JGQTQwQ0E1NDY4MzYxRjg0OEYxQTU4";
private PrintingService mPrintingService = null;
…
Then, you should implement the ConnectionListener to listen when the connection
with service was initialized successfully:
private ConnectionListener mConnectionListener = new
ConnectionListener() {
@Override
public void onServiceDisconnected() {
/*
* When service disconnection, this event will be
* called, so you should implement it to clean the
* resource if any
*/
Log.d(TAG, "Disonnected to printing service");
}
@Override
public void onServiceConnected() {
/*
* This event will be called when service was
* connected, the APIs only available after this
* event.
*/
Log.d(TAG, "Connected to printing service");
}
};
Finally, on the onCreate() method of Activity, call the bind() method with your key like
this:
® ISB Vietnam Co., Ltd. (IVC)
Page 4/12
Android Printing Framework 2.0
Developer Guide
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
/*
* On the onCreate of activity, you must create a
* connection to service
*/
mPrintingService = PrintingService.getInstance(this);
mPrintingService.setConnectionListener(mConnectionListener);
try {
mPrintingService.bind(SECRET_KEY);
} catch (InvalidKeyException e) {
e.printStackTrace();
}
}
Don’t forget disconnect the service on onDestroy() method of activity when you don’t use
the connection anymore
@Override
protected void onDestroy() {
super.onDestroy();
/*
* Application should release connection to
* Printing rervice when exit
*/
if (mPrintingService != null)
mPrintingService.unbind();
}
3.3.2
Search the available devices connected to the system
Once you connect with the PrintingService, you can find the devices which connected
to the system by calling searching device method. The service provides 2 ways to searching device:
synchronously and asynchronously.
Both of 2 searching ways, we provide 5 modes of searching for Network, Bluetooth and USB
printer on Device class includes:
•
SEARCH_NW_NATIVE: Search Network printers using SNMP protocol
® ISB Vietnam Co., Ltd. (IVC)
Page 5/12
Android Printing Framework 2.0
Developer Guide
•
SEARCH_NW_BOUNJOUR: Search Network printers using ZeroConfig protocol
•
SEARCH_NW_ALL: Search all network printers using SNMP and ZeroConfig protocol
•
SEARCH_BLUETOOTH: Search Bluetooth printer
•
SEARCH_USB: Search USB printer.
3.3.2.1 Synchronously searching method
With synchronously way, use the searchAvailableDevices() method which will return a
array list of devices that connected to the system:
ArrayList<Device> devices =
mPrintingService.searchAvailableDevices(Device.SEARCH_NW_ALL);
The devices object will be null in case there is not any device connected to system.
Otherwise, each Device object in devices will contain the uri, marker, model, serial and
commandSet of the device and can be gotten by using getter method:
ArrayList<Device> devices =
mPrintingService.searchAvailableDevices(Device.SEARCH_NW_ALL);
if (devices == null)
System.out.println("Devices list is null");
else {
for (int i = 0; i < devices.size(); i ++) {
Device device = devices.get(i);
System.out.println("URI = " + device.getUri());
System.out.println("Model = " + device.getModel());
System.out.println("Command = " + device.getCommandSet());
}
}
3.3.2.2
Asynchronously searching method
With asynchronously searching way, you need to register to PrintingService the listener
which to listen when a new device was found.
The device listener OnDeviceScaningListener object should be global variable and
implement 3 needed methods which receive events from PrintingService:
•
onStart(String token): Start scanning device, this method will be first call when
scanning with token. You should store this token to distinguish with other scanning session or use
to cancel this scanning session.
•
onFound(String token, Device device): This method will be called when a new
devices was found with this scanning session.
® ISB Vietnam Co., Ltd. (IVC)
Page 6/12
Android Printing Framework 2.0
•
Developer Guide
onFinished(String token): This scanning process was finished when calling this
method.
private OnDeviceScanningListener mDeviceScanningListener = new
OnDeviceScanningListener() {
@Override
public void onStart(String token) {
mSearchAsyncToken = token;
Log.d(TAG, "Search with token = " + token);
}
@Override
public void onFound(String token, Device device) {
Log.d(TAG, "Device found with token = " + token);
Log.d(TAG, "Model = " + device.getModel());
Log.d(TAG, "Uri = " + device.getUri());
Log.d(TAG, "Cmd = " + device.getCommandSet());
}
@Override
public void onFinished(String token) {
Log.d(TAG, "Finished with token = " + token);
}
};
Then, from somewhere you want to call scanning device method, just simple call
searchAvailableDevices() with searching mode and the listener object:
mPrintingService.searchAvailableDevices(
Device.SEARCH_NW_BONJOUR,
mDeviceScanningListener);
…
3.3.2.3 Combine searching modes
You can also combine the searching mode search more device at the searching session like
this:
mPrintingService.searchAvailableDevices(
Device.SEARCH_NW_BONJOUR | Device.SEARCH_BLUETOOTH,
mDeviceScanningListener);
…
® ISB Vietnam Co., Ltd. (IVC)
Page 7/12
Android Printing Framework 2.0
Developer Guide
In above sample, we combine Bonjour searching method with Bluetooth searching method at
one searching session.
3.3.2.4 Cancel searching method
To force stop searching device process, you must have the searching token of that session,
and simple call cancelSearch() with that token
private static String mSearchToken = null;
...
// You already have the searching token from searching method
boolean cancel = mPrintingService.cancelSearch(mSearchToken);
…
3.3.3 Create new device object
The Device object can be created by 2 ways: using the searchAvailableDevices()
method and manual.
The manual way let you create a Device object by yourself by using setter method to set the
maker, model, uri, commandSet and series. However, only uri field is required of one Device
object, you can leave other fields as null.
Device deviceOne = new Device();
deviceOne.setUri("usb://device_one");
deviceOne.setModel("Model of device one");
deviceOne.setCommandSet("PS,PCL,PZL");
Device deviceTwo = new Device("Maker", "Model of device two",
"socket://device_two", "PS, PCL", null);
We highly recommend that you should use the devices object list which receive from
searching method instead of devices create by manual except you know clearly about your devices
you want to add to system.
3.3.4 Search printer driver
After you have the Device object, the next step is - find the compatible driver for him. One
device model has 2 parts: maker and model. You can search driver using this 2 parts.
Example: I have device with model is: Canon MG6100 series. The maker of him is “Canon”,
and the model is “Canon MG6100 series”. So search drivers for this printer is very easy by calling
searchDrivers() method.
The return values of searchDrivers() method is an array list of drivers or null object:
•
The result is not null: in case your searching parameters are match or similar the driver
from our system.
® ISB Vietnam Co., Ltd. (IVC)
Page 8/12
Android Printing Framework 2.0
•
Developer Guide
The result is null: We not support your requested models OR the request parameters are
incorrect. In this case, please check your request parameters.
/*
* This maker and model should be return from searching method,
* however, we assume that those values like this
*/
// String maker = device.getMaker();
String maker = "Canon";
// String model = device.getModel();
String model = "Canon MG6100 series";
/*
* The result of searching by model will be little or null
* if we don't have the driver for this printer
*/
ArrayList<Driver> drivers_1 = mPrintingService.searchDrivers(
Driver.SEARCH_DEVICE_MODEL, model);
/* Search by maker will return all drivers of this makers */
ArrayList<Driver> drivers_2 = mPrintingService.searchDrivers(
Driver.SEARCH_DEVICE_MAKER, maker);
/* Or we can get all drivers from system */
ArrayList<Driver> drivers_3 = mPrintingService.searchDrivers(
Driver.SEARCH_ALL, null);
3.3.5 Add a new printer to the system
When you have a Device object, you can insert it into system by addPrinter() method
with parameters are this Device, the name of printer (and the driver if any).
Printer name, in the system, is the id of printer, it must be unique and followed name format.
Printer name must contain only letters, numbers, underscores, hyphens; and must be begun with
letter or number.
We provide 2 ways of adding printer method: add printer without driver and add printer with
driver.
3.3.5.1 Add printer without driver
By default, if you add printer without giving driver object, the printer will be added with driver
which be chosen by PrintingService:
® ISB Vietnam Co., Ltd. (IVC)
Page 9/12
Android Printing Framework 2.0
•
Developer Guide
If you device is contain model of printer, we will search driver based on this model. In
case we could not found any driver compatible with this driver, the adding process will failed and we
will return null.
•
If you device is not contain model (model is null), we will understand that you added the
printer without using driver. In this case, any job for this printer will go out directly to printer without
over any filters
Device deviceOne = new Device();
deviceOne.setUri("usb://device_one");
deviceOne.setModel("Model of device one");
Printer printer = ptmInstance.addPrinter(deviceOne, "Printer-1");
In case printer was inserted successfully, addPrinter() method will return the Printer
object which installed to the system; and in the otherwise, it will return the null object.
3.3.5.2 Add printer with giving driver
This method requires you have the Driver object before (by searching drivers APIs). In this
case, we will add this printer with your driver right away. So please sure that you have choose the
correct driver.
ArrayList<Driver> drivers = mPrintingService.searchDrivers(
Driver.SEARCH_DEVICE_MODEL, model);
/* We assume that the first driver is best choice for printer one */
Driver driverOne = drivers.get(0)
Device deviceOne = new Device();
deviceOne.setUri("usb://device_one");
deviceOne.setModel("Model of device one");
Printer printer = ptmInstance.addPrinter(
deviceOne, "Printer-1", driverOne.getKey());
3.3.6 Get printer from the system
In case you want to get the printer which you knew the name on the system, you can call
getPrinter() method with parameter is the name of printer that you want to get.
® ISB Vietnam Co., Ltd. (IVC)
Page 10/12
Android Printing Framework 2.0
Developer Guide
Printer printer = mPrintingService.getPrinter("Printer-1");
if (printer == null)
System.out.println("The printer is null");
else {
System.out.println(printer.getName());
System.out.println(printer.getModel());
System.out.println(printer.getUri());
System.out.println(printer.getDriver());
// Other getter methods
}
If you want to get all printers from the system, you can call getPrinters() method. That
function will get the array list of printer objects (hold all printers that be added into system).
ArrayList<Printer> printers = mPrintingService.getPrinters();
The printers object holds the list of printers that has been inserted into system. Each
printer of printers object will contain name of printer. If you want to get full information of a printer,
you can call the getter methods of Printer object.
ArrayList<Printer> printers = mPrintingService.getPrinters();
if (listPrinter == null)
System.out.println("Devices list is null");
else {
for (int i = 0; i < printers.size(); i ++) {
Printer printer = printers.get(i);
System.out.println("Printer URI = " + printer.getName());
System.out.println("Printer URI = " + printer.getUri());
System.out.println("Printer model = " + printer.getModel());
System.out.println("Printer URI = " + printer.getDriver());
}
}
3.3.7 Remove the printer
In order to manage printer easily and smoothly, The PrintingService provides
removePrinter() method to delete incorrect, unused printer or other purposes.
To use removePrinter() function, you must specify the correct printer name which you
want to delete; in case you delete a incorrect printer, no printer is deleted and it will return false, and
in the otherwise, it will return true.
® ISB Vietnam Co., Ltd. (IVC)
Page 11/12
Android Printing Framework 2.0
Developer Guide
boolean result = mPrintingService.removePrinter("Printer-1");
3.3.8 Print a file (submit a print job)
A print job was created must be contain a file name which to be printed, the destination
printer and print options if any. You can create new print job like this:
String filename = "/mnt/sdcard/test.pdf";
String printerName = "HP-P1006";
PrintOption option = null;
long jobId = mPrintingService.printFile(printerName, filename, option);
Or if you want to set specific PrintOption, you can:
PrintOption option = new PrintOption();
option.setCollate(true);
option.setNumberOfCopies(2);
long jobId = mPrintingService.printFile(printerName, filename, option);
The jobId must be greater than zero if success.
3.3.9 Print an URL
Like the printFile() method, the printURL() method will print the internet web page
with giving address.
String url = "http://isb-vietnam.com.vn/";
String printerName = "HP-P1006";
PrintOption option = null;
long jobId = mPrintingService.printFile(printerName, url, option);
Please note that this method will take time since we need to download this web page then
render it to out print file.
3.3.10 Print preview
Before making real print a file or an URL, maybe you want to make print preview to take a
look for your job. We can support you that feature by providing printPreview() method and
OnPrintPreviewListener class.
The print preview method is asynchonouslly method and the output of print preview is JPEG
file. So you should register OnPrintPreviewListener to know which pages was preview
completed.
You also need one token for print preview and cancel print preview. Please note that the
listener object and the print preview token should be global variable.
® ISB Vietnam Co., Ltd. (IVC)
Page 12/12
Android Printing Framework 2.0
Developer Guide
private OnPrintPreviewListener mPrintPreviewListener = new
OnPrintPreviewListener() {
@Override
public void onBeginPreview(String token) {
// Start preview with token
}
@Override
public void onPageFinished(String token, int number,
String path) {
// Be called when one page is preview completed
}
@Override
public void onFinishedPreview(String token) {
// The preview process was completed
}
};
private static String mPreviewToken = null;
Then, register this listener object to PrintingService and start to preview:
mPrintingService.setOnPrintPreviewListener(mPrintPreviewListener);
String printerName = "Canon-MG6130";
String filePath = "/mnt/sdcard/myfolder/myfile.png";
PrintOption options = new PrintOption();
options.setFitToPage(true);
option.setOrientation(Orientation.PORTRAIT);
String outputDir = "/mnt/sdcard/preview";
String outputPrefix = "mypreview_%03d.png";
Int outWidth = 100;
Int outHeight = 100;
mPrintingService.printPreview(printerName, filePath,
options, outputDir, outputPreview,
outWidth, outHeight));
3.3.11 Cancel / Remove job
® ISB Vietnam Co., Ltd. (IVC)
Page 13/12
Android Printing Framework 2.0
Developer Guide
PrintingService also provides method to take more operations to job consist of: cancel /
remove job.
long jobId = mPrintingService.printFile(filename, printerName, option);
// Call pause / resume / cancel / remove job
boolean result = false;
result = mPrintingService.cancelJob(printerName, jobId);
// result = mPrintingService.removeJob(printerName, jobId);
The result return value is true if the operation is success, false otherwise
3.3.12 Get jobs
To view the list of jobs which submitted, PrintingService provides many types of get job
methods to serve many purposes.
3.3.12.1
Get all jobs
The first one is get all jobs. This method simple return all jobs were submitted of all printers
ArrayList<Job> completedJobs = mPrintingService.getJobs();
3.3.12.2
Get job by id
The next one is get job by id, allow you get the job with the giving id. If the id is invalid or not
existed on the system, the null object will be return.
int jobId = 10;
Job job = mPrintingService.getJob(jobId);
3.3.12.3
Get job by state
The next one is get job by state, the giving state will decides which jobs will be selected and
return. The definition of state is defined in JobState class. The giving state should be one of these
states, or combine them for more states
// I want to get jobs which completed
ArrayList<Job> completedJobs =
mPrintingService.getJobs(JobState.COMPLETED);
// Then I want to get jobs pending and processing
ArrayList<Job> activeJobs =
mPrintingService.getJobs(JobState.PENDING | JobState.PROCESSING);
3.3.12.4
Get job by printer
To get jobs of printer, simple giving the name of printer to get job method
® ISB Vietnam Co., Ltd. (IVC)
Page 14/12
Android Printing Framework 2.0
Developer Guide
String printerName = "Canon-MG6130";
ArrayList<Job> jobs = mPrintingService.getJobs(printerName);
3.3.12.5
Get job by printer and state
Like other get job method, this method simple giving the name of printer and the states to get
the list of jobs. You also can combine job state to get more jobs:
// I want to get jobs which completed of printer EPSON-EP804A
String printerName = "EPSON-EP804A";
ArrayList<Job> completedJobs =
mPrintingService.getJobs(printerName, JobState.COMPLETED);
// Then I want to get jobs pending and processing
ArrayList<Job> activeJobs =
mPrintingService.getJobs(printerName ,
JobState.PENDING | JobState.PROCESSING);
3.3.13 Using extend print options
Beside many standard options which defined in PrintOption class, PrintingService
also provides many extend options base on driver such as: Paper size, Paper type and Paper
source…
We used Choice object to present one option of them. Examine that Paper sizes supported
are: A4, A5, Letter, Legal, so that each item (A4 or A5 or Letter or Legal) is a Choice.
Each choice has 3 fields: keyword, value and display:
•
The keyword and value is used to PrintOption can knows which extend option was
chosen.
•
The display is the user-friendly text can help the end-user understand the option easily
To get these extend options, use the appropriate methods:
ArrayList<Choice> paperSizes =
mPrintingService.getPaperSizes(printerName);
PrintOption option = new PrintOption();
option.setCollate(true);
option.setNumberOfCopies(2);
// Get one of paper sizes
option.addExOption(paperSizes.get(0));
long jobId = mPrintingService.printFile(filename, printerName, option);
® ISB Vietnam Co., Ltd. (IVC)
Page 15/12
Android Printing Framework 2.0
Developer Guide
Moreover, if you want to get the default value of these extend option, PrintingService
can do it for you by providing many methods to get it. The default extend option value help you
define which item on the list of extend options is default.
ArrayList<Choice> paperSizes =
mPrintingService.getPaperSizes(printerName);
String defaultSizeValue =
mPrintingService.getDefaultPaperSize(printerName);
Choice defaultPaperSize = null;
for (Choice choice : paperSizes) {
if (choice.getValue().equals(defaultSizeValue) {
defaultPaperSize = choice;
break;
}
}
PrintOption option = new PrintOption();
option.setCollate(true);
option.setNumberOfCopies(2);
// Get one of paper sizes
option.addExOption(defaultPaperSize);
long jobId = mPrintingService.printFile(filename, printerName, option);
® ISB Vietnam Co., Ltd. (IVC)
Page 16/12
Android Printing Framework 2.0
Developer Guide
4 Technical Support
For technical support or advice, please contact these mail addresses:
•
Mr. Tan Quang Sang: [email protected]
•
Mr. Phan Dang Duy Thinh: [email protected]
® ISB Vietnam Co., Ltd. (IVC)
Page 17/12

Download Report