Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Print APIs documentation update

Browse Source 
Change-Id: I0df438e45ef540cc42c9ee5baafc816ebafa1c7b
This commit is contained in:
Svetoslav
2013-06-24 09:04:48 -07:00
parent 53f57d162b
commit fd90651cfc
12 changed files with 81 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Android.mk
View File

@@ -160,7 +160,7 @@ LOCAL_SRC_FILES += \
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 \

4
api/current.txt
View File

@@ -18404,12 +18404,12 @@ package android.print {
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>);
}

4
core/java/android/print/IPrintAdapter.aidl
View File

@@ -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 @@ oneway interface IPrintAdapter {
void start();
void printAttributesChanged(in PrintAttributes attributes);
void print(in List<PageRange> pages, in ParcelFileDescriptor fd,
IPrintProgressListener progressListener);
IPrintResultCallback callback);
void finish();
}

8
core/java/android/print/IPrintProgressListener.aidl → core/java/android/print/IPrintResultCallback.aidl
View File

@@ -26,8 +26,8 @@ import android.print.PrintAdapterInfo;
*
* @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);
}

2
core/java/android/print/PageRange.java
View File

@@ -21,7 +21,7 @@ import android.os.Parcelable;
/**
* 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 {

48
core/java/android/print/PrintAdapter.java
View File

@@ -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 @@ import android.os.CancellationSignal;
* 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 @@ public abstract class PrintAdapter {
/**
* 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 class PrintAdapter {
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 */
}

14
core/java/android/print/PrintFileAdapter.java
View File

@@ -53,9 +53,9 @@ class PrintFileAdapter extends PrintAdapter {
@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 @@ class PrintFileAdapter extends PrintAdapter {
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 @@ class PrintFileAdapter extends PrintAdapter {
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;

32
core/java/android/print/PrintManager.java
View File

@@ -26,7 +26,7 @@ import android.os.Looper;
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 @@ public final class PrintManager {
* @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 @@ public final class PrintManager {
* @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 @@ public final class PrintManager {
@Override
public void print(List<PageRange> pages, ParcelFileDescriptor fd,
IPrintProgressListener progressListener) {
IPrintResultCallback callback) {
synchronized (mLock) {
if (isFinishedLocked()) {
return;
@@ -261,7 +265,7 @@ public final class PrintManager {
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 @@ public final class PrintManager {
@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 @@ public final class PrintManager {
}
}
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);
}
}
}

2
core/java/android/print/pdf/PdfDocument.java
View File

@@ -105,7 +105,7 @@ public final class PdfDocument {
* 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()}.

10
core/java/android/printservice/PrintJob.java
View File

@@ -62,7 +62,7 @@ public final class PrintJob {
* <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 @@ public final class PrintJob {
*
* @see #complete()
* @see #cancel()
* @see #fail()
* @see #fail(CharSequence)
*/
public boolean isStarted() {
return getInfo().getState() == PrintJobInfo.STATE_STARTED;
@@ -140,7 +140,8 @@ public final class PrintJob {
* 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 @@ public final class PrintJob {
* 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>.
*/

9
core/java/android/printservice/PrintService.java
View File

@@ -52,7 +52,7 @@ import java.util.List;
* 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 @@ import java.util.List;
* 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 @@ public abstract class PrintService extends Service {
/**
* 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 @@ public abstract class PrintService extends Service {
/**
* 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.
*/

18
packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
View File

@@ -20,7 +20,7 @@ import android.os.ICancellationSignal;
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 @@ final class RemotePrintAdapter {
private final File mFile;
private final IPrintProgressListener mIPrintProgressListener;
private final IPrintResultCallback mIPrintProgressListener;
private PrintAdapterInfo mInfo;
@@ -61,12 +61,12 @@ final class RemotePrintAdapter {
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 @@ final class RemotePrintAdapter {
}
@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 @@ final class RemotePrintAdapter {
}
@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()) {