Add custom printer-state-reasons keyword support, add support for web forms, and document the simple web/REST interface (Issue #142)

Author: michaelrsweet

CHANGES.md

@@ -10,6 +10,8 @@ v3.0.1 - YYYY-MM-DD
   returns "localhost" for a non-loopback address.
 - Updated `cupsFileGetConf` and `cupsFilePutConf` to escape more characters.
 - Updated `cupsRasterReadHeader` to validate more of the page header values.
+- Updated `ippeveprinter` to support custom "printer-state-reasons" keyword
+  values (Issue #142)
 - Fixed a bug when the `ippFindXxx` and `ippSetXxx` functions were mixed
   (Issue #138)
 - Fixed error handling in the low-level TLS read/write functions.

doc/ippeveprinter.html

@@ -187,7 +187,8 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 Show program usage.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--no-web-forms</strong><br>
-Disable the web interface forms used to update the media and supply levels.
+Disable the web interface forms used to update the media, state, and supply levels.
+See the &quot;WEB INTERFACE FORMS&quot; section for more information.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--pam-service </strong><em>SERVICE</em><br>
 Set the PAM service name.
@@ -369,6 +370,29 @@ <h2 id="ippeveprinter-1.command-output">Command Output</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>STATE: +</strong><em>keyword[,keyword,...]</em><br>
 Adds the listed keywords to the printer's &quot;printer-state-reasons&quot; attribute.
+</p>
+    <h2 id="ippeveprinter-1.web-interface-forms">Web Interface Forms</h2>
+<p><strong>ippeveprinter</strong>
+provides a simple web interface with forms for updating the current media, state, and supply levels of the printer.
+Since these forms offer no security restrictions, they can be disabled using the
+<strong>--no-web-forms</strong>
+option.
+HTTP &quot;GET&quot; requests can be used to update printer values programmatically:
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GET /?reasons=</strong><em>KEYWORD[,...,KEYWORD]</em><br>
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GET /?reasons=+</strong><em>KEYWORD[,...,KEYWORD]</em><br>
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GET /?reasons=-</strong><em>KEYWORD[,...,KEYWORD]</em><br>
+Set, add, or remove the specified &quot;printer-state-reasons&quot; keywords.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GET /media?sizeN=</strong><em>SIZE-NAME</em><strong>&amp;typeN=</strong><em>TYPE-NAME</em><strong>&amp;levelN=</strong><em>NUM-SHEETS</em><br>
+Update the media size, type, and number of sheets for source N (starting at 0).
+Multiple sources can be updated in a single request by adding more sets of form values.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GET /supplies?supplyN=</strong><em>PERCENT</em><br>
+Update the current level of supply N (starting at 0).
+Multiple supplies can be updated in a single request by adding more form values.
 </p>
     <h2 id="ippeveprinter-1.examples">Examples</h2>
 <p>Run

man/ippeveprinter.1

@@ -7,7 +7,7 @@
 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
 .\" information.
 .\"
-.TH ippeveprinter 1 "CUPS" "2026-01-07" "OpenPrinting"
+.TH ippeveprinter 1 "CUPS" "2026-03-11" "OpenPrinting"
 .SH NAME
 ippeveprinter \- an ipp everywhere printer application for cups
 .SH SYNOPSIS
@@ -96,7 +96,8 @@ The following options are recognized by
 Show program usage.
 .TP 5
 .B \-\-no\-web\-forms
-Disable the web interface forms used to update the media and supply levels.
+Disable the web interface forms used to update the media, state, and supply levels.
+See the "WEB INTERFACE FORMS" section for more information.
 .TP 5
 \fB\-\-pam\-service \fISERVICE\fR
 Set the PAM service name.
@@ -267,6 +268,28 @@ Removes the listed keywords from the printer's "printer-state-reasons" attribute
 .TP 5
 \fBSTATE: +\fIkeyword[,keyword,...]\fR
 Adds the listed keywords to the printer's "printer-state-reasons" attribute.
+.SH WEB INTERFACE FORMS
+.B ippeveprinter
+provides a simple web interface with forms for updating the current media, state, and supply levels of the printer.
+Since these forms offer no security restrictions, they can be disabled using the
+.B \-\-no\-web\-forms
+option.
+HTTP "GET" requests can be used to update printer values programmatically:
+.TP 5
+\fBGET /?reasons=\fIKEYWORD[,...,KEYWORD]\fR
+.TP 5
+\fBGET /?reasons=+\fIKEYWORD[,...,KEYWORD]\fR
+.TP 5
+\fBGET /?reasons=-\fIKEYWORD[,...,KEYWORD]\fR
+Set, add, or remove the specified "printer-state-reasons" keywords.
+.TP 5
+\fBGET /media?sizeN=\fISIZE-NAME\fB&typeN=\fITYPE-NAME\fB&levelN=\fINUM-SHEETS\fR
+Update the media size, type, and number of sheets for source N (starting at 0).
+Multiple sources can be updated in a single request by adding more sets of form values.
+.TP 5
+\fBGET /supplies?supplyN=\fIPERCENT\fR
+Update the current level of supply N (starting at 0).
+Multiple supplies can be updated in a single request by adding more form values.
 .SH EXAMPLES
 Run
 .B ippeveprinter