Changeset b3a56af for server


Ignore:
Timestamp:
Jan 22, 2012, 12:15:47 AM (12 years ago)
Author:
Jessica B. Hamrick <jhamrick@…>
Branches:
no-cups
Children:
97f20dd
Parents:
17eb586
git-author:
Jessica B. Hamrick <jhamrick@…> (01/22/12 00:15:47)
git-committer:
Jessica B. Hamrick <jhamrick@…> (01/22/12 00:15:47)
Message:

Some IPP documentation in printer.py

Location:
server/lib/gutenbach/server
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • server/lib/gutenbach/server/printer.py

    rd42236e rb3a56af  
    463463                  document_natural_language=None, requesting_user_name=None,
    464464                  compression=None, job_name=None, job_k_octets=None):
    465 
     465        """RFC 2911: 3.2.1 Print-Job Operation
     466       
     467        This REQUIRED operation allows a client to submit a print job
     468        with only one document and supply the document data (rather
     469        than just a reference to the data). See Section 15 for the
     470        suggested steps for processing create operations and their
     471        Operation and Job Template attributes.
     472
     473        Parameters
     474        ----------
     475        document (file)
     476            an open file handler to the document
     477        document_name (string)
     478            the name of the document
     479        document_format (string)
     480            the encoding/format of the document
     481        document_natural_language (string)
     482            if the document is a text file, what language it is in
     483        requesting_user_name (string)
     484            the user name of the job owner
     485        compression (string)
     486            the form of compression used on the file
     487        job_name (string)
     488            the name that the job should be called
     489        job_k_octets (int)
     490            the size of the job in bytes
     491
     492        """
     493       
    466494        self.assert_running()
    467495
    … …  
    489517                     document_natural_language=None, requesting_user_name=None,
    490518                     compression=None, job_name=None, job_k_octets=None):
    491 
     519        """RFC 2911: 3.2.3 Validate-Job Operation
     520
     521        This REQUIRED operation is similar to the Print-Job operation
     522        (section 3.2.1) except that a client supplies no document data
     523        and the Printer allocates no resources (i.e., it does not
     524        create a new Job object).  This operation is used only to
     525        verify capabilities of a printer object against whatever
     526        attributes are supplied by the client in the Validate-Job
     527        request.  By using the Validate-Job operation a client can
     528        validate that an identical Print-Job operation (with the
     529        document data) would be accepted. The Validate-Job operation
     530        also performs the same security negotiation as the Print-Job
     531        operation (see section 8), so that a client can check that the
     532        client and Printer object security requirements can be met
     533        before performing a Print-Job operation.
     534
     535        The Validate-Job operation does not accept a 'document-uri'
     536        attribute in order to allow a client to check that the same
     537        Print-URI operation will be accepted, since the client doesn't
     538        send the data with the Print-URI operation.  The client SHOULD
     539        just issue the Print-URI request.
     540
     541        Parameters
     542        ----------
     543        document (file)
     544            an open file handler to the document
     545        document_name (string)
     546            the name of the document
     547        document_format (string)
     548            the encoding/format of the document
     549        document_natural_language (string)
     550            if the document is a text file, what language it is in
     551        requesting_user_name (string)
     552            the user name of the job owner
     553        compression (string)
     554            the form of compression used on the file
     555        job_name (string)
     556            the name that the job should be called
     557        job_k_octets (int)
     558            the size of the job in bytes
     559
     560        """
     561       
    492562        self.assert_running()
    493563
    … …  
    504574    def get_jobs(self, requesting_user_name=None, which_jobs=None,
    505575                 requested_attributes=None):
     576        """RFC 2911: 3.2.6 Get-Jobs Operation
     577       
     578        This REQUIRED operation allows a client to retrieve the list
     579        of Job objects belonging to the target Printer object. The
     580        client may also supply a list of Job attribute names and/or
     581        attribute group names. A group of Job object attributes will
     582        be returned for each Job object that is returned.
     583
     584        This operation is similar to the Get-Job-Attributes operation,
     585        except that this Get-Jobs operation returns attributes from
     586        possibly more than one object.
     587
     588        Parameters
     589        ----------
     590        requesting_user_name (string)
     591            the user name of the job owner, used as a filter
     592        which_jobs (string)
     593            a filter for the types of jobs to return:
     594              * 'completed' -- only jobs that have finished
     595              * 'not-completed' -- processing or pending jobs
     596            this defaults to 'not-completed'
     597        requested_attributes (list)
     598            the job attributes to return
     599
     600        """
    506601       
    507602        self.assert_running()
    … …  
    533628    @sync
    534629    def print_uri(self):
    535         self.assert_running()
     630        """RFC 2911: 3.2.2 Print-URI Operation
     631
     632        This OPTIONAL operation is identical to the Print-Job
     633        operation (section 3.2.1) except that a client supplies a URI
     634        reference to the document data using the 'document-uri' (uri)
     635        operation attribute (in Group 1) rather than including the
     636        document data itself.  Before returning the response, the
     637        Printer MUST validate that the Printer supports the retrieval
     638        method (e.g., http, ftp, etc.) implied by the URI, and MUST
     639        check for valid URI syntax.  If the client-supplied URI scheme
     640        is not supported, i.e. the value is not in the Printer
     641        object's 'referenced-uri-scheme-supported' attribute, the
     642        Printer object MUST reject the request and return the
     643        'client-error-uri- scheme-not-supported' status code.
     644                                                                             
     645        If the Printer object supports this operation, it MUST support
     646        the 'reference-uri-schemes-supported' Printer attribute (see
     647        section 4.4.27).
     648
     649        It is up to the IPP object to interpret the URI and
     650        subsequently 'pull' the document from the source referenced by
     651        the URI string.
     652
     653        """
     654       
     655        self.assert_running()
     656        # XXX: todo
    536657
    537658    @sync
    538659    def create_job(self, requesting_user_name=None,
    539660                   job_name=None, job_k_octets=None):
    540 
     661        """RFC 2911: 3.2.4 Create-Job Operation
     662
     663        This OPTIONAL operation is similar to the Print-Job operation
     664        (section 3.2.1) except that in the Create-Job request, a
     665        client does not supply document data or any reference to
     666        document data. Also, the client does not supply any of the
     667        'document-name', 'document- format', 'compression', or
     668        'document-natural-language' operation attributes. This
     669        operation is followed by one or more Send-Document or Send-URI
     670        operations. In each of those operation requests, the client
     671        OPTIONALLY supplies the 'document-name', 'document-format',
     672        and 'document-natural-language' attributes for each document
     673        in the multi-document Job object.
     674
     675        Parameters
     676        ----------
     677        requesting_user_name (string)
     678            the user name of the job owner
     679        job_name (string)
     680            the name that the job should be called
     681        job_k_octets (int)
     682            the size of the job in bytes
     683
     684        """
     685       
    541686        self.assert_running()
    542687
    … …  
    554699    @sync
    555700    def pause_printer(self):
    556         """Pause the printer.
    557 
    558         Does nothing if the printer is already paused.
     701        """RFC 2911: 3.2.7 Pause-Printer Operation
     702
     703        This OPTIONAL operation allows a client to stop the Printer
     704        object from scheduling jobs on all its devices.  Depending on
     705        implementation, the Pause-Printer operation MAY also stop the
     706        Printer from processing the current job or jobs.  Any job that
     707        is currently being printed is either stopped as soon as the
     708        implementation permits or is completed, depending on
     709        implementation.  The Printer object MUST still accept create
     710        operations to create new jobs, but MUST prevent any jobs from
     711        entering the 'processing' state.
     712
     713        If the Pause-Printer operation is supported, then the
     714        Resume-Printer operation MUST be supported, and vice-versa.
     715
     716        The IPP Printer MUST accept the request in any state and
     717        transition the Printer to the indicated new 'printer-state'
     718        before returning as follows:
     719
     720        Current       New         Reasons             Reponse
     721        --------------------------------------------------------------
     722        'idle'       'stopped'    'paused'            'successful-ok'
     723        'processing' 'processing' 'moving-to-paused'  'successful-ok'
     724        'processing' 'stopped'    'paused'            'successful-ok'
     725        'stopped'    'stopped'    'paused'            'successful-ok'
     726
    559727        """
    560728       
    … …  
    568736    @sync
    569737    def resume_printer(self):
    570         """Resume the printer.
    571 
    572         Does nothing if the printer is not paused.
     738        """RFC 2911: 3.2.8 Resume-Printer Operation
     739
     740        This operation allows a client to resume the Printer object
     741        scheduling jobs on all its devices.  The Printer object MUST
     742        remove the 'paused' and 'moving-to-paused' values from the
     743        Printer object's 'printer-state-reasons' attribute, if
     744        present.  If there are no other reasons to keep a device
     745        paused (such as media-jam), the IPP Printer is free to
     746        transition itself to the 'processing' or 'idle' states,
     747        depending on whether there are jobs to be processed or not,
     748        respectively, and the device(s) resume processing jobs.
     749
     750        If the Pause-Printer operation is supported, then the
     751        Resume-Printer operation MUST be supported, and vice-versa.
     752
     753        The IPP Printer removes the 'printer-stopped' value from any
     754        job's 'job-state-reasons' attributes contained in that
     755        Printer.
     756
     757        The IPP Printer MUST accept the request in any state,
     758        transition the Printer object to the indicated new state as
     759        follows:
     760
     761        Current       New           Response
     762        ---------------------------------------------
     763        'idle'       'idle'         'successful-ok'
     764        'processing' 'processing'   'successful-ok'
     765        'stopped'    'processing'   'successful-ok'
     766        'stopped'    'idle'         'successful-ok'
     767
    573768        """
    574769       
    … …  
    582777    @sync
    583778    def get_printer_attributes(self, requested_attributes=None):
     779        """RFC 2911: 3.2.5 Get-Printer-Attributes Operation
     780
     781        This REQUIRED operation allows a client to request the values
     782        of the attributes of a Printer object.
     783       
     784        In the request, the client supplies the set of Printer
     785        attribute names and/or attribute group names in which the
     786        requester is interested. In the response, the Printer object
     787        returns a corresponding attribute set with the appropriate
     788        attribute values filled in.
     789
     790        Parameters
     791        ----------
     792        requested_attributes (list)
     793            the attributes to return
     794
     795        """
     796       
    584797        self.assert_running()
    585798        if requested_attributes is None:
    … …  
    604817    @sync
    605818    def cancel_job(self, job_id, requesting_user_name=None):
     819        """RFC 2911: 3.3.3 Cancel-Job Operation
     820
     821        This REQUIRED operation allows a client to cancel a Print Job
     822        from the time the job is created up to the time it is
     823        completed, canceled, or aborted. Since a Job might already be
     824        printing by the time a Cancel-Job is received, some media
     825        sheet pages might be printed before the job is actually
     826        terminated.
     827
     828        The IPP object MUST accept or reject the request based on the
     829        job's current state and transition the job to the indicated
     830        new state as follows:
     831
     832        Current State       New State           Response
     833        -----------------------------------------------------------------
     834        pending             canceled            successful-ok
     835        pending-held        canceled            successful-ok
     836        processing          canceled            successful-ok
     837        processing          processing          successful-ok               See Rule 1
     838        processing          processing          client-error-not-possible   See Rule 2
     839        processing-stopped  canceled            successful-ok
     840        processing-stopped  processing-stopped  successful-ok               See Rule 1
     841        processing-stopped  processing-stopped  client-error-not-possible   See Rule 2
     842        completed           completed           client-error-not-possible
     843        canceled            canceled            client-error-not-possible
     844        aborted             aborted             client-error-not-possible
     845
     846        Rule 1: If the implementation requires some measurable time to
     847        cancel the job in the 'processing' or 'processing-stopped' job
     848        states, the IPP object MUST add the 'processing-to-stop-point'
     849        value to the job's 'job-state-reasons' attribute and then
     850        transition the job to the 'canceled' state when the processing
     851        ceases (see section 4.3.8).
     852
     853        Rule 2: If the Job object already has the
     854        'processing-to-stop-point' value in its 'job-state-reasons'
     855        attribute, then the Printer object MUST reject a Cancel-Job
     856        operation.
     857
     858        Parameters
     859        ----------
     860        job_id (integer)
     861            the id of the job to cancel
     862        requesting_user_name (string)
     863            the name of the job's owner
     864
     865        """
     866
    606867        self.assert_running()
    607868        job = self.get_job(job_id)
    … …  
    617878                      requesting_user_name=None, compression=None,
    618879                      last_document=None):
    619 
     880        """RFC 2911: 3.3.1 Send-Document Operation
     881       
     882        This OPTIONAL operation allows a client to create a
     883        multi-document Job object that is initially 'empty' (contains
     884        no documents). In the Create-Job response, the Printer object
     885        returns the Job object's URI (the 'job-uri' attribute) and the
     886        Job object's 32-bit identifier (the 'job-id' attribute). For
     887        each new document that the client desires to add, the client
     888        uses a Send-Document operation. Each Send- Document Request
     889        contains the entire stream of document data for one document.
     890
     891        If the Printer supports this operation but does not support
     892        multiple documents per job, the Printer MUST reject subsequent
     893        Send-Document operations supplied with data and return the
     894        'server-error-multiple- document-jobs-not-supported'. However,
     895        the Printer MUST accept the first document with a 'true' or
     896        'false' value for the 'last-document' operation attribute (see
     897        below), so that clients MAY always submit one document jobs
     898        with a 'false' value for 'last-document' in the first
     899        Send-Document and a 'true' for 'last-document' in the second
     900        Send-Document (with no data).
     901       
     902        Since the Create-Job and the send operations (Send-Document or
     903        Send- URI operations) that follow could occur over an
     904        arbitrarily long period of time for a particular job, a client
     905        MUST send another send operation within an IPP Printer defined
     906        minimum time interval after the receipt of the previous
     907        request for the job. If a Printer object supports the
     908        Create-Job and Send-Document operations, the Printer object
     909        MUST support the 'multiple-operation-time-out' attribute (see
     910        section 4.4.31). This attribute indicates the minimum number
     911        of seconds the Printer object will wait for the next send
     912        operation before taking some recovery action.
     913
     914        An IPP object MUST recover from an errant client that does not
     915        supply a send operation, sometime after the minimum time
     916        interval specified by the Printer object's
     917        'multiple-operation-time-out' attribute.
     918
     919        Parameters
     920        ----------
     921        job_id (integer)
     922            the id of the job to send the document
     923        document (file)
     924            an open file handler to the document
     925        document_name (string)
     926            the name of the document
     927        document_format (string)
     928            the encoding/format of the document
     929        document_natural_language (string)
     930            if the document is a text file, what language it is in
     931        requesting_user_name (string)
     932            the user name of the job owner
     933        compression (string)
     934            the form of compression used on the file
     935        last_document (boolean)
     936            whether or not this is the last document in this job
     937
     938        """
     939       
    620940        self.assert_running()
    621941        job = self.get_job(job_id)
    … …  
    630950                 requesting_user_name=None, compression=None,
    631951                 last_document=None):
     952        """RFC 2911: 3.2.2 Send URI
     953
     954        This OPTIONAL operation is identical to the Send-Document
     955        operation (see section 3.3.1) except that a client MUST supply
     956        a URI reference ('document-uri' operation attribute) rather
     957        than the document data itself.  If a Printer object supports
     958        this operation, clients can use both Send-URI or Send-Document
     959        operations to add new documents to an existing multi-document
     960        Job object.  However, if a client needs to indicate that the
     961        previous Send-URI or Send-Document was the last document, the
     962        client MUST use the Send-Document operation with no document
     963        data and the 'last-document' flag set to 'true' (rather than
     964        using a Send-URI operation with no 'document-uri' operation
     965        attribute).
     966
     967        If a Printer object supports this operation, it MUST also
     968        support the Print-URI operation (see section 3.2.2).
     969
     970        The Printer object MUST validate the syntax and URI scheme of
     971        the supplied URI before returning a response, just as in the
     972        Print-URI operation.  The IPP Printer MAY validate the
     973        accessibility of the document as part of the operation or
     974        subsequently (see section 3.2.2).
     975
     976        Parameters
     977        ----------
     978        job_id (integer)
     979            the id of the job to send the uri
     980        document_uri (string)
     981            the uri of the document
     982        document_name (string)
     983            the name of the document
     984        document_format (string)
     985            the encoding/format of the document
     986        document_natural_language (string)
     987            if the document is a text file, what language it is in
     988        requesting_user_name (string)
     989            the user name of the job owner
     990        compression (string)
     991            the form of compression used on the file
     992        last_document (boolean)
     993            whether or not this is the last document in this job
     994
     995        """
    632996
    633997        self.assert_running()
    … …  
    6431007    @sync
    6441008    def get_job_attributes(self, job_id, requested_attributes=None):
     1009        """RFC 2911: 3.3.4 Get-Job-Attributes Operation
     1010
     1011        This REQUIRED operation allows a client to request the values
     1012        of attributes of a Job object and it is almost identical to
     1013        the Get- Printer-Attributes operation (see section 3.2.5). The
     1014        only differences are that the operation is directed at a Job
     1015        object rather than a Printer object, there is no
     1016        'document-format' operation attribute used when querying a Job
     1017        object, and the returned attribute group is a set of Job
     1018        object attributes rather than a set of Printer object
     1019        attributes.
     1020
     1021        For Jobs, the possible names of attribute groups are:
     1022          - 'job-template': the subset of the Job Template attributes
     1023            that apply to a Job object (the first column of the table
     1024            in Section 4.2) that the implementation supports for Job
     1025            objects.
     1026          - 'job-description': the subset of the Job Description
     1027            attributes specified in Section 4.3 that the
     1028            implementation supports for Job objects.
     1029          - 'all': the special group 'all' that includes all
     1030            attributes that the implementation supports for Job
     1031            objects.
     1032
     1033        Since a client MAY request specific attributes or named
     1034        groups, there is a potential that there is some overlap. For
     1035        example, if a client requests, 'job-name' and
     1036        'job-description', the client is actually requesting the
     1037        'job-name' attribute once by naming it explicitly, and once by
     1038        inclusion in the 'job-description' group. In such cases, the
     1039        Printer object NEED NOT return the attribute only once in the
     1040        response even if it is requested multiple times. The client
     1041        SHOULD NOT request the same attribute in multiple ways.
     1042
     1043        It is NOT REQUIRED that a Job object support all attributes
     1044        belonging to a group (since some attributes are
     1045        OPTIONAL). However it is REQUIRED that each Job object support
     1046        all these group names.
     1047
     1048        Parameters
     1049        ----------
     1050        job_id (integer)
     1051            the id of the job to send the uri
     1052        requested_attributes (list)
     1053            the attributes to return
     1054
     1055        """
    6451056
    6461057        self.assert_running()
    … …  
    6571068    @sync
    6581069    def set_job_attributes(self, job_id, attributes):
    659 
    6601070        self.assert_running()
    6611071        job = self.get_job(job_id)
    … …  
    6701080    @sync
    6711081    def restart_job(self, job_id, requesting_user_name=None):
    672 
    6731082        self.assert_running()
    6741083        job = self.get_job(job_id)

  • server/lib/gutenbach/server/requests.py

    r17eb586 rb3a56af  
    229229    @handler_for(ipp.OperationCodes.VALIDATE_JOB)
    230230    def validate_job(self, request, response):
    231         """3.2.3 Validate-Job Operation
     231        """RFC 2911: 3.2.3 Validate-Job Operation
    232232
    233233        This REQUIRED operation is similar to the Print-Job operation
    … …  
    312312    @handler_for(ipp.OperationCodes.GET_JOBS)
    313313    def get_jobs(self, request, response):
    314         """3.2.6 Get-Jobs Operation
     314        """RFC 2911: 3.2.6 Get-Jobs Operation
    315315       
    316316        This REQUIRED operation allows a client to retrieve the list
    … …  
    401401    @handler_for(ipp.OperationCodes.PRINT_URI)
    402402    def print_uri(self, request, response):
    403         """3.2.2 Print-URI Operation
     403        """RFC 2911: 3.2.2 Print-URI Operation
    404404
    405405        This OPTIONAL operation is identical to the Print-Job
    … …  
    415415        Printer object MUST reject the request and return the
    416416        'client-error-uri- scheme-not-supported' status code.
    417 
    418         The IPP Printer MAY validate the accessibility of the document
    419         as part of the operation or subsequently.  If the Printer
    420         determines an accessibility problem before returning an
    421         operation response, it rejects the request and returns the
    422         'client-error-document-access- error' status code.  The
    423         Printer MAY also return a specific document access error code
    424         using the 'document-access-error' operation attribute (see
    425         section 3.1.6.4).
    426 
    427         If the Printer determines this document accessibility problem
    428         after accepting the request and returning an operation
    429         response with one of the successful status codes, the Printer
    430         adds the 'document-access- error' value to the job's
    431         'job-state-reasons' attribute and MAY populate the job's
    432         'job-document-access-errors' Job Description attribute (see
    433         section 4.3.11).  See The Implementer's Guide [IPP- IIG] for
    434         suggested additional checks.
    435417                                                                             
    436418        If the Printer object supports this operation, it MUST support
    … …  
    631613    @handler_for(ipp.OperationCodes.PAUSE_PRINTER)
    632614    def pause_printer(self, request, response):
    633         """3.2.7 Pause-Printer Operation
     615        """RFC 2911: 3.2.7 Pause-Printer Operation
    634616
    635617        This OPTIONAL operation allows a client to stop the Printer
    … …  
    694676    @handler_for(ipp.OperationCodes.RESUME_PRINTER)
    695677    def resume_printer(self, request, response):
    696         """3.2.8 Resume-Printer Operation
     678        """RFC 2911: 3.2.8 Resume-Printer Operation
    697679
    698680        This operation allows a client to resume the Printer object
    … …  
    838820    @handler_for(ipp.OperationCodes.CANCEL_JOB)
    839821    def cancel_job(self, request, response):
    840         """3.3.3 Cancel-Job Operation
     822        """RFC 2911: 3.3.3 Cancel-Job Operation
    841823
    842824        This REQUIRED operation allows a client to cancel a Print Job
    … …  
    877859        operation.
    878860
    879         Access Rights: The authenticated user (see section 8.3)
    880         performing this operation must either be the job owner or an
    881         operator or administrator of the Printer object (see Sections
    882         1 and 8.5).  Otherwise, the IPP object MUST reject the
    883         operation and return: 'client-error-forbidden',
    884         'client-error-not-authenticated', or
    885         'client-error-not-authorized' as appropriate.
    886 
    887861        Request
    888862        -------
    … …  
    938912    @handler_for(ipp.OperationCodes.SEND_DOCUMENT)
    939913    def send_document(self, request, response):
    940         """3.3.1 Send-Document Operation
     914        """RFC 2911: 3.3.1 Send-Document Operation
    941915       
    942916        This OPTIONAL operation allows a client to create a
    … …  
    976950        interval specified by the Printer object's
    977951        'multiple-operation-time-out' attribute.
    978 
    979         Access Rights: The authenticated user (see section 8.3)
    980         performing this operation must either be the job owner (as
    981         determined in the Create-Job operation) or an operator or
    982         administrator of the Printer object (see Sections 1 and
    983         8.5). Otherwise, the IPP object MUST reject the operation and
    984         return: 'client-error-forbidden', 'client-
    985         error-not-authenticated', or 'client-error-not-authorized' as
    986         appropriate.
    987952
    988953        Request
    … …  
    10901055    @handler_for(ipp.OperationCodes.SEND_URI)
    10911056    def send_uri(self, request, response):
    1092 
    1093         """3.2.2 Send URI
     1057        """RFC 2911: 3.2.2 Send URI
    10941058
    10951059        This OPTIONAL operation is identical to the Send-Document
    … …  
    12221186    @handler_for(ipp.OperationCodes.GET_JOB_ATTRIBUTES)
    12231187    def get_job_attributes(self, request, response):
    1224         """3.3.4 Get-Job-Attributes Operation
     1188        """RFC 2911: 3.3.4 Get-Job-Attributes Operation
    12251189
    12261190        This REQUIRED operation allows a client to request the values
Note: See TracChangeset for help on using the changeset viewer.