From e71ca2ffd3e91e08cff8902e73ae01afcf99c151 Mon Sep 17 00:00:00 2001
From: Gabor Hojtsy <goba@php.net>
Date: Sat, 20 Jul 2002 15:23:25 +0000
Subject: [PATCH] Adding documentation gathered from source files and also add
 comments to examples. Some minor problems may be in my observations, but in
 general IMHO what I have written down is right. I worked from the C source...

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@89206 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/w32api/functions/w32api-deftype.xml | 13 +++--
 .../w32api/functions/w32api-init-dtype.xml    | 16 ++++---
 .../functions/w32api-invoke-function.xml      | 11 ++++-
 .../functions/w32api-register-function.xml    |  9 +++-
 .../functions/w32api-set-call-method.xml      |  7 ++-
 reference/w32api/reference.xml                | 47 +++++++++++++++----
 6 files changed, 79 insertions(+), 24 deletions(-)

diff --git a/reference/w32api/functions/w32api-deftype.xml b/reference/w32api/functions/w32api-deftype.xml
index e34f8e80b2..11bebf9429 100644
--- a/reference/w32api/functions/w32api-deftype.xml
+++ b/reference/w32api/functions/w32api-deftype.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/w32api.xml, last change in rev 1.1 -->
   <refentry id="function.w32api-deftype">
    <refnamediv>
@@ -9,14 +9,21 @@
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
-      <type>int</type><methodname>w32api_deftype</methodname>
+      <type>bool</type><methodname>w32api_deftype</methodname>
       <methodparam><type>string</type><parameter>typename</parameter></methodparam>
       <methodparam><type>string</type><parameter>member1_type</parameter></methodparam>
       <methodparam><type>string</type><parameter>member1_name</parameter></methodparam>
+      <methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam>
+      <methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam>
      </methodsynopsis>
      &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     If you would like to define a type for a w32api call, you need to call
+     <function>w32api_deftype</function>. This function takes 2n+1 arguments,
+     where n is the number of members the type has. The first argument is the
+     name of the type. After that is the type of the member followed by the
+     members name (in pairs). A member type can be a user defined type.
+     &return.success;
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/w32api/functions/w32api-init-dtype.xml b/reference/w32api/functions/w32api-init-dtype.xml
index 868b883722..180c6ee6a2 100644
--- a/reference/w32api/functions/w32api-init-dtype.xml
+++ b/reference/w32api/functions/w32api-init-dtype.xml
@@ -1,13 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/w32api.xml, last change in rev 1.1 -->
   <refentry id="function.w32api-init-dtype">
    <refnamediv>
     <refname>w32api_init_dtype</refname>
     <refpurpose>
-     Creates an instance to the data type typename and fills it with 
-     the values val1, val2, the function then returns a DYNAPARM which can be 
-     passed when invoking a function as a parameter
+     Creates an instance of the data type typename and fills it with the values passed
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -15,12 +13,16 @@
      <methodsynopsis>
       <type>resource</type><methodname>w32api_init_dtype</methodname>
       <methodparam><type>string</type><parameter>typename</parameter></methodparam>
-      <methodparam><type>mixed</type><parameter>val1</parameter></methodparam>
-      <methodparam><type>mixed</type><parameter>val2</parameter></methodparam>
+      <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
+      <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
      </methodsynopsis>
      &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     This function creates an instance of the data type named
+     <parameter>typename</parameter>, filling in the values of the data
+     type. You should give the values in the same order as you defined the
+     data type with <function>w32api_deftype</function>. The type of the
+     resource returned is <literal>dynaparm</literal>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/w32api/functions/w32api-invoke-function.xml b/reference/w32api/functions/w32api-invoke-function.xml
index 01a0c1d65a..75c9a85f5b 100644
--- a/reference/w32api/functions/w32api-invoke-function.xml
+++ b/reference/w32api/functions/w32api-invoke-function.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/w32api.xml, last change in rev 1.1 -->
   <refentry id="function.w32api-invoke-function">
    <refnamediv>
@@ -11,10 +11,17 @@
      <methodsynopsis>
       <type>mixed</type><methodname>w32api_invoke_function</methodname>
       <methodparam><type>string</type><parameter>funcname</parameter></methodparam>
+      <methodparam><type>mixed</type><parameter>argument</parameter></methodparam>
+      <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
      </methodsynopsis>
      &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>w32api_invoke_function</function> tries to find the previously
+     registered function, named <parameter>funcname</parameter>, passing the
+     parameters you provided. The return type is the one you set when you
+     registered the function, the value is the one returned by the function
+     itself. Any of the arguments can be of any PHP type or
+     <function>w32api_deftype</function> defined type, as needed.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/w32api/functions/w32api-register-function.xml b/reference/w32api/functions/w32api-register-function.xml
index 32c3a52cc9..5677fb7010 100644
--- a/reference/w32api/functions/w32api-register-function.xml
+++ b/reference/w32api/functions/w32api-register-function.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/w32api.xml, last change in rev 1.1 -->
   <refentry id="function.w32api-register-function">
    <refnamediv>
