margin-bottom: 0;
}
p code, li code, p.code, pre, ul.code li {
+ background: rgba(127,127,127,0.25);
+ border: thin dotted gray;
font-family: monospace;
hyphens: manual;
-webkit-hyphens: manual;
}
+p code, li code {
+ padding: 0 5px;
+}
p.code, pre, ul.code li {
- background: rgba(127,127,127,0.25);
- border: thin dotted gray;
padding: 10px;
page-break-inside: avoid;
}
a:link:hover, a:visited:hover, a:active {
color: #f06;
}
+ span.comment {
+ color: #7c7;
+ }
+ span.directive {
+ color: red;
+ }
+ span.number {
+ color: #c64;
+ }
+ span.reserved {
+ color: #77f;
+ }
+ span.string {
+ color: #f7f;
+ }
}
/* Show contents on left side in web browser */
@media screen and (min-width: 800px) {
<li><a href="#creating-an-ipp-request">Creating an IPP Request</a></li>
<li><a href="#sending-the-ipp-request">Sending the IPP Request</a></li>
<li><a href="#processing-the-ipp-response">Processing the IPP Response</a></li>
-<li><a href="#authentication">Authentication</a></li>
+</ul></li>
+<li><a href="#authentication-and-authorization">Authentication and Authorization</a><ul class="subcontents">
+<li><a href="#authentication-using-passwords">Authentication Using Passwords</a></li>
+<li><a href="#authorization-using-oauthopenid-connect">Authorization using OAuth/OpenID Connect</a></li>
</ul></li>
<li><a href="#ipp-data-file-api">IPP Data File API</a><ul class="subcontents">
<li><a href="#creating-an-ipp-data-file">Creating an IPP Data File</a></li>
<li><a href="#cupsOAuthCopyUserId">cupsOAuthCopyUserId</a></li>
<li><a href="#cupsOAuthGetAuthorizationCode">cupsOAuthGetAuthorizationCode</a></li>
<li><a href="#cupsOAuthGetClientId">cupsOAuthGetClientId</a></li>
+<li><a href="#cupsOAuthGetDeviceGrant">cupsOAuthGetDeviceGrant</a></li>
<li><a href="#cupsOAuthGetJWKS">cupsOAuthGetJWKS</a></li>
<li><a href="#cupsOAuthGetMetadata">cupsOAuthGetMetadata</a></li>
<li><a href="#cupsOAuthGetTokens">cupsOAuthGetTokens</a></li>
<p>Once you are done using the IPP response message, free it using the <a href="#ippDelete"><code>ippDelete</code></a> function:</p>
<pre><code class="language-c">ippDelete(response);
</code></pre>
-<h3 class="title" id="authentication">Authentication</h3>
-<p>CUPS normally handles authentication through the console. GUI applications should set a password callback using the <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> function:</p>
+<h2 class="title" id="authentication-and-authorization">Authentication and Authorization</h2>
+<p>CUPS supports authentication and authorization using HTTP Basic, HTTP Digest, peer credentials when communicating over domain sockets, and OAuth/OpenID Connect.</p>
+<p>Peer credential authorization happens automatically when connected over a domain socket. Other types of authentication requires the application to handle <code>HTTP_STATUS_UNAUTHORIZED</code> responses beyond simply calling <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a>.</p>
+<h3 class="title" id="authentication-using-passwords">Authentication Using Passwords</h3>
+<p>When you call <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a> and the HTTP server requires the "Basic" or "Digest" authentication schemes, CUPS normally requests a password from the console. GUI applications should set a password callback using the <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> function:</p>
+<pre><code class="language-c"><span class="reserved">void</span>
+cupsSetPasswordCB2(cups_password_cb2_t cb, <span class="reserved">void</span> *cb_data);
+</code></pre>
+<p>The password callback is called when needed and is responsible for setting the current user name using <a href="#cupsSetUser"><code>cupsSetUser</code></a> and returning a (password) string:</p>
+<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *
+cups_password_cb(<span class="reserved">const</span> <span class="reserved">char</span> *prompt, http_t *http,
+ <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *resource,
+ <span class="reserved">void</span> *cb_data);
+</code></pre>
+<p>The "prompt" argument is a string from CUPS that should be displayed to the user.</p>
+<p>The "http" argument is the connection hosting the request that is being authenticated. The password callback can call the <a href="#httpGetField"><code>httpGetField</code></a> and <a href="#httpGetSubField"><code>httpGetSubField</code></a> functions to look for additional details concerning the authentication challenge.</p>
+<p>The "method" argument specifies the HTTP method used for the request and is typically "GET", "POST", or "PUT".</p>
+<p>The "resource" argument specifies the path or URI used for the request.</p>
+<p>The "cb_data" argument provides the data pointer from the <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> call.</p>
+<h3 class="title" id="authorization-using-oauthopenid-connect">Authorization using OAuth/OpenID Connect</h3>
+<p>When you call <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a> and the HTTP server requires the "Bearer" authentication scheme, CUPS will call an OAuth callback that you register using the <a href="#cupsSetOAuthCB"><code>cupsSetOAuthCB</code></a> function:</p>
<pre><code class="language-c"><span class="reserved">void</span>
-cupsSetPasswordCB2(cups_password_cb2_t cb, <span class="reserved">void</span> *user_data);
+cupsSetOAuthCB(cups_oauth_cb_t cb, <span class="reserved">void</span> *cb_data);
</code></pre>
-<p>The password callback will be called when needed and is responsible for setting the current user name using <a href="#cupsSetUser"><code>cupsSetUser</code></a> and returning a string:</p>
+<p>The OAuth callback is called when needed and is responsible for performing any necessary authorization and returning an access token string:</p>
<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *
-cups_password_cb2(<span class="reserved">const</span> <span class="reserved">char</span> *prompt, http_t *http,
- <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *resource,
- <span class="reserved">void</span> *user_data);
+cups_oauth_cb(http_t *http, <span class="reserved">const</span> <span class="reserved">char</span> *realm, <span class="reserved">const</span> <span class="reserved">char</span> *scope,
+ <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">void</span> *cb_data);
+</code></pre>
+<p>The "http" argument is the connection hosting the request that is being authenticated. The OAuth callback can call the <a href="#httpGetField"><code>httpGetField</code></a> and <a href="#httpGetSubField"><code>httpGetSubField</code></a> functions to look for additional details concerning the authentication challenge.</p>
+<p>The "realm" and "scope" arguments provide the "realm" and "scope" parameters, if any, from the "WWW-Authenticate" header.</p>
+<p>The "resource" argument specifies the path or URI used for the request.</p>
+<p>The "cb_data" argument provides the data pointer from the <a href="#cupsSetOAuthCB"><code>cupsSetOAuthCB</code></a> call.</p>
+<h4 id="oauth-client-functions">OAuth Client Functions</h4>
+<p>CUPS provides a generic OAuth/OpenID client for authorizing access to printers and other network resources. The following functions are provided:</p>
+<ul>
+<li><p><a href="#cupsOAuthClearTokens"><code>cupsOAuthClearTokens</code></a>: Clear all cached tokens.</p>
+</li>
+<li><p><a href="#cupsOAuthCopyAccessToken"><code>cupsOAuthCopyAccessToken</code></a>: Copy the cached access token.</p>
+</li>
+<li><p><a href="#cupsOAuthCopyClientId"><code>cupsOAuthCopyClientId</code></a>: Copy the cached client ID.</p>
+</li>
+<li><p><a href="#cupsOAuthCopyRefreshToken"><code>cupsOAuthCopyRefreshToken</code></a>: Copy the cached refresh token.</p>
+</li>
+<li><p><a href="#cupsOAuthCopyUserId"><code>cupsOAuthCopyUserId</code></a>: Copy the cached user ID.</p>
+</li>
+<li><p><a href="#cupsOAuthGetAuthorizationCode"><code>cupsOAuthGetAuthorizationCode</code></a>: Get an authorization code using a web browser.</p>
+</li>
+<li><p><a href="#cupsOAuthGetClientId"><code>cupsOAuthGetClientId</code></a>: Get a client ID using dynamic client registration.</p>
+</li>
+<li><p><a href="#cupsOAuthGetDeviceGrant"><code>cupsOAuthGetDeviceGrant</code></a>: Get a device authorization grant code.</p>
+</li>
+<li><p><a href="#cupsOAuthGetJWKS"><code>cupsOAuthGetJWKS</code></a>: Get the key set for an authorization server.</p>
+</li>
+<li><p><a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>: Get the metadata for an authorization server.</p>
+</li>
+<li><p><a href="#cupsOAuthGetTokens"><code>cupsOAuthGetTokens</code></a>: Get access and refresh tokens for an authorization/grant code.</p>
+</li>
+<li><p><a href="#cupsOAuthGetUserId"><code>cupsOAuthGetUserId</code></a>: Get the user ID associated with an access token.</p>
+</li>
+<li><p><a href="#cupsOAuthMakeAuthorizationURL"><code>cupsOAuthMakeAuthorizationURL</code></a>: Make the URL for web browser authorization.</p>
+</li>
+<li><p><a href="#cupsOAuthMakeBase64Random"><code>cupsOAuthMakeBase64Random</code></a>: Make a Base64-encoded string of random bytes.</p>
+</li>
+<li><p><a href="#cupsOAuthSaveClientData"><code>cupsOAuthSaveClientData</code></a>: Save a client ID and secret for an authorization server.</p>
+</li>
+<li><p><a href="#cupsOAuthSaveTokens"><code>cupsOAuthSaveTokens</code></a>: Save access and refresh tokens for an authorization server.</p>
+</li>
+</ul>
+<p>Once you have an access token you use the <a href="#httpSetAuthString"><code>httpSetAuthString</code></a> function to use it for a HTTP connection:</p>
+<pre><code class="language-c">http_t *http;
+<span class="reserved">char</span> *access_token;
+
+httpSetAuthString(http, <span class="string">"Bearer"</span>, access_token);
+</code></pre>
+<h4 id="authorizing-using-a-web-browser">Authorizing Using a Web Browser</h4>
+<p>Users can authorize using their preferred web browser via the <a href="#cupsOAuthGetAuthorizationCode"><code>cupsOAuthGetAuthorizationCode</code></a> function, which returns an authorization grant code string. The following code gets the authorization server metadata, authorizes access through the web browser, and then obtains a HTTP Bearer access token:</p>
+<pre><code class="language-c">http_t *http; <span class="comment">// HTTP connection</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri; <span class="comment">// Base URL for Authorization Server</span>
+cups_json_t *metadata; <span class="comment">// Authorization Server metadata</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *printer_uri; <span class="comment">// Printer URI</span>
+<span class="reserved">char</span> *auth_code; <span class="comment">// Authorization grant code</span>
+<span class="reserved">char</span> *access_token; <span class="comment">// Access token</span>
+time_t access_expires; <span class="comment">// Date/time when access token expires</span>
+
+<span class="comment">// Get the metadata for the authorization server.</span>
+metadata = cupsOAuthGetMetadata(auth_uri);
+
+<span class="reserved">if</span> (metadata == NULL)
+{
+ <span class="comment">// Handle error getting metadata from authorization server.</span>
+}
+
+<span class="comment">// Bring up the web browser to authorize and get an authorization code.</span>
+auth_code = cupsOAuthGetAuthorizationCode(auth_uri, metadata, printer_uri,
+ <span class="comment">/*scopes*/</span>NULL,
+ <span class="comment">/*redirect_uri*/</span>NULL);
+
+<span class="reserved">if</span> (auth_code == NULL)
+{
+ <span class="comment">// Unable to authorize.</span>
+}
+
+<span class="comment">// Get the access code from the authorization code.</span>
+access_token = cupsOAuthGetTokens(auth_uri, metadata, printer_uri, auth_code,
+ CUPS_OGRANT_AUTHORIZATION_CODE,
+ <span class="comment">/*redirect_uri*/</span>NULL, &access_expires);
+
+<span class="reserved">if</span> (access_token == NULL)
+{
+ <span class="comment">// Unable to get access token.</span>
+}
+
+<span class="comment">// Set the Bearer token for authorization.</span>
+httpSetAuthString(http, <span class="string">"Bearer"</span>, access_token);
+free(access_token);
+</code></pre>
+<h4 id="authorizing-using-a-mobile-device">Authorizing Using a Mobile Device</h4>
+<p>Users can authorize using a mobile device via the <a href="#cupsOAuthGetDeviceGrant"><code>cupsOAuthGetDeviceGrant</code></a> function, which returns a JSON object with the mobile authorization URLs, user (verification) code string, and device grant code. The following code gets the authorization server metadata, gets the mobile device authorization information, and then obtains a HTTP Bearer access token:</p>
+<pre><code class="language-c">http_t *http; <span class="comment">// HTTP connection</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri; <span class="comment">// Base URL for Authorization Server</span>
+cups_json_t *metadata; <span class="comment">// Authorization Server metadata</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *printer_uri; <span class="comment">// Printer URI</span>
+cups_json_t *device_grant; <span class="comment">// Device authorization grant object</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *device_code; <span class="comment">// Device grant code</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *verify_url; <span class="comment">// Mobile device URL</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *verify_urlc; <span class="comment">// Mobile device URL with user code</span>
+<span class="reserved">const</span> <span class="reserved">char</span> *user_code; <span class="comment">// User code</span>
+<span class="reserved">char</span> *access_token; <span class="comment">// Access token</span>
+time_t access_expires; <span class="comment">// Date/time when access token expires</span>
+
+<span class="comment">// Get the metadata for the authorization server.</span>
+metadata = cupsOAuthGetMetadata(auth_uri);
+
+<span class="reserved">if</span> (metadata == NULL)
+{
+ <span class="comment">// Handle error getting metadata from authorization server.</span>
+}
+
+<span class="comment">// Get a device authorization grant for mobile authorization.</span>
+device_grant = cupsOAuthGetDeviceGrant(auth_uri, metadata, printer_uri,
+ <span class="comment">/*scopes*/</span>NULL);
+
+device_code = cupsJSONGetString(
+ cupsJSONFind(device_grant, CUPS_ODEVGRANT_DEVICE_CODE));
+verify_url = cupsJSONGetString(
+ cupsJSONFind(device_grant, CUPS_ODEVGRANT_VERIFICATION_URI));
+verify_urlc = cupsJSONGetString(
+ cupsJSONFind(device_grant, CUPS_ODEVGRANT_VERIFICATION_URI_COMPLETE));
+user_code = cupsJSONGetString(
+ cupsJSONFind(device_grant, CUPS_ODEVGRANT_USER_CODE));
+
+<span class="reserved">if</span> (device_code == NULL || verify_url == NULL || verify_urlc == NULL ||
+ user_code == NULL)
+{
+ <span class="comment">// Unable to authorize.</span>
+}
+
+<span class="comment">// Show the URLs and user code to the user (links and/or QR codes).</span>
+printf(<span class="string">"Open this URL: %s\n"</span>, verify_urlc);
+
+<span class="comment">// Get the access code from the authorization code.</span>
+<span class="reserved">do</span>
+{
+ <span class="comment">// Delay check for several seconds.</span>
+ sleep(<span class="number">5</span>);
+
+ <span class="comment">// Try getting an access token.</span>
+ access_token = cupsOAuthGetTokens(auth_uri, metadata, printer_uri, device_code,
+ CUPS_OGRANT_DEVICE_CODE,
+ <span class="comment">/*redirect_uri*/</span>NULL, &access_expires);
+}
+<span class="reserved">while</span> (access_token == NULL && access_expires > <span class="number">0</span>);
+ <span class="comment">// Continue checking until we have an access token or</span>
+ <span class="comment">// the device code has expired.</span>
+
+<span class="reserved">if</span> (access_token == NULL)
+{
+ <span class="comment">// Unable to get access token.</span>
+}
+
+<span class="comment">// Set the Bearer token for authorization.</span>
+httpSetAuthString(http, <span class="string">"Bearer"</span>, access_token);
+free(access_token);
</code></pre>
-<p>The <code>prompt</code> argument is a string from CUPS that should be displayed to the user.</p>
-<p>The <code>http</code> argument is the connection hosting the request that is being authenticated. The password callback can call the <a href="#httpGetField"><code>httpGetField</code></a> and <a href="#httpGetSubField"><code>httpGetSubField</code></a> functions to look for additional details concerning the authentication challenge.</p>
-<p>The <code>method</code> argument specifies the HTTP method used for the request and is typically "POST".</p>
-<p>The <code>resource</code> argument specifies the path used for the request.</p>
-<p>The <code>user_data</code> argument provides the user data pointer from the <code>cupsSetPasswordCB2</code> call.</p>
+<h4 id="supported-oauth-standards">Supported OAuth Standards</h4>
+<p>The following standards are supported:</p>
+<ul>
+<li><p><a href="https://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect Core v1.0</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc6749">RFC 6749: The OAuth 2.0 Authorization Framework</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc6750">RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc7591">RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc7636">RFC 7636: Proof Key for Code Exchange by OAuth Public Clients</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc8252">RFC 8252: OAuth 2.0 for Native Apps</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc8414">RFC 8414: OAuth 2.0 Authorization Server Metadata</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc8628">RFC 8628: OAuth 2.0 Device Authorization Grant</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc8693">RFC 8693: OAuth 2.0 Token Exchange</a></p>
+</li>
+<li><p><a href="https://datatracker.ietf.org/doc/html/rfc9068">RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens</a></p>
+</li>
+</ul>
<h2 class="title" id="ipp-data-file-api">IPP Data File API</h2>
<p>The IPP data file API provides functions to read and write IPP attributes and other commands or data using a common base format that supports tools such as <code>ipptool</code> and <code>ippeveprinter</code>.</p>
<h3 class="title" id="creating-an-ipp-data-file">Creating an IPP Data File</h3>
<td class="description">Resource path</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">0 on success, -1 on error</p>
+<p class="description"><code>0</code> on success, <code>-1</code> on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function should be called in response to a <code>HTTP_STATUS_UNAUTHORIZED</code>
-status, prior to resubmitting your request.
+<p class="discussion">This function performs authentication for a request. It should be called in
+response to a <code>HTTP_STATUS_UNAUTHORIZED</code> status, prior to resubmitting your
+request.
</p>
<h3 class="function"><a id="cupsDoFileRequest">cupsDoFileRequest</a></h3>
<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="cupsJSONNewKey">cupsJSONNewKey</a></h3>
<p class="description">Create a new JSON key node.</p>
<p class="code">
-<a href="#cups_json_t">cups_json_t</a> *cupsJSONNewKey(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
+<a href="#cups_json_t">cups_json_t</a> *cupsJSONNewKey(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <span class="reserved">const</span> <span class="reserved">char</span> *key);</p>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>parent</th>
<td class="description">Parent JSON node or <code>NULL</code> for a root node</td></tr>
<tr><th>after</th>
<td class="description">Previous sibling node or <code>NULL</code> to append to the end</td></tr>
-<tr><th>value</th>
+<tr><th>key</th>
<td class="description">Key string</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="discussion">This function performs a local/"native" OAuth authorization flow to obtain an
authorization code for use with the <a href="#cupsOAuthGetTokens"><code>cupsOAuthGetTokens</code></a> function.<br>
<br>
-The "auth_uri" parameter specifies the URI for the OAuth Authorization
-Server. The "metadata" parameter specifies the Authorization Server metadata
+The "auth_uri" argument specifies the URI for the OAuth Authorization
+Server. The "metadata" argument specifies the Authorization Server metadata
as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
<br>
-The "resource_uri" parameter specifies the URI for a resource (printer, web
+The "resource_uri" argument specifies the URI for a resource (printer, web
file, etc.) that you which to access.<br>
<br>
-The "scopes" parameter specifies zero or more whitespace-delimited scope
+The "scopes" argument specifies zero or more whitespace-delimited scope
names to request during authorization. The list of supported scope names are
available from the Authorization Server metadata, for example:
cups_json_t *scopes_supported = cupsJSONFind(metadata, "scopes_supported");
</pre>
-The "redirect_uri" parameter specifies a 'http:' URL with a listen address,
+The "redirect_uri" argument specifies a 'http:' URL with a listen address,
port, and path to use. If <code>NULL</code>, 127.0.0.1 on a random port is used with a
path of "/".<br>
<br>
<p class="discussion">This function registers a client application with the specified OAuth
Authorization Server.<br>
<br>
-The "auth_uri" parameter specifies the URI for the OAuth Authorization
-Server. The "metadata" parameter specifies the Authorization Server metadata
+The "auth_uri" argument specifies the URI for the OAuth Authorization
+Server. The "metadata" argument specifies the Authorization Server metadata
as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
<br>
<a href="#cupsOAuthGetAuthorizationCode"><code>cupsOAuthGetAuthorizationCode</code></a> function handles registration of
local/"native" applications for you.
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="cupsOAuthGetDeviceGrant">cupsOAuthGetDeviceGrant</a></h3>
+<p class="description">Get a device authorization grant for the specified resource and scope(s).</p>
+<p class="code">
+<a href="#cups_json_t">cups_json_t</a> *cupsOAuthGetDeviceGrant(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri, <span class="reserved">const</span> <span class="reserved">char</span> *scopes);</p>
+<h4 class="parameters">Parameters</h4>
+<table class="list"><tbody>
+<tr><th>auth_uri</th>
+<td class="description">Authorization Server URI</td></tr>
+<tr><th>metadata</th>
+<td class="description">Authorization Server metadata</td></tr>
+<tr><th>resource_uri</th>
+<td class="description">Resource URI</td></tr>
+<tr><th>scopes</th>
+<td class="description">Space-delimited scopes</td></tr>
+</tbody></table>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Grant data or <code>NULL</code> on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function requests a device authorization grant for the specified
+resource and scope(s). Device authorization grants allow a user to open a
+web page on any device to authorize access to the resource.<br>
+<br>
+The "auth_uri" argument specifies the URI for the OAuth Authorization
+Server. The "metadata" argument specifies the Authorization Server metadata
+as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
+<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
+<br>
+The "resource_uri" argument specifies the URI for a resource (printer, web
+file, etc.) that you which to access.<br>
+<br>
+The "scopes" argument specifies zero or more whitespace-delimited scope
+names to request during authorization. The list of supported scope names are
+available from the Authorization Server metadata, for example:
+
+<pre>
+cups_json_t *metadata = cupsOAuthGetMetadata(auth_uri);
+cups_json_t *scopes_supported = cupsJSONFind(metadata, "scopes_supported");
+</pre>
+
+The returned JSON object must be freed using the <a href="#cupsJSONDelete"><code>cupsJSONDelete</code></a>
+function and contains the following information:
+
+</p><ul>
+<li><code>CUPS_ODEVGRANT_DEVICE_CODE</code>: The device code string to be used in
+ subsequent <a href="#cupsOAuthGetTokens"><code>cupsOAuthGetTokens</code></a> calls.
+</li>
+<li><code>CUPS_ODEVGRANT_EXPIRES_IN</code>: The expiration date/time as a number of
+ seconds since the Unix epoch.
+</li>
+<li><code>CUPS_ODEVGRANT_INTERVAL</code>: The number of seconds to wait between calls to
+ <a href="#cupsOAuthGetTokens"><code>cupsOAuthGetTokens</code></a>.
+</li>
+<li><code>CUPS_ODEVGRANT_USER_CODE</code>: The user code to enter on the verification
+ web page.
+</li>
+<li><code>CUPS_ODEVGRANT_VERIFICATION_URL</code>: The URL for the verification web page.
+</li>
+<li><code>CUPS_ODEVGRANT_VERIFICATION_URL_COMPLETE</code>: The URL for the verification
+ web page with the user code filled in.</li>
+</ul>
+<p class="discussion">The values can be obtained using the <a href="#cupsJSONFind"><code>cupsJSONFind</code></a>,
+@cupsJSONGetNumber@, and @cupsJSONGetString@ functions, for example:
+
+<pre>
+cups_json_t *grant = cupsOAuthGetDeviceGrant(...);
+
+const char *verification_url = cupsJSONGetString(cupsJSONFind(grant, CUPS_ODEVGRANT_VERIFICATION_URL));
+double interval = cupsJSONGetNumber(cupsJSONFind(grant, CUPS_ODEVGRANT_INTERVAL));
+</pre>
+
</p>
<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="cupsOAuthGetJWKS">cupsOAuthGetJWKS</a></h3>
<p class="description">Get the JWT key set for an Authorization Server.</p>
<tr><th>resource_uri</th>
<td class="description">Resource URI</td></tr>
<tr><th>grant_code</th>
-<td class="description">Authorization code or refresh token</td></tr>
+<td class="description">Authorization code, device code, or refresh token</td></tr>
<tr><th>grant_type</th>
<td class="description">Grant code type</td></tr>
<tr><th>redirect_uri</th>
-<td class="description">Redirect URI</td></tr>
+<td class="description">Redirect URI or <code>NULL</code> for device grants</td></tr>
<tr><th>access_expires</th>
<td class="description">Expiration time for access token</td></tr>
</tbody></table>
Server. OpenID Authorization Servers also provide user identification
information.<br>
<br>
-The "auth_uri" parameter specifies the URI for the OAuth Authorization
-Server. The "metadata" parameter specifies the Authorization Server metadata
+The "auth_uri" argument specifies the URI for the OAuth Authorization
+Server. The "metadata" argument specifies the Authorization Server metadata
as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
<br>
-The "resource_uri" parameter specifies the URI for a resource (printer, web
+The "resource_uri" argument specifies the URI for a resource (printer, web
file, etc.) that you which to access.<br>
<br>
-The "grant_code" parameter specifies the code or token to use while the
-"grant_type" parameter specifies the type of code:
+The "grant_code" argument specifies the code or token to use while the
+"grant_type" argument specifies the type of code:
</p><ul>
<li><code>CUPS_OGRANT_AUTHORIZATION_CODE</code>: A user authorization grant code.
access token must be freed using the <code>free</code> function. The new refresh token
and any user ID information can be obtained using the
<a href="#cupsOAuthCopyRefreshToken"><code>cupsOAuthCopyRefreshToken</code></a> and <a href="#cupsOAuthCopyUserId"><code>cupsOAuthCopyUserId</code></a> functions
-respectively.
+respectively.<br>
+<br>
+When authorizing using a device code (<code>CUPS_OGRANT_DEVICE_CODE</code>) and a device
+access token is not yet ready, a <code>NULL</code> access token is returned with the
+expiration time set to the next recommended query time. If the
+"access_expires" value is set to <code>0</code> then the device authorization failed.
</p>
<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="cupsOAuthGetUserId">cupsOAuthGetUserId</a></h3>
<p class="discussion">This function makes an authorization URL for the specified authorization
server and resource.<br>
<br>
-The "auth_uri" parameter specifies the URI for the OAuth Authorization
-Server. The "metadata" parameter specifies the Authorization Server metadata
+The "auth_uri" argument specifies the URI for the OAuth Authorization
+Server. The "metadata" argument specifies the Authorization Server metadata
as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
<br>
-The "resource_uri" parameter specifies the URI for a resource (printer, web
+The "resource_uri" argument specifies the URI for a resource (printer, web
file, etc.) that you which to access.<br>
<br>
-The "scopes" parameter specifies zero or more whitespace-delimited scope
+The "scopes" argument specifies zero or more whitespace-delimited scope
names to request during authorization. The list of supported scope names are
available from the Authorization Server metadata, for example:
cups_json_t *scopes_supported = cupsJSONFind(metadata, "scopes_supported");
</pre>
-The "client_id" parameter specifies the client identifier obtained using
+The "client_id" argument specifies the client identifier obtained using
<a href="#cupsOAuthCopyClientId"><code>cupsOAuthCopyClientId</code></a> and/or <a href="#cupsOAuthGetClientId"><code>cupsOAuthGetClientId</code></a>.<br>
<br>
-The "client_id" parameter is the string returned by
+The "client_id" argument is the string returned by
<a href="#cupsOAuthCopyClientId"><code>cupsOAuthCopyClientId</code></a> or <a href="#cupsOAuthGetClientId"><code>cupsOAuthGetClientId</code></a>.<br>
<br>
-The "code_verifier" parameter specifies a random Base64URL-encoded string
+The "code_verifier" argument specifies a random Base64URL-encoded string
that is used by the Proof Key for Code Exchange [RFC7636] extension to help
secure the authorization flow. The <a href="#cupsOAuthMakeBase64Random"><code>cupsOAuthMakeBase64Random</code></a> function
can be used to generate this string.<br>
<br>
-The "nonce" parameter specifies a random Base64URL-encoded string that is
+The "nonce" argument specifies a random Base64URL-encoded string that is
used by OpenID to validate the ID token. The <a href="#cupsOAuthMakeBase64Random"><code>cupsOAuthMakeBase64Random</code></a>
function can be used to generate this string.<br>
<br>
-The "redirect_uri" parameter specifies the URI that will receive the
+The "redirect_uri" argument specifies the URI that will receive the
authorization grant code.<br>
<br>
-The "state" parameter is a unique (random) identifier for the authorization
+The "state" argument is a unique (random) identifier for the authorization
request. It is provided to the redirection URI as a form parameter.
</p>
<h3 class="function"><span class="info"> CUPS 2.4 </span><a id="cupsSetOAuthCB">cupsSetOAuthCB</a></h3>
<p class="description">Set the OAuth 2.0 callback for CUPS.</p>
<p class="code">
-<span class="reserved">void</span> cupsSetOAuthCB(<a href="#cups_oauth_cb_t">cups_oauth_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
+<span class="reserved">void</span> cupsSetOAuthCB(<a href="#cups_oauth_cb_t">cups_oauth_cb_t</a> cb, <span class="reserved">void</span> *cb_data);</p>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>cb</th>
<td class="description">Callback function</td></tr>
-<tr><th>user_data</th>
-<td class="description">User data pointer</td></tr>
+<tr><th>cb_data</th>
+<td class="description">Callback data pointer</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the OAuth 2.0 callback for the various CUPS APIs that
-send HTTP requests. Pass <code>NULL</code> to restore the default (console-based)
-callback.<br>
+send HTTP requests. Pass <code>NULL</code> to disable OAuth authorization.<br>
<br>
The OAuth callback receives the HTTP connection, realm name, scope name (if
any), resource path, and the "user_data" pointer for each request that
<h3 class="function"><span class="info"> CUPS 1.4 </span><a id="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
<p class="description">Set the advanced password callback for CUPS.</p>
<p class="code">
-<span class="reserved">void</span> cupsSetPasswordCB2(<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb, <span class="reserved">void</span> *user_data);</p>
+<span class="reserved">void</span> cupsSetPasswordCB2(<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb, <span class="reserved">void</span> *cb_data);</p>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>cb</th>
<td class="description">Callback function</td></tr>
-<tr><th>user_data</th>
-<td class="description">User data pointer</td></tr>
+<tr><th>cb_data</th>
+<td class="description">Callback data pointer</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
<p class="description">Encoded string</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function encodes a Base64 string as defined by RFC 4648. The "url"
-parameter controls whether the original Base64 ("url" = <code>false</code>) or the
+argument controls whether the original Base64 ("url" = <code>false</code>) or the
Base64url ("url" = <code>true</code>) alphabet is used.
</p>
<tr><th>http</th>
<td class="description">HTTP connection</td></tr>
<tr><th>buffer</th>
-<td class="description">Hostname buffer</td></tr>
+<td class="description">Hostname buffer or <code>NULL</code> to use HTTP buffer</td></tr>
<tr><th>bufsize</th>
<td class="description">Size of buffer</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function resolves a DNS-SD URI of the form
"scheme://service-instance-name._protocol._tcp.domain/...". The "options"
-parameter specifies a bitfield of resolution options including:
+argument specifies a bitfield of resolution options including:
</p><ul>
<li><code>HTTP_RESOLVE_DEFAULT</code>: Use default options
</li>
<li><code>HTTP_RESOLVE_FAXOUT</code>: Resolve the FaxOut service instead of Print (IPP/IPPS)</li>
</ul>
-<p class="discussion">The "cb" parameter specifies a callback that allows resolution to be
+<p class="discussion">The "cb" argument specifies a callback that allows resolution to be
terminated. The callback is provided the "cb_data" value and returns a
<code>bool</code> value that is <code>true</code> to continue and <code>false</code> to stop. If no callback
is specified ("cb" is <code>NULL</code>), then this function will block up to 90 seconds
<h4 class="returnvalue">Return Value</h4>
<p class="description">Localized status string</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The returned string is localized to the current POSIX locale and is based
-on the status strings defined in RFC 7231.
+<p class="discussion">This function returns a short (localized) string describing a HTTP status
+code. The strings are taken from the IANA HTTP Status Code registry.
</p>
<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpURIStatusString">httpURIStatusString</a></h3>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Localized status string</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns a short (localized) string describing a URI status
+value.
+
+</p>
<h3 class="function"><a id="httpUpdate">httpUpdate</a></h3>
<p class="description">Update the current HTTP state for incoming data.</p>
<p class="code">
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
-(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
+(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
+<br>
+The "name" argument specifies the name of the attribute, while the "value"
+argument provides an IPP message containing the collection member attributes.<br>
+<br>
+</p><blockquote>
+<strong>Note:</strong> You must call the <a href="#ippDelete"><code>ippDelete</code></a> function on the "value"
+argument to make sure the memory used by the value is released.</blockquote>
</p>
<h3 class="function"><span class="info"> CUPS 1.1.19 </span><a id="ippAddCollections">ippAddCollections</a></h3>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
-(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
+(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
+<br>
+The "name" argument specifies the name of the attribute, while the
+"num_values" and "values" arguments provide IPP messages containing the
+collection member attributes for each value.<br>
+<br>
+</p><blockquote>
+<strong>Note:</strong> You must call the <a href="#ippDelete"><code>ippDelete</code></a> function on each of the
+"values" arguments to make sure the memory used by the value is released.</blockquote>
</p>
<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippAddCredentialsString">ippAddCredentialsString</a></h3>
<p class="discussion">This function adds a 1setOf text attribute to an IPP message corresponding to
the specified credentials string.<br>
<br>
-The "ipp" parameter refers to an IPP message previously created using
+The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function adds an integer or enum attribute to an IPP message.<br>
<br>
-The "ipp" parameter refers to an IPP message previously created using
+The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
<br>
-The "lower" parameter must be less than or equal to the "upper" parameter.</p>
+The "lower" argument must be less than or equal to the "upper" argument.</p>
<h3 class="function"><a id="ippAddRanges">ippAddRanges</a></h3>
<p class="description">Add ranges of values to an IPP message.</p>
<p class="code">
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.</p>
<h3 class="function"><a id="ippAddString">ippAddString</a></h3>
<p class="description">Add a language-encoded string to an IPP message.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
(`IPP_TAG_URISCHEME`).
-The "language" parameter must be non-`NULL` for nameWithLanguage and
+The "language" argument must be non-`NULL` for nameWithLanguage and
textWithLanguage string values and must be `NULL` for all other string values.</code></p>
<h3 class="function"><span class="info"> CUPS 1.7 </span><a id="ippAddStringf">ippAddStringf</a></h3>
<p class="description">Add a formatted string to an IPP message.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document
(<code>IPP_TAG_DOCUMENT</code>), event notification
(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>),
(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
(`IPP_TAG_URISCHEME`).
-The "language" parameter must be non-`NULL` for nameWithLanguage
+The "language" argument must be non-`NULL` for nameWithLanguage
and textWithLanguage string values and must be `NULL` for all other
string values.
-The "format" parameter uses formatting characters compatible with the
+The "format" argument uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document
(<code>IPP_TAG_DOCUMENT</code>), event notification
(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>),
(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
(`IPP_TAG_URISCHEME`).
-The "language" parameter must be non-`NULL` for nameWithLanguage
+The "language" argument must be non-`NULL` for nameWithLanguage
and textWithLanguage string values and must be `NULL` for all other
string values.
-The "format" parameter uses formatting characters compatible with the
+The "format" argument uses formatting characters compatible with the
printf family of standard functions. Additional arguments are passed in the
stdarg pointer "ap". The formatted string is truncated as needed to the
maximum length of the corresponding value type.
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
(`IPP_TAG_URISCHEME`).
-The "language" parameter must be non-`NULL` for nameWithLanguage and
+The "language" argument must be non-`NULL` for nameWithLanguage and
textWithLanguage string values and must be `NULL` for all other string values.</code></p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippAttributeString">ippAttributeString</a></h3>
<p class="description">Convert the attribute's value to a string.</p>
<tr><th>attr</th>
<td class="description">Attribute</td></tr>
<tr><th>buffer</th>
-<td class="description">String buffer or NULL</td></tr>
+<td class="description">String buffer or <code>NULL</code></td></tr>
<tr><th>bufsize</th>
<td class="description">Size of string buffer</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Number of bytes less nul</p>
+<p class="description">Number of bytes less <code>nul</code></p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Returns the number of bytes that would be written, not including the
-trailing nul. The buffer pointer can be NULL to get the required length,
-just like (v)snprintf.
+<p class="discussion">This function converts an attribute's values into a string and returns the
+number of bytes that would be written, not including the trailing <code>nul</code>. The
+buffer pointer can be NULL to get the required length, just like
+<code>(v)snprintf</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.7 </span><a id="ippContainsInteger">ippContainsInteger</a></h3>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on a match, 0 on no match</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Returns non-zero when the attribute contains either a matching integer or
-enum value, or the value falls within one of the rangeOfInteger values for
-the attribute.
+<p class="discussion">This function returns non-zero when the attribute contains either a matching
+integer or enum value, or the value falls within one of the rangeOfInteger
+values for the attribute.
</p>
<h3 class="function"><span class="info"> CUPS 1.7 </span><a id="ippContainsString">ippContainsString</a></h3>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on a match, 0 on no match</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Returns non-zero when the attribute contains a matching charset, keyword,
-naturalLanguage, mimeMediaType, name, text, uri, or uriScheme value.
+<p class="discussion">This function returns non-zero when the attribute contains a matching
+charset, keyword, naturalLanguage, mimeMediaType, name, text, uri, or
+uriScheme value.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippCopyAttribute">ippCopyAttribute</a></h3>
<tr><th>srcattr</th>
<td class="description">Attribute to copy</td></tr>
<tr><th>quickcopy</th>
-<td class="description">1 for a referenced copy, 0 for normal</td></tr>
+<td class="description"><code>1</code> for a referenced copy, <code>0</code> for a new copy</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New attribute</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The specified attribute, <code>attr</code>, is copied to the destination IPP message.
-When "quickcopy" is non-zero, a "shallow" reference copy of the attribute is
-created - this should only be done as long as the original source IPP message will
-not be freed for the life of the destination.
+<p class="discussion">This function copies an attribute to another IPP message. When "quickcopy"
+is non-zero, a shallow reference copy of the attribute is created - this
+should only be done as long as the original source IPP message will not be
+freed for the life of the destination.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippCopyAttributes">ippCopyAttributes</a></h3>
<p class="description">Copy attributes from one IPP message to another.</p>
<p class="code">
-<span class="reserved">int</span> ippCopyAttributes(<a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_t">ipp_t</a> *src, <span class="reserved">int</span> quickcopy, <a href="#ipp_copy_cb_t">ipp_copy_cb_t</a> cb, <span class="reserved">void</span> *context);</p>
+<span class="reserved">int</span> ippCopyAttributes(<a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_t">ipp_t</a> *src, <span class="reserved">int</span> quickcopy, <a href="#ipp_copy_cb_t">ipp_copy_cb_t</a> cb, <span class="reserved">void</span> *cb_data);</p>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>dst</th>
<tr><th>src</th>
<td class="description">Source IPP message</td></tr>
<tr><th>quickcopy</th>
-<td class="description">1 for a referenced copy, 0 for normal</td></tr>
+<td class="description"><code>1</code> for a referenced copy, <code>0</code> for normal</td></tr>
<tr><th>cb</th>
<td class="description">Copy callback or <code>NULL</code> for none</td></tr>
-<tr><th>context</th>
-<td class="description">Context pointer</td></tr>
+<tr><th>cb_data</th>
+<td class="description">Callback data pointer</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on error</p>
+<p class="description"><code>1</code> on success, <code>0</code> on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Zero or more attributes are copied from the source IPP message "src" to the
-destination IPP message "dst". When "quickcopy" is non-zero, a "shallow"
-reference copy of the attribute is created - this should only be done as long
-as the original source IPP message will not be freed for the life of the
+<p class="discussion">This function copies zero or more attributes from the source to the
+destination IPP message. When "quickcopy" is non-zero, a shallow reference
+copy of the attribute is created - this should only be done as long as the
+original source IPP message will not be freed for the life of the
destination.<br>
<br>
-The "cb" and "context" parameters provide a generic way to "filter" the
-attributes that are copied - the function must return 1 to copy the attribute or
-0 to skip it. The function may also choose to do a partial copy of the source attribute
-itself.
+The "cb" and "cb_data" arguments provide a generic way to "filter" the
+attributes that are copied - the function must return <code>1</code> to copy the
+attribute or <code>0</code> to skip it. The function may also choose to do a
+partial copy of the source attribute itself and return <code>0</code> to tell this
+function to skip it.
</p>
<h3 class="function"><a id="ippCopyCredentialsString">ippCopyCredentialsString</a></h3>
registered values are supported in addition to the CUPS IPP extension
attributes.<br>
<br>
-The <code>request</code> parameter specifies the request message that was read from
-the client.
-
+The "request" argument specifies the request message that was read from
+the client.<br>
+<br>
<code>NULL</code> is returned if all attributes should be returned. Otherwise, the
-result is a sorted array of attribute names, where <code>cupsArrayFind(array,
-"attribute-name")</code> will return a non-NULL pointer. The array must be freed
-using the <code>cupsArrayDelete</code> function.
+result is a sorted array of attribute names, where
+<code>cupsArrayFind(array, "attribute-name")</code> will return a non-<code>NULL</code> pointer.
+The array must be freed using <a href="#cupsArrayDelete"><code>cupsArrayDelete</code></a>.
</p>
<h3 class="function"><a id="ippDateToTime">ippDateToTime</a></h3>
<tr><th>attr</th>
<td class="description">Attribute</td></tr>
<tr><th>element</th>
-<td class="description">Index of first value to delete (0-based)</td></tr>
+<td class="description">Index of first value to delete (<code>0</code>-based)</td></tr>
<tr><th>count</th>
<td class="description">Number of values to delete</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function deletes one or more values in an attribute. The "element"
-parameter specifies the first value to delete, starting at 0. It must be
+argument specifies the first value to delete, starting at <code>0</code>. It must be
less than the number of values returned by <a href="#ippGetCount"><code>ippGetCount</code></a>.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value,
+The "attr" argument may be modified as a result of setting the value,
which will set the variable to <code>NULL</code>.<br>
<br>
Deleting all values in an attribute deletes the attribute.
<td class="description">Enum string</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Enum value or -1 if unknown</p>
+<p class="description">Enum value or <code>-1</code> if unknown</p>
<h3 class="function"><a id="ippErrorString">ippErrorString</a></h3>
<p class="description">Return a name for the given status code.</p>
<p class="code">
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">IPP status code</p>
-<h3 class="function"><a id="ippFileClose">ippFileClose</a></h3>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileClose">ippFileClose</a></h3>
<p class="description">Close an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileClose(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function closes the current IPP data file. The <code>ipp_file_t</code> object can
-be reused for another file as needed.</p>
-<h3 class="function"><a id="ippFileDelete">ippFileDelete</a></h3>
+be reused for another file as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileDelete">ippFileDelete</a></h3>
<p class="description">Close an IPP data file and free all memory.</p>
<p class="code">
<span class="reserved">bool</span> ippFileDelete(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function closes an IPP data file, if necessary, and frees all memory
-associated with it.</p>
-<h3 class="function"><a id="ippFileExpandVars">ippFileExpandVars</a></h3>
+associated with it.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileExpandVars">ippFileExpandVars</a></h3>
<p class="description">Expand IPP data file and environment variables in a string.</p>
<p class="code">
size_t ippFileExpandVars(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">char</span> *dst, <span class="reserved">const</span> <span class="reserved">char</span> *src, size_t dstsize);</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function expands IPP data file variables of the form "$name" and
environment variables of the form "$ENV[name]" in the source string to the
-destination string. The</p>
-<h3 class="function"><a id="ippFileGetAttribute">ippFileGetAttribute</a></h3>
+destination string. The
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileGetAttribute">ippFileGetAttribute</a></h3>
<p class="description">Get a single named attribute from an IPP data file.</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFileGetAttribute(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name, ipp_tag_t value_tag);</p>
<p class="discussion">This function finds the first occurence of a named attribute in the current
IPP attributes in the specified data file. Unlike
<a href="#ippFileGetAttributes"><code>ippFileGetAttributes</code></a>, this function does not clear the attribute
-state.</p>
-<h3 class="function"><a id="ippFileGetAttributes">ippFileGetAttributes</a></h3>
+state.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileGetAttributes">ippFileGetAttributes</a></h3>
<p class="description">Get the current set of attributes from an IPP data file.</p>
<p class="code">
<a href="#ipp_t">ipp_t</a> *ippFileGetAttributes(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">IPP attributes</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function gets the current set of attributes from an IPP data file.</p>
-<h3 class="function"><a id="ippFileGetFilename">ippFileGetFilename</a></h3>
+<p class="discussion">This function gets the current set of attributes from an IPP data file.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileGetFilename">ippFileGetFilename</a></h3>
<p class="description">Get the filename for an IPP data file.</p>
<p class="code">
<span class="reserved">const</span> <span class="reserved">char</span> *ippFileGetFilename(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Filename</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function returns the filename associated with an IPP data file.</p>
-<h3 class="function"><a id="ippFileGetLineNumber">ippFileGetLineNumber</a></h3>
+<p class="discussion">This function returns the filename associated with an IPP data file.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileGetLineNumber">ippFileGetLineNumber</a></h3>
<p class="description">Get the current line number in an IPP data file.</p>
<p class="code">
<span class="reserved">int</span> ippFileGetLineNumber(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Line number</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function returns the current line number in an IPP data file.</p>
-<h3 class="function"><a id="ippFileGetVar">ippFileGetVar</a></h3>
+<p class="discussion">This function returns the current line number in an IPP data file.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileGetVar">ippFileGetVar</a></h3>
<p class="description">Get the value of an IPP data file variable.</p>
<p class="code">
<span class="reserved">const</span> <span class="reserved">char</span> *ippFileGetVar(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
<p class="description">Variable value or <code>NULL</code> if none.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns the value of an IPP data file variable. <code>NULL</code> is
-returned if the variable is not set.</p>
-<h3 class="function"><a id="ippFileNew">ippFileNew</a></h3>
-<p class="description">Create a new IPP data file object for reading or writing.</p>
+returned if the variable is not set.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileNew">ippFileNew</a></h3>
+<p class="description">Create a new IPP data file object in preparation for reading or writing.</p>
<p class="code">
<a href="#ipp_file_t">ipp_file_t</a> *ippFileNew(<a href="#ipp_file_t">ipp_file_t</a> *parent, <a href="#ipp_fattr_cb_t">ipp_fattr_cb_t</a> attr_cb, <a href="#ipp_ferror_cb_t">ipp_ferror_cb_t</a> error_cb, <span class="reserved">void</span> *cb_data);</p>
<h4 class="parameters">Parameters</h4>
<h4 class="returnvalue">Return Value</h4>
<p class="description">IPP data file</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function opens an IPP data file for reading (mode="r") or writing
-(mode="w"). If the "parent" argument is not <code>NULL</code>, all variables from the
-parent data file are copied to the new file.</p>
-<h3 class="function"><a id="ippFileOpen">ippFileOpen</a></h3>
+<p class="discussion">This function creates a new IPP data file object. If the "parent" argument
+is not <code>NULL</code>, all variables from the parent data file are copied to the new
+object.<br>
+<br>
+Call the <a href="#ippFileOpen"><code>ippFileOpen</code></a> function to open the IPP data file.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileOpen">ippFileOpen</a></h3>
<p class="description">Open an IPP data file for reading or writing.</p>
<p class="code">
<span class="reserved">bool</span> ippFileOpen(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *filename, <span class="reserved">const</span> <span class="reserved">char</span> *mode);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function opens an IPP data file for reading (mode="r") or writing
-(mode="w"). If the "parent" argument is not <code>NULL</code>, all variables from the
-parent data file are copied to the new file.</p>
-<h3 class="function"><a id="ippFileRead">ippFileRead</a></h3>
+<p class="discussion">This function opens the IPP data file specified by the "filename" argument
+for reading ("mode" is "r") or writing ("mode" is "w").
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileRead">ippFileRead</a></h3>
<p class="description">Read an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileRead(<a href="#ipp_file_t">ipp_file_t</a> *file, <a href="#ipp_ftoken_cb_t">ipp_ftoken_cb_t</a> token_cb, <span class="reserved">bool</span> with_groups);</p>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
-<h3 class="function"><a id="ippFileReadCollection">ippFileReadCollection</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function reads tokens from an IPP data file, processes standard
+directives that define attributes and values, and passes on unknown tokens
+to the token callback "token_cb" for processing.<br>
+<br>
+If the "with_groups" argument is <code>true</code> then the "GROUP" directive will be
+supported for specifying the attribute group(s) associated with any
+defined attributes.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileReadCollection">ippFileReadCollection</a></h3>
<p class="description">Read a collection from an IPP data file.</p>
<p class="code">
<a href="#ipp_t">ipp_t</a> *ippFileReadCollection(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function reads a collection value from an IPP data file. Collection
values are surrounded by curly braces ("{" and "}") and have "MEMBER"
-directives to define member attributes in the collection.</p>
-<h3 class="function"><a id="ippFileReadToken">ippFileReadToken</a></h3>
+directives to define member attributes in the collection.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileReadToken">ippFileReadToken</a></h3>
<p class="description">Read a token from an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileReadToken(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">char</span> *token, size_t tokensize);</p>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function reads a single token or value from an IPP data file, skipping
-comments and whitespace as needed.</p>
-<h3 class="function"><a id="ippFileRestorePosition">ippFileRestorePosition</a></h3>
+comments and whitespace as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileRestorePosition">ippFileRestorePosition</a></h3>
<p class="description">Restore the previous position in an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileRestorePosition(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function restores the previous position in an IPP data file that is open
-for reading.</p>
-<h3 class="function"><a id="ippFileSavePosition">ippFileSavePosition</a></h3>
+for reading.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileSavePosition">ippFileSavePosition</a></h3>
<p class="description">Save the current position in an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileSavePosition(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function saves the current position in an IPP data file that is open
-for reading.</p>
-<h3 class="function"><a id="ippFileSetAttributes">ippFileSetAttributes</a></h3>
+for reading.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileSetAttributes">ippFileSetAttributes</a></h3>
<p class="description">Set the attributes for an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileSetAttributes(<a href="#ipp_file_t">ipp_file_t</a> *file, <a href="#ipp_t">ipp_t</a> *attrs);</p>
<p class="description"><code>true</code> on success, <code>false</code> otherwise</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the current set of attributes for an IPP data file,
-typically an empty collection created with <a href="#ippNew"><code>ippNew</code></a>.</p>
-<h3 class="function"><a id="ippFileSetGroupTag">ippFileSetGroupTag</a></h3>
+typically an empty collection created with <a href="#ippNew"><code>ippNew</code></a>.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileSetGroupTag">ippFileSetGroupTag</a></h3>
<p class="description">Set the group tag for an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileSetGroupTag(<a href="#ipp_file_t">ipp_file_t</a> *file, ipp_tag_t group_tag);</p>
<p class="description"><code>true</code> on success, <code>false</code> otherwise</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the group tag associated with attributes that are read
-from an IPP data file.</p>
-<h3 class="function"><a id="ippFileSetVar">ippFileSetVar</a></h3>
+from an IPP data file.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileSetVar">ippFileSetVar</a></h3>
<p class="description">Set an IPP data file variable to a constant value.</p>
<p class="code">
<span class="reserved">bool</span> ippFileSetVar(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets an IPP data file variable to a constant value. Setting
the "uri" variable also initializes the "scheme", "uriuser", "hostname",
-"port", and "resource" variables.</p>
-<h3 class="function"><a id="ippFileSetVarf">ippFileSetVarf</a></h3>
+"port", and "resource" variables.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileSetVarf">ippFileSetVarf</a></h3>
<p class="description">Set an IPP data file variable to a formatted value.</p>
<p class="code">
<span class="reserved">bool</span> ippFileSetVarf(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *value, ...);</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets an IPP data file variable to a formatted value. Setting
the "uri" variable also initializes the "scheme", "uriuser", "hostname",
-"port", and "resource" variables.</p>
-<h3 class="function"><a id="ippFileWriteAttributes">ippFileWriteAttributes</a></h3>
+"port", and "resource" variables.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileWriteAttributes">ippFileWriteAttributes</a></h3>
<p class="description">Write an IPP message to an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileWriteAttributes(<a href="#ipp_file_t">ipp_file_t</a> *file, <a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">bool</span> with_groups);</p>
<p class="discussion">This function writes an IPP message to an IPP data file using the attribute
filter specified in the call to <a href="#ippFileOpen"><code>ippFileOpen</code></a>. If "with_group" is
<code>true</code>, "GROUP" directives are written as necessary to place the attributes
-in the correct groups.</p>
-<h3 class="function"><a id="ippFileWriteComment">ippFileWriteComment</a></h3>
+in the correct groups.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileWriteComment">ippFileWriteComment</a></h3>
<p class="description">Write a comment to an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileWriteComment(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *comment, ...);</p>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function writes a comment to an IPP data file. Every line in the string
-is prefixed with the "#" character and indented as needed.</p>
-<h3 class="function"><a id="ippFileWriteToken">ippFileWriteToken</a></h3>
+is prefixed with the "#" character and indented as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileWriteToken">ippFileWriteToken</a></h3>
<p class="description">Write a token or value string to an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileWriteToken(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *token);</p>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function writes a token or value string to an IPP data file, quoting
-and indenting the string as needed.</p>
-<h3 class="function"><a id="ippFileWriteTokenf">ippFileWriteTokenf</a></h3>
+and indenting the string as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippFileWriteTokenf">ippFileWriteTokenf</a></h3>
<p class="description">Write a formatted token or value string to an IPP data file.</p>
<p class="code">
<span class="reserved">bool</span> ippFileWriteTokenf(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *token, ...);</p>
<p class="description"><code>true</code> on success, <code>false</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function writes a formatted token or value string to an IPP data file,
-quoting and indenting the string as needed.</p>
+quoting and indenting the string as needed.
+
+</p>
<h3 class="function"><a id="ippFindAttribute">ippFindAttribute</a></h3>
-<p class="description">Find a named attribute in a request.</p>
+<p class="description">Find a named attribute in an IPP message.</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">const</span> <span class="reserved">char</span> *name, ipp_tag_t type);</p>
<h4 class="parameters">Parameters</h4>
message. The attribute name can contain a hierarchical list of attribute and
member names separated by slashes, for example "media-col/media-size".</p>
<h3 class="function"><a id="ippFindNextAttribute">ippFindNextAttribute</a></h3>
-<p class="description">Find the next named attribute in a request.</p>
+<p class="description">Find the next named attribute in an IPP message.</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">const</span> <span class="reserved">char</span> *name, ipp_tag_t type);</p>
<h4 class="parameters">Parameters</h4>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Boolean value or 0 on error</p>
+<p class="description">Boolean value or <code>0</code> on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippGetCollection">ippGetCollection</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Collection value or <code>NULL</code> on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippGetCount">ippGetCount</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">dateTime value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 2.5 </span><a id="ippGetFirstAttribute">ippGetFirstAttribute</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Value or 0 on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><a id="ippGetLength">ippGetLength</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>datalen</th>
<td class="description">Length of octetString data</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Pointer to octetString data</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippGetOperation">ippGetOperation</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>uppervalue</th>
<td class="description">Upper value of range</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Lower value of range or 0</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippGetRequestId">ippGetRequestId</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>yres</th>
<td class="description">Vertical/feed resolution</td></tr>
<tr><th>units</th>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Horizontal/cross feed resolution or 0</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippGetState">ippGetState</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>language</th>
<td class="description">Language code (<code>NULL</code> for don't care)</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Get the string and optionally the language code for an attribute.</p>
-<p class="discussion">The "element" parameter specifies which value to get from 0 to
-<code>ippGetCount(attr)</code> - 1.
+<p class="discussion">The "element" argument specifies which value to get from <code>0</code> to
+<code>ippGetCount(attr) - 1</code>.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippGetValueTag">ippGetValueTag</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>boolvalue</th>
<td class="description">Boolean value</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>colvalue</th>
<td class="description">Collection value</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>datevalue</th>
<td class="description">dateTime value</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<td class="description">Group tag</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "group" parameter specifies the IPP attribute group tag: none
+The "group" argument specifies the IPP attribute group tag: none
(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>intvalue</th>
<td class="description">Integer/enum value</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<td class="description">Attribute name</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.
+The "attr" argument may be modified as a result of setting the value.
</p>
<h3 class="function"><span class="info"> CUPS 1.7 </span><a id="ippSetOctetString">ippSetOctetString</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>data</th>
<td class="description">Pointer to octetString data</td></tr>
<tr><th>datalen</th>
<td class="description">Length of octetString data</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<td class="description">Operation ID</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.
</p>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>lowervalue</th>
<td class="description">Lower bound for range</td></tr>
<tr><th>uppervalue</th>
<td class="description">Upper bound for range</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<td class="description">Request ID</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The <code>request_id</code> parameter must be greater than 0.
+The "request_id" argument must be greater than 0.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippSetResolution">ippSetResolution</a></h3>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>unitsvalue</th>
<td class="description">Resolution units</td></tr>
<tr><th>xresvalue</th>
<td class="description">Vertical/feed resolution</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<td class="description">IPP state value</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippSetStatusCode">ippSetStatusCode</a></h3>
<p class="description">Set the status code in an IPP response or event message.</p>
<p class="code">
<td class="description">Status code</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.
</p>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>strvalue</th>
<td class="description">String value</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.
</p>
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>format</th>
<td class="description">Printf-style format string</td></tr>
<tr><th>...</th>
<td class="description">Additional arguments as needed</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.<br>
<br>
-The "format" parameter uses formatting characters compatible with the
+The "format" argument uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
<tr><th>attr</th>
<td class="description">IPP attribute</td></tr>
<tr><th>element</th>
-<td class="description">Value number (0-based)</td></tr>
+<td class="description">Value number (<code>0</code>-based)</td></tr>
<tr><th>format</th>
<td class="description">Printf-style format string</td></tr>
<tr><th>ap</th>
<td class="description">Pointer to additional arguments</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
-The "element" parameter specifies which value to set from 0 to
+The "element" argument specifies which value to set from <code>0</code> to
<code>ippGetCount(attr)</code>.<br>
<br>
-The "format" parameter uses formatting characters compatible with the
+The "format" argument uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
<td class="description">Value tag</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
-The "attr" parameter may be modified as a result of setting the value.<br>
+The "attr" argument may be modified as a result of setting the value.<br>
<br>
Integer (<code>IPP_TAG_INTEGER</code>) values can be promoted to rangeOfInteger
(<code>IPP_TAG_RANGE</code>) values, the various string tags can be promoted to name
out-of-band value tags such as no-value (<code>IPP_TAG_NOVALUE</code>). All other
changes will be rejected.<br>
<br>
-Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language
-code in the "attributes-natural-language" attribute or, if not present, the language
-code for the current locale.
+Promoting a string attribute to nameWithLanguage or textWithLanguage adds the
+language code in the "attributes-natural-language" attribute or, if not
+present, the language code for the current locale.
</p>
<h3 class="function"><span class="info"> CUPS 1.6 </span><a id="ippSetVersion">ippSetVersion</a></h3>
<td class="description">Minor version number (major.minor)</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on failure</p>
+<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The "ipp" parameter refers to an IPP message previously created using
+<p class="discussion">The "ipp" argument refers to an IPP message previously created using
the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
<br>
The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
<td class="description">Attribute</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 if valid, 0 otherwise</p>
+<p class="description"><code>1</code> if valid, <code>0</code> otherwise</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function validates the contents of an attribute based on the name and
-value tag. 1 is returned if the attribute is valid, 0 otherwise. On
+value tag. <code>1</code> is returned if the attribute is valid, <code>0</code> otherwise. On
failure, <a href="#cupsGetErrorString"><code>cupsGetErrorString</code></a> is set to a human-readable message.
</p>
<td class="description">IPP message</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 if valid, 0 otherwise</p>
+<p class="description"><code>1</code> if valid, <code>0</code> otherwise</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function validates the contents of the IPP message, including each
attribute. Like <a href="#ippValidateAttribute"><code>ippValidateAttribute</code></a>, <a href="#cupsGetErrorString"><code>cupsGetErrorString</code></a> is
<h3 class="typedef"><a id="cups_oauth_cb_t"><span class="info"> CUPS 2.4 </span>cups_oauth_cb_t</a></h3>
<p class="description">OAuth callback </p>
<p class="code">
-typedef const char *(*)(http_t *http, const char *realm, const char *scope, const char *resource, void *user_data)cups_oauth_cb_t;
+typedef const char *(*)(http_t *http, const char *realm, const char *scope, const char *resource, void *cb_data)cups_oauth_cb_t;
</p>
<h3 class="typedef"><a id="cups_ogrant_t">cups_ogrant_t</a></h3>
<p class="description">OAuth Grant Types</p>
<h3 class="typedef"><a id="cups_password_cb2_t"><span class="info"> CUPS 1.4 </span>cups_password_cb2_t</a></h3>
<p class="description">New password callback </p>
<p class="code">
-typedef const char *(*)(const char *prompt, <a href="#http_t">http_t</a> *http, const char *method, const char *resource, void *user_data)cups_password_cb2_t;
+typedef const char *(*)(const char *prompt, <a href="#http_t">http_t</a> *http, const char *method, const char *resource, void *cb_data)cups_password_cb2_t;
</p>
<h3 class="typedef"><a id="cups_ptype_t">cups_ptype_t</a></h3>
<p class="description">Combined printer type/capability flags</p>
projects / thirdparty / cups.git / commitdiff
