• Device Authentication
• User Authentication
• Protocol Specification ezeep Blue Pull Printing Release Action
  • Personal Printing Header Elements
  • UNICODE Support
  • Commands
    • Get Version
    • Get Capabilities
    • Get Print Job List
    • Delete Print Job
    • Print Job
    • Cancel Print Job
    • Set Job Properties
  • Error Codes

Pull Printing Release Workflow for Trusted Device App

This article describes the authentication and print job management of an app running on a printer-releated device (or even the printer itself) that authenticates itself using some fixed secret and identifies the user by verifying some credentials (user input or smartcard serial number). How to obtain the requested print data for forwarding to the print device is not subject of this API/article). An external ezeep Blue Hub may be used or a ezeep Blue Print Connector PS is required.

Device Authentication

The calls to this API are authentication via HTTP Basic Authorization scheme.

The assignment of an ezeep Blue Release Station card reader to a certain ezeep Blue printer object and its Authentication is made by the ‘Pull Printing Password’ sent as password part in the basic Authorization header of every web request. The (secret) value needs to be configured by the ezeep Blue organization administrator, who can obtain this value from the ezeep Blue Portal.

User Authentication

The user is identified by some ID. That ID can be obtained for example from a Smartcard (serial number) or via keyboard input interactively from the user. The ID is send as user name in the Authorization header. A system-unknown (i.e. new) user ID causes the printout of a registration code for user self-registration.

Protocol Specification ezeep Blue Pull Printing Release Action

base URL

https://pp2.ezeep.com/

Personal Printing Header Elements

Every request header has to contain the tag X-Lang-ID which specifies the language code for the error messages delivered by the server. The language code is specified as ISO 639: 2-letter code. The sample language code which is used within this document is “en” for English. Furthermore the client has to describe itself by sending the XFMP-User-Agent with a customized description. Every response of the server may contain at least the X-FMP-Return HTTP header. This header value specifies the result of the request. A value of zero indicates success. A value unequal zero indicates an error. For further information about errors see chapter Error codes.

UNICODE Support

All string values (among them for instance print job names and display names) are UTF-8 encoded, if not otherwise mentioned. If you use such values in URLs, don’t forget to canonalize the UTF-8 strings.

Commands

Get Version

This request returns the filenames and version numbers of all PPS components. This is useful for support purposes. The request does not require authentication. Future server versions may append more data sections.

GET https://pp2.ezeep.com/TPFM/?Cmd=GetVersion HTTP/1.1
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

If successful, returns Error code of 0, otherwise 1 or 2.

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=GetVersion \
        --header "X-Lang-ID: en" \
        --header "X-FMP-User-Agent: printer-model"  

Example Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 0
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

[FileVersions]

Get Capabilities

This request returns the list of commands supported by the PPS for the specified user. Authentication is optional. If no authentication was made, the capabilities of the guest user are returned.
Future server versions may append more data sections.

GET https://pp2.ezeep.com/TPFM/?Cmd=GetCapabilities HTTP/1.1
Authorization: Basic dGhpbnByaW50OmZtcA==
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

If successful, returns Error code of 0, otherwise 2.

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=GetCapabilities \
        --header "X-Lang-ID: en" \
        --header "X-FMP-User-Agent: printer-model" 

Example Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 0
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

[Commands]
1=GetVersion
2=GetCapabilities
3=GetJobList
4=DeleteJob
5=PrintJob
6=CancelPrintJob
7=SetJobProperties
[SYSTEM]
Type=essentials

Get Print Job List

This request returns the list of print jobs of the specified user. This request requires a user authentication. The result contains a list of print jobs of the specified user. The print job information is formatted as a list of job properties separated by ‘:’. The information contain (in this order) - the job filename (which cannot contain a colon), - the job file size, the creation date, the last modified date, - the file attributes, - the job id (alphanumeric, the ezeep Blue Pull Printing endpoint uses UUIDs), - the display name of the job and - the display name of the printer driver, used to create this job. All string values are UTF-8 encoded.

The date attributes are represented as number of seconds since January 1, 1970 GMT. The display name of the job may be empty. In this case the job filename should be used.

If a printer id is specified, the server filters the result list for compatible print jobs.

