Android_Printservice_API _ Partial Translation

Android_Printservice_API _ Partial Translation
Android. printservice

Provides the printing service implementation class. The Print Service is a plug-in (plug-in components) that can communicate with printers through some standard protocols. These services are like a bridge between the system and the printer. Therefore, the specific implementation of printer and print protocols is separated from the system and can be independently developed and updated.

The implementation of a printing service should be based onPrintServiceClass, and implements its abstract method (abstract methods ). In addition, the printing service must be managed as agreedPrintJob(Print task) class.

The system is responsible for starting and stopping a printing service. This operation depends on whether the printer managed by the printing service has an active print job ). Printer discovery must be performed in a timely manner to ensure a good user experience. During printer discovery, the interaction between the system and the printing service is encapsulated inPrinterDiscoverySessionClass instance, which is created by the print service when required by the system.

Class (Classes) PrintDocument

From the perspective of a print service, this class represents a document to be printed ).

PrinterDiscoverySession

This class encapsulates the interaction between a printing service and the system during the printer discovery process.

PrintJob

For a print service, this class represents a print job ).

PrintService

This basic class is used to implement the Print Service.

Public abstract class

PrintService

Extends Service

java.lang.Object   ?    android.content.Context       ?    android.content.ContextWrapper           ?    android.app.Service               ?    android.printservice.PrintService

Class Overview

This is the basic class implemented by print services. A print service knows how to discover printers and communicate with one or more printers through one or more protocols.

Printer discovery

A print service discovers the printer, adds the printer, removes the added printer, and updates the added printer. When the system requires a printer managed by your service, the system callsonCreatePrinterDiscoverySession()In this function, you must returnPrinterDiscoverySessionObject instance ). The returned session encapsulates the interaction between the system and your service, including the operations in the printer discovery phase. For more information about the interaction, seePrinterDiscoverySessionDocumentation.

For each print session, all printers must be added because the system will not retain the printer after the session. Therefore, each printer detected by the print service should be added only once in a discovery session. Only the added printers can be removed (removed) or updated (updated ). The removed printer can also be added again.

Print job Print jobs

When a new print job is assigned to the printer managed by the print Service, the print job is put into the queue (queued ). That is, prepare the printing service for processing. You will receiveonPrintJobQueued(PrintJob)Call. The printing service may immediately process the printing job or schedule it when it is placed into the plan. All the activities of the Print Service are printed in a list.getActivePrintJobs(). Active print jobs are the ones in the queue or started.

When a printing service is processing a printing job, the printing service is responsible for setting the printing job to the appropriate status. First, a print works in the queue, that isPrintJob.isQueued()Returns true, which means that the document to be printed has been scheduled by the system and can be processed by the printing service at any time. You can callPrintJob.getDocument()Obtain the document to be printed.PrintDocument.getData()Read. When the print service starts printing data, the print job status should be set to started.start()Function settings. After setting,PrintJob.isStarted()Returns true. After the work is completed successfully, the printing work should be marked as completed by callingPrintJob.complete(). After setting,PrintJob.isCompleted()Returns true. If it fails, the print task should be marked as failed by callingPrintJob.fail( String). After setting,PrintJob.isFailed()Returns true.

If a print job is in a queue (queued) or has been started (started), the print Service receivesonRequestCancelPrintJob(PrintJob)Call. This request in the Service is expected to cancel the job as much as possible ). If the job is successfully canceled, its status needs to passPrintJob.cancel()Marked to be canceled. After marking,PrintJob.isCacnelled()Returns true.

Lifecycle

The lifecycle of a print service is only managed by the system and activities are performed according to the specified lifecycle. In addition, starting or stopping a printing service is only triggered by a specific user action, that is, enabling or disabling in the device settings. After the system binds a printing service (binds), the system callsonConnected(). This method can be rewritten by the client (clients) to perform binding operations. In addition, after the system unbinds A printing service, the system callsonDisconnected(). This method can be overwritten by the client (clients) to perform unbinding-related cleanup operations. You should not do any work after the system is disconnected from your printing service, because this service will be killed at any time when memory is recycled. When the printer managed by the Print Service has active printing, the system will not disconnect it.

Declare Declaration

Like any other service, a printing service must be declared in AndroidManifest. xml. However, it must also processandroid.printservice.PrintServiceIntent. If the intent declaration fails, the system ignores the Print Service. In addition, a printing service must requestandroid.permission.BIND_PRINT_SERVICETo ensure that only the system can bind it. Declaring this failure will cause the system to ignore this printing service. The following is an example of a declaration:

 
       
                 
        . . . 
  

Configure Configuration

A printing service can be configured through the setting activity page, which provides the custom setting function. You can manually add a printer or supplier name to an activity that adds a printer. The system is responsible for starting the setting and adding the printer's activities when appropriate.

When declaring a print service, you must providemeta-data, Which specifies the activities method. One servicemeta-dataThe tag declaration is as follows:

For more details about how to configure your print service through meta-data, referSERVICE_META_DATAAnd .

Tip:All callback functions in this class are executed in the main thread of the program. You should also call the methods in the (invoke) Class in the main thread of the program.

 

Public abstract class

PrinterDiscoverySession

