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