From ca6b43fc04e0fe678dbb47c3c1c31be42fcdd4b2 Mon Sep 17 00:00:00 2001 From: msweet Date: Thu, 27 Mar 2014 20:57:18 +0000 Subject: [PATCH] Update CUPS filter/backend programming guide (STR #4355) git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@11758 a1ca3aef-8c08-0410-bb20-df032aa958be --- CHANGES-1.7.txt | 2 +- cups/api-filter.header | 2 +- cups/api-filter.shtml | 105 +++++++- doc/help/api-array.html | 4 +- doc/help/api-cgi.html | 4 +- doc/help/api-cups.html | 4 +- doc/help/api-filedir.html | 4 +- doc/help/api-filter.html | 111 +++++++- doc/help/api-httpipp.html | 459 +++++++++++++++++++++++++++----- doc/help/api-mime.html | 4 +- doc/help/api-overview.html | 4 +- doc/help/api-ppd.html | 4 +- doc/help/api-ppdc.html | 4 +- doc/help/api-raster.html | 4 +- doc/help/postscript-driver.html | 4 +- doc/help/ppd-compiler.html | 4 +- doc/help/raster-driver.html | 4 +- doc/help/spec-ppd.html | 4 +- 18 files changed, 612 insertions(+), 119 deletions(-) diff --git a/CHANGES-1.7.txt b/CHANGES-1.7.txt index c52c40dda..1b7758087 100644 --- a/CHANGES-1.7.txt +++ b/CHANGES-1.7.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 5b7ee181f..303145212 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 3f912ba86..4b8372edd 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-array.html b/doc/help/api-array.html index 0c1998ee3..6bd01d94e 100644 --- a/doc/help/api-array.html +++ b/doc/help/api-array.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-cgi.html b/doc/help/api-cgi.html index 82c740a86..57087c5f5 100644 --- a/doc/help/api-cgi.html +++ b/doc/help/api-cgi.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html index b355e108b..cdd11fdfa 100644 --- a/doc/help/api-cups.html +++ b/doc/help/api-cups.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-filedir.html b/doc/help/api-filedir.html index fc7b72a40..f07524af7 100644 --- a/doc/help/api-filedir.html +++ b/doc/help/api-filedir.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html index 542805879..db774c4c0 100644 --- a/doc/help/api-filter.html +++ b/doc/help/api-filter.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } @@ -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 f6f117b56..5f4f2f38c 100644 --- a/doc/help/api-httpipp.html +++ b/doc/help/api-httpipp.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } @@ -408,7 +408,10 @@ current thread.">cupsLastErrorString specified listening socket.">httpAcceptConnection

  • httpAddCredential
  • httpAddrAny
    • +
  • httpAddrClose
  • httpAddrEqual
    • +
  • httpAddrFamily
  • httpAddrLength
  • httpAddrListen
    • @@ -426,11 +429,10 @@ components with a formatted resource.">httpAssembleURIf
  • httpClearCookie
  • httpClearFields
  • httpClose
    • +
  • httpCompareCredentials
  • httpConnect
  • httpConnect2
  • httpConnectEncrypt
    • -
  • httpCopyCredentials
  • httpDecode64
  • httpDecode64_2
  • httpDelete
    • @@ -438,10 +440,14 @@ connection.">httpCopyCredentials
  • httpEncode64_2
  • httpEncryption
  • httpError
    • +
  • httpFieldValue
  • httpFlush
  • httpFlushWrite
  • httpFreeCredentials
  • httpGet
    • +
  • httpGetActivity
    • +
  • httpGetAddress
  • httpGetAuthString
  • httpGetBlocking
  • httpGetContentEncoding
  • httpGetDateString
  • httpGetDateString2
  • httpGetDateTime
    • +
  • httpGetEncryption
  • httpGetExpect
  • httpGetFd
  • httpGetField
  • httpGetHostByName
  • httpGetHostname
    • +
  • httpGetKeepAlive
  • httpGetLength
  • httpGetLength2
    • +
  • httpGetPending
    • +
  • httpGetReady
    • +
  • httpGetRemaining
  • httpGetState
  • httpGetStatus
  • httpGetSubField
    • @@ -469,6 +481,8 @@ content-length or transfer-encoding fields.">httpGetLength2
  • httpHead
  • httpInitialize
    • +
  • httpIsChunked
    • +
  • httpIsEncrypted
  • httpMD5
  • httpMD5Final
  • httpReconnect
  • httpReconnect2
    • +
  • httpResolveHostname
  • httpSeparate
  • httpSetCredentials
  • httpSetDefaultField
  • httpSetExpect
  • httpSetField
    • +
  • httpSetKeepAlive
  • httpSetLength
  • httpSetTimeout
    • +
  • httpShutdown
    • +
  • httpStateString
  • httpStatus
  • httpTrace
    • +
  • httpURIStatusString
  • httpUpdate
  • httpWait
  • httpWrite
    • @@ -592,6 +612,7 @@ in seconds.">ippDateToTime
  • ippSetStringfv
  • ippSetValueTag
  • ippSetVersion
    • +
  • ippStateString
  • ippTagString
  • ippTagValue
  • ippTimeToDate
    • @@ -1455,6 +1476,29 @@ int httpAddrAny (

    Return Value

    1 if "any", 0 otherwise

    +

     CUPS 2.0 httpAddrClose

    +

    Close a socket created by httpAddrConnect or +httpAddrListen.

    +

    +int httpAddrClose (
    +    http_addr_t *addr,
    +    int fd
    +);

    +

    Parameters

    +
    +
    addr
    +
    Listen address or NULL
    +
    fd
    +
    Socket file descriptor
    +
    +

    Return Value

    +

    0 on success, -1 on failure

    +

    Discussion

    +

    Pass NULL for sockets created with httpAddrConnect and the +listen address for sockets created with httpAddrListen. This will +ensure that domain sockets are removed when closed. + +

     CUPS 1.2/OS X 10.5 httpAddrEqual

    Compare two addresses.

    @@ -1471,6 +1515,19 @@ int httpAddrEqual (

    Return Value

    1 if equal, 0 if not

    +

    httpAddrFamily

    +

    Get the address family of an address.

    +

    +int httpAddrFamily (
    +    http_addr_t *addr
    +);

    +

    Parameters

    +
    +
    addr
    +
    Address
    +
    +

    Return Value

    +

    Address family

     CUPS 1.2/OS X 10.5 httpAddrLength

    Return the length of the address in bytes.

    @@ -1699,7 +1756,7 @@ void httpBlocking (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    b
    1 = blocking, 0 = non-blocking
    @@ -1712,7 +1769,7 @@ int httpCheck (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    0 = no data, 1 = data available

    @@ -1725,7 +1782,7 @@ void httpClearCookie (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    httpClearFields

    Clear HTTP request fields.

    @@ -1736,7 +1793,7 @@ void httpClearFields (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    httpClose

    Close an HTTP connection.

    @@ -1747,8 +1804,24 @@ void httpClose (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    +

     CUPS 2.0 httpCompareCredentials

    +

    Compare two sets of X.509 credentials.

    +

    +int httpCompareCredentials (
    +    cups_array_t *cred1,
    +    cups_array_t *cred2
    +);

    +

    Parameters

    +
    +
    cred1
    +
    First set of X.509 credentials
    +
    cred2
    +
    Second set of X.509 credentials
    +
    +

    Return Value

    +

    1 if they match, 0 if they do not

     DEPRECATED httpConnect

    Connect to a HTTP server.

    @@ -1827,23 +1900,6 @@ void httpClose (
    instead.

    -

     CUPS 1.5/OS X 10.7 httpCopyCredentials

    -

    Copy the credentials associated with an encrypted -connection.

    -

    -int httpCopyCredentials (
    -    http_t *http,
    -    cups_array_t **credentials
    -);

    -

    Parameters

    -
    -
    http
    -
    Connection to server
    -
    credentials
    -
    Array of credentials
    -
    -

    Return Value

    -

    Status of call (0 = success)

     DEPRECATED httpDecode64

    Base64-decode a string.

    @@ -1894,7 +1950,7 @@ int httpDelete (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI to delete
    @@ -1953,7 +2009,7 @@ int httpEncryption (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    e
    New encryption preference
    @@ -1968,10 +2024,24 @@ int httpError (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Error code (errno) value

    +

    httpFieldValue

    +

    Return the HTTP field enumeration value for a field +name.

    +

    +http_field_t httpFieldValue (
    +    const char *name
    +);

    +

    Parameters

    +
    +
    name
    +
    String name
    +
    +

    Return Value

    +

    Field index

    httpFlush

    Flush data from a HTTP connection.

    @@ -1981,7 +2051,7 @@ void httpFlush (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

     CUPS 1.2/OS X 10.5 httpFlushWrite

    Flush data in write buffer.

    @@ -1992,7 +2062,7 @@ int httpFlushWrite (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Bytes written or -1 on error

    @@ -2017,12 +2087,46 @@ int httpGet (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI to get

    Return Value

    Status of call (0 = success)

    +

     CUPS 2.0 httpGetActivity

    +

    Get the most recent activity for a connection.

    +

    +time_t httpGetActivity (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Time of last read or write

    +

    Discussion

    +

    The return value is the UNIX time of the last read or write. + +

    +

     CUPS 2.0 httpGetAddress

    +

    Get the address of the connected peer of a connection.

    +

    +http_addr_t *httpGetAddress (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Connected address or NULL

    +

    Discussion

    +

    Returns NULL if the socket is currently unconnected. + +

     CUPS 1.3/OS X 10.5 httpGetAuthString

    Get the current authorization string.

    @@ -2032,7 +2136,7 @@ char *httpGetAuthString (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Authorization string

    @@ -2052,7 +2156,7 @@ int httpGetBlocking (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    1 if blocking, 0 if non-blocking

    @@ -2066,7 +2170,7 @@ const char *httpGetContentEncoding (

    Parameters

    http
    -
    Connection to client/server
    +
    HTTP connection

    Return Value

    Content-Coding value or @@ -2137,6 +2241,25 @@ time_t httpGetDateTime (

    Return Value

    UNIX time

    +

     CUPS 2.0 httpGetEncryption

    +

    Get the current encryption mode of a connection.

    +

    +http_encryption_t httpGetEncryption (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Current encryption mode

    +

    Discussion

    +

    This function returns the encryption mode for the connection. Use the +httpIsEncrypted function to determine whether a TLS session has +been established. + +

     CUPS 1.7/OS X 10.9 httpGetExpect

    Get the value of the Expect header, if any.

    @@ -2146,7 +2269,7 @@ http_status_t httpGetExpect (

    Parameters

    http
    -
    Connection to client
    +
    HTTP connection

    Return Value

    Expect: status, if any

    @@ -2164,7 +2287,7 @@ int httpGetFd (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    File descriptor or -1 if none

    @@ -2178,7 +2301,7 @@ const char *httpGetField (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    field
    Field to get
    @@ -2219,11 +2342,25 @@ const char *httpGetHostname (

    FQDN for connection or system

    Discussion

    When "http" points to a connected socket, return the hostname or -address that was used in the call to httpConnect() or httpConnectEncrypt(). +address that was used in the call to httpConnect() or httpConnectEncrypt(), +or the address of the client for the connection from httpAcceptConnection(). Otherwise, return the FQDN for the local system using both gethostname() and gethostbyname() to get the local hostname with domain.

    +

     CUPS 2.0 httpGetKeepAlive

    +

    Get the current Keep-Alive state of the connection.

    +

    +http_keepalive_t httpGetKeepAlive (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Keep-Alive state

     DEPRECATED httpGetLength

    Get the amount of data remaining from the content-length or transfer-encoding fields.

    @@ -2234,7 +2371,7 @@ int httpGetLength (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Content length

    @@ -2253,7 +2390,7 @@ off_t httpGetLength2 (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Content length

    @@ -2261,6 +2398,51 @@ off_t httpGetLength2 (

    This function returns the complete content length, even for content larger than 2^31 - 1. +

    +

     CUPS 2.0 httpGetPending

    +

    Get the number of bytes that are buffered for writing.

    +

    +size_t httpGetPending (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Number of bytes buffered

    +

     CUPS 2.0 httpGetReady

    +

    Get the number of bytes that can be read without blocking.

    +

    +size_t httpGetReady (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Number of bytes available

    +

     CUPS 2.0 httpGetRemaining

    +

    Get the number of remaining bytes in the message +body or current chunk.

    +

    +size_t httpGetRemaining (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    Remaining bytes

    +

    Discussion

    +

    The httpIsChunked function can be used to determine whether the +message body is chunked or fixed-length. +

    httpGetState

    Get the current state of the HTTP request.

    @@ -2271,7 +2453,7 @@ content larger than 2^31 - 1.

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    HTTP state

    @@ -2284,7 +2466,7 @@ http_status_t httpGetStatus (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    HTTP status

    @@ -2300,7 +2482,7 @@ char *httpGetSubField (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    field
    Field index
    name
    @@ -2323,7 +2505,7 @@ char *httpGetSubField2 (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    field
    Field index
    name
    @@ -2344,7 +2526,7 @@ char *httpGetSubField2 (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Version number

    @@ -2363,7 +2545,7 @@ char *httpGets (
    length
    Max length of buffer
    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    Line or NULL

    @@ -2377,7 +2559,7 @@ int httpHead (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI for head
    @@ -2388,6 +2570,41 @@ int httpHead (
    default HTTP proxy (if any).

    void httpInitialize (void);

    +

     CUPS 2.0 httpIsChunked

    +

    Report whether a message body is chunked.

    +

    +int httpIsChunked (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    1 if chunked, 0 if not

    +

    Discussion

    +

    This function returns non-zero if the message body is composed of +variable-length chunks. + +

    +

     CUPS 2.0 httpIsEncrypted

    +

    Report whether a connection is encrypted.

    +

    +int httpIsEncrypted (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

    Return Value

    +

    1 if encrypted, 0 if not

    +

    Discussion

    +

    This function returns non-zero if the connection is currently encrypted. + +

    httpMD5

    Compute the MD5 sum of the username:group:password.

    @@ -2460,7 +2677,7 @@ int httpOptions (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI for options
    @@ -2477,7 +2694,7 @@ ssize_t httpPeek (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    buffer
    Buffer for data
    length
    @@ -2503,7 +2720,7 @@ int httpPost (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI for post
    @@ -2519,7 +2736,7 @@ int httpPut (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI to put
    @@ -2536,7 +2753,7 @@ int httpRead (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    buffer
    Buffer for data
    length
    @@ -2560,7 +2777,7 @@ ssize_t httpRead2 (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    buffer
    Buffer for data
    length
    @@ -2596,7 +2813,7 @@ int httpReconnect (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    0 on success, non-zero on failure

    @@ -2617,7 +2834,7 @@ int httpReconnect2 (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    msec
    Timeout in milliseconds
    cancel
    @@ -2625,6 +2842,26 @@ int httpReconnect2 (

    Return Value

    0 on success, non-zero on failure

    +

     CUPS 2.0 httpResolveHostname

    +

    Resolve the hostname of the HTTP connection +address.

    +

    +const char *httpResolveHostname (
    +    http_t *http,
    +    char *buffer,
    +    size_t bufsize
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    buffer
    +
    Hostname buffer
    +
    bufsize
    +
    Size of buffer
    +
    +

    Return Value

    +

    Resolved hostname or NULL

     DEPRECATED httpSeparate

    Separate a Universal Resource Identifier into its components.

    @@ -2755,7 +2992,7 @@ void httpSetAuthString (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    scheme
    Auth scheme (NULL to clear it)
    data
    @@ -2793,7 +3030,7 @@ int httpSetCredentials (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    credentials
    Array of credentials
    @@ -2810,7 +3047,7 @@ void httpSetDefaultField (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    field
    Field index
    value
    @@ -2831,7 +3068,7 @@ void httpSetExpect (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    expect
    HTTP status to expect (HTTP_STATUS_CONTINUE)
    @@ -2852,12 +3089,26 @@ void httpSetField (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    field
    Field index
    value
    Value
    +

     CUPS 2.0 httpSetKeepAlive

    +

    Set the current Keep-Alive state of a connection.

    +

    +void httpSetKeepAlive (
    +    http_t *http,
    +    http_keepalive_t keep_alive
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    keep_alive
    +
    New Keep-Alive value
    +

     CUPS 1.2/OS X 10.5 httpSetLength

    Set the content-length and content-encoding.

    @@ -2868,7 +3119,7 @@ void httpSetLength (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    length
    Length (0 for chunked)
    @@ -2884,7 +3135,7 @@ void httpSetTimeout (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    timeout
    Number of seconds for timeout, must be greater than 0
    @@ -2898,6 +3149,30 @@ must be greater than 0
    data pointer and must return 1 to continue or 0 to error (time) out.

    +

     CUPS 2.0 httpShutdown

    +

    Shutdown one side of an HTTP connection.

    +

    +void httpShutdown (
    +    http_t *http
    +);

    +

    Parameters

    +
    +
    http
    +
    HTTP connection
    +
    +

     CUPS 2.0 httpStateString

    +

    Return the string describing a HTTP state value.

    +

    +const char *httpStateString (
    +    http_state_t state
    +);

    +

    Parameters

    +
    +
    state
    +
    HTTP state value
    +
    +

    Return Value

    +

    State string

    httpStatus

    Return a short string describing a HTTP status code.

    @@ -2924,12 +3199,25 @@ int httpTrace (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    uri
    URI for trace

    Return Value

    Status of call (0 = success)

    +

     CUPS 2.0 httpURIStatusString

    +

    Return a string describing a URI status code.

    +

    +const char *httpURIStatusString (
    +    http_uri_status_t status
    +);

    +

    Parameters

    +
    +
    status
    +
    URI status code
    +
    +

    Return Value

    +

    Localized status string

    httpUpdate

    Update the current HTTP state for incoming data.

    @@ -2939,7 +3227,7 @@ http_status_t httpUpdate (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection

    Return Value

    HTTP status

    @@ -2953,7 +3241,7 @@ int httpWait (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    msec
    Milliseconds to wait
    @@ -2970,7 +3258,7 @@ int httpWrite (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    buffer
    Buffer for data
    length
    @@ -2994,7 +3282,7 @@ ssize_t httpWrite2 (

    Parameters

    http
    -
    Connection to server
    +
    HTTP connection
    buffer
    Buffer for data
    length
    @@ -5083,6 +5371,19 @@ the ippNew, ip The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.

    +

     CUPS 2.0 ippStateString

    +

    Return the name corresponding to a state value.

    +

    +const char *ippStateString (
    +    ipp_state_t state
    +);

    +

    Parameters

    +
    +
    state
    +
    State value
    +
    +

    Return Value

    +

    State name

     CUPS 1.4/OS X 10.6 ippTagString

    Return the tag name corresponding to a tag value.

    @@ -5784,6 +6085,8 @@ are server-oriented...

    Bind on top
    IPP_FINISHINGS_BOOKLET_MAKER
    Fold to make booklet
    +
    IPP_FINISHINGS_COAT
    +
    Apply protective liquid or powder coating
    IPP_FINISHINGS_COVER
    Add cover
    IPP_FINISHINGS_CUPS_FOLD_ACCORDIAN
    @@ -5876,6 +6179,8 @@ are server-oriented...

    Fold the paper vertically into three sections, forming a Z
    IPP_FINISHINGS_JOG_OFFSET
    Offset for binding (any type)
    +
    IPP_FINISHINGS_LAMINATE
    +
    Apply protective (solid) material
    IPP_FINISHINGS_NONE
    No finishing
    IPP_FINISHINGS_PUNCH
    @@ -5932,6 +6237,14 @@ are server-oriented...

    Staple top left corner
    IPP_FINISHINGS_STAPLE_TOP_RIGHT
    Staple top right corner
    +
    IPP_FINISHINGS_STAPLE_TRIPLE_BOTTOM
    +
    Three staples on bottom
    +
    IPP_FINISHINGS_STAPLE_TRIPLE_LEFT
    +
    Three staples on left
    +
    IPP_FINISHINGS_STAPLE_TRIPLE_RIGHT
    +
    Three staples on right
    +
    IPP_FINISHINGS_STAPLE_TRIPLE_TOP
    +
    Three staples on top
    IPP_FINISHINGS_TRIM
    Trim (any type)
    IPP_FINISHINGS_TRIM_AFTER_COPIES
    @@ -5986,10 +6299,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
    @@ -6073,6 +6386,8 @@ are server-oriented...

    IPP_ORIENT_LANDSCAPE
    90 degrees counter-clockwise
    +
    IPP_ORIENT_NONE
    +
    No rotation
    IPP_ORIENT_PORTRAIT
    No rotation
    IPP_ORIENT_REVERSE_LANDSCAPE
    diff --git a/doc/help/api-mime.html b/doc/help/api-mime.html index 226992780..dab2365fd 100644 --- a/doc/help/api-mime.html +++ b/doc/help/api-mime.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-overview.html b/doc/help/api-overview.html index a310f6e16..95c64e29a 100644 --- a/doc/help/api-overview.html +++ b/doc/help/api-overview.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html index 6530d4b9f..47c10386c 100644 --- a/doc/help/api-ppd.html +++ b/doc/help/api-ppd.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-ppdc.html b/doc/help/api-ppdc.html index 484288e68..63285b48e 100644 --- a/doc/help/api-ppdc.html +++ b/doc/help/api-ppdc.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/api-raster.html b/doc/help/api-raster.html index f2dade43c..859dde421 100644 --- a/doc/help/api-raster.html +++ b/doc/help/api-raster.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/postscript-driver.html b/doc/help/postscript-driver.html index fde5890be..0a3314b76 100644 --- a/doc/help/postscript-driver.html +++ b/doc/help/postscript-driver.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/ppd-compiler.html b/doc/help/ppd-compiler.html index 27decdbbb..2ef33fd28 100644 --- a/doc/help/ppd-compiler.html +++ b/doc/help/ppd-compiler.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/raster-driver.html b/doc/help/raster-driver.html index 0399f057c..40fc01d3e 100644 --- a/doc/help/raster-driver.html +++ b/doc/help/raster-driver.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } diff --git a/doc/help/spec-ppd.html b/doc/help/spec-ppd.html index 5853ede5f..894e0bf44 100644 --- a/doc/help/spec-ppd.html +++ b/doc/help/spec-ppd.html @@ -38,7 +38,7 @@ P.example { font-style: italic; margin-left: 36pt; } - + PRE.example { background: #eeeeee; border: dotted thin #999999; @@ -77,7 +77,7 @@ A:link:hover IMG { } A:link, A:visited { - font-weight: normal; + font-weight: inherit; text-decoration: none; } -- 2.39.2