From 1ad035ee05f2fa27973c029e8b325c63e8549f9e Mon Sep 17 00:00:00 2001
From: Moriyoshi Koizumi <moriyoshi@php.net>
Date: Mon, 22 Dec 2003 20:19:34 +0000
Subject: [PATCH] - Add "see also" section to iconv_mime_decode() and
 iconv_mime_encode() - Add documentation of iconv_mime_decode_headers()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@147193 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../functions/iconv-mime-decode-headers.xml   | 156 ++++++++++++++++++
 .../iconv/functions/iconv-mime-decode.xml     |  10 +-
 .../iconv/functions/iconv-mime-encode.xml     |   7 +-
 3 files changed, 170 insertions(+), 3 deletions(-)
 create mode 100644 reference/iconv/functions/iconv-mime-decode-headers.xml

diff --git a/reference/iconv/functions/iconv-mime-decode-headers.xml b/reference/iconv/functions/iconv-mime-decode-headers.xml
new file mode 100644
index 0000000000..26adb5b24e
--- /dev/null
+++ b/reference/iconv/functions/iconv-mime-decode-headers.xml
@@ -0,0 +1,156 @@
+<?xml version='1.0' encoding='iso-8859-1'?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.iconv-mime-decode-headers">
+   <refnamediv>
+    <refname>iconv_mime_decode_headers</refname>
+    <refpurpose>
+     Decodes multiple <literal>MIME</literal> header fields at once
+    </refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <methodsynopsis>
+     <type>array</type><methodname>iconv_mime_decode</methodname>
+     <methodparam><type>string</type><parameter>encoded_headers</parameter></methodparam>
+     <methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
+     <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
+    </methodsynopsis>
+
+    <para>
+     Returns an associative array that holds a whole set of
+     <literal>MIME</literal> header fields specified by
+     <parameter>encoded_headers</parameter> on success, or &false;
+     if an error occurs during the decoding.
+    </para>
+
+    <para>
+     Each key of the return value represents an individual
+     field name and the corresponding element represents a field value.
+     If more than one field of the same field name are present,
+     <function>iconv_mime_decode_headers</function> automatically incorporates
+     them into an numerically indexed array in the order of occurrence.
+    </para>
+
+    <para>
+     <parameter>mode</parameter> determines the behaviour in the event 
+     <function>iconv_mime_decode_headers</function> encounters a malformed
+     <literal>MIME</literal> header field. You can specify any combination
+     of the following bitmasks.
+     <table>
+      <title>Bitmasks acceptable to <function>iconv_mime_decode_headers</function></title>
+      <tgroup cols="3">
+       <thead>
+        <row>
+         <entry>Value</entry>
+         <entry>Constant</entry>
+         <entry>Description</entry>
+        </row>
+       </thead>
+       <tbody>
+        <row>
+         <entry>1</entry>
+         <entry>ICONV_MIME_DECODE_STRICT</entry>
+         <entry>
+          If set, the given header is decoded in full conformance with the
+          standards defined in <ulink url="&url.rfc;2047">RFC2047</ulink>.
+          This option is disabled by default because there are a lot of
+          broken mail user agents that don't follow the specification and don't
+          produce correct <literal>MIME</literal> headers.
+         </entry>
+        </row>
+        <row>
+         <entry>2</entry>
+         <entry>ICONV_MIME_DECODE_CONTINUE_ON_ERROR</entry>
+         <entry>
+          If set, <function>iconv_mime_decode_headers</function>
+          attempts to continue to process the given header even though
+          an error occurs.
+         </entry>
+        </row>
+       </tbody>
+      </tgroup>
+     </table>
+    </para>
+
+    <para>
+     The optional <parameter>charset</parameter> parameter specifies the
+     character set to represent the result by. If omitted, 
+     <link linkend="iconv.configuration">iconv.internal_charset</link>
+     will be used.
+    </para>
+
+    <para>
+     <example>
+      <title><function>iconv_mime_decode_function</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$headers_string = <<<EOF
+Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
+To: example@example.com
+Date: Thu, 1 Jan 1970 00:00:00 +0000
+Message-Id: <example@example.com>
+Received: from localhost (localhost [127.0.0.1]) by localhost
+	with SMTP id example for <example@example.com>;
+	Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
+	(envelope-from example-return-0000-example=example.com@example.com)
+Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
+
+EOF;
+
+$headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
+print_r($headers);
+?>
+]]>
+      </programlisting>
+
+      The output of this script should look like:
+
+      <screen>
+<![CDATA[
+Array
+(
+    [Subject] => Pr&uuml;fung Pr&uuml;fung
+    [To] => example@example.com
+    [Date] => Thu, 1 Jan 1970 00:00:00 +0000
+    [Message-Id] => <example@example.com>
+    [Received] => Array
+        (
+            [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
+            [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
+        )
+
+)
+]]>
+      </screen>
+     </example>
+    </para>
+
+    <para>
+     See also <function>iconv_mime_decode</function>,
+     <function>imap_base64_decode</function>,
+     and <function>imap_qprint</function>.
+    </para>
+   </refsect1>
+  </refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/iconv/functions/iconv-mime-decode.xml b/reference/iconv/functions/iconv-mime-decode.xml
index 45fd7a72f0..980911331e 100644
--- a/reference/iconv/functions/iconv-mime-decode.xml
+++ b/reference/iconv/functions/iconv-mime-decode.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
   <refentry id="function.iconv-mime-decode">
    <refnamediv>
@@ -12,7 +12,7 @@
     <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>iconv_mime_decode</methodname>
-     <methodparam><type>string</type><parameter>encoded_string</parameter></methodparam>
+     <methodparam><type>string</type><parameter>encoded_header</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
     </methodsynopsis>
@@ -83,6 +83,12 @@ echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
       </programlisting>
      </example>
     </para>
+
+    <para>
+     See also <function>iconv_mime_decode_headers</function>,
+     <function>imap_base64_decode</function>,
+     and <function>imap_qprint</function>.
+    </para>
    </refsect1>
   </refentry>
 
diff --git a/reference/iconv/functions/iconv-mime-encode.xml b/reference/iconv/functions/iconv-mime-encode.xml
index c2085c5705..2debc89ec1 100644
--- a/reference/iconv/functions/iconv-mime-encode.xml
+++ b/reference/iconv/functions/iconv-mime-encode.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
   <refentry id="function.iconv-mime-encode">
    <refnamediv>
@@ -145,6 +145,11 @@ echo iconv_mime_encode("Subject", "Pr&uuml;fung Pr&uuml;fung", $preferences);
       </programlisting>
      </example>
     </para>
+
+    <para>
+     See also <function>imap_base64_encode</function>,
+     and <function>imap_8bit</function>.
+    </para>
    </refsect1>
   </refentry>