Return-Path: 
 <cvs-return-38282-apmail-httpd-cvs-archive=httpd.apache.org@httpd.apache.org>
Delivered-To: apmail-httpd-cvs-archive@www.apache.org
Received: (qmail 10122 invoked from network); 14 Mar 2011 20:58:59 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 14 Mar 2011 20:58:59 -0000
Received: (qmail 57283 invoked by uid 500); 14 Mar 2011 20:58:59 -0000
Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org
Received: (qmail 57236 invoked by uid 500); 14 Mar 2011 20:58:59 -0000
Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@httpd.apache.org
list-help: <mailto:cvs-help@httpd.apache.org>
list-unsubscribe: <mailto:cvs-unsubscribe@httpd.apache.org>
List-Post: <mailto:cvs@httpd.apache.org>
List-Id: <cvs.httpd.apache.org>
Delivered-To: mailing list cvs@httpd.apache.org
Received: (qmail 57229 invoked by uid 99); 14 Mar 2011 20:58:59 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 14 Mar 2011 20:58:59 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=5.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 14 Mar 2011 20:58:56 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 7561C23889D7; Mon, 14 Mar 2011 20:58:32 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1081559 -
 /httpd/httpd/trunk/docs/manual/developer/new_api_2_4.xml
Date: Mon, 14 Mar 2011 20:58:32 -0000
To: cvs@httpd.apache.org
From: trawick@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20110314205832.7561C23889D7@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: trawick
Date: Mon Mar 14 20:58:32 2011
New Revision: 1081559

URL: http://svn.apache.org/viewvc?rev=1081559&view=rev
Log:
add more module upgrade hints

change some existing text to be more correct+readable

Modified:
    httpd/httpd/trunk/docs/manual/developer/new_api_2_4.xml

Modified: httpd/httpd/trunk/docs/manual/developer/new_api_2_4.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/developer/new_api_2_4.xml?rev=1081559&r1=1081558&r2=1081559&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/developer/new_api_2_4.xml (original)
+++ httpd/httpd/trunk/docs/manual/developer/new_api_2_4.xml Mon Mar 14 20:58:32 2011
@@ -297,17 +297,32 @@
          eliminating that mechanism and relying on the use of
          different <code>APLOG_TRACEn</code> levels.  If expensive
          trace processing needs to be bypassed depending on the
-         configured log level, use
-         the <code>APLOGtrace<em>n</em></code>
-         and <code>APLOGrtrace<em>n</em></code> macros.</li>
+         configured log level, use the <code>APLOGtrace<em>n</em></code>
+         and <code>APLOGrtrace<em>n</em></code> macros to first check
+         if tracing is enabled.</li>
        </ul></p>
 
+    <p>Modules sometimes add process id and/or thread id to their log
+       messages.  These ids are now logged by default, so it may not
+       be necessary for the module to log them explicitly.  (Users may
+       remove them from the error log format, but they can be
+       instructed to add it back if necessary for problem diagnosis.)</p>
   </section>
 
   <section id="upgrading_byfunction">
-    <title>If your module uses these APIs...</title>
+    <title>If your module uses these existing APIs...</title>
 
     <dl>
+      <dt><code>ap_default_type()</code></dt>
+      <dd>This is no longer available; Content-Type must be configured
+          explicitly or added by the application.</dd>
+
+      <dt><code>ap_get_server_name()</code></dt>
+      <dd>If the returned server name is used in a URL,
+      use <code>ap_get_server_name_for_url()</code> instead.  This new
+      function handles the odd case where the server name is an IPv6
+      literal address.</dd>
+
       <dt><code>ap_get_server_version()</code></dt>
       <dd>For logging purposes, where detailed information is 
           appropriate, use <code>ap_get_server_description()</code>.
@@ -369,6 +384,8 @@
       0/APR_SUCCESS if there is no such error information, or a valid
       <code>apr_status_t</code> value otherwise.</dd>
 
+      <dt><code>unixd_config</code></dt>
+      <dd>This has been renamed to ap_unixd_config.</dd>
     </dl>
   </section>
 
@@ -376,19 +393,41 @@
     <title>If your module interfaces with this feature...</title>
     <dl>
       <dt>suEXEC</dt>
-      <dd>Optional: <code>ap_unixd_config.suexec_enabled</code> is
-          still provided, but new
-          field <code>suexec_disabled_reason</code> provides an
-          explanation if the feature is not available.</dd>
+      <dd>Optional: If your module logs an error
+          when <code>ap_unixd_config.suexec_enabled</code> is 0,
+          also log the value of the new
+          field <code>suexec_disabled_reason</code>, which contains an
+          explanation of why it is not available.</dd>
 
       <dt>Extended status data in the scoreboard</dt>
-      <dd>Instead of requiring mod_status and <code>ExtendedStatus
-          On</code>, just set <code>ap_extended_status</code>
-          to <code>1</code> in a pre-config hook.</dd>
+      <dd>In previous releases, <code>ExtendedStatus</code> had to be
+          set to <code>On</code>, which in turn required that
+          mod_status was loaded.  In 2.4, just
+          set <code>ap_extended_status</code> to <code>1</code> in a
+          pre-config hook and the extended status data will be
+          available.</dd>
 
     </dl>
   </section>
 
+  <section id="upgrading_newfeatures">
+    <title>Does your module...</title>
+    <dt>Parse query args</dt>
+    <dd>Consider if <code>ap_args_to_table()</code> would be
+    helpful.</dd>
+
+    <dt>Parse form data...</dt>
+    <dd>Use <code>ap_parse_form_data()</code>.</dd>
+
+    <dt>Check for request header fields <code>Content-Length</code>
+    and <code>Transfer-Encoding</code> to see if a body was
+    specified</dt>
+    <dd>Use <code>ap_request_has_body()</code>.</dd>
+
+    <dt>Implement cleanups which clear pointer variables</dt>
+    <dd>Use <code>ap_pool_cleanup_set_null()</code>.</dd>
+  </section>
+
 </section>
 
 </manualpage>