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