- Security: The scheduler now blocks URLs containing embedded HTML
(STR #4356)
- - Documentation fixes (STR #3259, STR #4346)
+ - Documentation fixes (STR #3259, STR #4346, STR #4355)
- Fixed the Japanese localization (STR #4385)
- Added a German localization (STR #4363)
- Fixed documentation and naming of Create-Job/Printer-Subscriptions
Filter and backend programming header for CUPS.
- Copyright 2008-2011 by Apple Inc.
+ Copyright 2008-2014 by Apple Inc.
These coded instructions, statements, and computer programs are the
property of Apple Inc. and are protected by Federal copyright
<code>marker-types</code>, <code>printer-alert</code>, and
<code>printer-alert-description</code> printer attributes. Standard
<code>marker-types</code> values are listed in <a href='#TABLE1'>Table
- 1</a>.</dd>
+ 1</a>. String values need special handling - see <a href="#ATTR_STRINGS">Reporting Attribute String Values</a> below.</dd>
<dt>CRIT: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
<td>Fuser unit</td>
</tr>
<tr>
- <td>fuserCleaningPad</td>
+ <td>fuser-cleaning-pad</td>
<td>Fuser cleaning pad</td>
</tr>
<tr>
- <td>fuserOil</td>
+ <td>fuser-oil</td>
<td>Fuser oil</td>
</tr>
<tr>
<td>Photo conductor</td>
</tr>
<tr>
- <td>solidWax</td>
+ <td>solid-wax</td>
<td>Wax supply</td>
</tr>
<tr>
<td>Toner supply</td>
</tr>
<tr>
- <td>transferUnit</td>
+ <td>transfer-unit</td>
<td>Transfer unit</td>
</tr>
<tr>
- <td>wasteInk</td>
+ <td>waste-ink</td>
<td>Waste ink tank</td>
</tr>
<tr>
- <td>wasteToner</td>
+ <td>waste-toner</td>
<td>Waste toner tank</td>
</tr>
<tr>
- <td>wasteWax</td>
+ <td>waste-wax</td>
<td>Waste wax tank</td>
</tr>
</tbody>
</tbody>
</table></div>
+
+<h4><a name="ATTR_STRINGS">Reporting Attribute String Values</a></h4>
+
+<p>When reporting string values using "ATTR:" messages, a filter or backend must take special care to appropriately quote those values. The scheduler uses the CUPS option parsing code for attributes, so the general syntax is:</p>
+
+<pre class="example">
+name=simple
+name=simple,simple,...
+name='complex value'
+name="complex value"
+name='"complex value"','"complex value"',...
+</pre>
+
+<p>Simple values are strings that do not contain spaces, quotes, backslashes, or the comma and can be placed verbatim in the "ATTR:" message, for example:</p>
+
+<pre class="example">
+int levels[4] = { 40, 50, 60, 70 }; /* CMYK */
+
+fputs("ATTR: marker-colors=#00FFFF,#FF00FF,#FFFF00,#000000\n", stderr);
+fputs("ATTR: marker-high-levels=100,100,100,100\n", stderr);
+fprintf(stderr, "ATTR: marker-levels=%d,%d,%d,%d\n", levels[0], levels[1],
+ levels[2], levels[3], levels[4]);
+fputs("ATTR: marker-low-levels=5,5,5,5\n", stderr);
+fputs("ATTR: marker-types=toner,toner,toner,toner\n", stderr);
+</pre>
+
+<p>Complex values that contains spaces, quotes, backslashes, or the comma must be quoted. For a single value a single set of quotes is sufficient:</p>
+
+<pre class="example">
+fputs("ATTR: marker-message='Levels shown are approximate.'\n", stderr);
+</pre>
+
+<p>When multiple values are reported, each value must be enclosed by a set of single and double quotes:</p>
+
+<pre class="example">
+fputs("ATTR: marker-names='\"Cyan Toner\"','\"Magenta Toner\"',"
+ "'\"Yellow Toner\"','\"Black Toner\"'\n", stderr);
+</pre>
+
+<p>The IPP backend includes a <var>quote_string</var> function that may be used to properly quote a complex value in an "ATTR:" message:</p>
+
+<pre class="example">
+static const char * /* O - Quoted string */
+quote_string(const char *s, /* I - String */
+ char *q, /* I - Quoted string buffer */
+ size_t qsize) /* I - Size of quoted string buffer */
+{
+ char *qptr, /* Pointer into string buffer */
+ *qend; /* End of string buffer */
+
+
+ qptr = q;
+ qend = q + qsize - 5;
+
+ if (qend < q)
+ {
+ *q = '\0';
+ return (q);
+ }
+
+ *qptr++ = '\'';
+ *qptr++ = '\"';
+
+ while (*s && qptr < qend)
+ {
+ if (*s == '\\' || *s == '\"' || *s == '\'')
+ {
+ if (qptr < (qend - 4))
+ {
+ *qptr++ = '\\';
+ *qptr++ = '\\';
+ *qptr++ = '\\';
+ }
+ else
+ break;
+ }
+
+ *qptr++ = *s++;
+ }
+
+ *qptr++ = '\"';
+ *qptr++ = '\'';
+ *qptr = '\0';
+
+ return (q);
+}
+</pre>
+
+
<h4><a name="MANAGING_STATE">Managing Printer State in a Filter</a></h4>
<p>Filters are responsible for managing the state keywords they set using
Filter and backend programming header for CUPS.
- Copyright 2008-2011 by Apple Inc.
+ Copyright 2008-2014 by Apple Inc.
These coded instructions, statements, and computer programs are the
property of Apple Inc. and are protected by Federal copyright
<code>marker-types</code>, <code>printer-alert</code>, and
<code>printer-alert-description</code> printer attributes. Standard
<code>marker-types</code> values are listed in <a href='#TABLE1'>Table
- 1</a>.</dd>
+ 1</a>. String values need special handling - see <a href="#ATTR_STRINGS">Reporting Attribute String Values</a> below.</dd>
<dt>CRIT: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
<td>Fuser unit</td>
</tr>
<tr>
- <td>fuserCleaningPad</td>
+ <td>fuser-cleaning-pad</td>
<td>Fuser cleaning pad</td>
</tr>
<tr>
- <td>fuserOil</td>
+ <td>fuser-oil</td>
<td>Fuser oil</td>
</tr>
<tr>
<td>Photo conductor</td>
</tr>
<tr>
- <td>solidWax</td>
+ <td>solid-wax</td>
<td>Wax supply</td>
</tr>
<tr>
<td>Toner supply</td>
</tr>
<tr>
- <td>transferUnit</td>
+ <td>transfer-unit</td>
<td>Transfer unit</td>
</tr>
<tr>
- <td>wasteInk</td>
+ <td>waste-ink</td>
<td>Waste ink tank</td>
</tr>
<tr>
- <td>wasteToner</td>
+ <td>waste-toner</td>
<td>Waste toner tank</td>
</tr>
<tr>
- <td>wasteWax</td>
+ <td>waste-wax</td>
<td>Waste wax tank</td>
</tr>
</tbody>
</tbody>
</table></div>
+
+<h4><a name="ATTR_STRINGS">Reporting Attribute String Values</a></h4>
+
+<p>When reporting string values using "ATTR:" messages, a filter or backend must take special care to appropriately quote those values. The scheduler uses the CUPS option parsing code for attributes, so the general syntax is:</p>
+
+<pre class="example">
+name=simple
+name=simple,simple,...
+name='complex value'
+name="complex value"
+name='"complex value"','"complex value"',...
+</pre>
+
+<p>Simple values are strings that do not contain spaces, quotes, backslashes, or the comma and can be placed verbatim in the "ATTR:" message, for example:</p>
+
+<pre class="example">
+int levels[4] = { 40, 50, 60, 70 }; /* CMYK */
+
+fputs("ATTR: marker-colors=#00FFFF,#FF00FF,#FFFF00,#000000\n", stderr);
+fputs("ATTR: marker-high-levels=100,100,100,100\n", stderr);
+fprintf(stderr, "ATTR: marker-levels=%d,%d,%d,%d\n", levels[0], levels[1],
+ levels[2], levels[3], levels[4]);
+fputs("ATTR: marker-low-levels=5,5,5,5\n", stderr);
+fputs("ATTR: marker-types=toner,toner,toner,toner\n", stderr);
+</pre>
+
+<p>Complex values that contains spaces, quotes, backslashes, or the comma must be quoted. For a single value a single set of quotes is sufficient:</p>
+
+<pre class="example">
+fputs("ATTR: marker-message='Levels shown are approximate.'\n", stderr);
+</pre>
+
+<p>When multiple values are reported, each value must be enclosed by a set of single and double quotes:</p>
+
+<pre class="example">
+fputs("ATTR: marker-names='\"Cyan Toner\"','\"Magenta Toner\"',"
+ "'\"Yellow Toner\"','\"Black Toner\"'\n", stderr);
+</pre>
+
+<p>The IPP backend includes a <var>quote_string</var> function that may be used to properly quote a complex value in an "ATTR:" message:</p>
+
+<pre class="example">
+static const char * /* O - Quoted string */
+quote_string(const char *s, /* I - String */
+ char *q, /* I - Quoted string buffer */
+ size_t qsize) /* I - Size of quoted string buffer */
+{
+ char *qptr, /* Pointer into string buffer */
+ *qend; /* End of string buffer */
+
+
+ qptr = q;
+ qend = q + qsize - 5;
+
+ if (qend < q)
+ {
+ *q = '\0';
+ return (q);
+ }
+
+ *qptr++ = '\'';
+ *qptr++ = '\"';
+
+ while (*s && qptr < qend)
+ {
+ if (*s == '\\' || *s == '\"' || *s == '\'')
+ {
+ if (qptr < (qend - 4))
+ {
+ *qptr++ = '\\';
+ *qptr++ = '\\';
+ *qptr++ = '\\';
+ }
+ else
+ break;
+ }
+
+ *qptr++ = *s++;
+ }
+
+ *qptr++ = '\"';
+ *qptr++ = '\'';
+ *qptr = '\0';
+
+ return (q);
+}
+</pre>
+
+
<h4><a name="MANAGING_STATE">Managing Printer State in a Filter</a></h4>
<p>Filters are responsible for managing the state keywords they set using
<dd class="description">Close-Job</dd>
<dt>IPP_OP_CREATE_JOB </dt>
<dd class="description">Create an empty print job</dd>
-<dt>IPP_OP_CREATE_JOB_SUBSCRIPTION <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
-<dd class="description">Create a job subscription </dd>
-<dt>IPP_OP_CREATE_PRINTER_SUBSCRIPTION <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
-<dd class="description">Create a printer subscription </dd>
+<dt>IPP_OP_CREATE_JOB_SUBSCRIPTIONS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Create one of more job subscriptions </dd>
+<dt>IPP_OP_CREATE_PRINTER_SUBSCRIPTIONS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Create one or more printer subscriptions </dd>
<dt>IPP_OP_CUPS_ACCEPT_JOBS </dt>
<dd class="description">Accept new jobs on a printer</dd>
<dt>IPP_OP_CUPS_ADD_MODIFY_CLASS </dt>
projects / thirdparty / cups.git / commitdiff
