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.

Print jobs

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(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 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 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.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 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:

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:

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
PrinterInfo to your activity allowing you to inspect it.

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 PrintDocumentInfo to your activity allowing
you to inspect it.

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.

Flag for bindService(Intent, ServiceConnection, int): If binding from an activity, allow the
target service's process importance to be raised based on whether the
activity is visible to the user, regardless whether another flag is
used to reduce the amount that the client process's overall importance
is used to impact it.

This constant was deprecated
in API level 23.
MODE_MULTI_PROCESS does not work reliably in
some versions of Android, and furthermore does not provide any
mechanism for reconciling concurrent modifications across
processes. Applications should not attempt to use it. Instead,
they should use an explicit cross-process data management
approach such as ContentProvider.

This constant was deprecated
in API level 17.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider,
BroadcastReceiver, and Service.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.

This constant was deprecated
in API level 17.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider,
BroadcastReceiver, and Service.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.

Level for onTrimMemory(int): the process is around the middle
of the background LRU list; freeing memory can help the system keep
other processes running later in the list for better overall performance.

Level for onTrimMemory(int): the process is not an expendable
background process, but the device is running extremely low on memory
and is about to not be able to keep any background processes running.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

EXTRA_PRINTER_INFO

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
PrinterInfo to your activity allowing you to inspect it.

EXTRA_PRINT_DOCUMENT_INFO

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 PrintDocumentInfo to your activity allowing
you to inspect it.

EXTRA_PRINT_JOB_INFO

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.

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.

SERVICE_META_DATA

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:

If you declare a settings or add a printers activity, they have to be exported,
by setting the 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
permission activity attribute.

onBind

Return the communication channel to the service. May return null if
clients can not bind to the service. The returned
IBinder is usually for a complex interface
that has been described using
aidl.

Note that unlike other application components, calls on to the
IBinder interface returned here may not happen on the main thread
of the process. More information about the main thread can be found in
Processes and
Threads.

Parameters

intent

Intent: The Intent that was used to bind to this service,
as given to Context.bindService. Note that any extras that were included with
the Intent at that point will not be seen here.

onRequestCancelPrintJob

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