Printer discovery

Print jobs

Lifecycle

Declaration

 <service android:name=".MyPrintService"
         android:permission="android.permission.BIND_PRINT_SERVICE">
     <intent-filter>
         <action android:name="android.printservice.PrintService" />
     </intent-filter>
     . . .
 </service>
 

Configuration

This is the base class for implementing print services. A print service knows how to discover and interact one or more printers via one or more protocols.

A print service is responsible for discovering printers, adding discovered printers, removing added printers, and updating added printers. When the system is interested in printers managed by your service it will call PrintService.OnCreatePrinterDiscoverySession from which you must return a new Android.PrintServices.PrinterDiscoverySession instance. The returned session encapsulates the interaction between the system and your service during printer discovery. For description of this interaction refer to the documentation for Android.PrintServices.PrinterDiscoverySession.

For every printer discovery session all printers have to be added since system does not retain printers across sessions. Hence, each printer known to this print service should be added only once during a discovery session. Only an already added printer can be removed or updated. Removed printers can be added again.

When a new print job targeted to a printer managed by this print service is is queued, i.e. ready for processing by the print service, you will receive a call to PrintService.OnPrintJobQueued(PrintJob). The print service may handle the print job immediately or schedule that for an appropriate time in the future. The list of all active print jobs for this service is obtained by calling PrintService.ActivePrintJobs. Active print jobs are ones that are queued or started.

A print service is responsible for setting a print job's state as appropriate while processing it. Initially, a print job is queued, i.e. PrintJob.IsQueued returns true, which means that the document to be printed is spooled by the system and the print service can begin processing it. You can obtain the printed document by calling PrintJob.Document whose data is accessed via PrintDocument.Data. After the print service starts printing the data it should set the print job's state to started by calling PrintJob.Start after which PrintJob.IsStarted would return true. Upon successful completion, the print job should be marked as completed by calling PrintJob.Complete after which PrintJob.IsCompleted would return true. In case of a failure, the print job should be marked as failed by calling PrintJob.Fail(string) after which PrintJob.IsFailed would return true.

If a print job is queued or started and the user requests to cancel it, the print service will receive a call to PrintService.OnRequestCancelPrintJob(PrintJob) which requests from the service to do best effort in canceling the job. In case the job is successfully canceled, its state has to be marked as cancelled by calling PrintJob.Cancel after which PrintJob.IsCancelled would return true.

The lifecycle of a print service is managed exclusively by the system and follows the established service lifecycle. Additionally, starting or stopping a print service is triggered exclusively by an explicit user action through enabling or disabling it in the device settings. After the system binds to a print service, it calls PrintService.OnConnected. This method can be overriden by clients to perform post binding setup. Also after the system unbinds from a print service, it calls PrintService.OnDisconnected. This method can be overriden by clients to perform post unbinding cleanup. Your should not do any work after the system disconnected from your print service since the service can be killed at any time to reclaim memory. The system will not disconnect from a print service if there are active print jobs for the printers managed by it.

A print service is declared as any other service in an AndroidManifest.xml but it must also specify that it handles the Android.Content.Intent with action PrintService.ServiceInterface. Failure to declare this intent will cause the system to ignore the print service. Additionally, a print service must request the NoType:android/Manifest$permission;Href=../../../reference/android/Manifest.permission.html#BIND_PRINT_SERVICE permission to ensure that only the system can bind to it. Failure to declare this intent will cause the system to ignore the print service. Following is an example declaration:

A print service can be configured by specifying an optional settings activity which exposes service specific settings, an optional add printers activity which is used for manual addition of printers, vendor name ,etc. It is a responsibility of the system to launch the settings and add printers activities when appropriate.

A print service is configured by providing a PrintService.ServiceMetaData entry in the manifest when declaring the service. A service declaration with a meta-data tag is presented below:

 <service android:name=".MyPrintService"
         android:permission="android.permission.BIND_PRINT_SERVICE">
     <intent-filter>
         <action android:name="android.printservice.PrintService" />
     </intent-filter>
     <meta-data android:name="android.printservice" android:resource="@xml/printservice" />
 </service>

For more details for how to configure your print service via the meta-data refer to PrintService.ServiceMetaData and <NoType:android/R$styleable;Href=../../../reference/android/R.styleable.html#PrintService>.

Note: All callbacks in this class are executed on the main application thread. You should also invoke any method of this class on the main application thread.

[Android Documentation]