Android_Printservice_API_部分翻译

文件夹
* package android.printservice
* public abstract class PrintService
* public abstract class PrinterDiscoverySession
* public final class PrinterInfo
* public final class PrinterId
* public final class PrintJob
* public final class PrintJobInfo
* public final class PrinterCapabilitiesInfo
* public final class PrintDocument
* public final class PrintDocumentInfo

---

原连接：https://developer.android.com/reference/android/printservice/package-summary.html

package

android.printservice

提供打印服务实现的类。打印服务是一种插件（ plug-in components），它可以经过一些标准协议和打印机通信。

这些服务像一座桥。处于系统和打印机之间。所以，打印机和打印协议的具体实现从系统中分离的，可以独立开发和更新。

一个打印服务实现应该基于PrintService类。并且实现它的抽象方法（abstract methods）。

另外，打印服务必需要按约定来管理PrintJob（打印任务）类。

系统负责启动和中止一个打印服务。这个操做取决于该打印服务管理的打印机是否有激活的打印任务（active print jobs）。打印服务还要及时运行打印机发现操做，来保证好的用户体验。

在打印机发现过程当中系统和该打印服务的交互封装在PrinterDiscoverySession类的实例中。由打印服务在系统需要的时候建立。

类 （Classes）

PrintDocument

从一个打印服务的角度来讲，这个类表明一个待打印的文件（document）。

PrinterDiscoverySession

这个类封装了打印机发现过程当中一个打印服务和系统的交互操做。

PrintJob

对一个打印服务来讲，这个类表明一个打印任务（print job）。

PrintService

这个基础类用来实现打印服务。

---

原连接：https://developer.android.com/reference/android/printservice/PrintService.html

public abstract class

PrintService

extends Service

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

类综述 Class Overview

这是打印服务（print services）实现的基础类。

一个打印服务知道怎样去发现打印机。并且经过一个或多个协议和一个或多个打印机交流。

打印机发现 Printer discovery

一个打印服务负责发现打印机，加入发现的打印机。移除加入的打印机和更新加入的打印机。

当系统需要你的服务所管理的打印机时，系统会调用onCreatePrinterDiscoverySession(),在这个函数里你必须返回一个PrinterDiscoverySession对象实例（instance）。

这个返回的session（会话）封装了系统和你的服务交互的内容。包括在打印机发现阶段的操做。

这个交互的不少其它描写叙述。參考PrinterDiscoverySession文档。

对每个打印发现会话（session）来讲。所有的打印机必需要被加入，因为系统在会话事后不会保留。所以。打印服务检測到的每个打印机都应该被加入。并且在一个发现会话中仅加入一次。仅仅有已经加入的打印机才干被移除（removed）或者更新（updated）。

移除的打印机也能被再次加入。

打印工做 Print jobs

当一个新的打印工做（print jobs）指派到该打印服务所管理的打印机上，打印工做被放入队列（queued）。也就是，准备好由打印服务处理。

你会收到一个onPrintJobQueued(PrintJob)调用。该打印服务可能会立刻处理这个打印工做或者放入计划中过会调度。该打印服务的所有活动的打印工做在一个列表里，这个列表经过调用getActivePrintJobs()可以得到。活动的打印工做（Active print jobs）就是在队列中或已開始的那些。

当一个打印服务在处理一个打印工做时。打印服务负责设置该打印工做为适当的状态。

首先，一个打印工做在队列中，也就是PrintJob.isQueued()返回true。这意味着要打印的文档已被系统安排(spooled)，该打印服务可以随时处理它。

你可以经过调用PrintJob.getDocument()得到要打印的文档。这里面的数据可以经过PrintDocument.getData()读取。在打印服务開始打印数据，该打印工做（print job）状态应该被设置为已開始（started），经过调用start()函数设置。设置以后，PrintJob.isStarted()应该会返回true。在工做成功完毕后。该打印工做应该被标记为已完毕（completed），经过调用PrintJob.complete()设置。设置以后，PrintJob.isCompleted()应该会返回true。

失败的话，该打印工做应该被标记为失败（failed）,经过调用PrintJob.fail( String)设置。

