Update documentation to avoid confusion, add links.

git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@10588 7a7537e8-13f0-0310-91df-b6672ffda945

diff --git a/cups/request.c b/cups/request.c
index e64540ef32f360a8817744ec29bdf60fa5716b03..958461e970fe7a16c903e7e7f340053c37980016 100644 (file)
--- a/cups/request.c
+++ b/cups/request.c
@@ -51,9 +51,9 @@
 /*
  * 'cupsDoFileRequest()' - Do an IPP request with a file.
  *
- * This function sends the IPP request to the specified server, retrying
- * and authenticating as necessary.  The request is freed with @link ippDelete@
- * after receiving a valid IPP response.
+ * This function sends the IPP request and attached file to the specified
+ * server, retrying and authenticating as necessary.  The request is freed with
+ * @link ippDelete@.
  */
 
 ipp_t *                                        /* O - Response data */
@@ -102,14 +102,14 @@ cupsDoFileRequest(http_t     *http,       /* I - Connection to server or @code CUPS_HT
 /*
  * 'cupsDoIORequest()' - Do an IPP request with file descriptors.
  *
- * This function sends the IPP request to the specified server, retrying
- * and authenticating as necessary.  The request is freed with ippDelete()
- * after receiving a valid IPP response.
+ * This function sends the IPP request with the optional input file "infile" to
+ * the specified server, retrying and authenticating as necessary.  The request
+ * is freed with @link ippDelete@.
  *
- * If "infile" is a valid file descriptor, cupsDoIORequest() copies
+ * If "infile" is a valid file descriptor, @code cupsDoIORequest@ copies
  * all of the data from the file after the IPP request message.
  *
- * If "outfile" is a valid file descriptor, cupsDoIORequest() copies
+ * If "outfile" is a valid file descriptor, @code cupsDoIORequest@ copies
  * all of the data after the IPP response message to the file.
  *
  * @since CUPS 1.3/OS X 10.5@
@@ -309,8 +309,7 @@ cupsDoIORequest(http_t     *http,   /* I - Connection to server or @code CUPS_HTTP
  * 'cupsDoRequest()' - Do an IPP request.
  *
  * This function sends the IPP request to the specified server, retrying
- * and authenticating as necessary.  The request is freed with ippDelete()
- * after receiving a valid IPP response.
+ * and authenticating as necessary.  The request is freed with @link ippDelete@.
  */
 
 ipp_t *                                        /* O - Response data */
@@ -331,9 +330,9 @@ cupsDoRequest(http_t     *http,             /* I - Connection to server or @code CUPS_HTTP_
  * 'cupsGetResponse()' - Get a response to an IPP request.
  *
  * Use this function to get the response for an IPP request sent using
- * cupsSendDocument() or cupsSendRequest(). For requests that return
- * additional data, use httpRead() after getting a successful response,
- * otherwise call httpFlush() to complete the response processing.
+ * @link cupsSendRequest@. For requests that return additional data, use
+ * @link cupsReadResponseData@ after getting a successful response,
+ * otherwise call @link httpFlush@ to complete the response processing.
  *
  * @since CUPS 1.4/OS X 10.6@
  */
@@ -481,7 +480,8 @@ cupsGetResponse(http_t     *http,   /* I - Connection to server or @code CUPS_HTTP
 
 
 /*
- * 'cupsLastError()' - Return the last IPP status code.
+ * 'cupsLastError()' - Return the last IPP status code received on the current
+ *                     thread.
  */
 
 ipp_status_t                           /* O - IPP status code from last request */
@@ -492,7 +492,8 @@ cupsLastError(void)
 
 
 /*
- * 'cupsLastErrorString()' - Return the last IPP status-message.
+ * 'cupsLastErrorString()' - Return the last IPP status-message received on the
+ *                           current thread.
  *
  * @since CUPS 1.2/OS X 10.5@
  */
@@ -537,8 +538,9 @@ _cupsNextDelay(int current,         /* I  - Current delay value or 0 */
 /*
  * 'cupsReadResponseData()' - Read additional data after the IPP response.
  *
- * This function is used after cupsGetResponse() to read the PPD or document
- * files for CUPS_GET_PPD and CUPS_GET_DOCUMENT requests, respectively.
+ * This function is used after @link cupsGetResponse@ to read the PPD or document
+ * files from @code CUPS_GET_PPD@ and @code CUPS_GET_DOCUMENT@ requests,
+ * respectively.
  *
  * @since CUPS 1.4/OS X 10.6@
  */
@@ -579,13 +581,17 @@ cupsReadResponseData(
 /*
  * 'cupsSendRequest()' - Send an IPP request.
  *
- * Use httpWrite() to write any additional data (document, PPD file, etc.)
- * for the request, cupsGetResponse() to get the IPP response, and httpRead()
- * to read any additional data following the response. Only one request can be
- * sent/queued at a time.
+ * Use @link cupsWriteRequestData@ to write any additional data (document, PPD
+ * file, etc.) for the request, @link cupsGetResponse@ to get the IPP response,
+ * and @link cupsReadResponseData@ to read any additional data following the
+ * response. Only one request can be sent/queued at a time per @code http_t@
+ * connection.
+ *
+ * Returns the initial HTTP status code, which will be @code HTTP_CONTINUE@
+ * on a successful send of the request.
  *
- * Unlike cupsDoFileRequest(), cupsDoIORequest(), and cupsDoRequest(), the
- * request is not freed.
+ * Note: Unlike @link cupsDoFileRequest@, @link cupsDoIORequest@, and
+ * @link cupsDoRequest@, the request is NOT freed with @link ippDelete@.
  *
  * @since CUPS 1.4/OS X 10.6@
  */

diff --git a/doc/help/api-httpipp.html b/doc/help/api-httpipp.html
index 33e1672af6993be38f6c80cc71f0d1a685596c4e..b30af9eb8c87f8fa1a223f6062f432afeb32d2ab 100644 (file)
--- a/doc/help/api-httpipp.html
+++ b/doc/help/api-httpipp.html
@@ -395,8 +395,10 @@ div.contents ul.subcontents li {
        <li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li>
        <li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li>
        <li><a href="#cupsGetResponse" title="Get a response to an IPP request.">cupsGetResponse</a></li>
-       <li><a href="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li>
-       <li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li>
+       <li><a href="#cupsLastError" title="Return the last IPP status code received on the current
+thread.">cupsLastError</a></li>
+       <li><a href="#cupsLastErrorString" title="Return the last IPP status-message received on the
+current thread.">cupsLastErrorString</a></li>
        <li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li>
        <li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li>
        <li><a href="#cupsReadResponseData" title="Read additional data after the IPP response.">cupsReadResponseData</a></li>
@@ -1010,9 +1012,9 @@ status, prior to resubmitting your request.
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Response data</p>
 <h4 class="discussion">Discussion</h4>
-<p class="discussion">This function sends the IPP request to the specified server, retrying
-and authenticating as necessary.  The request is freed with <a href="#ippDelete"><code>ippDelete</code></a>
-after receiving a valid IPP response.</p>
+<p class="discussion">This function sends the IPP request and attached file to the specified
+server, retrying and authenticating as necessary.  The request is freed with
+<a href="#ippDelete"><code>ippDelete</code></a>.</p>
 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="cupsDoIORequest">cupsDoIORequest</a></h3>
 <p class="description">Do an IPP request with file descriptors.</p>
 <p class="code">
@@ -1039,14 +1041,14 @@ after receiving a valid IPP response.</p>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Response data</p>
 <h4 class="discussion">Discussion</h4>
-<p class="discussion">This function sends the IPP request to the specified server, retrying
-and authenticating as necessary.  The request is freed with ippDelete()
-after receiving a valid IPP response.<br>
+<p class="discussion">This function sends the IPP request with the optional input file &quot;infile&quot; to
+the specified server, retrying and authenticating as necessary.  The request
+is freed with <a href="#ippDelete"><code>ippDelete</code></a>.<br>
 <br>
-If &quot;infile&quot; is a valid file descriptor, cupsDoIORequest() copies
+If &quot;infile&quot; is a valid file descriptor, <code>cupsDoIORequest</code> copies
 all of the data from the file after the IPP request message.<br>
 <br>
-If &quot;outfile&quot; is a valid file descriptor, cupsDoIORequest() copies
+If &quot;outfile&quot; is a valid file descriptor, <code>cupsDoIORequest</code> copies
 all of the data after the IPP response message to the file.
 
 </p>
@@ -1071,8 +1073,7 @@ all of the data after the IPP response message to the file.
 <p class="description">Response data</p>
 <h4 class="discussion">Discussion</h4>
 <p class="discussion">This function sends the IPP request to the specified server, retrying
-and authenticating as necessary.  The request is freed with ippDelete()
-after receiving a valid IPP response.</p>
+and authenticating as necessary.  The request is freed with <a href="#ippDelete"><code>ippDelete</code></a>.</p>
 <h3 class="function"><a name="cupsEncodeOptions">cupsEncodeOptions</a></h3>
 <p class="description">Encode printer options into IPP attributes.</p>
 <p class="code">
@@ -1220,19 +1221,21 @@ the request respectively.
 <p class="description">Response or <code>NULL</code> on HTTP error</p>
 <h4 class="discussion">Discussion</h4>
 <p class="discussion">Use this function to get the response for an IPP request sent using
-cupsSendDocument() or cupsSendRequest(). For requests that return
-additional data, use httpRead() after getting a successful response,
-otherwise call httpFlush() to complete the response processing.
+<a href="#cupsSendRequest"><code>cupsSendRequest</code></a>. For requests that return additional data, use
+<a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> after getting a successful response,
+otherwise call <a href="#httpFlush"><code>httpFlush</code></a> to complete the response processing.
 
 </p>
 <h3 class="function"><a name="cupsLastError">cupsLastError</a></h3>
-<p class="description">Return the last IPP status code.</p>
+<p class="description">Return the last IPP status code received on the current
+thread.</p>
 <p class="code">
 ipp_status_t cupsLastError (void);</p>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">IPP status code from last request</p>
 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
-<p class="description">Return the last IPP status-message.</p>
+<p class="description">Return the last IPP status-message received on the
+current thread.</p>
 <p class="code">
 const char *cupsLastErrorString (void);</p>
 <h4 class="returnvalue">Return Value</h4>
@@ -1305,8 +1308,9 @@ ssize_t cupsReadResponseData (<br>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Bytes read, 0 on EOF, -1 on error</p>
 <h4 class="discussion">Discussion</h4>
-<p class="discussion">This function is used after cupsGetResponse() to read the PPD or document
-files for CUPS_GET_PPD and CUPS_GET_DOCUMENT requests, respectively.
+<p class="discussion">This function is used after <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to read the PPD or document
+files from <code>CUPS_GET_PPD</code> and <code>CUPS_GET_DOCUMENT</code> requests,
+respectively.
 
 </p>
 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsSendRequest">cupsSendRequest</a></h3>
@@ -1332,13 +1336,17 @@ files for CUPS_GET_PPD and CUPS_GET_DOCUMENT requests, respectively.
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Initial HTTP status</p>
 <h4 class="discussion">Discussion</h4>
-<p class="discussion">Use httpWrite() to write any additional data (document, PPD file, etc.)
-for the request, cupsGetResponse() to get the IPP response, and httpRead()
-to read any additional data following the response. Only one request can be
-sent/queued at a time.<br>
+<p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write any additional data (document, PPD
+file, etc.) for the request, <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to get the IPP response,
+and <a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> to read any additional data following the
+response. Only one request can be sent/queued at a time per <code>http_t</code>
+connection.<br>
+<br>
+Returns the initial HTTP status code, which will be <code>HTTP_CONTINUE</code>
+on a successful send of the request.<br>
 <br>
-Unlike cupsDoFileRequest(), cupsDoIORequest(), and cupsDoRequest(), the
-request is not freed.
+Note: Unlike <a href="#cupsDoFileRequest"><code>cupsDoFileRequest</code></a>, <a href="#cupsDoIORequest"><code>cupsDoIORequest</code></a>, and
+<a href="#cupsDoRequest"><code>cupsDoRequest</code></a>, the request is NOT freed with <a href="#ippDelete"><code>ippDelete</code></a>.
 
 </p>
 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsWriteRequestData">cupsWriteRequestData</a></h3>