From 6c019649f4fe60c55f009906cf687402cbe3d2b6 Mon Sep 17 00:00:00 2001 From: msweet Date: Thu, 27 Mar 2014 20:57:33 +0000 Subject: [PATCH] Mirror fix from trunk. git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/branches/branch-1.7@11759 a1ca3aef-8c08-0410-bb20-df032aa958be --- CHANGES.txt | 2 +- cups/api-filter.header | 2 +- cups/api-filter.shtml | 105 ++++++++++++++++++++++++++++++++++--- doc/help/api-filter.html | 107 ++++++++++++++++++++++++++++++++++---- doc/help/api-httpipp.html | 8 +-- 5 files changed, 201 insertions(+), 23 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index b86b5b7bc8..4cd505eaba 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -5,7 +5,7 @@ CHANGES IN CUPS V1.7.2 - 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 diff --git a/cups/api-filter.header b/cups/api-filter.header index 5b7ee181fb..303145212d 100644 --- a/cups/api-filter.header +++ b/cups/api-filter.header @@ -3,7 +3,7 @@ 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 diff --git a/cups/api-filter.shtml b/cups/api-filter.shtml index 3f912ba864..4b8372edda 100644 --- a/cups/api-filter.shtml +++ b/cups/api-filter.shtml @@ -237,7 +237,7 @@ prefix strings:

marker-types, printer-alert, and printer-alert-description printer attributes. Standard marker-types values are listed in Table - 1. + 1. String values need special handling - see Reporting Attribute String Values below.
CRIT: message
Sets the printer-state-message attribute and adds the specified @@ -320,11 +320,11 @@ the "DEBUG:" prefix string.

Fuser unit - fuserCleaningPad + fuser-cleaning-pad Fuser cleaning pad - fuserOil + fuser-oil Fuser oil @@ -336,7 +336,7 @@ the "DEBUG:" prefix string.

Photo conductor - solidWax + solid-wax Wax supply @@ -348,19 +348,19 @@ the "DEBUG:" prefix string.

Toner supply - transferUnit + transfer-unit Transfer unit - wasteInk + waste-ink Waste ink tank - wasteToner + waste-toner Waste toner tank - wasteWax + waste-wax Waste wax tank @@ -440,6 +440,95 @@ the "DEBUG:" prefix string.

+ +

Reporting Attribute String Values

+ +

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:

+ +
+name=simple
+name=simple,simple,...
+name='complex value'
+name="complex value"
+name='"complex value"','"complex value"',...
+
+ +

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:

+ +
+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);
+
+ +

Complex values that contains spaces, quotes, backslashes, or the comma must be quoted. For a single value a single set of quotes is sufficient:

+ +
+fputs("ATTR: marker-message='Levels shown are approximate.'\n", stderr);
+
+ +

When multiple values are reported, each value must be enclosed by a set of single and double quotes:

+ +
+fputs("ATTR: marker-names='\"Cyan Toner\"','\"Magenta Toner\"',"
+      "'\"Yellow Toner\"','\"Black Toner\"'\n", stderr);
+
+ +

The IPP backend includes a quote_string function that may be used to properly quote a complex value in an "ATTR:" message:

+ +
+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);
+}
+
+ +

Managing Printer State in a Filter

Filters are responsible for managing the state keywords they set using diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html index 5428058792..566bc149df 100644 --- a/doc/help/api-filter.html +++ b/doc/help/api-filter.html @@ -345,7 +345,7 @@ div.contents ul.subcontents li { 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 @@ -664,7 +664,7 @@ prefix strings:

marker-types, printer-alert, and printer-alert-description printer attributes. Standard marker-types values are listed in Table - 1.
+ 1. String values need special handling - see Reporting Attribute String Values below.
CRIT: message
Sets the printer-state-message attribute and adds the specified @@ -747,11 +747,11 @@ the "DEBUG:" prefix string.

Fuser unit - fuserCleaningPad + fuser-cleaning-pad Fuser cleaning pad - fuserOil + fuser-oil Fuser oil @@ -763,7 +763,7 @@ the "DEBUG:" prefix string.

Photo conductor - solidWax + solid-wax Wax supply @@ -775,19 +775,19 @@ the "DEBUG:" prefix string.

Toner supply - transferUnit + transfer-unit Transfer unit - wasteInk + waste-ink Waste ink tank - wasteToner + waste-toner Waste toner tank - wasteWax + waste-wax Waste wax tank @@ -867,6 +867,95 @@ the "DEBUG:" prefix string.

+ +

Reporting Attribute String Values

+ +

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:

+ +
+name=simple
+name=simple,simple,...
+name='complex value'
+name="complex value"
+name='"complex value"','"complex value"',...
+
+ +

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:

+ +
+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);
+
+ +

Complex values that contains spaces, quotes, backslashes, or the comma must be quoted. For a single value a single set of quotes is sufficient:

+ +
+fputs("ATTR: marker-message='Levels shown are approximate.'\n", stderr);
+
+ +

When multiple values are reported, each value must be enclosed by a set of single and double quotes:

+ +
+fputs("ATTR: marker-names='\"Cyan Toner\"','\"Magenta Toner\"',"
+      "'\"Yellow Toner\"','\"Black Toner\"'\n", stderr);
+
+ +

The IPP backend includes a quote_string function that may be used to properly quote a complex value in an "ATTR:" message:

+ +
+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);
+}
+
+ +

Managing Printer State in a Filter

Filters are responsible for managing the state keywords they set using diff --git a/doc/help/api-httpipp.html b/doc/help/api-httpipp.html index f6f117b56b..9023f0e980 100644 --- a/doc/help/api-httpipp.html +++ b/doc/help/api-httpipp.html @@ -5986,10 +5986,10 @@ are server-oriented...

Close-Job
IPP_OP_CREATE_JOB
Create an empty print job
-
IPP_OP_CREATE_JOB_SUBSCRIPTION  CUPS 1.2/OS X 10.5 
-
Create a job subscription
-
IPP_OP_CREATE_PRINTER_SUBSCRIPTION  CUPS 1.2/OS X 10.5 
-
Create a printer subscription
+
IPP_OP_CREATE_JOB_SUBSCRIPTIONS  CUPS 1.2/OS X 10.5 
+
Create one of more job subscriptions
+
IPP_OP_CREATE_PRINTER_SUBSCRIPTIONS  CUPS 1.2/OS X 10.5 
+
Create one or more printer subscriptions
IPP_OP_CUPS_ACCEPT_JOBS
Accept new jobs on a printer
IPP_OP_CUPS_ADD_MODIFY_CLASS
-- 2.47.2