Only if X-FMP-Visible is set to 1, the client is allowed to show a print job selection/deletion dialog. If this header field is missing (or set to any other value), the client must not allow selecting or deleting unprinted print jobs by the user.

GET https://pp2.ezeep.com/TPFM/?Cmd=GetJobList&Printer=7 HTTP/1.1
Authorization: Basic dGhpbnByaW50OmZtcA==
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

Supported parameters (passed as query parameters in URL):

If successful, returns Error code of 0, otherwise 1, 2, 3, 4.

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=GetJobList&Printer=7 \
        --header "X-Lang-ID: en" \
        --header "X-FMP-User-Agent: printer-model" 

Sample Reponse:

HTTP/1.1 200 OK
Date: Wed, 12 Oct 2022 07:54:07 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 570
Connection: keep-alive
Server: ThinPrint Personal Printing Server
Strict-Transport-Security: max-age=31536000
X-FMP-Return: 0
X-FMP-Visible: 0

[Jobs]
2022-10-12_07.47.31_1fd4e6b9-44d1-4964-8f1e-e656978d3e79_9dce68fe-0814-4b74-a6c0-b2ae73fe6190_19cf8e9a-aa6b-4086-aad4-bbd9cef15810:11993:1665560851:1665560851:0:0:"on
e_char.docx":" "
2022-10-12_07.48.19_7984b5ef-0169-4bf1-b7f6-07e30100886c_9dce68fe-0814-4b74-a6c0-b2ae73fe6190_19cf8e9a-aa6b-4086-aad4-bbd9cef15810:4632133:1665560899:1665560899:0:0:"
Polarlicht_2.png":" "
2022-10-12_07.48.37_416bdc49-337e-4e54-9dad-3189578b0491_9dce68fe-0814-4b74-a6c0-b2ae73fe6190_19cf8e9a-aa6b-4086-aad4-bbd9cef15810:100117:1665560917:1665560917:0:0:"b
ittetesten.pdf":" "

Delete Print Job

This request deletes the specified print job of the specified user. The request requires a user authentication.

GET https://pp2.ezeep.com/TPFM/?Cmd=DeleteJob&Job=12345.tpf HTTP/1.1
Authorization: Basic dGhpbnByaW50OmZtcA==
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

Supported parameters (passed as query parameters in URL):

If successful, returns Error code of 0, otherwise 1, 2, 3 or 5

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=DeleteJob&Job=12345.tpf \
        --header "X-Lang-ID: en" \
        --header "X-FMP-User-Agent: printer-model" 

Example Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 0
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

Print Job

This request prints the specified job of the specified user to the specified printer. The response is sent by the ezeep Blue backend after successfully starting printing or an error occurred during print start.
If printing was started successfully the response header contains the HTTP header value X-FMP-ProcId which identifies the printing process and can be used for further calls to CancelPrintJob. If progress information delivery is enabled, the response header will also contain the HTTP header X-FMP-ProgressType which identifies the type of progress information. Possible values are ‘Pages’ to identify a “number of pages printed” progress and ‘Percentage’ for a “percent of document printed” progress. This logic is realized by simulating a chunked download. The request requires a user authentication.

If an error occurs during printing, the progress delivery is cancelled by sending ‘0’ (to stop the chunked download) followed by the (non-HTTP conform) trailer ‘X-FMP-Return’, ‘X-FMP-ErrText’, ‘X-FMP-OSError’ and ‘X-FMP-OSErrText’ which describe the error.
If the printing process finished successfully, the progress download is stopped by sending ‘0’ (to stop the chunked download) followed by the (non-HTTP conform) footer ‘X-FMP-Return’ which will be set to zero.
If progress delivery was disabled, the footer with the appropriate print result is send after printing has finished.
Since some HTTPClient Framework (for instance .NET CF) may have problems to process trailer rows, these trailers are repeated inside the response data.

The content is defined as series of chunks as defined in RFC-2616:

 Chunked-Body = *chunk
                 last-chunk
                 trailer
                 CRLF

Every chunk is defined as:

 chunk = chunk-size [ chunk-extension ] CRLF
         chunk-data CRLF

The chunk-data for ezeep Blue Pull Print response is defined as:

 chunk-data = token / token CRLF

(Please recognize: the CRLF here is part of the data and must be counted as data)

