Developer Guide. Android Printing Framework. ISB Vietnam Co., Ltd. (IVC) Page i

Transcription

1 Android Printing Framework ISB Vietnam Co., Ltd. (IVC) Page i

2 Table of Content 1 Introduction Terms and definitions Developer guide Overview Configure development environment Install APF Core module Install and configure APF SDK module Using APF SDK for proramming Create a connection to printing service Search the available devices connected to the system Synchronously searching method Asynchronously searching method Combine searching modes Cancel searching method Create new device object Search printer driver Add a new printer to the system Add printer without driver Add printer with giving driver Get printer from the system Remove the printer Print a file (submit a print job) Print an URL Print preview Cancel / Remove job Get jobs Get all jobs Get job by id Get job by state Get job by printer Get job by printer and state Using extend print options Technical Support ISB Vietnam Co., Ltd. (IVC) Page ii

3 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: 3 Developer guide 3.1 Overview APF Mobile included two modules: APFCore: The core application of APF, was packed as Android package (APK) APFSdk: The SDK provide printing APIs for building printing application using APF 3.2 Configure development environment 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 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

4 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

5 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(); 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 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

6 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() { 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"); ; 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"); this: Finally, on the oncreate() method of Activity, call the bind() method with your key like ISB Vietnam Co., Ltd. (IVC) Page 4/12

7 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 protected void ondestroy() { super.ondestroy(); /* * Application should release connection to * Printing rervice when exit */ if (mprintingservice!= null) mprintingservice.unbind(); 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

8 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 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()); 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

9 method. onfinished(string token): This scanning process was finished when calling this private OnDeviceScanningListener mdevicescanninglistener = new OnDeviceScanningListener() { public void onstart(string token) { msearchasynctoken = token; Log.d(TAG, "Search with token = " + token); 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()); ; 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); Combine searching modes this: You can also combine the searching mode search more device at the searching session like mprintingservice.searchavailabledevices( Device.SEARCH_NW_BONJOUR Device.SEARCH_BLUETOOTH, mdevicescanninglistener); ISB Vietnam Co., Ltd. (IVC) Page 7/12

10 In above sample, we combine Bonjour searching method with Bluetooth searching method at one searching session 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); 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 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

11 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); 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. driver. We provide 2 ways of adding printer method: add printer without driver and add printer with 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

12 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 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()); 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

13 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()); 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

14 boolean result = mprintingservice.removeprinter("printer-1"); 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 Print an URL Like the printfile() method, the printurl() method will print the internet web page with giving address. String url = " 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 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

15 private OnPrintPreviewListener mprintpreviewlistener = new OnPrintPreviewListener() { public void onbeginpreview(string token) { // Start preview with token public void onpagefinished(string token, int number, String path) { // Be called when one page is preview completed 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)); Cancel / Remove job ISB Vietnam Co., Ltd. (IVC) Page 13/12

16 remove job. PrintingService also provides method to take more operations to job consist of: cancel / 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 Get jobs To view the list of jobs which submitted, PrintingService provides many types of get job methods to serve many purposes 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(); 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); 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); 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

17 String printername = "Canon-MG6130"; ArrayList<Job> jobs = mprintingservice.getjobs(printername); 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); 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

18 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

19 4 Technical Support For technical support or advice, please contact these mail addresses: Mr. Tan Quang Sang: Mr. Phan Dang Duy Thinh: ISB Vietnam Co., Ltd. (IVC) Page 17/12