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 {@link
#onCreatePrinterDiscoverySession()} from which you must return a new {@link
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 {@link 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 {@link
#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 {@link #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. {@link PrintJob#isQueued()
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 {@link PrintJob#getDocument() PrintJob.getDocument()}
whose data is accessed via {@link PrintDocument#getData() PrintDocument.getData()}.
After the print service starts printing the data it should set the print job's
state to started by calling {@link PrintJob#start()} after which
{@link PrintJob#isStarted() PrintJob.isStarted()} would return true. Upon successful
completion, the print job should be marked as completed by calling {@link
PrintJob#complete() PrintJob.complete()} after which {@link PrintJob#isCompleted()
PrintJob.isCompleted()} would return true. In case of a failure, the print job should
be marked as failed by calling {@link PrintJob#fail(String) PrintJob.fail(
String)} after which {@link PrintJob#isFailed() 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 {@link #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 {@link
PrintJob#cancel() PrintJob.cancel()} after which {@link PrintJob#isCancelled()
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 {@link
#onConnected()}. This method can be overriden by clients to perform post binding setup.
Also after the system unbinds from a print service, it calls {@link #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 {@link android.content.Intent} with action {@link
#SERVICE_INTERFACE android.printservice.PrintService}. Failure to declare this intent
will cause the system to ignore the print service. Additionally, a print service must
request the {@link android.Manifest.permission#BIND_PRINT_SERVICE
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 {@link #SERVICE_META_DATA 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
{@link #SERVICE_META_DATA} and <{@link android.R.styleable#PrintService
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.
| 