Added in API level 19

PrintService


abstract class PrintService : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ android.printservice.PrintService

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.

Printer discovery

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 onCreatePrinterDiscoverySession() from which you must return a new 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 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 onPrintJobQueued(android.printservice.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 getActivePrintJobs(). 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.getDocument() whose data is accessed via PrintDocument.getData(). 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 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 onRequestCancelPrintJob(android.printservice.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.isCacnelled() would return true.

Lifecycle

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 onConnected(). This method can be overriden by clients to perform post binding setup. Also after the system unbinds from a print service, it calls 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.

Declaration

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 android.printservice.PrintService. Failure to declare this intent will cause the system to ignore the print service. Additionally, a print service must request the android.permission.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:

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

Configuration

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 meta-data 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 SERVICE_META_DATA and < print-service>.

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.

Summary

Constants
static String

When the PendingIntent declared via PrinterInfo.Builder#setInfoIntent(PendingIntent) is called this boolean extra will be filled in if the activity can select the printer.

static String

If you declared an optional activity with advanced print options via the advancedPrintOptionsActivity attribute, this extra is used to pass in the currently selected printer's android.print.PrinterInfo to your activity allowing you to inspect it.

static String

If you declared an optional activity with advanced print options via the advancedPrintOptionsActivity attribute, this extra is used to pass in the meta-data for the currently printed document as a android.print.PrintDocumentInfo to your activity allowing you to inspect it.

static String

If you declared an optional activity with advanced print options via the advancedPrintOptionsActivity attribute, this extra is used to pass in the currently constructed PrintJobInfo to your activity allowing you to modify it.

static String

If this boolean extra is set to true in the result data from the activity specified in PrinterInfo.Builder#setInfoIntent(PendingIntent) the printer will be selected.

static String

The Intent action that must be declared as handled by a service in its manifest for the system to recognize it as a print service.

static String

Name under which a PrintService component publishes additional information about itself.

Inherited constants
Public constructors

Public methods
PrinterId

Generates a global printer id given the printer's locally unique one.

MutableList<PrintJob!>!

Gets the active print jobs for the printers managed by this service.

IBinder?
onBind(intent: Intent!)

Protected methods
Unit

open Unit

The system has connected to this service.

abstract PrinterDiscoverySession?

Callback asking you to create a new PrinterDiscoverySession.

open Unit

The system has disconnected from this service.

abstract Unit

Called when there is a queued print job for one of the printers managed by this print service.

abstract Unit

Called when cancellation of a print job is requested.

Inherited functions

Constants

EXTRA_CAN_SELECT_PRINTER

Added in API level 26
static val EXTRA_CAN_SELECT_PRINTER: String

When the PendingIntent declared via PrinterInfo.Builder#setInfoIntent(PendingIntent) is called this boolean extra will be filled in if the activity can select the printer.

Value: "android.printservice.extra.CAN_SELECT_PRINTER"

EXTRA_PRINTER_INFO

Added in API level 21
static val EXTRA_PRINTER_INFO: String

If you declared an optional activity with advanced print options via the advancedPrintOptionsActivity attribute, this extra is used to pass in the currently selected printer's android.print.PrinterInfo to your activity allowing you to inspect it.

Value: "android.intent.extra.print.EXTRA_PRINTER_INFO"

EXTRA_PRINT_DOCUMENT_INFO

Added in API level 23
static val EXTRA_PRINT_DOCUMENT_INFO: String

If you declared an optional activity with advanced print options via the advancedPrintOptionsActivity attribute, this extra is used to pass in the meta-data for the currently printed document as a android.print.PrintDocumentInfo to your activity allowing you to inspect it.

Value: "android.printservice.extra.PRINT_DOCUMENT_INFO"

EXTRA_PRINT_JOB_INFO

Added in API level 19
static val EXTRA_PRINT_JOB_INFO: String

If you declared an optional activity with advanced print options via the advancedPrintOptionsActivity attribute, this extra is used to pass in the currently constructed PrintJobInfo to your activity allowing you to modify it. After you are done, you must return the modified PrintJobInfo via the same extra.

You cannot modify the passed in PrintJobInfo directly, rather you should build another one using the PrintJobInfo.Builder class. You can specify any standard properties and add advanced, printer specific, ones via PrintJobInfo.Builder.putAdvancedOption(String, String) and PrintJobInfo.Builder.putAdvancedOption(String, int). The advanced options are not interpreted by the system, they will not be visible to applications, and can only be accessed by your print service via PrintJob.getAdvancedStringOption(String) and PrintJob.getAdvancedIntOption(String).

If the advanced print options activity offers changes to the standard print options, you can get the current PrinterInfo using the EXTRA_PRINTER_INFO extra which will allow you to present the user with UI options supported by the current printer. For example, if the current printer does not support a given media size, you should not offer it in the advanced print options UI.

Value: "android.intent.extra.print.PRINT_JOB_INFO"

EXTRA_SELECT_PRINTER

Added in API level 26
static val EXTRA_SELECT_PRINTER: String

If this boolean extra is set to true in the result data from the activity specified in PrinterInfo.Builder#setInfoIntent(PendingIntent) the printer will be selected.

Value: "android.printservice.extra.SELECT_PRINTER"

SERVICE_INTERFACE

Added in API level 19
static val SERVICE_INTERFACE: String

The Intent action that must be declared as handled by a service in its manifest for the system to recognize it as a print service.

Value: "android.printservice.PrintService"

SERVICE_META_DATA

Added in API level 19
static val SERVICE_META_DATA: String

Name under which a PrintService component publishes additional information about itself. This meta-data must reference a XML resource containing a <print-service> tag. This is a sample XML file configuring a print service:

<print-service
      android:vendor="SomeVendor"
      android:settingsActivity="foo.bar.MySettingsActivity"
      android:addPrintersActivity="foo.bar.MyAddPrintersActivity."
      . . .
  />

For detailed configuration options that can be specified via the meta-data refer to android.R.styleable.PrintService.

If you declare a settings or add a printers activity, they have to be exported, by setting the android.R.attr#exported activity attribute to true . Also in case you want only the system to be able to start any of these activities you can specify that they request the android.permission .START_PRINT_SERVICE_CONFIG_ACTIVITY permission by setting the android.R.attr#permission activity attribute.

Value: "android.printservice"

Public constructors

PrintService

PrintService()

Public methods

generatePrinterId

Added in API level 19
fun generatePrinterId(localId: String!): PrinterId

Generates a global printer id given the printer's locally unique one.

Parameters
localId String!: A locally unique id in the context of your print service.
Return
PrinterId Global printer id. This value cannot be null.

getActivePrintJobs

Added in API level 19
fun getActivePrintJobs(): MutableList<PrintJob!>!

Gets the active print jobs for the printers managed by this service. Active print jobs are ones that are not in a final state, i.e. whose state is queued or started.

Return
MutableList<PrintJob!>! The active print jobs.

onBind

Added in API level 19
fun onBind(intent: Intent!): IBinder?
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
IBinder? Return an IBinder through which clients can call on to the service.

Protected methods

attachBaseContext

Added in API level 19
protected fun attachBaseContext(base: Context!): Unit
Parameters
base Context!: The new base context for this wrapper.

onConnected

Added in API level 19
protected open fun onConnected(): Unit

The system has connected to this service.

onCreatePrinterDiscoverySession

Added in API level 19
protected abstract fun onCreatePrinterDiscoverySession(): PrinterDiscoverySession?

Callback asking you to create a new PrinterDiscoverySession.

Return
PrinterDiscoverySession? The created session. This value may be null.

onDisconnected

Added in API level 19
protected open fun onDisconnected(): Unit

The system has disconnected from this service.

onPrintJobQueued

Added in API level 19
protected abstract fun onPrintJobQueued(printJob: PrintJob!): Unit

Called when there is a queued print job for one of the printers managed by this print service.

Parameters
printJob PrintJob!: The new queued print job.

onRequestCancelPrintJob

Added in API level 19
protected abstract fun onRequestCancelPrintJob(printJob: PrintJob!): Unit

Called when cancellation of a print job is requested. The service should do best effort to fulfill the request. After the cancellation is performed, the print job should be marked as cancelled state by calling PrintJob#cancel().

Parameters
printJob PrintJob!: The print job to cancel.