1 /*
2  * Copyright (C) 2013 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.print;
18 
19 import android.os.Bundle;
20 import android.os.Parcel;
21 import android.os.Parcelable;
22 
23 import java.util.Arrays;
24 
25 /**
26  * This class represents the description of a print job. The print job
27  * state includes properties such as its id, print attributes used for
28  * generating the content, and so on. Note that the print jobs state may
29  * change over time and this class represents a snapshot of this state.
30  */
31 public final class PrintJobInfo implements Parcelable {
32 
33     /**
34      * Constant for matching any print job state.
35      *
36      * @hide
37      */
38     public static final int STATE_ANY = -1;
39 
40     /**
41      * Constant for matching any print job state.
42      *
43      * @hide
44      */
45     public static final int STATE_ANY_VISIBLE_TO_CLIENTS = -2;
46 
47     /**
48      * Constant for matching any active print job state.
49      *
50      * @hide
51      */
52     public static final int STATE_ANY_ACTIVE = -3;
53 
54     /**
55      * Constant for matching any scheduled, i.e. delivered to a print
56      * service, print job state.
57      *
58      * @hide
59      */
60     public static final int STATE_ANY_SCHEDULED = -4;
61 
62     /**
63      * Print job state: The print job is being created but not yet
64      * ready to be printed.
65      * <p>
66      * Next valid states: {@link #STATE_QUEUED}
67      * </p>
68      */
69     public static final int STATE_CREATED = 1;
70 
71     /**
72      * Print job state: The print jobs is created, it is ready
73      * to be printed and should be processed.
74      * <p>
75      * Next valid states: {@link #STATE_STARTED}, {@link #STATE_FAILED},
76      * {@link #STATE_CANCELED}
77      * </p>
78      */
79     public static final int STATE_QUEUED = 2;
80 
81     /**
82      * Print job state: The print job is being printed.
83      * <p>
84      * Next valid states: {@link #STATE_COMPLETED}, {@link #STATE_FAILED},
85      * {@link #STATE_CANCELED}, {@link #STATE_BLOCKED}
86      * </p>
87      */
88     public static final int STATE_STARTED = 3;
89 
90     /**
91      * Print job state: The print job is blocked.
92      * <p>
93      * Next valid states: {@link #STATE_FAILED}, {@link #STATE_CANCELED},
94      * {@link #STATE_STARTED}
95      * </p>
96      */
97     public static final int STATE_BLOCKED = 4;
98 
99     /**
100      * Print job state: The print job is successfully printed.
101      * This is a terminal state.
102      * <p>
103      * Next valid states: None
104      * </p>
105      */
106     public static final int STATE_COMPLETED = 5;
107 
108     /**
109      * Print job state: The print job was printing but printing failed.
110      * <p>
111      * Next valid states: {@link #STATE_CANCELED}, {@link #STATE_STARTED}
112      * </p>
113      */
114     public static final int STATE_FAILED = 6;
115 
116     /**
117      * Print job state: The print job is canceled.
118      * This is a terminal state.
119      * <p>
120      * Next valid states: None
121      * </p>
122      */
123     public static final int STATE_CANCELED = 7;
124 
125     /** The unique print job id. */
126     private PrintJobId mId;
127 
128     /** The human readable print job label. */
129     private String mLabel;
130 
131     /** The unique id of the printer. */
132     private PrinterId mPrinterId;
133 
134     /** The name of the printer - internally used */
135     private String mPrinterName;
136 
137     /** The state of the print job. */
138     private int mState;
139 
140     /** The id of the app that created the job. */
141     private int mAppId;
142 
143     /** Optional tag assigned by a print service.*/
144     private String mTag;
145 
146     /** The wall time when the print job was created. */
147     private long mCreationTime;
148 
149     /** How many copies to print. */
150     private int mCopies;
151 
152     /** Reason for the print job being in its current state. */
153     private String mStateReason;
154 
155     /** The pages to print */
156     private PageRange[] mPageRanges;
157 
158     /** The print job attributes size. */
159     private PrintAttributes mAttributes;
160 
161     /** Information about the printed document. */
162     private PrintDocumentInfo mDocumentInfo;
163 
164     /** Advanced printer specific options. */
165     private Bundle mAdvancedOptions;
166 
167     /** Whether we are trying to cancel this print job. */
168     private boolean mCanceling;
169 
170     /** @hide*/
PrintJobInfo()171     public PrintJobInfo() {
172         /* do nothing */
173     }
174 
175     /** @hide */
PrintJobInfo(PrintJobInfo other)176     public PrintJobInfo(PrintJobInfo other) {
177         mId = other.mId;
178         mLabel = other.mLabel;
179         mPrinterId = other.mPrinterId;
180         mPrinterName = other.mPrinterName;
181         mState = other.mState;
182         mAppId = other.mAppId;
183         mTag = other.mTag;
184         mCreationTime = other.mCreationTime;
185         mCopies = other.mCopies;
186         mStateReason = other.mStateReason;
187         mPageRanges = other.mPageRanges;
188         mAttributes = other.mAttributes;
189         mDocumentInfo = other.mDocumentInfo;
190         mCanceling = other.mCanceling;
191         mAdvancedOptions = other.mAdvancedOptions;
192     }
193 
PrintJobInfo(Parcel parcel)194     private PrintJobInfo(Parcel parcel) {
195         mId = parcel.readParcelable(null);
196         mLabel = parcel.readString();
197         mPrinterId = parcel.readParcelable(null);
198         mPrinterName = parcel.readString();
199         mState = parcel.readInt();
200         mAppId = parcel.readInt();
201         mTag = parcel.readString();
202         mCreationTime = parcel.readLong();
203         mCopies = parcel.readInt();
204         mStateReason = parcel.readString();
205         Parcelable[] parcelables = parcel.readParcelableArray(null);
206         if (parcelables != null) {
207             mPageRanges = new PageRange[parcelables.length];
208             for (int i = 0; i < parcelables.length; i++) {
209                 mPageRanges[i] = (PageRange) parcelables[i];
210             }
211         }
212         mAttributes = (PrintAttributes) parcel.readParcelable(null);
213         mDocumentInfo = (PrintDocumentInfo) parcel.readParcelable(null);
214         mCanceling = (parcel.readInt() == 1);
215         mAdvancedOptions = parcel.readBundle();
216     }
217 
218     /**
219      * Gets the unique print job id.
220      *
221      * @return The id.
222      */
getId()223     public PrintJobId getId() {
224         return mId;
225     }
226 
227     /**
228      * Sets the unique print job id.
229      *
230      * @param The job id.
231      *
232      * @hide
233      */
setId(PrintJobId id)234     public void setId(PrintJobId id) {
235         this.mId = id;
236     }
237 
238     /**
239      * Gets the human readable job label.
240      *
241      * @return The label.
242      */
getLabel()243     public String getLabel() {
244         return mLabel;
245     }
246 
247     /**
248      * Sets the human readable job label.
249      *
250      * @param label The label.
251      *
252      * @hide
253      */
setLabel(String label)254     public void setLabel(String label) {
255         mLabel = label;
256     }
257 
258     /**
259      * Gets the unique target printer id.
260      *
261      * @return The target printer id.
262      */
getPrinterId()263     public PrinterId getPrinterId() {
264         return mPrinterId;
265     }
266 
267     /**
268      * Sets the unique target pritner id.
269      *
270      * @param printerId The target printer id.
271      *
272      * @hide
273      */
setPrinterId(PrinterId printerId)274     public void setPrinterId(PrinterId printerId) {
275         mPrinterId = printerId;
276     }
277 
278     /**
279      * Gets the name of the target printer.
280      *
281      * @return The printer name.
282      *
283      * @hide
284      */
getPrinterName()285     public String getPrinterName() {
286         return mPrinterName;
287     }
288 
289     /**
290      * Sets the name of the target printer.
291      *
292      * @param printerName The printer name.
293      *
294      * @hide
295      */
setPrinterName(String printerName)296     public void setPrinterName(String printerName) {
297         mPrinterName = printerName;
298     }
299 
300     /**
301      * Gets the current job state.
302      *
303      * @return The job state.
304      *
305      * @see #STATE_CREATED
306      * @see #STATE_QUEUED
307      * @see #STATE_STARTED
308      * @see #STATE_COMPLETED
309      * @see #STATE_BLOCKED
310      * @see #STATE_FAILED
311      * @see #STATE_CANCELED
312      */
getState()313     public int getState() {
314         return mState;
315     }
316 
317     /**
318      * Sets the current job state.
319      *
320      * @param state The job state.
321      *
322      * @hide
323      */
setState(int state)324     public void setState(int state) {
325         mState = state;
326     }
327 
328     /**
329      * Sets the owning application id.
330      *
331      * @return The owning app id.
332      *
333      * @hide
334      */
getAppId()335     public int getAppId() {
336         return mAppId;
337     }
338 
339     /**
340      * Sets the owning application id.
341      *
342      * @param appId The owning app id.
343      *
344      * @hide
345      */
setAppId(int appId)346     public void setAppId(int appId) {
347         mAppId = appId;
348     }
349 
350     /**
351      * Gets the optional tag assigned by a print service.
352      *
353      * @return The tag.
354      *
355      * @hide
356      */
getTag()357     public String getTag() {
358         return mTag;
359     }
360 
361     /**
362      * Sets the optional tag assigned by a print service.
363      *
364      * @param tag The tag.
365      *
366      * @hide
367      */
setTag(String tag)368     public void setTag(String tag) {
369         mTag = tag;
370     }
371 
372     /**
373      * Gets the wall time in millisecond when this print job was created.
374      *
375      * @return The creation time in milliseconds.
376      */
getCreationTime()377     public long getCreationTime() {
378         return mCreationTime;
379     }
380 
381     /**
382      * Sets the wall time in milliseconds when this print job was created.
383      *
384      * @param creationTime The creation time in milliseconds.
385      *
386      * @hide
387      */
setCreationTime(long creationTime)388     public void setCreationTime(long creationTime) {
389         if (creationTime < 0) {
390             throw new IllegalArgumentException("creationTime must be non-negative.");
391         }
392         mCreationTime = creationTime;
393     }
394 
395     /**
396      * Gets the number of copies.
397      *
398      * @return The number of copies or zero if not set.
399      */
getCopies()400     public int getCopies() {
401         return mCopies;
402     }
403 
404     /**
405      * Sets the number of copies.
406      *
407      * @param copyCount The number of copies.
408      *
409      * @hide
410      */
setCopies(int copyCount)411     public void setCopies(int copyCount) {
412         if (copyCount < 1) {
413             throw new IllegalArgumentException("Copies must be more than one.");
414         }
415         mCopies = copyCount;
416     }
417 
418     /**
419      * Gets the reason for the print job being in the current state.
420      *
421      * @return The reason, or null if there is no reason or the
422      * reason is unknown.
423      *
424      * @hide
425      */
getStateReason()426     public String getStateReason() {
427         return mStateReason;
428     }
429 
430     /**
431      * Sets the reason for the print job being in the current state.
432      *
433      * @param stateReason The reason, or null if there is no reason
434      * or the reason is unknown.
435      *
436      * @hide
437      */
setStateReason(String stateReason)438     public void setStateReason(String stateReason) {
439         mStateReason = stateReason;
440     }
441 
442     /**
443      * Gets the included pages.
444      *
445      * @return The included pages or <code>null</code> if not set.
446      */
getPages()447     public PageRange[] getPages() {
448         return mPageRanges;
449     }
450 
451     /**
452      * Sets the included pages.
453      *
454      * @param pageRanges The included pages.
455      *
456      * @hide
457      */
setPages(PageRange[] pageRanges)458     public void setPages(PageRange[] pageRanges) {
459         mPageRanges = pageRanges;
460     }
461 
462     /**
463      * Gets the print job attributes.
464      *
465      * @return The attributes.
466      */
getAttributes()467     public PrintAttributes getAttributes() {
468         return mAttributes;
469     }
470 
471     /**
472      * Sets the print job attributes.
473      *
474      * @param attributes The attributes.
475      *
476      * @hide
477      */
setAttributes(PrintAttributes attributes)478     public void setAttributes(PrintAttributes attributes) {
479         mAttributes = attributes;
480     }
481 
482     /**
483      * Gets the info describing the printed document.
484      *
485      * @return The document info.
486      *
487      * @hide
488      */
getDocumentInfo()489     public PrintDocumentInfo getDocumentInfo() {
490         return mDocumentInfo;
491     }
492 
493     /**
494      * Sets the info describing the printed document.
495      *
496      * @param info The document info.
497      *
498      * @hide
499      */
setDocumentInfo(PrintDocumentInfo info)500     public void setDocumentInfo(PrintDocumentInfo info) {
501         mDocumentInfo = info;
502     }
503 
504     /**
505      * Gets whether this print is being cancelled.
506      *
507      * @return True if the print job is being cancelled.
508      *
509      * @hide
510      */
isCancelling()511     public boolean isCancelling() {
512         return mCanceling;
513     }
514 
515     /**
516      * Sets whether this print is being cancelled.
517      *
518      * @param cancelling True if the print job is being cancelled.
519      *
520      * @hide
521      */
setCancelling(boolean cancelling)522     public void setCancelling(boolean cancelling) {
523         mCanceling = cancelling;
524     }
525 
526     /**
527      * Gets whether this job has a given advanced (printer specific) print
528      * option.
529      *
530      * @param key The option key.
531      * @return Whether the option is present.
532      *
533      * @hide
534      */
hasAdvancedOption(String key)535     public boolean hasAdvancedOption(String key) {
536         return mAdvancedOptions != null && mAdvancedOptions.containsKey(key);
537     }
538 
539     /**
540      * Gets the value of an advanced (printer specific) print option.
541      *
542      * @param key The option key.
543      * @return The option value.
544      *
545      * @hide
546      */
getAdvancedStringOption(String key)547     public String getAdvancedStringOption(String key) {
548         if (mAdvancedOptions != null) {
549             return mAdvancedOptions.getString(key);
550         }
551         return null;
552     }
553 
554     /**
555      * Gets the value of an advanced (printer specific) print option.
556      *
557      * @param key The option key.
558      * @return The option value.
559      *
560      * @hide
561      */
getAdvancedIntOption(String key)562     public int getAdvancedIntOption(String key) {
563         if (mAdvancedOptions != null) {
564             return mAdvancedOptions.getInt(key);
565         }
566         return 0;
567     }
568 
569     /**
570      * Gets the advanced options.
571      *
572      * @return The advanced options.
573      *
574      * @hide
575      */
getAdvancedOptions()576     public Bundle getAdvancedOptions() {
577         return mAdvancedOptions;
578     }
579 
580     /**
581      * Sets the advanced options.
582      *
583      * @param options The advanced options.
584      *
585      * @hide
586      */
setAdvancedOptions(Bundle options)587     public void setAdvancedOptions(Bundle options) {
588         mAdvancedOptions = options;
589     }
590 
591     @Override
describeContents()592     public int describeContents() {
593         return 0;
594     }
595 
596     @Override
writeToParcel(Parcel parcel, int flags)597     public void writeToParcel(Parcel parcel, int flags) {
598         parcel.writeParcelable(mId, flags);
599         parcel.writeString(mLabel);
600         parcel.writeParcelable(mPrinterId, flags);
601         parcel.writeString(mPrinterName);
602         parcel.writeInt(mState);
603         parcel.writeInt(mAppId);
604         parcel.writeString(mTag);
605         parcel.writeLong(mCreationTime);
606         parcel.writeInt(mCopies);
607         parcel.writeString(mStateReason);
608         parcel.writeParcelableArray(mPageRanges, flags);
609         parcel.writeParcelable(mAttributes, flags);
610         parcel.writeParcelable(mDocumentInfo, 0);
611         parcel.writeInt(mCanceling ? 1 : 0);
612         parcel.writeBundle(mAdvancedOptions);
613     }
614 
615     @Override
toString()616     public String toString() {
617         StringBuilder builder = new StringBuilder();
618         builder.append("PrintJobInfo{");
619         builder.append("label: ").append(mLabel);
620         builder.append(", id: ").append(mId);
621         builder.append(", state: ").append(stateToString(mState));
622         builder.append(", printer: " + mPrinterId);
623         builder.append(", tag: ").append(mTag);
624         builder.append(", creationTime: " + mCreationTime);
625         builder.append(", copies: ").append(mCopies);
626         builder.append(", attributes: " + (mAttributes != null
627                 ? mAttributes.toString() : null));
628         builder.append(", documentInfo: " + (mDocumentInfo != null
629                 ? mDocumentInfo.toString() : null));
630         builder.append(", cancelling: " + mCanceling);
631         builder.append(", pages: " + (mPageRanges != null
632                 ? Arrays.toString(mPageRanges) : null));
633         builder.append(", hasAdvancedOptions: " + (mAdvancedOptions != null));
634         builder.append("}");
635         return builder.toString();
636     }
637 
638     /** @hide */
stateToString(int state)639     public static String stateToString(int state) {
640         switch (state) {
641             case STATE_CREATED: {
642                 return "STATE_CREATED";
643             }
644             case STATE_QUEUED: {
645                 return "STATE_QUEUED";
646             }
647             case STATE_STARTED: {
648                 return "STATE_STARTED";
649             }
650             case STATE_BLOCKED: {
651                 return "STATE_BLOCKED";
652             }
653             case STATE_FAILED: {
654                 return "STATE_FAILED";
655             }
656             case STATE_COMPLETED: {
657                 return "STATE_COMPLETED";
658             }
659             case STATE_CANCELED: {
660                 return "STATE_CANCELED";
661             }
662             default: {
663                 return "STATE_UNKNOWN";
664             }
665         }
666     }
667 
668     /**
669      * Builder for creating a {@link PrintJobInfo}.
670      */
671     public static final class Builder {
672         private final PrintJobInfo mPrototype;
673 
674         /**
675          * Constructor.
676          *
677          * @param prototype Prototype to use as a starting point.
678          * Can be <code>null</code>.
679          */
Builder(PrintJobInfo prototype)680         public Builder(PrintJobInfo prototype) {
681             mPrototype = (prototype != null)
682                     ? new PrintJobInfo(prototype)
683                     : new PrintJobInfo();
684         }
685 
686         /**
687          * Sets the number of copies.
688          *
689          * @param copies The number of copies.
690          */
setCopies(int copies)691         public void setCopies(int copies) {
692             mPrototype.mCopies = copies;
693         }
694 
695         /**
696          * Sets the print job attributes.
697          *
698          * @param attributes The attributes.
699          */
setAttributes(PrintAttributes attributes)700         public void setAttributes(PrintAttributes attributes) {
701             mPrototype.mAttributes = attributes;
702         }
703 
704         /**
705          * Sets the included pages.
706          *
707          * @param pages The included pages.
708          */
setPages(PageRange[] pages)709         public void setPages(PageRange[] pages) {
710             mPrototype.mPageRanges = pages;
711         }
712 
713         /**
714          * Puts an advanced (printer specific) option.
715          *
716          * @param key The option key.
717          * @param value The option value.
718          */
putAdvancedOption(String key, String value)719         public void putAdvancedOption(String key, String value) {
720             if (mPrototype.mAdvancedOptions == null) {
721                 mPrototype.mAdvancedOptions = new Bundle();
722             }
723             mPrototype.mAdvancedOptions.putString(key, value);
724         }
725 
726         /**
727          * Puts an advanced (printer specific) option.
728          *
729          * @param key The option key.
730          * @param value The option value.
731          */
putAdvancedOption(String key, int value)732         public void putAdvancedOption(String key, int value) {
733             if (mPrototype.mAdvancedOptions == null) {
734                 mPrototype.mAdvancedOptions = new Bundle();
735             }
736             mPrototype.mAdvancedOptions.putInt(key, value);
737         }
738 
739         /**
740          * Creates a new {@link PrintJobInfo} instance.
741          *
742          * @return The new instance.
743          */
build()744         public PrintJobInfo build() {
745             return mPrototype;
746         }
747     }
748 
749     public static final Parcelable.Creator<PrintJobInfo> CREATOR =
750             new Creator<PrintJobInfo>() {
751         @Override
752         public PrintJobInfo createFromParcel(Parcel parcel) {
753             return new PrintJobInfo(parcel);
754         }
755 
756         @Override
757         public PrintJobInfo[] newArray(int size) {
758             return new PrintJobInfo[size];
759         }
760     };
761 }
762