| Methods Summary |
|---|
| public final void | addPrinters(java.util.List printers)Adds discovered printers. Adding an already added printer updates it.
Removed printers can be added again. You can call this method multiple
times during the life of this session. Duplicates will be ignored.
Note: Calls to this method after the session is
destroyed, that is after the {@link #onDestroy()} callback, will be ignored.
PrintService.throwIfNotCalledOnMainThread();
// If the session is destroyed - nothing do to.
if (mIsDestroyed) {
Log.w(LOG_TAG, "Not adding printers - session destroyed.");
return;
}
if (mIsDiscoveryStarted) {
// If during discovery, add the new printers and send them.
List<PrinterInfo> addedPrinters = null;
final int addedPrinterCount = printers.size();
for (int i = 0; i < addedPrinterCount; i++) {
PrinterInfo addedPrinter = printers.get(i);
PrinterInfo oldPrinter = mPrinters.put(addedPrinter.getId(), addedPrinter);
if (oldPrinter == null || !oldPrinter.equals(addedPrinter)) {
if (addedPrinters == null) {
addedPrinters = new ArrayList<PrinterInfo>();
}
addedPrinters.add(addedPrinter);
}
}
// Send the added printers, if such.
if (addedPrinters != null) {
try {
mObserver.onPrintersAdded(new ParceledListSlice<PrinterInfo>(addedPrinters));
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error sending added printers", re);
}
}
} else {
// Remember the last sent printers if needed.
if (mLastSentPrinters == null) {
mLastSentPrinters = new ArrayMap<PrinterId, PrinterInfo>(mPrinters);
}
// Update the printers.
final int addedPrinterCount = printers.size();
for (int i = 0; i < addedPrinterCount; i++) {
PrinterInfo addedPrinter = printers.get(i);
if (mPrinters.get(addedPrinter.getId()) == null) {
mPrinters.put(addedPrinter.getId(), addedPrinter);
}
}
}
|
| void | destroy()
if (!mIsDestroyed) {
mIsDestroyed = true;
mIsDiscoveryStarted = false;
mPrinters.clear();
mLastSentPrinters = null;
mObserver = null;
onDestroy();
}
|
| int | getId()
return mId;
|
| public final java.util.List | getPrinters()Gets the printers reported in this session. For example, if you add two
printers and remove one of them, the returned list will contain only
the printer that was added but not removed.
Note: Calls to this method after the session is
destroyed, that is after the {@link #onDestroy()} callback, will be ignored.
PrintService.throwIfNotCalledOnMainThread();
if (mIsDestroyed) {
return Collections.emptyList();
}
return new ArrayList<PrinterInfo>(mPrinters.values());
|
| public final java.util.List | getTrackedPrinters()Gets the printers that should be tracked. These are printers that are
important to the user and for which you received a call to {@link
#onStartPrinterStateTracking(PrinterId)} asking you to observer their
state and reporting it to the system via {@link #addPrinters(List)}.
You will receive a call to {@link #onStopPrinterStateTracking(PrinterId)}
if you should stop tracking a printer.
Note: Calls to this method after the session is
destroyed, that is after the {@link #onDestroy()} callback, will be ignored.
PrintService.throwIfNotCalledOnMainThread();
if (mIsDestroyed) {
return Collections.emptyList();
}
return new ArrayList<PrinterId>(mTrackedPrinters);
|
| public final boolean | isDestroyed()Gets whether the session is destroyed.
PrintService.throwIfNotCalledOnMainThread();
return mIsDestroyed;
|
| public final boolean | isPrinterDiscoveryStarted()Gets whether printer discovery is started.
PrintService.throwIfNotCalledOnMainThread();
return mIsDiscoveryStarted;
|
| public abstract void | onDestroy()Notifies you that the session is destroyed. After this callback is invoked
any calls to the methods of this class will be ignored, {@link #isDestroyed()}
will return true and you will also no longer receive callbacks.
|
| public abstract void | onStartPrinterDiscovery(java.util.List priorityList)Callback asking you to start printer discovery. Discovered printers should be
added via calling {@link #addPrinters(List)}. Added printers that disappeared
should be removed via calling {@link #removePrinters(List)}. Added printers
whose properties or capabilities changed should be updated via calling {@link
#addPrinters(List)}. You will receive a call to {@link #onStopPrinterDiscovery()}
when you should stop printer discovery.
During the lifetime of this session all printers that are known to your print
service have to be added. The system does not retain any printers across sessions.
However, if you were asked to start and then stop performing printer discovery
in this session, then a subsequent discovering should not re-discover already
discovered printers. You can get the printers reported during this session by
calling {@link #getPrinters()}.
Note: You are also given a list of printers whose availability
has to be checked first. For example, these printers could be the user's favorite
ones, therefore they have to be verified first. You do not need
to provide the capabilities of the printers, rather verify whether they exist
similarly to {@link #onValidatePrinters(List)}.
|
| public abstract void | onStartPrinterStateTracking(android.print.PrinterId printerId)Callback asking you to start tracking the state of a printer. Tracking
the state means that you should do a best effort to observe the state
of this printer and notify the system if that state changes via calling
{@link #addPrinters(List)}.
Note: A printer can be initially added without its
capabilities to avoid polling printers that the user will not select.
However, after this method is called you are expected to update the
printer including its capabilities. Otherwise, the
printer will be ignored.
A scenario when you may be requested to track a printer's state is if
the user selects that printer and the system has to present print
options UI based on the printer's capabilities. In this case the user
should be promptly informed if, for example, the printer becomes
unavailable.
|
| public abstract void | onStopPrinterDiscovery()Callback notifying you that you should stop printer discovery.
|
| public abstract void | onStopPrinterStateTracking(android.print.PrinterId printerId)Callback asking you to stop tracking the state of a printer. The passed
in printer id is the one for which you received a call to {@link
#onStartPrinterStateTracking(PrinterId)}.
|
| public abstract void | onValidatePrinters(java.util.List printerIds)Callback asking you to validate that the given printers are valid, that
is they exist. You are responsible for checking whether these printers
exist and for the ones that do exist notify the system via calling
{@link #addPrinters(List)}.
Note: You are not required to provide
the printer capabilities when updating the printers that do exist.
|
| public final void | removePrinters(java.util.List printerIds)Removes added printers. Removing an already removed or never added
printer has no effect. Removed printers can be added again. You can
call this method multiple times during the lifetime of this session.
Note: Calls to this method after the session is
destroyed, that is after the {@link #onDestroy()} callback, will be ignored.
PrintService.throwIfNotCalledOnMainThread();
// If the session is destroyed - nothing do to.
if (mIsDestroyed) {
Log.w(LOG_TAG, "Not removing printers - session destroyed.");
return;
}
if (mIsDiscoveryStarted) {
// If during discovery, remove existing printers and send them.
List<PrinterId> removedPrinterIds = new ArrayList<PrinterId>();
final int removedPrinterIdCount = printerIds.size();
for (int i = 0; i < removedPrinterIdCount; i++) {
PrinterId removedPrinterId = printerIds.get(i);
if (mPrinters.remove(removedPrinterId) != null) {
removedPrinterIds.add(removedPrinterId);
}
}
// Send the removed printers, if such.
if (!removedPrinterIds.isEmpty()) {
try {
mObserver.onPrintersRemoved(new ParceledListSlice<PrinterId>(
removedPrinterIds));
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error sending removed printers", re);
}
}
} else {
// Remember the last sent printers if needed.
if (mLastSentPrinters == null) {
mLastSentPrinters = new ArrayMap<PrinterId, PrinterInfo>(mPrinters);
}
// Update the printers.
final int removedPrinterIdCount = printerIds.size();
for (int i = 0; i < removedPrinterIdCount; i++) {
PrinterId removedPrinterId = printerIds.get(i);
mPrinters.remove(removedPrinterId);
}
}
|
| private void | sendOutOfDiscoveryPeriodPrinterChanges()
// Noting changed since the last discovery period - nothing to do.
if (mLastSentPrinters == null || mLastSentPrinters.isEmpty()) {
mLastSentPrinters = null;
return;
}
// Determine the added printers.
List<PrinterInfo> addedPrinters = null;
for (PrinterInfo printer : mPrinters.values()) {
PrinterInfo sentPrinter = mLastSentPrinters.get(printer.getId());
if (sentPrinter == null || !sentPrinter.equals(printer)) {
if (addedPrinters == null) {
addedPrinters = new ArrayList<PrinterInfo>();
}
addedPrinters.add(printer);
}
}
// Send the added printers, if such.
if (addedPrinters != null) {
try {
mObserver.onPrintersAdded(new ParceledListSlice<PrinterInfo>(addedPrinters));
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error sending added printers", re);
}
}
// Determine the removed printers.
List<PrinterId> removedPrinterIds = null;
for (PrinterInfo sentPrinter : mLastSentPrinters.values()) {
if (!mPrinters.containsKey(sentPrinter.getId())) {
if (removedPrinterIds == null) {
removedPrinterIds = new ArrayList<PrinterId>();
}
removedPrinterIds.add(sentPrinter.getId());
}
}
// Send the removed printers, if such.
if (removedPrinterIds != null) {
try {
mObserver.onPrintersRemoved(new ParceledListSlice<PrinterId>(removedPrinterIds));
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error sending removed printers", re);
}
}
mLastSentPrinters = null;
|
| void | setObserver(IPrintServiceClient observer)
mObserver = observer;
// If some printers were added in the method that
// created the session, send them over.
if (!mPrinters.isEmpty()) {
try {
mObserver.onPrintersAdded(new ParceledListSlice<PrinterInfo>(getPrinters()));
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error sending added printers", re);
}
}
|
| void | startPrinterDiscovery(java.util.List priorityList)
if (!mIsDestroyed) {
mIsDiscoveryStarted = true;
sendOutOfDiscoveryPeriodPrinterChanges();
if (priorityList == null) {
priorityList = Collections.emptyList();
}
onStartPrinterDiscovery(priorityList);
}
|
| void | startPrinterStateTracking(android.print.PrinterId printerId)
if (!mIsDestroyed && mObserver != null
&& !mTrackedPrinters.contains(printerId)) {
mTrackedPrinters.add(printerId);
onStartPrinterStateTracking(printerId);
}
|
| void | stopPrinterDiscovery()
if (!mIsDestroyed) {
mIsDiscoveryStarted = false;
onStopPrinterDiscovery();
}
|
| void | stopPrinterStateTracking(android.print.PrinterId printerId)
if (!mIsDestroyed && mObserver != null
&& mTrackedPrinters.remove(printerId)) {
onStopPrinterStateTracking(printerId);
}
|
| void | validatePrinters(java.util.List printerIds)
if (!mIsDestroyed && mObserver != null) {
onValidatePrinters(printerIds);
}
|
