From 0f81f5a62837570e147b44c0aedc3a63d97d5bbf Mon Sep 17 00:00:00 2001
From: Marcus Boerger <helly@php.net>
Date: Fri, 12 Apr 2002 19:46:42 +0000
Subject: [PATCH] Updat documentation for exif_read_data

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@77937 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/image.xml | 63 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 45 insertions(+), 18 deletions(-)

diff --git a/functions/image.xml b/functions/image.xml
index 6ce864fd8d..76e9a69177 100644
--- a/functions/image.xml
+++ b/functions/image.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.93 $ -->
+<!-- $Revision: 1.94 $ -->
 <reference id="ref.image">
  <title>Image functions</title>
  <titleabbrev>Image</titleabbrev>
@@ -126,7 +126,8 @@
        </row>
        <row>
         <entry>COMPUTED</entry>
-        <entry>html, Width, Height, IsColor and some more if available.</entry>
+        <entry>html, Width, Height, IsColor and some more if available. 
+        </entry>
        </row>
        <row>
         <entry>ANY_TAG</entry>
@@ -145,7 +146,7 @@
        </row>
        <row>
         <entry>COMMENT</entry>
-        <entry>Cemment headers of JPEG images.</entry>
+        <entry>Comment headers of JPEG images.</entry>
        </row>
        <row>
         <entry>EXIF</entry>
@@ -202,23 +203,27 @@ test1.jpg:
 No header data found.
 test2.jpg:
 FILE.FileName: test2.jpg
-FILE.FileDateTime: 1015448798
+FILE.FileDateTime: 1017666176
 FILE.FileSize: 1240
-FILE.SectionsFound: COMPUTED, ANY_TAG, IFD0, THUMBNAIL, COMMENT
-COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
-COMPUTED.Copyright.Editor: Edited by M.Boerger.
+FILE.FileType: 2
+FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
 COMPUTED.html: width="1" height="1"
 COMPUTED.Height: 1
 COMPUTED.Width: 1
 COMPUTED.IsColor: 1
+COMPUTED.ByteOrderMotorola: 1
 COMPUTED.UserComment: Exif test image.
 COMPUTED.UserCommentEncoding: ASCII
+COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
+COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
+COMPUTED.Copyright.Editor: Edited by M.Boerger.
 IFD0.Copyright: Photo (c) M.Boerger
 IFD0.UserComment: ASCII
+THUMBNAIL.JPEGInterchangeFormat: 134
 THUMBNAIL.JPEGInterchangeFormatLength: 523
 COMMENT.0: Comment #1.
 COMMENT.1: Comment #2.
-COMMENT.2: Comment #3end?>
+COMMENT.2: Comment #3end
 ]]>
 <!-- Version 4.3 will provide additional lines
 THUMBNAIL.JPEGInterchangeFormat: 134
@@ -231,26 +236,43 @@ THUMBNAIL.Thumbnail.Height: 1
     </para>
     <note>
      <para>
-      When an Exif header contains a Copyright note this itself can contain
-      two values. As the solution is inconsitent in the Exif 2.10 standard the
-      COMPUTED section will return both entries <emphasis>Copyright.Photographer</emphasis>
+      If the image contains any IFD0 data then COMPUTED contains the entry 
+      ByteOrderMotorola which is 0 for little-endian (intel) and 1 for
+      big-endian (motorola) byte order. This was added in PHP 4.3.
+     </para>
+     <para>
+      When an Exif header contains a Copyright note this itself can contain two 
+      values. As the solution is inconsitent in the Exif 2.10 standard the COMPUTED 
+      section will return both entries <emphasis>Copyright.Photographer</emphasis>
       and <emphasis>Copyright.Editor</emphasis> while the IFD0 sections contains
       the byte array with the NULL character that splits both entries. Or just the
-      first entry if the datatype was wrong.
+      first entry if the datatype was wrong (normal behaviour of Exif). The
+      COMPUTED will contain also an entry <emphasis>Copyright</emphasis> Which
+      is either the original copyright string or it is a comma separated list of 
+      photo and editor copyright.
      </para>
     </note>
     <note>
      <para>
-     The UserComment has the same problem as the Copyright tag. It can store two values
-     first the encoding used and second the value itself. If so the IFD section only
-     contains the encoding or a byte array. The COMPUTED section will store both.
+      The tag UserComment has the same problem as the Copyright tag. It can store 
+      two values first the encoding used and second the value itself. If so the 
+      IFD section only contains the encoding or a byte array. The COMPUTED section 
+      will store both in the entries <emphasis>UserCommentEncoding</emphasis> and 
+      <emphasis>UserComment</emphasis>. The entry <emphasis>UserComment</emphasis> 
+      is available in both cases so it should be used in preference to the value
+      in IFD0 section.
+     </para>
+     <para>
+      If the user comment uses Unicode or JIS encoding and the module mbstring is 
+      available this encoding will automatically changed according to the exif
+      ini settings. This was added in PHP 4.3.
      </para>
     </note>
     <note>
      <para>
      Height and Width are computed the same way <function>getimagesize</function>
      does so their values must not be part of any header returned. Also html is
-     a height/width text string to be used inside a normal <acronym>HTML</acronym>.
+     a height/width text string to be used inside normal <acronym>HTML</acronym>.
      </para>
     </note>
     <note>
@@ -259,7 +281,8 @@ THUMBNAIL.Thumbnail.Height: 1
      data including arrays (returned as such). Also the size of an embedded thumbnail
      is returned in <emphasis>THUMBNAIL</emphasis> subarray and the function
      <function>exif_read_data</function> can return thumbnails in <acronym>TIFF</acronym>
-     format.
+     format. Last but not least there is no longer a maximum legth for returned
+     values (not until memory limit is reached).
      </para>
     </note>
     <note>
@@ -267,7 +290,11 @@ THUMBNAIL.Thumbnail.Height: 1
        This function is only available in PHP 4 compiled using 
        <option role="configure">--enable-exif</option>.
        Its functionality and behaviour has changed in PHP 4.2. Earlier versions
-       are very unstable.
+       are very unstable. 
+      </simpara>
+      <simpara>
+       Since PHP 4.3 user comment can automatically change encoding if PHP 4 was 
+       compiled using <option role="configure">--enable-mbstring</option>.
       </simpara>
       <simpara>
        This function does not require the GD image library.