Print APIs documentation update
Change-Id: I0df438e45ef540cc42c9ee5baafc816ebafa1c7b
diff --git a/Android.mk b/Android.mk
index 618f404..603f5c3 100644
--- a/Android.mk
+++ b/Android.mk
@@ -160,7 +160,7 @@
core/java/android/print/IPrinterDiscoveryObserver.aidl \
core/java/android/print/IPrintAdapter.aidl \
core/java/android/print/IPrintClient.aidl \
- core/java/android/print/IPrintProgressListener.aidl \
+ core/java/android/print/IPrintResultCallback.aidl \
core/java/android/print/IPrintManager.aidl \
core/java/android/print/IPrintSpoolerService.aidl \
core/java/android/print/IPrintSpoolerServiceCallbacks.aidl \
diff --git a/api/current.txt b/api/current.txt
index 667f564..626f52c 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -18404,12 +18404,12 @@
ctor public PrintAdapter();
method public abstract android.print.PrintAdapterInfo getInfo();
method public void onFinish();
- method public abstract void onPrint(java.util.List<android.print.PageRange>, java.io.FileDescriptor, android.os.CancellationSignal, android.print.PrintAdapter.PrintProgressCallback);
+ method public abstract void onPrint(java.util.List<android.print.PageRange>, java.io.FileDescriptor, android.os.CancellationSignal, android.print.PrintAdapter.PrintResultCallback);
method public boolean onPrintAttributesChanged(android.print.PrintAttributes);
method public void onStart();
}
- public static abstract class PrintAdapter.PrintProgressCallback {
+ public static abstract class PrintAdapter.PrintResultCallback {
method public void onPrintFailed(java.lang.CharSequence);
method public void onPrintFinished(java.util.List<android.print.PageRange>);
}
diff --git a/core/java/android/print/IPrintAdapter.aidl b/core/java/android/print/IPrintAdapter.aidl
index a9b4fb7..f3ff8c4 100644
--- a/core/java/android/print/IPrintAdapter.aidl
+++ b/core/java/android/print/IPrintAdapter.aidl
@@ -17,7 +17,7 @@
package android.print;
import android.os.ParcelFileDescriptor;
-import android.print.IPrintProgressListener;
+import android.print.IPrintResultCallback;
import android.print.PageRange;
import android.print.PrintAttributes;
@@ -30,6 +30,6 @@
void start();
void printAttributesChanged(in PrintAttributes attributes);
void print(in List<PageRange> pages, in ParcelFileDescriptor fd,
- IPrintProgressListener progressListener);
+ IPrintResultCallback callback);
void finish();
}
diff --git a/core/java/android/print/IPrintProgressListener.aidl b/core/java/android/print/IPrintResultCallback.aidl
similarity index 81%
rename from core/java/android/print/IPrintProgressListener.aidl
rename to core/java/android/print/IPrintResultCallback.aidl
index 2c0d607..838377e 100644
--- a/core/java/android/print/IPrintProgressListener.aidl
+++ b/core/java/android/print/IPrintResultCallback.aidl
@@ -26,8 +26,8 @@
*
* @hide
*/
-oneway interface IPrintProgressListener {
- void onWriteStarted(in PrintAdapterInfo info, ICancellationSignal cancellationSignal);
- void onWriteFinished(in List<PageRange> pages);
- void onWriteFailed(CharSequence error);
+oneway interface IPrintResultCallback {
+ void onPrintStarted(in PrintAdapterInfo info, ICancellationSignal cancellationSignal);
+ void onPrintFinished(in List<PageRange> pages);
+ void onPrintFailed(CharSequence error);
}
diff --git a/core/java/android/print/PageRange.java b/core/java/android/print/PageRange.java
index 044a715..60e6229 100644
--- a/core/java/android/print/PageRange.java
+++ b/core/java/android/print/PageRange.java
@@ -21,7 +21,7 @@
/**
* Represents a range of pages. The start and end page indices of
- * the range are zero based and are inclusive.
+ * the range are zero based and inclusive.
*/
public final class PageRange implements Parcelable {
diff --git a/core/java/android/print/PrintAdapter.java b/core/java/android/print/PrintAdapter.java
index a7f809b..6547c55 100644
--- a/core/java/android/print/PrintAdapter.java
+++ b/core/java/android/print/PrintAdapter.java
@@ -16,12 +16,11 @@
package android.print;
-import java.io.FileDescriptor;
-import java.io.IOException;
-import java.util.List;
-
import android.os.CancellationSignal;
+import java.io.FileDescriptor;
+import java.util.List;
+
/**
* Base class that provides data to be printed.
*
@@ -33,19 +32,23 @@
* This callback can be used to allocate resources.
* </li>
* <li>
- * Next you will get one or more calls to the pair
- * {@link #onPrintAttributesChanged(PrintAttributes)} and {@link #onPrint(List,
- * FileDescriptor, CancellationSignal, PrintProgressCallback)}. The first callback
- * informs you that the print attributes (page size, density, etc) changed giving
- * you an opportunity to re-layout the content. The second method asks you to write
- * a PDF file with the content for specific pages.
+ * Next you will get one or more calls to {@link #onPrintAttributesChanged(
+ * PrintAttributes) to informs you that the print attributes (page size, density,
+ * etc) changed giving you an opportunity to re-layout the content.
+ * </li>
+ * <li>
+ * After every {@link #onPrintAttributesChanged(PrintAttributes) you will receive
+ * one or more calls to {@link #onPrint(List, FileDescriptor, CancellationSignal,
+ * PrintResultCallback)} asking you to write a PDF file with the content for
+ * specific pages.
* </li>
* <li>
* Finally, you will receive a call on {@link #onFinish()} right after printing.
* You can use this callback to release resources.
* </li>
* <li>
- * You can receive calls to {@link #getInfo()} at any point which should return
+ * You can receive calls to {@link #getInfo()} at any point after a call to
+ * {@link #onPrintAttributesChanged(PrintAttributes)} which should return
* a {@link PrintAdapterInfo} describing your {@link PrintAdapter}.
* </li>
* </ul>
@@ -83,29 +86,28 @@
/**
* Called when specific pages of the content have to be printed in the from of
* a PDF file to the given file descriptor. You should <strong>not</strong>
- * close the file descriptor instead you have to invoke {@link PrintProgressCallback
- * #onWriteFinished()} or {@link PrintProgressCallback#onPrintFailed(CharSequence)}.
+ * close the file descriptor instead you have to invoke {@link PrintResultCallback
+ * #onPrintFinished()} or {@link PrintResultCallback#onPrintFailed(CharSequence)}.
* <p>
* <strong>Note:</strong> If the printed content is large, it is a good
* practice to schedule writing it on a dedicated thread and register a
- * callback in the provided {@link CancellationSignal} upon which to stop
- * writing data. The cancellation callback will not be made on the main
- * thread.
+ * callback in the provided {@link CancellationSignal} upon invocation of
+ * which you should stop writing data. The cancellation callback will not
+ * be made on the main thread.
* </p>
* <p>
* <strong>Note:</strong> Invoked on the main thread.
* </p>
- * <p>
*
- * @param pages The pages whose content to write.
+ * @param pages The pages whose content to print.
* @param destination The destination file descriptor to which to start writing.
- * @param cancellationSignal Signal for observing cancel write requests.
+ * @param cancellationSignal Signal for observing cancel print requests.
* @param progressListener Callback to inform the system with the write progress.
*
* @see CancellationSignal
*/
public abstract void onPrint(List<PageRange> pages, FileDescriptor destination,
- CancellationSignal cancellationSignal, PrintProgressCallback progressListener);
+ CancellationSignal cancellationSignal, PrintResultCallback progressListener);
/**
* Called when printing finished. You can use this callback to release
@@ -132,12 +134,12 @@
public abstract PrintAdapterInfo getInfo();
/**
- * Base class for implementing a listener for the printing progress
+ * Base class for implementing a listener for the print result
* of a {@link PrintAdapter}.
*/
- public static abstract class PrintProgressCallback {
+ public static abstract class PrintResultCallback {
- PrintProgressCallback() {
+ PrintResultCallback() {
/* do nothing - hide constructor */
}
diff --git a/core/java/android/print/PrintFileAdapter.java b/core/java/android/print/PrintFileAdapter.java
index bbfc394..dab9648 100644
--- a/core/java/android/print/PrintFileAdapter.java
+++ b/core/java/android/print/PrintFileAdapter.java
@@ -53,9 +53,9 @@
@Override
public void onPrint(List<PageRange> pages, FileDescriptor destination,
- CancellationSignal cancellationSignal, PrintProgressCallback progressListener) {
+ CancellationSignal cancellationSignal, PrintResultCallback callback) {
mWriteFileAsyncTask = new WriteFileAsyncTask(mFile, destination, cancellationSignal,
- progressListener);
+ callback);
mWriteFileAsyncTask.executeOnExecutor(AsyncTask.THREAD_POOL_EXECUTOR,
(Void[]) null);
@@ -73,15 +73,15 @@
private final FileDescriptor mDestination;
- private final PrintProgressCallback mProgressListener;
+ private final PrintResultCallback mResultCallback;
private final CancellationSignal mCancellationSignal;
public WriteFileAsyncTask(File source, FileDescriptor destination,
- CancellationSignal cancellationSignal, PrintProgressCallback progressListener) {
+ CancellationSignal cancellationSignal, PrintResultCallback callback) {
mSource = source;
mDestination = destination;
- mProgressListener = progressListener;
+ mResultCallback = callback;
mCancellationSignal = cancellationSignal;
mCancellationSignal.setOnCancelListener(new OnCancelListener() {
@Override
@@ -113,9 +113,9 @@
if (!isCancelled()) {
List<PageRange> pages = new ArrayList<PageRange>();
pages.add(PageRange.ALL_PAGES);
- mProgressListener.onPrintFinished(pages);
+ mResultCallback.onPrintFinished(pages);
} else {
- mProgressListener.onPrintFailed("Cancelled");
+ mResultCallback.onPrintFailed("Cancelled");
}
}
return null;
diff --git a/core/java/android/print/PrintManager.java b/core/java/android/print/PrintManager.java
index 32a0f5a..be9b596 100644
--- a/core/java/android/print/PrintManager.java
+++ b/core/java/android/print/PrintManager.java
@@ -26,7 +26,7 @@
import android.os.Message;
import android.os.ParcelFileDescriptor;
import android.os.RemoteException;
-import android.print.PrintAdapter.PrintProgressCallback;
+import android.print.PrintAdapter.PrintResultCallback;
import android.util.Log;
import com.android.internal.os.SomeArgs;
@@ -162,6 +162,8 @@
* @param pdfFile The PDF file to print.
* @param attributes The default print job attributes.
* @return The created print job.
+ *
+ * @see PrintJob
*/
public PrintJob print(String printJobName, File pdfFile, PrintAttributes attributes) {
PrintFileAdapter printable = new PrintFileAdapter(pdfFile);
@@ -176,6 +178,8 @@
* @param printAdapter The printable adapter to print.
* @param attributes The default print job attributes.
* @return The created print job.
+ *
+ * @see PrintJob
*/
public PrintJob print(String printJobName, PrintAdapter printAdapter,
PrintAttributes attributes) {
@@ -252,7 +256,7 @@
@Override
public void print(List<PageRange> pages, ParcelFileDescriptor fd,
- IPrintProgressListener progressListener) {
+ IPrintResultCallback callback) {
synchronized (mLock) {
if (isFinishedLocked()) {
return;
@@ -261,7 +265,7 @@
args.arg1 = mPrintAdapter;
args.arg2 = pages;
args.arg3 = fd.getFileDescriptor();
- args.arg4 = progressListener;
+ args.arg4 = callback;
mHandler.obtainMessage(MyHandler.MESSAGE_PRINT, args).sendToTarget();
}
}
@@ -318,16 +322,16 @@
@SuppressWarnings("unchecked")
List<PageRange> pages = (List<PageRange>) args.arg2;
final FileDescriptor fd = (FileDescriptor) args.arg3;
- IPrintProgressListener listener = (IPrintProgressListener) args.arg4;
+ IPrintResultCallback callback = (IPrintResultCallback) args.arg4;
args.recycle();
try {
ICancellationSignal remoteSignal = CancellationSignal.createTransport();
- listener.onWriteStarted(adapter.getInfo(), remoteSignal);
+ callback.onPrintStarted(adapter.getInfo(), remoteSignal);
CancellationSignal localSignal = CancellationSignal.fromTransport(
remoteSignal);
adapter.onPrint(pages, fd, localSignal,
- new PrintProgressListenerWrapper(listener) {
+ new PrintResultCallbackWrapper(callback) {
@Override
public void onPrintFinished(List<PageRange> pages) {
IoUtils.closeQuietly(fd);
@@ -363,29 +367,29 @@
}
}
- private static abstract class PrintProgressListenerWrapper extends PrintProgressCallback {
+ private static abstract class PrintResultCallbackWrapper extends PrintResultCallback {
- private final IPrintProgressListener mWrappedListener;
+ private final IPrintResultCallback mWrappedCallback;
- public PrintProgressListenerWrapper(IPrintProgressListener listener) {
- mWrappedListener = listener;
+ public PrintResultCallbackWrapper(IPrintResultCallback callback) {
+ mWrappedCallback = callback;
}
@Override
public void onPrintFinished(List<PageRange> pages) {
try {
- mWrappedListener.onWriteFinished(pages);
+ mWrappedCallback.onPrintFinished(pages);
} catch (RemoteException re) {
- Log.e(LOG_TAG, "Error calling onWriteFinished", re);
+ Log.e(LOG_TAG, "Error calling onPrintFinished", re);
}
}
@Override
public void onPrintFailed(CharSequence error) {
try {
- mWrappedListener.onWriteFailed(error);
+ mWrappedCallback.onPrintFailed(error);
} catch (RemoteException re) {
- Log.e(LOG_TAG, "Error calling onWriteFailed", re);
+ Log.e(LOG_TAG, "Error calling onPrintFailed", re);
}
}
}
diff --git a/core/java/android/print/pdf/PdfDocument.java b/core/java/android/print/pdf/PdfDocument.java
index 7fb170e..7ce036d 100644
--- a/core/java/android/print/pdf/PdfDocument.java
+++ b/core/java/android/print/pdf/PdfDocument.java
@@ -105,7 +105,7 @@
* is created you can draw arbitrary content on the page's canvas which
* you can get by calling {@link Page#getCanvas()}. After you are done
* drawing the content you should finish the page by calling
- * {@link #finishPage(Page). After the page is finished you should
+ * {@link #finishPage(Page)}. After the page is finished you should
* no longer access the page or its canvas.
* <p>
* <strong>Note:</strong> Do not call this method after {@link #close()}.
diff --git a/core/java/android/printservice/PrintJob.java b/core/java/android/printservice/PrintJob.java
index 9688761..f490f91 100644
--- a/core/java/android/printservice/PrintJob.java
+++ b/core/java/android/printservice/PrintJob.java
@@ -62,7 +62,7 @@
* <p>
* <strong>Node:</strong>The returned info object is a snapshot of the
* current print job state. Every call to this method returns a fresh
- * info object that reflects the current print jobs state.
+ * info object that reflects the current print job state.
* </p>
*
* @return The print job info.
@@ -100,7 +100,7 @@
*
* @see #complete()
* @see #cancel()
- * @see #fail()
+ * @see #fail(CharSequence)
*/
public boolean isStarted() {
return getInfo().getState() == PrintJobInfo.STATE_STARTED;
@@ -140,7 +140,8 @@
* Fails the print job. You should call this method if {@link
* #isStarted()} returns true you filed while printing.
*
- * @return Whether the job as failed.
+ * @param error The reason for the failure.
+ * @return Whether the job was failed.
*
* @see #isStarted()
*/
@@ -191,6 +192,9 @@
* Gets the data associated with this print job. It is a responsibility of
* the print service to open a stream to the returned file descriptor
* and fully read the content.
+ * <p>
+ * <strong>Note:</strong> It is your responsibility to close the file descriptor.
+ * </p>
*
* @return A file descriptor for reading the data or <code>null</code>.
*/
diff --git a/core/java/android/printservice/PrintService.java b/core/java/android/printservice/PrintService.java
index d5cadc0..9256966 100644
--- a/core/java/android/printservice/PrintService.java
+++ b/core/java/android/printservice/PrintService.java
@@ -52,7 +52,7 @@
* Calls to {@link #addDiscoveredPrinters(List)} and
* {@link #removeDiscoveredPrinters(List)} before a call to
* {@link #onStartPrinterDiscovery()} and after a call to
- * {@link #onStopPrinterDiscovery()} is a no-op.
+ * {@link #onStopPrinterDiscovery()} are a no-op.
* </p>
* <p>
* For every printer discovery period all printers have to be added. Each
@@ -68,7 +68,7 @@
* service may handle it immediately or schedule that for an appropriate
* time in the future. The list of all print jobs for this service
* are be available by calling {@link #getPrintJobs()}. A queued print
- * job is in a {@link PrintJobInfo#STATE_QUEUED} state.
+ * job is one whose {@link PrintJob#isQueued()} return true.
* </p>
* <p>
* A print service is responsible for setting the print job state as
@@ -200,7 +200,7 @@
/**
* Callback requesting from this service to start printer discovery.
* At the end of the printer discovery period the system will call
- * {@link #onStopPrinterDiscovery(). Discovered printers should be
+ * {@link #onStopPrinterDiscovery()}. Discovered printers should be
* reported by calling #addDiscoveredPrinters(List) and reported ones
* that disappear should be reported by calling
* {@link #removeDiscoveredPrinters(List)}.
@@ -299,8 +299,7 @@
/**
* Called when canceling of a print job is requested. The service
* should do best effort to fulfill the request. After the print
- * job is canceled it state has to be set to
- * {@link PrintJobInfo#STATE_CANCELED}.
+ * job is canceled by calling {@link PrintJob#cancel()}.
*
* @param printJob The print job to be canceled.
*/
diff --git a/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java b/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
index 7537218..c81b00c 100644
--- a/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
+++ b/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
@@ -20,7 +20,7 @@
import android.os.ParcelFileDescriptor;
import android.os.RemoteException;
import android.print.IPrintAdapter;
-import android.print.IPrintProgressListener;
+import android.print.IPrintResultCallback;
import android.print.PageRange;
import android.print.PrintAdapterInfo;
import android.print.PrintAttributes;
@@ -50,7 +50,7 @@
private final File mFile;
- private final IPrintProgressListener mIPrintProgressListener;
+ private final IPrintResultCallback mIPrintProgressListener;
private PrintAdapterInfo mInfo;
@@ -61,12 +61,12 @@
public RemotePrintAdapter(IPrintAdapter printAdatper, File file) {
mRemoteInterface = printAdatper;
mFile = file;
- mIPrintProgressListener = new IPrintProgressListener.Stub() {
+ mIPrintProgressListener = new IPrintResultCallback.Stub() {
@Override
- public void onWriteStarted(PrintAdapterInfo info,
+ public void onPrintStarted(PrintAdapterInfo info,
ICancellationSignal cancellationSignal) {
if (DEBUG) {
- Log.i(LOG_TAG, "IPrintProgressListener#onWriteStarted()");
+ Log.i(LOG_TAG, "IPrintProgressListener#onPrintStarted()");
}
synchronized (mLock) {
mInfo = info;
@@ -75,9 +75,9 @@
}
@Override
- public void onWriteFinished(List<PageRange> pages) {
+ public void onPrintFinished(List<PageRange> pages) {
if (DEBUG) {
- Log.i(LOG_TAG, "IPrintProgressListener#onWriteFinished(" + pages + ")");
+ Log.i(LOG_TAG, "IPrintProgressListener#onPrintFinished(" + pages + ")");
}
synchronized (mLock) {
if (isPrintingLocked()) {
@@ -88,9 +88,9 @@
}
@Override
- public void onWriteFailed(CharSequence error) {
+ public void onPrintFailed(CharSequence error) {
if (DEBUG) {
- Log.i(LOG_TAG, "IPrintProgressListener#onWriteFailed(" + error + ")");
+ Log.i(LOG_TAG, "IPrintProgressListener#onPrintFailed(" + error + ")");
}
synchronized (mLock) {
if (isPrintingLocked()) {