Android教程網 >> Android技術 >> Android開發 >> 關於android開發 >> Android_Printservice_API_部分翻譯

Android_Printservice_API_部分翻譯

編輯：關於android開發

Android_Printservice_API_部分翻譯

android.printservice

提供打印服務實現的類。打印服務是一種插件（ plug-in components），它能夠通過一些標准協議和打印機通訊。這些服務像一座橋，處於系統和打印機之間。因此，打印機和打印協議的具體實現從系統中分離的，能夠獨立開發和更新。

一個打印服務實現應該基於PrintService類，並且實現它的抽象方法（abstract methods）。另外，打印服務必須要按約定來管理PrintJob（打印任務）類。

系統負責啟動和停止一個打印服務，這個操作取決於該打印服務管理的打印機是否有激活的打印任務（active print jobs）。打印服務還要及時執行打印機發現操作，來保證好的用戶體驗。在打印機發現過程中系統和該打印服務的交互封裝在PrinterDiscoverySession類的實例中，由打印服務在系統需要的時候創建。

類（Classes）

PrintDocument

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

PrinterDiscoverySession

這個類封裝了打印機發現過程中一個打印服務和系統的交互操作。

PrintJob

對一個打印服務來說，這個類代表一個打印任務（print job）。

PrintService

這個基礎類用來實現打印服務。

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）它。聲明這個失敗會導致系統忽略這個打印服務。下面是一個聲明的例子：

配置 Configuration

一個打印服務可通過自定義設置頁面（setting activity）進行配置，該activity提供自定義設置功能。一個添加打印機的activity可以手動添加打印機，供應商名稱等等。系統負責在適當的時候啟動設置和添加打印機的activities。

一個打印服務在聲明的時候，要在mainfest裡提供一條meta-data，這是指定上述activities的方式。一個服務的meta-data標簽（tag）聲明如下所示：

關於通過meta-data配置你的打印服務的更多細節，可以參考SERVICE_META_DATA和。

提示：這個類裡的所有回調函數（callbacks）都在程序的主線程裡執行。你也應該在程序的主線程裡調用（invoke）這個類裡的方法。

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

   . . .