Print job confirmation (DELETE)

CloudPRNT protocol using this HTTP method

CloudPRNT Version HTTP	✓
CloudPRNT Version MQTT (Trigger POST)	✓
CloudPRNT Version MQTT (Full MQTT / Pass URL)	-

Clients will confirm job completion with the server.
This is handled by issuing an http DELETE request to inform the server to clear the current job.
The query string is equivalent to the Print job requests (GET) request, but with the addition of a code parameter, and no need for the type parameter.
A DELETE may be used by the client to clear a completed print job, or to clear a job that it is unable to process.
the server should check the code parameter to determine the difference.

Some models will confirm the results of an update job execution.

Please refer to the description of firmware, skip`, ``error query parameters and Job execution result for media type of application/vnd.star.starconfiguration for details.

[http/https]://[cloudprntURL]?uid=<printer ID>&mac=<MAC address>&code=<status code>(&token=<job token>)((&firmware=<result>)(&config=<result>)&skip=<number>&error=<number>)(&retry=<number>)

Some Query parameters are supported from certain firmware versions, depending on the supported models:

Query Parameter	IFBD-HI01X/HI02X	mC-Print2/3	TSP100IV	TSP100IV SK	mC-Label3
token	1.8 or later	3.2 or later	1.0 or later	2.0 or later	1.0 or later
firmware	n/a	3.5 or later	1.0 or later	2.0 or later	1.0 or later
config	n/a	n/a	n/a	n/a	1.0 or later
skip	n/a	3.5 or later	1.0 or later	2.0 or later	1.0 or later(*1)
error	n/a	3.5 or later	1.0 or later	2.0 or later	1.0 or later

(*1) Value is fixed at 0.

Note

JSON parameters and supported models not listed in the table are supported by all firmware versions.

uid

A server specified UniqueID.

This will only be included if it has been set by the server.
code

A URL encoded printer response code. The corresponding code value as described in Printer Status Codes is set. e.g.) “200 OK”
mac

The printer MAC address, as used in the POST request.
token

Some models are supported from specific firmware versions.

A token is the URL encoded string token, present if one was provided by the server in its POST response.

This may be used by the server to uniquely identify jobs.
firmware

Some models are supported from specific firmware versions.

The result of the execution will be set when a printer fetches a job of the application/vnd.star.starconfiguration media type from the server and executes a firmware update process. (e.g.) &firmware=success)
config

Some models are supported from specific firmware versions.

The result of the execution will be set when a printer fetches a job of the application/vnd.star.starconfiguration media type from the server and executes a setting update process. (e.g.) &config=success)

Please refer to Job execution result for media type of application/vnd.star.starconfiguration.
skip

Some models are supported from specific firmware versions.

The number of items skipped will be set when a printer fetches a job of the application/vnd.star.starconfiguration media type from the server and executes a update process. (e.g.) &skip=0)

Please refer to Job execution result for media type of application/vnd.star.starconfiguration.
error

Some models are supported from specific firmware versions.

The number of items that were processed in error will be set when a printer fetches a job of the application/vnd.star.starconfiguration media type from the server and executes a update process. (e.g.) &error=0)

Please refer to Job execution result for media type of application/vnd.star.starconfiguration.
retry

Indicates the number of times the printer automatically resended the request when there is no response from the server to a DELETE request. (e.g.) &retry=2)

Please refer to Network Reliability and request retry .

Print job success

In case printing completes correctly, the client will send a DELETE to the server, with the code parameter set to “OK”, the uid and mac, token parameters will be the same as the preceding GET.
Next, the client will begin usual polling through POST requests.
At this time, if there is token information in the client, it will be deleted.

Print failure or error

In case printing fails, or an error occurs during printing, the client will follow the sequence:

Send a POST request to the server with a relevant printer status code.
If status is not OK (beginning with a “2”), then the server can determine that printing did not succeed.
If the client determines that the failure is not related to the print data, then it will enter the normal polling process.
After the printer issue has been resolved and it is online again, it will attempt to GET the job again if the server is still reporting that job data is available.
If the client determines that printing failed because it is not able to handle the active print job data, then it will send a DELETE, with corresponding code value, as described in Printer Status Codes.
After the DELETE, the client will resume the usual POST based polling process. At this time, if there is token information in the client, it will be deleted.

Please refer to the following for setting the response from the server to a DELETE request from the client in CloudPRNT.

Response header	Response Body
HTTP Status Code	None (does not include JSON data)

Below is an example of how the printer operates after receiving each HTTP response status code related to the DELETE response from the server.

Status Code	Printer action
200 / Other than 200	Issue Polling the server (POST)

Network Reliability and request retry

the DELETE (or GET with “delete” query string) fails to receive a response from the server, then the client printer may re-try to send it.

In this case, an additional query parameter will be added (“retry= <x> ” there <x> is the number of retries performed) to make this situation easy to detect.

This provides a protection against unreliable networks where requests can sometimes be lost.

However, in that case of sever network instability of complete failure, it is still possible that a server may not always receive the final DELETE.

Supported Device Versions and Retry times:

FW Version	Retry (times)
mC-Print2/3 (3.4 or earlier)	3
mC-Print2/3 (3.5 or later)	5
TSP100IV (1.0 or later)	5
TSP100IV SK (2.0 or later)	5
mC-Label3 (1.0 or later)	5
IFBD-HI01X/HI02X (1.5 or later)	5

Servers can additionally catch situations where a DELETE request has been missed, by monitoring the “printingInProgress” field of the regular poll (POST) request.

If this changes from true to false, despite not receiving a DELETE or POST (with error), then the server can assume that printing has completed, and that http requests from the client have been lost.

It can also be inferred by monitoring the jobToken, similar to monitoring the “printingInProgress” field above.
Normally, when a DELETE request is issued, jobToken information is deleted from subsequent POST requests.
Therefore, in cases where a DELETE request has not been received by the server even though the printer has actually completed printing, it can be inferred that printing has been completed when a POST request without a jobToken is received after the GET request.

Alternative Print job confirmation (GET)

Some web servers do not support DELETE requests through server side CGI scripts.

Therefore, an alternative method is provided.

If the server requests this mode (see Polling the server (POST) JSON Response section) then the printer will send an http GET request instead of a DELETE.
This request can be differentiated from a standard Print job requests (GET) , because the printer will add “delete” as a query string parameter.
In all other respects, the query string and behavior are the same as for the usual DELETE request.

Job execution result for media type of application/vnd.star.starconfiguration

Supported Device Versions:

FW Version	Retry (times)
mC-Print2/3	3.5 or later
TSP100IV	1.0 or later
TSP100IV SK	2.0 or later
mC-Label3	1.0 or later
IFBD-HI01X/HI02X	n/a

The application/vnd.star.starconfiguration media type is JSON format data followed Star Configuration Format specification(Please refer to this link for the specification details) and unlike other media types, the printer performs an internal update process when receives a job from server.

The results of the execution will be notified to the server by the following query parameters.

firmware =success (or failed)
Indicates the result of firmware update process.
success: Firmware update process was successful.

failed: Firmware update process was failed.(Update process aborted)
config =success (or failed)
Indicates the result of setting update process.
- success: Setting update process was successful.
- failed: Setting update process was failed.(Update process aborted)
skip =<x> (<x> is numeric)

The value set indicates the number of skipped items.

If DELETE request in query returns the “firmware=success” and “skip=1(Any number)”, indicates that there is one unrecognized setting or other item in the job data, and the process was skipped.

(e.g.) A job data includes unsupported key by printer)
error =<x> (<x> is numeric)

The value set indicates the number of items that were processed in error.

If DELETE request in query returns the “firmware=failed” and “error=1(Any number)”, indicates that an error occurred during the processing of the job’s data, causing the entire process to be aborted.

Please refer to the following example for possible errors that may occur.

[Example of update process failure]

There are the pattern of error in update process for application/vnd.star.starconfiguration media type data. As shown below, there are two types of errors: an error in job data itself (code query parameter notifies 511) and error in job data analysis and update process ( firmware / config query parameter notifies failed).

Example of job data error ( code=511%20Media%20Decoding%20Error ):

The Star Configuration Format specification data is not JSON fomrat.
The required key “title” is not listed in the Star Configuration Format specification data.
The value of required key “version” is not supported value.
e.g.)
“1.32” (No Revision)

“1.3.a” (Include non numeric)

“2.0.0” (Major version is unsupported)

Example of an error during job data analysis and update processing ( code=200%20OK&firmware=failed ):

The Star Configuration Format specification data contains five or more “firmware” objects.
Required key name is not listed, or the value of the required key name is invalid. (e.g.) “action”: “up”)
Failed to download firmware
Downloaded firmware data is incorrect (e.g.) The data was not Motorola S record format, incorrect model ID (firmware was for other models), incorrect model name and version information.)

Example of an error during job data analysis and update processing ( code=200%20OK&config=failed ):

Invalid password entered in the password protection item (password is the value used in the Web Configuration UI)
Failure to update firmware process (In case of the job data includes firmware and settings update)

Client HTTP Request Header

Supported Device Versions:

Device Name	FW Version
IFBD-HI01X/HI02X	1.8 or later
mC-Print2/3	3.2 or later
TSP100IV	1.0 or later
TSP100IV SK	2.0 or later
mC-Label3	1.0 or later

Please refer to Client HTTP Request Headers for detail.