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