GET https://pp2.ezeep.com/TPFM/?Cmd=PrintJob&Job=12345.tpf&Printer=7373&Copies=2&Delete=1&Progress=1 HTTP/1.1
Authorization: Basic dGhpbnByaW50OmZtcA==
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

Supported parameters (passed as query parameters in URL):

If successful, returns Error code of 0.

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=PrintJob&Job=12345.tpf&Printer=7373&Copies=2&Delete=1&Progress=1 \
        --header "X-Lang-ID: en" \
        --header "X-FMP-User-Agent: printer-model" 

Example Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
X-FMP-Return: 0
X-FMP-ProgressType: Pages
X-FMP-ProcId: 738886
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT
6
 1/10
 6
 2/10
 6
 3/10
 6
 4/10
 ...
 7
 10/10
 11
 X-FMP-Return: 0 <-- result repeated inside response
0
X-FMP-Return: 0 <-- trailer / HTTP chunked response

Cancel Print Job

Cancels the running printing process identified by the specified print processing id returned by PrintJob. If the print was started with ‘Delete=1’ flag, the job is NOT deleted. The request requires a user authentication.

GET https://pp2.ezeep.com/TPFM/?Cmd=CancelPrintJob&ProcId=738886 HTTP/1.1
Authorization: Basic dGhpbnByaW50OmZtcA==
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

Supported parameters (passed as query parameters in URL):

If successful, returns Error code of 0, otherwise 1, 2, 3 or 9.

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=CancelPrintJob&ProcId=738886 \
        --header "X-Lang-ID: en" \
        --header "X-FMP-User-Agent: printer-model" 

Example Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 0
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

Set Job Properties

This request updates the specified properties of the specified pint job for the specified user. The request requires an user authentication.

GET https://pp2.ezeep.com/TPFM/?Cmd=SetJobProperties&Job=12345.tpf&PutOnHold=1&ModifiedDate=134156500 HTTP/1.1
Authorization: Basic dGhpbnByaW50OmZtcA==
X-Lang-ID: en
X-FMP-User-Agent: ezp-pp-manufatorer-model/1.0

Supported parameters (passed as query parameters in URL):

If successful, returns Error code of 0, otherwise 1, 2, 3, 5

Example Request:

curl -X GET https://pp2.ezeep.com/TPFM/?Cmd=SetJobProperties&Job=12345.tpf&PutOnHold=1&ModifiedDate=134156500 /
        --header "X-Lang-ID: en" /
        --header "X-FMP-User-Agent: printer-model" 

Example Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 0
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

Error Codes

If an error occurred during a ezeep Blue Pull Print API request, the HTTP response header X-FMP-Return will be set to a value unequal zero. In this case the HTTP response header X-FMP-ErrText specifies a localized error text which is base64 encoded. This error text may be empty (e.g. there is no error text available for the requested language).

If an operating system error occurred at the server while processing the request the HTTP response header X-FMP-OSError will be set to the operating system error code. Additionally the HTTP response header X-FMP-OSErrText specifies the localized operating system error text which is base64 encoded. This operating system error text may be empty (e.g. there is no error text available for the requested language).

Remark: If the authorization fails or is missing (and needed) the server will return corresponding HTTP status:

HTTP/1.1 401
Unauthorized. This is not handled via X-FMP-Returns values.

Example Responses:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 0
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 1
X-FMP-ErrText: b3BlcmF0aW5nIHN5c3RlbSBlcnJvciBvY2N1cnJlZCA=
X-FMP-OSError: 5
X-FMP-OSErrText: QWNjZXNzIGRlbmllZA==
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

HTTP/1.1 200 OK
Personal Printing Server
Content-Type: text/plain; charset=utf-8
X-FMP-Return: 4
X-FMP-ErrText: SW52YWxpZCBwcmludGVyIHdhcyBzcGVjaWZpZWQ=
Server: ThinPrint Personal Printing Server
Date: Sat, 05 Jan 2008 12:27:05 GMT

HTTP/1.1 401 Unauthorized
Connection: close
Date: Tue, 08 Jan 2008 09:14:09 GMT
Content-Type: text/plain; charset=utf-8
WWW-Authenticate: Basic realm="iisprint"
Server: ThinPrint Personal Printing Server
Personal Printing Server has rejected your unauthorized request.