设置后，PrintJob.isFailed()应该返回true。

假设一个打印工做（print job）处于队列（queued）或已開始（started）。这时用户请求取消它，该打印服务会收到一个onRequestCancelPrintJob(PrintJob)调用。服务里的这个请求但愿尽最大努力取消该工做（job）。若该工做被成功取消，它的状态需要经过PrintJob.cancel()被标记取消。

标记后。PrintJob.isCacnelled()应该返回true。

生命周期 Lifecycle

一个打印服务的生命周期仅仅由系统管理并且按规定的生命周期活动。另外。開始或者中止一个打印服务仅仅由一个特定的用户行为触发，就是在设备设置里启用（enabling）或者禁用（disabling）服务。

在系统绑定（binds）了一个打印服务后，系统会调用onConnected()。

这种方法可以被客户端（clients）重写来运行绑定（binding）有关的操做。并且在系统解绑（unbinds）一个打印服务后，系统会调用onDisconnected()。

这种方法可以被客户端（clients）重写来运行解绑（unbinding）有关的清理操做。你的不论什么工做都不该该在系统和你的打印服务断开链接以后作，因为这个服务在回收内存时随时会被杀死。当该打印服务管理的打印机有活动的打印工做时。系统不会与之断开链接。

声明 Declaration

一个打印服务和其它不论什么服务同样，需要在AndroidManifest.xml里声明。但是它还必须处理action为android.printservice.PrintService的Intent。

这个intent声明失败会致使系统忽略该打印服务。

另外，一个打印服务必须请求android.permission.BIND_PRINT_SERVICE权限，来保证仅仅有系统能绑定（bind）它。声明这个失败会致使系统忽略这个打印服务。如下是一个声明的样例：

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

配置 Configuration

一个打印服务可经过本身定义设置页面（setting activity）进行配置，该activity提供本身定义设置功能。

一个加入打印机的activity可以手动加入打印机。供应商名称等等。系统负责在适当的时候启动设置和加入打印机的activities。

一个打印服务在声明的时候，要在mainfest里提供一条meta-data。这是指定上述activities的方式。一个服务的meta-data标签（tag）声明例如如下所看到的：

<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>

关于经过meta-data配置你的打印服务的不少其它细节，可以參考SERVICE_META_DATA和<print-service>。

提示：这个类里的所有回调函数（callbacks）都在程序的主线程里运行。你也应该在程序的主线程里调用（invoke）这个类里的方法。

---

原连接： https://developer.android.com/reference/android/printservice/PrinterDiscoverySession.html

public abstract class

PrinterDiscoverySession

extends Object

java.lang.Object
   ↳    android.printservice.PrinterDiscoverySession

类综述 Class Overview

这个类封装了一个打印服务和系统在打印机寻找（printer discovery）过程当中的交互内容。在打印机寻找过程当中，你（指这个类）负责加入发现的打印机，移除以前加入但无效的打印机，更新已经加入的打印机。

在这个会话（session）的一辈子中，你可能会被屡次请求開始和中止寻找打印机。

你会被调用onStartPrinterDiscovery(List)来開始寻找打印机，而后被调用onStopPrinterDiscovery()来中止寻找打印机。

当系统再也不需要这个会话（session）来寻找打印机，你会收到onDestroy()调用。在这时。系统将不会再调用这个会话session，整个会话里的方法都再也不实用。

被发现的打印机经过调用addPrinters(List)方法加入。

加入好的打印机经过调用removePrinters(List)来移除。

加入的打印机的属性和功能（properties or capabilities ）经过调用addPrinters(List)来更新。

这些被加入的打印机能经过getPrinters()获取。在该方法里返回的打印机是你上报的打印机的一个最新快照（snapshot）。

这些打印机在会话（session）后不会保留。

假设你（推測指用户。以前指这个类）需要更新一些打印机，系统会调用onValidatePrinters(List)。

你可能会仅仅加入一个打印机而不配置它的功能特性（capabilities）。这个机制使得你避免为了配置打印机的功能而查询所有打印机。而是仅仅在必要的时候查询一个打印机的功能就能够。

好比，一个打印机被用户选择使用，系统会请求你更新这个打印机。

验证打印机时你不需要提供打印机的功能特性，但可以这样作。

假设系统要持续监測打印机的最新状态，你会收到一个onStartPrinterStateTracking(PrinterId)调用。

收到以后，你必须尽量地保持系统获得打印机最新的状态和功能特性。当你以前加入打印机的时候没有提供它的功能特性，你在这时必须更新这些内容。要否则打印机就会被忽略。当系统再也不需要获取打印机的最新状态时，你会收到一个onStopPrinterStateTracking(PrinterId)调用。

提示：这个类里的所有回调函数都在程序的主线程运行。你本身用的时候也要在主线程调用这些函数。

---

public final class

PrinterInfo

extends Object
implements Parcelable

java.lang.Object
   ↳    android.print.PrinterInfo

类综述 Class Overview

这个类是一个打印机的描写叙述。

这个类的实例由打印服务建立。把它们管理的打印机报告给系统。这个类里面的信息有两大部分。第一部分。打印机属性，列如name（名称）,id（编号）,status（状态），description（描写叙述）。第二部分，printer capabilities（打印机能力）。printer capabilities描写叙述了打印机支持的各类打印模式，好比media sizes（大概是纸张尺寸），margins（留白大小）等等。

---

public final class

PrinterId

extends Object
implements Parcelable

java.lang.Object
   ↳    android.print.PrinterId

类综述 Class Overview

这个类表明一个打印机独一无二的编号

---

public final class

PrintJob

extends Object

java.lang.Object
   ↳    android.printservice.PrintJob

类综述 Class Overview

从一个打印服务的角度来看。这个类表明一个打印任务（print job）。它提供了一些API来观察打印任务的状态和在打印任务上运行操做。

提示：类里面的所有方法都必须在应用主线程里运行。

---

public final class

PrintJobInfo

extends Object
implements Parcelable

java.lang.Object
   ↳    android.print.PrintJobInfo

类综述 Class Overview

这个类表明了一个打印任务的具体描写叙述。

打印机任务的状态包括一些配置。好比：它的id（编号）、打印属性。这用来生成一些内容等等。注意，打印任务状态可能会随着时间改变。这个类仅仅表明了状态的一个时刻（snapshot）。

---

public final class

PrinterCapabilitiesInfo

extends Object
implements Parcelable

java.lang.Object
   ↳    android.print.PrinterCapabilitiesInfo

类综述 Class Overview

这个类表明了一个打印机的能力（capabilities）。

这个类的实例由一个打印服务建立，用来报告它所管理的打印机的能力。

一个打印机的能力指出了它怎样打印内容。

好比：打印机支持什么纸张大小（media sizes），打印机设计的最小留白（the minimal margins），等等。

---

public final class

PrintDocument

extends Object

java.lang.Object
   ↳    android.printservice.PrintDocument

类综述 Class Overview

对一个打印服务来讲，这个类表明一个待打印的文件。

它提供一些API来查询文件和其包括的数据。

提示：所有的方法必须在程序的主线程里运行。

---

public final class

PrintDocumentInfo

extends Object
implements Parcelable

java.lang.Object
   ↳    android.print.PrintDocumentInfo

类综述 Class Overview

这个类封装了关于一个文档跟打印有关的信息。

这个meta-data（元数据）被平台（platform）和打印服务使用，构成和打印机的交互。

好比，这个类包括文档的页数，文档页数展现给使用者是为了使他们可以选择打印的范围。一个打印服务可能会针对内容类型对打印进行优化，好比文档（document）或者照片。

这个类的实例由需要打印的应用建立。在成功排版内容（laying out the content）以后调用PrintDocumentAdapter.LayoutResultCallback.onLayoutFinished( PrintDocumentInfo, boolean)回调函数。这个过程运行在PrintDocumentAdapter.onLayout(PrintAttributes, PrintAttributes, android.os.CancellationSignal, PrintDocumentAdapter.LayoutResultCallback, android.os.Bundle)里。

一个使用样例例如如下：

. . .

 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());
   }

   . . .