/*
* Copyright (C) 2013 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.printservice;
import android.annotation.FloatRange;
import android.annotation.MainThread;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.StringRes;
import android.content.Context;
import android.os.RemoteException;
import android.print.PrintJobId;
import android.print.PrintJobInfo;
import android.text.TextUtils;
import android.util.Log;
import com.android.internal.util.Preconditions;
/**
* This class represents a print job from the perspective of a print
* service. It provides APIs for observing the print job state and
* performing operations on the print job.
* <p>
* <strong>Note: </strong> All methods of this class must be invoked on
* the main application thread.
* </p>
*/
public final class PrintJob {
private static final String LOG_TAG = "PrintJob";
private final IPrintServiceClient mPrintServiceClient;
private final PrintDocument mDocument;
private PrintJobInfo mCachedInfo;
/** Context that created the object */
private final Context mContext;
PrintJob(@NonNull Context context, @NonNull PrintJobInfo jobInfo,
@NonNull IPrintServiceClient client) {
mContext = context;
mCachedInfo = jobInfo;
mPrintServiceClient = client;
mDocument = new PrintDocument(mCachedInfo.getId(), client,
jobInfo.getDocumentInfo());
}
/**
* Gets the unique print job id.
*
* @return The id.
*/
@MainThread
public PrintJobId getId() {
PrintService.throwIfNotCalledOnMainThread();
return mCachedInfo.getId();
}
/**
* Gets the {@link PrintJobInfo} that describes this job.
* <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 job state.
* </p>
*
* @return The print job info.
*/
@MainThread
public @NonNull PrintJobInfo getInfo() {
PrintService.throwIfNotCalledOnMainThread();
if (isInImmutableState()) {
return mCachedInfo;
}
PrintJobInfo info = null;
try {
info = mPrintServiceClient.getPrintJobInfo(mCachedInfo.getId());
} catch (RemoteException re) {
Log.e(LOG_TAG, "Couldn't get info for job: " + mCachedInfo.getId(), re);
}
if (info != null) {
mCachedInfo = info;
}
return mCachedInfo;
}
/**
* Gets the printed document.
*
* @return The document.
*/
@MainThread
public @NonNull PrintDocument getDocument() {
PrintService.throwIfNotCalledOnMainThread();
return mDocument;
}
/**
* Gets whether this print job is queued. Such a print job is
* ready to be printed and can be started or cancelled.
*
* @return Whether the print job is queued.
*
* @see #start()
* @see #cancel()
*/
@MainThread
public boolean isQueued() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getState() == PrintJobInfo.STATE_QUEUED;
}
/**
* Gets whether this print job is started. Such a print job is
* being printed and can be completed or canceled or failed.
*
* @return Whether the print job is started.
*
* @see #complete()
* @see #cancel()
* @see #fail(String)
*/
@MainThread
public boolean isStarted() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getState() == PrintJobInfo.STATE_STARTED;
}
/**
* Gets whether this print job is blocked. Such a print job is halted
* due to an abnormal condition and can be started or canceled or failed.
*
* @return Whether the print job is blocked.
*
* @see #start()
* @see #cancel()
* @see #fail(String)
*/
@MainThread
public boolean isBlocked() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getState() == PrintJobInfo.STATE_BLOCKED;
}
/**
* Gets whether this print job is completed. Such a print job
* is successfully printed. This is a final state.
*
* @return Whether the print job is completed.
*
* @see #complete()
*/
@MainThread
public boolean isCompleted() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getState() == PrintJobInfo.STATE_COMPLETED;
}
/**
* Gets whether this print job is failed. Such a print job is
* not successfully printed due to an error. This is a final state.
*
* @return Whether the print job is failed.
*
* @see #fail(String)
*/
@MainThread
public boolean isFailed() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getState() == PrintJobInfo.STATE_FAILED;
}
/**
* Gets whether this print job is cancelled. Such a print job was
* cancelled as a result of a user request. This is a final state.
*
* @return Whether the print job is cancelled.
*
* @see #cancel()
*/
@MainThread
public boolean isCancelled() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getState() == PrintJobInfo.STATE_CANCELED;
}
/**
* Starts the print job. You should call this method if {@link
* #isQueued()} or {@link #isBlocked()} returns true and you started
* resumed printing.
* <p>
* This resets the print status to null. Set the new status by using {@link #setStatus}.
* </p>
*
* @return Whether the job was started.
*
* @see #isQueued()
* @see #isBlocked()
*/
@MainThread
public boolean start() {
PrintService.throwIfNotCalledOnMainThread();
final int state = getInfo().getState();
if (state == PrintJobInfo.STATE_QUEUED
|| state == PrintJobInfo.STATE_BLOCKED) {
return setState(PrintJobInfo.STATE_STARTED, null);
}
return false;
}
/**
* Blocks the print job. You should call this method if {@link #isStarted()} returns true and
* you need to block the print job. For example, the user has to add some paper to continue
* printing. To resume the print job call {@link #start()}. To change the reason call
* {@link #setStatus(CharSequence)}.
*
* @param reason The human readable, short, and translated reason why the print job is blocked.
* @return Whether the job was blocked.
*
* @see #isStarted()
* @see #isBlocked()
*/
@MainThread
public boolean block(@Nullable String reason) {
PrintService.throwIfNotCalledOnMainThread();
PrintJobInfo info = getInfo();
final int state = info.getState();
if (state == PrintJobInfo.STATE_STARTED || state == PrintJobInfo.STATE_BLOCKED) {
return setState(PrintJobInfo.STATE_BLOCKED, reason);
}
return false;
}
/**
* Completes the print job. You should call this method if {@link
* #isStarted()} returns true and you are done printing.
*
* @return Whether the job as completed.
*
* @see #isStarted()
*/
@MainThread
public boolean complete() {
PrintService.throwIfNotCalledOnMainThread();
if (isStarted()) {
return setState(PrintJobInfo.STATE_COMPLETED, null);
}
return false;
}
/**
* Fails the print job. You should call this method if {@link
* #isQueued()} or {@link #isStarted()} or {@link #isBlocked()}
* returns true you failed while printing.
*
* @param error The human readable, short, and translated reason
* for the failure.
* @return Whether the job was failed.
*
* @see #isQueued()
* @see #isStarted()
* @see #isBlocked()
*/
@MainThread
public boolean fail(@Nullable String error) {
PrintService.throwIfNotCalledOnMainThread();
if (!isInImmutableState()) {
return setState(PrintJobInfo.STATE_FAILED, error);
}
return false;
}
/**
* Cancels the print job. You should call this method if {@link
* #isQueued()} or {@link #isStarted() or #isBlocked()} returns
* true and you canceled the print job as a response to a call to
* {@link PrintService#onRequestCancelPrintJob(PrintJob)}.
*
* @return Whether the job is canceled.
*
* @see #isStarted()
* @see #isQueued()
* @see #isBlocked()
*/
@MainThread
public boolean cancel() {
PrintService.throwIfNotCalledOnMainThread();
if (!isInImmutableState()) {
return setState(PrintJobInfo.STATE_CANCELED, null);
}
return false;
}
/**
* Sets the progress of this print job as a fraction of 1.
*
* @param progress The new progress
*/
@MainThread
public void setProgress(@FloatRange(from=0.0, to=1.0) float progress) {
PrintService.throwIfNotCalledOnMainThread();
try {
mPrintServiceClient.setProgress(mCachedInfo.getId(), progress);
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error setting progress for job: " + mCachedInfo.getId(), re);
}
}
/**
* Sets the status of this print job. This should be a human readable, short, and translated
* description of the current state of the print job.
* <p />
* This overrides any previously set status set via {@link #setStatus(CharSequence)},
* {@link #setStatus(int)}, {@link #block(String)}, or {@link #fail(String)},
*
* @param status The new status. If null the status will be empty.
*/
@MainThread
public void setStatus(@Nullable CharSequence status) {
PrintService.throwIfNotCalledOnMainThread();
try {
mPrintServiceClient.setStatus(mCachedInfo.getId(), status);
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error setting status for job: " + mCachedInfo.getId(), re);
}
}
/**
* Sets the status of this print job as a string resource.
* <p />
* This overrides any previously set status set via {@link #setStatus(CharSequence)},
* {@link #setStatus(int)}, {@link #block(String)}, or {@link #fail(String)},
*
* @param statusResId The new status as a String resource. If 0 the status will be empty.
*/
@MainThread
public void setStatus(@StringRes int statusResId) {
PrintService.throwIfNotCalledOnMainThread();
try {
mPrintServiceClient.setStatusRes(mCachedInfo.getId(), statusResId,
mContext.getPackageName());
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error setting status for job: " + mCachedInfo.getId(), re);
}
}
/**
* Sets a tag that is valid in the context of a {@link PrintService}
* and is not interpreted by the system. For example, a print service
* may set as a tag the key of the print job returned by a remote
* print server, if the printing is off handed to a cloud based service.
*
* @param tag The tag.
* @return True if the tag was set, false otherwise.
*/
@MainThread
public boolean setTag(@NonNull String tag) {
PrintService.throwIfNotCalledOnMainThread();
if (isInImmutableState()) {
return false;
}
try {
return mPrintServiceClient.setPrintJobTag(mCachedInfo.getId(), tag);
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error setting tag for job: " + mCachedInfo.getId(), re);
}
return false;
}
/**
* Gets the print job tag.
*
* @return The tag or null.
*
* @see #setTag(String)
*/
@MainThread
public @Nullable String getTag() {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getTag();
}
/**
* Gets the value of an advanced (printer specific) print option.
*
* @param key The option key.
* @return The option value.
*/
@MainThread
public String getAdvancedStringOption(String key) {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getAdvancedStringOption(key);
}
/**
* Gets whether this job has a given advanced (printer specific) print
* option.
*
* @param key The option key.
* @return Whether the option is present.
*/
@MainThread
public boolean hasAdvancedOption(String key) {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().hasAdvancedOption(key);
}
/**
* Gets the value of an advanced (printer specific) print option.
*
* @param key The option key.
* @return The option value.
*/
@MainThread
public int getAdvancedIntOption(String key) {
PrintService.throwIfNotCalledOnMainThread();
return getInfo().getAdvancedIntOption(key);
}
@Override
public boolean equals(Object obj) {
if (this == obj) {
return true;
}
if (obj == null) {
return false;
}
if (getClass() != obj.getClass()) {
return false;
}
PrintJob other = (PrintJob) obj;
return (mCachedInfo.getId().equals(other.mCachedInfo.getId()));
}
@Override
public int hashCode() {
return mCachedInfo.getId().hashCode();
}
private boolean isInImmutableState() {
final int state = mCachedInfo.getState();
return state == PrintJobInfo.STATE_COMPLETED
|| state == PrintJobInfo.STATE_CANCELED
|| state == PrintJobInfo.STATE_FAILED;
}
private boolean setState(int state, @Nullable String error) {
try {
if (mPrintServiceClient.setPrintJobState(mCachedInfo.getId(), state, error)) {
// Best effort - update the state of the cached info since
// we may not be able to re-fetch it later if the job gets
// removed from the spooler as a result of the state change.
mCachedInfo.setState(state);
mCachedInfo.setStatus(error);
return true;
}
} catch (RemoteException re) {
Log.e(LOG_TAG, "Error setting the state of job: " + mCachedInfo.getId(), re);
}
return false;
}
}