Programming with APF

Introduction

 

This installation document guides you how to use APIs of APF Framework on Android project to build applications which support printing.

 

This installation guideline has some definitions:

APF: Android Printing Framework.

ADT Plug-in: Android Development Tools, link: http://developer.android.com/sdk/index.html

 

 

Developer guide

  

Overview

 

The APF Framework is a strong tool supported for printing on operating system like Unix. APF provided a framework to communicate with printer devices, very easy to develop printing application on Android.

 

 

Configure development environment

 

This APIs is provided under “libapf.jar” name, to use it, you must import it to your Android project by Eclipse with these steps:

 

Right-click on your Android project, choose “Properties”, a dialog will appear. Choose “Java Build Path” on the left panel, and choose “Libraries” tab on the right:

 

Picture 1 of installing apf lib

 

 

Then press “Add External JARs…” button and specific a “libapf.jar” file location and press “Open”, it will look like this:

Picture 2 of installing apf lib

 

Picture 3 of installing apf lib

 

 

Then press “OK” to finish installation steps.

 

 

Printer Manager & Printer classes

 

The PrinterManager class is designed to manage Printer and Device easily, and provided the full set of functions to operate the Printer and Device such as: search devices that connected to system, insert a new printer to system, delete a printer from system, set a printer as default printer of system, etc … To use those function, the first step is get the instance of PrinterManager by getInstance() method: 

PrinterManager ptmInstance = PrinterManager.getInstance();

 

Search the available devices connected to the system

 

To find the devices which connected to the system, you can use searchAvailableDevices() method which will return a array list of devices that connected to the system:

 

PrinterManager ptmInstance = PrinterManager.getInstance();

ArrayList<Device> listDevices = ptmInstance.searchAvailableDevices();

 

The arrDevices object will be null in case there is not any device connected to system.

Otherwise, each Device object in arrDevices will contain the “URI” and “model” of the device and can be gotten by using getter method:

 

PrinterManager ptmInstance = PrinterManager.getInstance();

ArrayList<Device> listDevices = ptmInstance.searchAvailableDevices();

 

if (listDevices == null)

      System.out.println("Devices list is null");

else {

      for (int i = 0; i < listDevices.size(); i ++) {

            Device device = listDevices.get(i);

            System.out.println("Device URI = " + device.getUri());

            System.out.println("Device model = " + device.getModel());

      }

}

 

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 “URI” and “model”.

 

Device deviceOne = new Device();

deviceOne.setUri("usb://device_one");

deviceOne.setModel("Model of device one");

 

Device deviceTwo = new Device("Model of device two", "socket://device_two");

 

Add a new printer to the system

 

When you have a Device object that contain at least 1 filed URI, you can insert it into system by addPrinter() method with parameters are this Device, the name of printer and the driver path.

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.

Driver path is a string path of PPD file contained some information about printer and filters. Each printer will have one or more PPD path, but only some of them may be work correctly; other of them get some problems with filters which not yet supported. So if you inserted a printer and it doesn’t work as your expectation, please try again with other PPD files.

 

Device deviceOne = new Device();

deviceOne.setUri("usb://device_one");

deviceOne.setModel("Model of device one");

String pathPPD = "/mnt/sdcard/Driver/hp-laserjet-p1006.ppd.gz";

 

Printer result = ptmInstance.addPrinter(deviceOne, "Printer-1", pathPPD);

 

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.

 

Printer result = ptmInstance.addPrinter(deviceOne, "Printer-1", pathPPD);

 

if (result == null)

      System.out.println("The printer is null");

else {

      System.out.println(result.getName());

      System.out.println(result.getModel());

      System.out.println(result.getUri());

      System.out.println(result.getDriver());

}

 

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.

 

PrinterManager ptmInstance = PrinterManager.getInstance();

Printer printer = ptmInstance.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());

}

 

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).

 

PrinterManager ptmInstance = PrinterManager.getInstance();

ArrayList<Printer> listPrinter = ptmInstance.getPrinters();

 

 

The listPrinter object holds the list of printers that has been inserted into system. Every printer of listPrinter 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.

 

PrinterManager ptmInstance = PrinterManager.getInstance();

ArrayList<Printer> listPrinter = ptmInstance.getPrinters();

if (listPrinter == null)

      System.out.println("Devices list is null");

else {

      for (int i = 0; i < listPrinter.size(); i ++) {

            Printer printer = listPrinter.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());

      }

}

 

Set a printer as default in printing system

 

Default printer is used for the print job which has not given a destination printer; in this case, print job will be printed by default printer. Printing system must have one default printer; if not, some operation of print job may not work smoothly.

 

Set default printer is easy by setDefaultPrinter() function of PrinterManager with parameter is a name of printer which you want to set default.

 

