Subject: IPP>MOD - SendDocument proposal

From: Roger K Debry <[email-masked]>
Date: Thu, 8 May 1997 13:06:58 -0400

The following text suggests revisions to the current model
  document to add the notion of createJob and SendDocument to the
  IPP Model. Line numbers and section numbers are from the April
  24th version 2.1 model document.  The text which follows will
  be slightly more readable if you use a mono-space font on your
  mail.

  Keith and I are proposing that we not use the byte range notion
  discussed in last week's telecon but go back to the original
  proposal. We do not believe that byte ranges add any value at
  this point, they complicate the model, and are not consistent
  with the way existing OS/2 and Windows drivers work.  If at some
  point we, or a specific vendor implementation, wants to add
  checkpointing and recovery then this issue can be revisited and
  properly designed to provide that function.

  Finally, we did not use Bob Herriot's suggestion to add document
  numbers. We see no immediate value in this proposal, it does not
  fit the OS/2 and Windows models, and it assumes that we will use
  a number to identify a document in the future and not a URL. It's
  not clear that this is the right decision. So, in the spirit of
  keeping things simple .............

  Section 3, lines 690 - 696 becomes

       Printer:
         Create Job (Section ...)
         Get Attributes (Section ...)
         Get Jobs (Section ...)
       Job Object:
         Send Document (Section ...)
         Get Attributes (Section ...)
         Cancel Job (Section ...)

  Section 4.1, lines 838 - 841 becomes

  Operations which can be invoked on a Printer include:

    Create Job (Section ...)
    Get Attributes (Section ...)
    Get Jobs (Section ...)

  Section 4.2, lines 905 - 909 becomes

  A Job object is used to model a print job. A job can contain one
  or more documents. The information required to create a job
  object is sent in a Create Job operation from the end user via a
  client implementation to a Printer. The Printer may perform some
  validation checks to verify that the job may indeed be processed.
  For example, the Create Job operation may request that the
  documents within the job be printed duplex (on both

  Section 4.2, lines 933 - 935 becomes

  The following operations can be invoked on Jobs:

    Send Document (Section ...)
    Cancel Job (Section ...)
    Get Attributes (Section ...)

  Section 4.3, lines 937 - 939 becomes

  Documents consist of printable data and attributes which describe
  the data to be printed. In this version of the protocol only
  attributes defined in section 6.4.1 may be defined for individual
  documents. Documents are sent in a Send Document operation.

  Section 5.1, lines 1042 - 1045 becomes

    For a Printer object:
       Create Job (Section ...)
       Get Attributes (Section ...)
       Get Jobs (Section ...)

  Section 5.1, lines 1047 - 1049 becomes

    For a Job object:
       Send Document (Section ...)
       Cancel Job (Section ...)
       Get Attributes (Section ...)

  Section 5.2.1 lines 1067 - 1074 becomes

  5.2.1 Create Job Operation

  When an end user desires to submit a print job, the client send a
  Create Job Request and receives a Create Job Response. The
  information in a Create Job Request along with any default
  information associated with the Printer is sufficient to create a
  Job object. An instance of a Job object contains all of the
  information needed by the Printer to print one or more documents
  as a print job.

  When a Printer receives a Create Job Request, it either accepts
  or rejects the request. The Printer accepts the Create Job
  Request and creates the a Job object if it is able to accept each

  Issue:  this section needs to be cleaned up to match the
  conformance section and get rid of adornments

  Section 5.2.1.1 lines 1101 - 1106 becomes

  5.2.1.1 Create Job Request

  The following abstract data types are part of the Print Request:

  Job and Document    A set of Job attributes as defined in
  Attributes          section  6.2. This section may be empty.
                      If so, Printer defaults are used.

  Section 5.2.1.2 lines 1108 - 1109 becomes

  5.2.1.2 Create Job Response

  The following abstract data types are part of the Create Job
  Response:

  New section to be added:

  x.x.x. Send Document Operation

  Once a Job object has been created, a client uses the Send
  Document operation to transport the documents to be printed and
  add them to the named Job object. A document may be sent in a
  single Send Document operation or split into pieces and sent with
  multiple Send Document operations.

  x.x.x.1 Send-Document Request

  The client submits the request to a Job URL.

  The following abstract data types are part of the Send-Document
  request:

  Content Length      Number of data bytes in this Request

  Document Part flag  Indicates that this is the first,
                      middle, last, or only segment
                      of a document

  End of job flag     Used in the last request of a job
                      to signal end-of-job to the Printer

  Document Attributes A set of Document attributes as
                      defined in section 6.4.

  Document Contents   <content-length> bytes of document
                      content in the format  defined by
                      the Document-format atttribute.
                      Document content is optional and
                      not included when printing by reference.

  x.x.x.2 Send-Document Response

  The following abstract data types are part of the Send-Document
  response:

    Bytes Written  Records the actual bytes accepted
                   by the Printer. This allows the client
                   to handle cases where the Printer failed
                   to accept the total amount of data in
                   the request for some reason.

    Status         status information, including error
                   status

    Message        optional status message

  Section 6.4,  replacement for the whole section

  Note: I re-wrote this section to put all document attributes in
  one place and clean up the definitions.

  6.4.1 Document Data Attributes (Set by a Client/End User)

  This group of attributes describes the document data for the job.
  They are supplied in the Send-Document request.

  6.4.1.1 document-name(name, Mandatory)

  This attribute contains the name of the document used by the
  client to initially identify the document. When a client prints
  by reference, i.e. includes the document-URL attribute and no
  document content, this attribute shall be absent. When a
  document's contents are spread across multiple Send Document
  operations, document-name is ignored by the Printer in all but
  the first Send Document operation for that document.

  6.4.1.2 document-format (type2 keyword)

  This attribute defines the document format of this document. When
  a client prints by reference, i.e. includes the document-URL
  attribute and no document content, this attribute shall be
  absent. When a document's contents are spread across multiple
  Send Document operations, document-format is ignored by the
  Printer in all but the first Send Document operation for that
  document.

  6.4.1.3 document-URL (url)

  This attribute contains the URL of the document when the document
  content is not included in the Send Document operation.
  Document-number is the only other attribute allowed when a
  document-URL attribute is present in a Send Document operation.

  Examples

  These examples may be included in the model document to halp
  clarify the use of send document. However, this is open to
  discussion. We believe that the model as now defined maps very
  nicely to both the OS/2 and Windows driver model. Using the
  proposal we saw from Babek at the San Jose PWG meeting, for
  example, the Windows API calls would map as shown:

  OpenPrinter - establish connection
  StartDocPrinter - Create Job (printer url, job attributes)
  WritePrinter - Send Document (job-url, part = first, length, data)
  WritePrinter - Send Document (job-url, part = middle, length, data)
  WritePrinter - Send Document (job-url, part = middle, length, data)
  EndDocPrinter - Send Document (job-url, eoj, part = last, length, data)
  ClosePrinter - close connection

  The following example illustrates the use of Send Document in
  more detail. In this example, a print job contains three
  documents. The first requires multiple writes to send the job,
  the second is a print by reference, the third can be sent in a
  single write:

  CreateJob (Printer URL, job-template attributes and values)
  SendDocument (Job URL, document-part=first,
               data-length=500,
               document-name=DOC1
               document-format=Postscript
              <document content>)
  SendDocument (Job URL, document-part=middle
               data-length=500,
              <document content>)
  SendDocument (Job URL, document-part=middle,
               data-length=500,
              <document content>)
  SendDocument (Job URL, document-part=last,
               data-length=150,
              <document content>)
  SendDocument (Job URL, document-URL=<url>
               document-name=DOC2)
  SendDocument (Job URL, document-part=only,
               End-of-Job,
               document-name=DOC3,
               document-format=PCL
               <document content>)