PrintService
  public
  
  
  abstract
  class
  PrintService
  
  
  
  
  
  
  
  
  
  
    extends Service
  
  
  
  
  
  
| java.lang.Object | ||||
| ↳ | 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.
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(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 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 | |
|---|---|
| String | EXTRA_CAN_SELECT_PRINTERWhen the  | 
| String | EXTRA_PRINTER_INFOIf you declared an optional activity with advanced print options via the
  | 
| String | EXTRA_PRINT_DOCUMENT_INFOIf you declared an optional activity with advanced print options via the
  | 
| String | EXTRA_PRINT_JOB_INFOIf you declared an optional activity with advanced print options via the
  | 
| String | EXTRA_SELECT_PRINTERIf this boolean extra is set to  | 
| String | SERVICE_INTERFACEThe  | 
| String | SERVICE_META_DATAName under which a  | 
| Inherited constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 
      From class
         android.app.Service
 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
      From class
         android.content.Context
 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
      From interface
         android.content.ComponentCallbacks2
 | 
| Public constructors | |
|---|---|
| 
      PrintService()
       | |
| Public methods | |
|---|---|
| 
        
        
        
        final
        
        PrinterId | 
      generatePrinterId(String localId)
      Generates a global printer id given the printer's locally unique one. | 
| 
        
        
        
        final
        
        List<PrintJob> | 
      getActivePrintJobs()
      Gets the active print jobs for the printers managed by this service. | 
| 
        
        
        
        final
        
        IBinder | 
      onBind(Intent intent)
      Return the communication channel to the service. | 
| Protected methods | |
|---|---|
| 
        
        
        
        final
        
        void | 
      attachBaseContext(Context base)
      Set the base context for this ContextWrapper. | 
| 
        
        
        
        
        
        void | 
      onConnected()
      The system has connected to this service. | 
| 
        abstract
        
        
        
        
        PrinterDiscoverySession | 
      onCreatePrinterDiscoverySession()
      Callback asking you to create a new  | 
| 
        
        
        
        
        
        void | 
      onDisconnected()
      The system has disconnected from this service. | 
| 
        abstract
        
        
        
        
        void | 
      onPrintJobQueued(PrintJob printJob)
      Called when there is a queued print job for one of the printers managed by this print service. | 
| 
        abstract
        
        
        
        
        void | 
      onRequestCancelPrintJob(PrintJob printJob)
      Called when cancellation of a print job is requested. | 
| Inherited methods | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 
    From class
       
        
          android.app.Service
        
      
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
    From class
       
        
          android.content.ContextWrapper
        
      
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
    From class
       
        
          android.content.Context
        
      
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
    From class
       
        
          java.lang.Object
        
      
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
    From interface
       
        
          android.content.ComponentCallbacks2
        
      
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 
    From interface
       
        
          android.content.ComponentCallbacks
        
      
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Constants
EXTRA_CAN_SELECT_PRINTER
public static final String EXTRA_CAN_SELECT_PRINTER
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.
See also:
Constant Value: "android.printservice.extra.CAN_SELECT_PRINTER"
EXTRA_PRINTER_INFO
public static final String 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.
See also:
Constant Value: "android.intent.extra.print.EXTRA_PRINTER_INFO"
EXTRA_PRINT_DOCUMENT_INFO
public static final String 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.
See also:
Constant Value: "android.printservice.extra.PRINT_DOCUMENT_INFO"
EXTRA_PRINT_JOB_INFO
public static final String 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.
 
 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.
 
See also:
Constant Value: "android.intent.extra.print.PRINT_JOB_INFO"
EXTRA_SELECT_PRINTER
public static final String EXTRA_SELECT_PRINTER
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.
See also:
Constant Value: "android.printservice.extra.SELECT_PRINTER"
SERVICE_INTERFACE
public static final String SERVICE_INTERFACE
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.
Constant Value: "android.printservice.PrintService"
SERVICE_META_DATA
public static final String SERVICE_META_DATA
Name under which a PrintService component publishes additional information
 about itself. This meta-data must reference a XML resource containing a 
 < tag. This is
 a sample XML file configuring a print service:
 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 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
 R.attr.permission activity attribute.
 
Constant Value: "android.printservice"
Public constructors
PrintService
public PrintService ()
Public methods
generatePrinterId
public final PrinterId generatePrinterId (String localId)
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. | 
| Returns | |
|---|---|
| PrinterId | Global printer id.
 This value cannot be null. | 
getActivePrintJobs
public final List<PrintJob> getActivePrintJobs ()
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.
| Returns | |
|---|---|
| List<PrintJob> | The active print jobs. | 
See also:
onBind
public final IBinder onBind (Intent intent)
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 toContext.bindService.  Note that any extras that were included with
 the Intent at that point will not be seen here. | 
| Returns | |
|---|---|
| IBinder | Return an IBinder through which clients can call on to the service. | 
Protected methods
attachBaseContext
protected final void attachBaseContext (Context base)
Set the base context for this ContextWrapper. All calls will then be delegated to the base context. Throws IllegalStateException if a base context has already been set.
| Parameters | |
|---|---|
| base | Context: The new base context for this wrapper. | 
onConnected
protected void onConnected ()
The system has connected to this service.
onCreatePrinterDiscoverySession
protected abstract PrinterDiscoverySession onCreatePrinterDiscoverySession ()
Callback asking you to create a new PrinterDiscoverySession.
| Returns | |
|---|---|
| PrinterDiscoverySession | The created session.
 This value may be null. | 
See also:
onDisconnected
protected void onDisconnected ()
The system has disconnected from this service.
onPrintJobQueued
protected abstract void onPrintJobQueued (PrintJob printJob)
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. | 
See also:
onRequestCancelPrintJob
protected abstract void onRequestCancelPrintJob (PrintJob printJob)
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. | 
See also:
