Android_Printservice_API_部分翻譯

時間 2019-11-05

標籤 android printservice api 部分翻譯欄目 Android 简体版

原文原文鏈接

文件夾
* 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 PrintDocumentInfohtml

原連接：https://developer.android.com/reference/android/printservice/package-summary.htmljava

packageandroid

android.printservice

提供打印服務實現的類。打印服務是一種插件（ plug-in components），它可以經過一些標準協議和打印機通信。markdown

這些服務像一座橋。處於系統和打印機之間。所以，打印機和打印協議的具體實現從系統中分離的，可以獨立開發和更新。session

一個打印服務實現應該基於PrintService類。並且實現它的抽象方法（abstract methods）。app

另外，打印服務必需要按約定來管理PrintJob（打印任務）類。函數

系統負責啓動和中止一個打印服務。這個操做取決於該打印服務管理的打印機是否有激活的打印任務（active print jobs）。打印服務還要及時運行打印機發現操做，來保證好的用戶體驗。post

在打印機發現過程當中系統和該打印服務的交互封裝在PrinterDiscoverySession類的實例中。由打印服務在系統需要的時候建立。優化

類（Classes）

PrintDocument

從一個打印服務的角度來講，這個類表明一個待打印的文件（document）。ui

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

   . . .