Extends Object

java.lang.Object   ?    android.printservice.PrinterDiscoverySession

Class Overview

This class encapsulates the interaction between a Print Service and the system during the printer discovery process. During the printer searching process, you (that is, this class) are responsible for adding the detected printer, removing the previously added but invalid printer, and updating the added printer.

During the lifetime of this session, you may be repeatedly requested to start and stop searching for a printer. You will be calledonStartPrinterDiscovery(List)To start searching for the printer and then be calledonStopPrinterDiscovery()To stop searching for printers. When the system no longer needs this session to look for a printer, you will receiveonDestroy()Call. At this time, the system will no longer call this sessionsessionMethods In the entire session are no longer useful.

The detected printer is calledaddPrinters(List)Method. The added printer is calledremovePrinters(List)To remove. Properties or capabilitiesaddPrinters(List). These added printers can pass throughgetPrinters()Get, In this method, the returned printer is the latest snapshot of the printer you reported (snapshot ). After sessions, these printersNot retained.

The system will callonValidatePrinters(List). You may add only one printer without configuring capabilities ). This mechanism prevents you from querying all the printers in order to configure the printer function. Instead, you can only query a printer function when necessary. For example, if a printer is selected by the user, the system will ask you to update the printer. You do not need to provide printer features when verifying the printer, but you can do so.

If the system constantly monitors the latest printer status, you will receiveonStartPrinterStateTracking(PrinterId)Call. After receiving this message, you must try to keep the system up-to-date with the printer's status and features. When you add a printer before, it does not provide its features.RequiredUpdate the content. Otherwise, the printer will be ignored. When the system no longer needs to obtain the latest printer status, you will receiveonStopPrinterStateTracking(PrinterId)Call.

Tip:All callback functions in this class are executed in the main thread of the program. You also need to call these functions in the main thread when using them.

 

Public final class

PrinterInfo

Extends Object
Implements Parcelable

java.lang.Object   ?    android.print.PrinterInfo

Class Overview

This class is the description of a printer. Instances of this type are created by the Print Service and the printers they manage are reported to the system. There are two parts of the information in this class. The first part includes printer attributes, such as name, id, status, and description ). Part 2: printer capabilities (printer capability ). Printer capabilities describes various print modes supported by the printer, such as media sizes (probably paper size) and margins (white space.

Public final class

PrinterId

Extends Object
Implements Parcelable

java.lang.Object   ?    android.print.PrinterId

Class Overview

This class represents a unique printer ID.

 

Public final class

PrintJob

Extends Object

java.lang.Object   ?    android.printservice.PrintJob

Class Overview

From the perspective of a print service, this class represents a print job ). It provides APIs to observe the status of the print task and perform operations on the print task.

Tip:All methods in the class must be executed in the main application thread.

 

Public final class

PrintJobInfo

Extends Object
Implements Parcelable

java.lang.Object   ?    android.print.PrintJobInfo

Class Overview

This class represents a detailed description of a print task. The status of a printer task includes some configurations, such as its id (number) and print attributes, which are used to generate some content. Note that the print task status may change over time. This class only represents a moment of State (snapshot ).

 

Public final class

PrinterCapabilitiesInfo

Extends Object
Implements Parcelable

java.lang.Object   ?    android.print.PrinterCapabilitiesInfo

Class Overview

This class represents the capabilities of a printer (capabilities ). An instance of this type is created by a print service to report the capabilities of the printers it manages. The ability of a printer shows how it prints content. For example, the printer supports media sizes and the minimal margins.

 

Public final class

PrintDocument

Extends Object

java.lang.Object   ?    android.printservice.PrintDocument

Class Overview

For a printing service, this class represents a file to be printed. It provides APIs to query files and their data.

Tip:All methods must be executed in the main thread of the program.

 

Public final class

PrintDocumentInfo

Extends Object
Implements Parcelable

java.lang.Object   ?    android.print.PrintDocumentInfo

Class Overview

This class encapsulates information about a document related to printing. Thismeta-data(Metadata) is used by platforms and print services to form interaction with printers. For example, this class contains the document page number, which is displayed to users so that they can select the Printing Range. A printing service may optimize the printing of content types, such as documents or photos.

The instance of this class is created by the application to be printed and called after the content is successfully laying out the content.PrintDocumentAdapter.LayoutResultCallback.onLayoutFinished( PrintDocumentInfo, boolean)Callback function. This process is executed inPrintDocumentAdapter.onLayout(PrintAttributes, PrintAttributes, android.os.CancellationSignal, PrintDocumentAdapter.LayoutResultCallback, android.os.Bundle).

An example is as follows:

 . . . public void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,         CancellationSignal cancellationSignal, LayoutResultCallback callback,         Bundle metadata) {        // Assume the app defined a LayoutResult class which contains        // the layout result data and that the content is a document.        LayoutResult result = doSomeLayoutWork();        PrintDocumentInfo info = new PrintDocumentInfo                .Builder("printed_file.pdf")                .setContentType(PrintDocumentInfo.CONTENT_TYPE_DOCUMENT)                .setPageCount(result.getPageCount())                .build();       callback.onLayoutFinished(info, result.getContentChanged());   }   . . .