PrinterManager ptmInstance = PrinterManager.getInstance();

int result = ptmInstance.setDefaultPrinter("Printer-1");

 

Or:

 

PrinterManager ptmInstance = PrinterManager.getInstance();

int result = ptmInstance.setDefaultPrinter(printer.getName());

 

In case printer was set as default successfully, setDefaultPrinter() method will return 1; and in the otherwise, it will return zero.

 

Get default printer in printing system

 

Similar to set default printer, we have getDefaultPrinter() in order to get default printer in system. This function will return a printer which has been set default before; and return null in case no printer has been set default.

 

PrinterManager ptmInstance = PrinterManager.getInstance();

Printer defautPrinter = ptmInstance.getDefaultPrinter();

 

if (defautPrinter == null)

      System.out.println("The default printer is null");

else {

      System.out.println(defautPrinter.getName());

      System.out.println(defautPrinter.getModel());

      System.out.println(defautPrinter.getUri());

      System.out.println(defautPrinter.getDriver());

}

 

Note: Beside getDefaultPrinter() function to get default printer, Printer object have isDefault() function to check a printer is default or not.

 

PrinterManager ptmInstance = PrinterManager.getInstance(); 

ArrayList<Printer> listPrinter = ptmInstance.getPrinters();

 

if (listPrinter == null)

      System.out.println("Devices list is null");

else { 

      for (int i = 0; i < listPrinter.size(); i ++) {

            Printer printer = listPrinter.get(i);

            if (printer.isDefaultPrinter() == true)

                  System.out.println("Default printer is+ printer.getName());

      }

}

 

Remove the printer

 

In order to manage printer easily and smoothly, PrinterManager class provides removePrinter() and removeAllPrinters() 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 0, and in the otherwise, it will return 1.

 

PrinterManager ptmInstance = PrinterManager.getInstance();

int result = ptmInstance.removePrinter("Printer-1");

 

The removeAllPrinters() method will remove all printers of the system and return the number of printer which was removed successfully, it will return 0 in case there is no any printer was remove from the system.

 

PrinterManager ptmInstance = PrinterManager.getInstance();

int removedPrinterCount = ptmInstance.removeAllPrinters();

 

Register the PrinterManager listener

 

The PrinterManager class provides several listeners to listen the action of the system such as: add a new printer, remove a printer or set a printer as the default printer, etc… There are 4 listeners:

- OnAddPrinterListener: the interface definition for a callback to be invoked when the system received a request to add a new printer.

- OnRemovePrinterListener: the interface definition for a callback to be invoked when the system received a request to remove a printer.

- OnUpdatePrinterListener: the interface definition for a callback to be invoked when the system received a request to update a printer.

- OnDefaultPrinterChangeListener: the interface definition for a callback to be invoked when the system received a request to change the default printer

 

  • This sample will give you a view of using the listener to listener the action “Add printer” to the system:

 

PrinterManager ptmInstance = PrinterManager.getInstance();

ptmInstance.setOnAddPrinterListener(new OnAddPrinterListener() {

      @Override

      publicboolean onAdd(Device device, String name, String driver) {

            System.out.println("New printer was request " + "to add to the system");

            System.out.println("New printer name = " + name);

            System.out.println("New printer URI = " + device.getUri());

            System.out.println("New printer model = " + device.getModel());

            System.out.println("New printer driver = " + driver);

            return true;

      }

      @Override

      publicvoid onAddFinished(String name) {

            System.out.println("The new printer " + name + "was added to the system");

      }

});

 

On this sample, the onAdd() method will be raised when system received a request to add a new printer. If this method return true, this mean the request was agreed and a new printer will be submitted to the system. In case this method return false, this mean the request was cancelled and a new printer will not be installed to the system.

 

The onAddFinished() method only will be raised when the new printer was added to the system successfully.

 

PrintJobManager & PrintJob classes

 

Manage job will be too easy by using PrintJobManager object with basic function such as: create new print job, print a job, pause/resume and cancel a job.

 

Print a file (submit a print job)

 

A print job was created must be contain a file name which to be printed, other values are optional. In case you didn’t declare these values: title, destination printer, options, etc… they will be set by default value. With destination printer, if you didn’t set destination printer, it will be set by default printer of system.

 

You can create new print job like this:

 

PrintJobManager jobManager = PrintJobManager.getInstance();

String filename = "/mnt/sdcard/test.pdf";

String printerName = "HP-P1006";

PrintJob job = jobManager.printJob(filename, printerName, null);

 

Or if you want to set specific PrintOption, you can:

 

PrintOption option = new PrintOption();

option.setCollate(true); 

option.setNumberOfCopies(2);

PrintJob job = jobManager.printJob(filename, printerName, option);

 

If anything wrong, job object will be null otherwise a new job object will be created.

 

 

Pause, Resume, Cancel a print job

 

PrintJobManager class provides 3 basic functions to operate on print job easily, such as: pause(), resume(), cancel(). Some other related APIs:

- cancelAllJobs()

- cancelAllJobs(Printer name)

- pauseAllJobs()

- pauseAllJobs(Printer name)

- resumeAllJobs()

- resumeAllJobs(Printer name)

 

Ex: if you want to cancel a job, just need:

 

PrintJobManager jobManager = PrintJobManager.getInstance();

int result = jobManager.cancelJob(job.getId());

 

If you want to cancel all active jobs, just call:

 

PrintJobManager jobManager = PrintJobManager.getInstance();

int result = jobManager.cancelAllJobs();

 

If you want to cancel all active jobs of printer “HP-P1006”, just call:

 

PrintJobManager jobManager = PrintJobManager.getInstance();

int result = jobManager.cancelAllJobs("HP-P1006");

 

 

Job action listener

 

The PrintJobManager class provides several listeners to listen the action of the system such as: print/pause/resume/cancel a print job, etc… There are 5 listeners:

- OnCancelJobListener: The Interface definition for a callback to be invoked when the system received a request to cancel a print job

- OnJobStateChangeListener: The Interface definition for a callback to be invoked when the system have a print job which state was changed

- OnPauseJobListener: The Interface definition for a callback to be invoked when the system received a request to pause a print job

- OnPrintJobListener: The Interface definition for a callback to be invoked when the system received a request to print a job

- OnResumeJobListener: The Interface definition for a callback to be invoked when the system received a request to resume a job

 

Following is the example to catch job state change listener:

- Implement OnJobStateChangeListener

- Set this implemented to PrintJobManager


publicclass JobStateMonitorService extends Service implements OnJobStateChangeListener {

 

publicvoid onCreate() {

   PrintJobManager jobManager = PrintJobManager.getInstance();

jobManager.setOnJobStateChangeListener(this, PrintJobManager.JOB_STATE_CHANGE_INTERVAL_DEFAULT);

}

 

publicvoid onJobStateChange(int jobId, int oldJobState, int newJobState) {

   // Do your job here

}

}

 

Note: remember to remove the listener by calling: 

PrintJobManager jobManager = PrintJobManager.getInstance();

jobManager.setOnJobStateChangeListener(null, 0);

 

 

PrintDialog

 

PrintDialog is a system application coming along with APF framework. Its full package name is vn.ivc.apf.printdialog.

 

This application is developed for easy to select print options for a job, such as: printer name, number of copies, orientation, etc...

 

 

Show Print Dialog

 

Create the Intent and set show action:

 

Intent intent = new Intent();

intent.setAction(vn.ivc.apf.PrintDialog.ACTION_SHOW);

 

If you want to specify a printer, just pass an extra parameter

 

intent.putExtra(vn.ivc.apf.PrintDialog.PARAM_PRINTER_NAME, "HP-P1006");

 

If you do not set vn.ivc.apf.PrintDialog.PARAM_PRINTER_NAME key, PrintDialog will show all printers in the system.

 

If you want to show the option for image, just pass an extra parameter:

 

intent.putExtra(vn.ivc.apf.PrintDialog.PARAM_TYPE, vn.ivc.apf.PrintDialog.OPTION_TYPE_IMAGE);

 

By default, it will show the PrintDialog activity with type is vn.ivc.apf.PrintDialog.OPTION_TYPE_DEFAULT

 

Then you just start Activity as usual.

 

startActivity(intent);

 

 

Get option returned from PrintDialog

 

After user press “Print” button on PrintDialog, an Intent data will return to called activity. It contains option value that user selected.

Then you should create a PrintOption object and passed the value from Intent data to set print option

Ex: if you request a default print dialog type, you just need:

 

PrintOption option = null;

option = PrintOption.fromIntent(intent);

// where intent is the Intent returned from PrintDialog

 

If you request an image-type print dialog, you just need: 

 

PrintOption option = null; 

option = (ImageOption) ImageOption.fromIntent(intent);

// where intent is the Intent returned from PrintDialog

 

Next, you should get the selected printer name from PrintDialog:

 

String printerName = intent.getStringExtra(PrintDialog.KEY_PRINTER_NAME); 

// where intent is the Intent returned from PrintDialog 

 

Finally, just request print:

 

PrintJobManager jobManager = PrintJobManager.getInstance();

PrintJob job = jobManager.printJob(“/mnt/sdcard/file.txt”, printerName, option);

Need to buy APF?

Excited with APF for your business? Select a Android print package you need or contact us for inquiry about specific printing solution.