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