@@ -12,10 +12,15 @@
       <type>bool</type><methodname>w32api_register_function</methodname>
       <methodparam><type>string</type><parameter>libary</parameter></methodparam>
       <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
+      <methodparam><type>string</type><parameter>return_type</parameter></methodparam>
      </methodsynopsis>
      &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     This function tries to find the <parameter>function_name</parameter> function
+     in <parameter>libary</parameter>, and tries to import it into PHP. The function
+     will be registered with the given <parameter>return_type</parameter>. This type
+     can be a generic PHP type, or a type defined with <function>w32api_deftype</function>.
+     &return.success;
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/w32api/functions/w32api-set-call-method.xml b/reference/w32api/functions/w32api-set-call-method.xml
index fed999872d..43771d1978 100644
--- a/reference/w32api/functions/w32api-set-call-method.xml
+++ b/reference/w32api/functions/w32api-set-call-method.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/w32api.xml, last change in rev 1.1 -->
   <refentry id="function.w32api-set-call-method">
    <refnamediv>
@@ -14,7 +14,10 @@
      </methodsynopsis>
      &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     This function sets the method call type. The parameter can be
+     one of the constants <constant>DC_CALL_CDECL</constant> or
+     <constant>DC_CALL_STD</constant>. The extension default is
+     <constant>DC_CALL_STD</constant>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/w32api/reference.xml b/reference/w32api/reference.xml
index 099a2bd795..66a171b888 100644
--- a/reference/w32api/reference.xml
+++ b/reference/w32api/reference.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
  <reference id="ref.w32api">
   <title>W32api functions</title>
   <titleabbrev>W32api</titleabbrev>
@@ -8,17 +8,42 @@
    <section id="w32api.intro">
     &reftitle.intro;
     <para>
-     This extension is a generic extension api to DLLs. This was originally
-     written to allow access to the Win32 API from PHP. Although you can also
+     This extension is a generic extension API to DLLs. This was originally
+     written to allow access to the Win32 API from PHP, although you can also
      access other functions exported via other DLLs.
     </para>
     <para>
-     Currently supported types are generic PHP types (strings, bools, doubles,
-     longs and null's) others will be added in the future.
+     Currently supported types are generic PHP types (strings, booleans, floats,
+     integers and nulls) and types you define with <function>w32api_deftype</function>.
     </para>
     &warn.experimental;
    </section>
+
+   <section id="w32api.requirements">
+    &reftitle.required;
+    <para>
+     This extension will only work on Windows systems.
+    </para>
+   </section>
    
+   <section id="w32api.installation">
+    &reftitle.install;
+    &no.install;
+   </section>
+   
+   <section id="w32api.configuration">
+    &reftitle.runtime;
+    &no.config;
+   </section>
+
+   <section id="w32api.resources">
+    &reftitle.resources;
+    <para>
+     This extension defines one resource type, used for user defined types.
+     The name of this resource is <literal>"dynaparm"</literal>.
+    </para>
+   </section>
+
    &reference.w32api.constants;
    
    <section id="w32api.examples">
@@ -28,7 +53,7 @@
      displays it in a message box.
     </para>
     <example>
-     <title>Get the uptime and display in a message box</title>
+     <title>Get the uptime and display it in a message box</title>
      <programlisting role="php">
 <![CDATA[
 <?php
@@ -36,20 +61,25 @@
 // Visual Studio/Tools/Winapi/WIN32API.txt
 define("MB_OK", 0);
 
+// Load the extension in
 dl("php_w32api.dll");
 
+// Register the GetTickCount function from kernel32.dll
 w32api_register_function("kernel32.dll", 
                          "GetTickCount",
                          "long");
                          
+// Register the MessageBoxA function from User32.dll
 w32api_register_function("User32.dll",
                          "MessageBoxA",
                          "long");
 
+// Get uptime information
 $ticks = GetTickCount();
 
-$secs = floor($ticks / 1000);
-$mins = floor($secs / 60);
+// Convert it to a nicely displayable text
+$secs  = floor($ticks / 1000);
+$mins  = floor($secs / 60);
 $hours = floor($mins / 60);
 
 $str = sprintf("You have been using your computer for:".
@@ -61,6 +91,7 @@ $str = sprintf("You have been using your computer for:".
                 $hours,
                 $mins - ($hours*60));
 
+// Display a message box with only an OK button and the uptime text
 MessageBoxA(NULL, 
             $str, 
             "Uptime Information",