Fix/win32service doc issues

reference/win32service/functions/win32-add-right-access-service.xml

@@ -14,7 +14,7 @@
    <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
    <methodparam><type>string</type><parameter>username</parameter></methodparam>
    <methodparam><type>int</type><parameter>right</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
   </methodsynopsis>
   <simpara>
    Add the rights access for <parameter>username</parameter> on <parameter>servicename</parameter>
@@ -67,19 +67,24 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Return a <classname>Win32Service\RightInfo</classname> object.
+   &return.void;
   </simpara>
  </refsect1>
 
  <refsect1 role="errors">
   &reftitle.errors;
   <simpara>
    A <exceptionname>ValueError</exceptionname> is thrown if the
-   value of <parameter>service</parameter> parameter is empty.
+   value of <parameter>service</parameter> parameter is empty or shorter than 2 characters.
   </simpara>
   <simpara>
    A <exceptionname>ValueError</exceptionname> is thrown if the
-   value of <parameter>username</parameter> parameter is empty.
+   value of <parameter>username</parameter> parameter is empty or shorter than 2 characters.
+  </simpara>
+  <simpara>
+   A <exceptionname>ValueError</exceptionname> is thrown if the
+   value of <parameter>right</parameter> parameter is not a positive combination of the
+   <link linkend="win32service.constants.rights">service rights constants</link>.
   </simpara>
   <simpara>
    A <exceptionname>Win32ServiceException</exceptionname> is thrown on error.

reference/win32service/functions/win32-add-service-env-var.xml

@@ -12,11 +12,11 @@
   <methodsynopsis>
    <type>void</type><methodname>win32_add_service_env_var</methodname>
    <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
-   <methodparam><type>string</type><parameter>varname</parameter></methodparam>
-   <methodparam><type>string</type><parameter>value</parameter></methodparam>
+   <methodparam><type>string</type><parameter>varName</parameter></methodparam>
+   <methodparam><type>string</type><parameter>varValue</parameter></methodparam>
   </methodsynopsis>
   <simpara>
-   Add a custom environment variables <parameter>varname</parameter> on <parameter>servicename</parameter>
+   Add a custom environment variables <parameter>varName</parameter> on <parameter>servicename</parameter>
    service. This function work only for the local computer. Administrative privileges are required for this to succeed.
   </simpara>
  </refsect1>
@@ -34,15 +34,15 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>varname</parameter></term>
+     <term><parameter>varName</parameter></term>
      <listitem>
       <simpara>
        The environment variable name.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>value</parameter></term>
+     <term><parameter>varValue</parameter></term>
      <listitem>
       <simpara>
        The environment variable value.
@@ -68,7 +68,7 @@
   </simpara>
   <simpara>
    A <exceptionname>ValueError</exceptionname> is thrown if the
-   value of <parameter>varname</parameter> parameter is empty.
+   value of <parameter>varName</parameter> parameter is empty.
   </simpara>
   <simpara>
    A <exceptionname>Win32ServiceException</exceptionname> is thrown on error.

reference/win32service/functions/win32-continue-service.xml

@@ -11,7 +11,7 @@
   <methodsynopsis>
    <type>void</type><methodname>win32_continue_service</methodname>
    <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
   </methodsynopsis>
 
   <simpara>

reference/win32service/functions/win32-create-service.xml

@@ -12,7 +12,7 @@
   <methodsynopsis>
    <type>void</type><methodname>win32_create_service</methodname>
    <methodparam><type>array</type><parameter>details</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
   </methodsynopsis>
   <simpara>
    Attempts to add a service into the SCM database. Administrative
@@ -72,6 +72,7 @@
          <listitem>
           <simpara>
            The password that corresponds to the <parameter>user</parameter>.
+           If omitted, the default value is an empty string.
           </simpara>
          </listitem>
         </varlistentry>
@@ -80,8 +81,7 @@
          <listitem>
           <simpara>
            The full path to the executable module that will be launched when
-           the service is started.  If omitted, the path to the current PHP
-           process will be used.
+           the service is started.  This key is mandatory.
           </simpara>
          </listitem>
         </varlistentry>
@@ -94,6 +94,7 @@
            parameter should be the full path to the PHP script that you intend
            to run. If the script name or path contains spaces, then wrap the
            full path to the PHP script with <literal>"</literal>.
+           If omitted, the default value is an empty string.
           </simpara>
          </listitem>
         </varlistentry>
@@ -113,6 +114,12 @@
            <constant>WIN32_SERVICE_WIN32_OWN_PROCESS</constant>.
            Don't change this unless you know what you're doing.
           </simpara>
+          <simpara>
+           The accepted values are <constant>WIN32_SERVICE_WIN32_OWN_PROCESS</constant>,
+           <constant>WIN32_SERVICE_INTERACTIVE_PROCESS</constant> and
+           <constant>WIN32_SERVICE_WIN32_OWN_PROCESS_INTERACTIVE</constant>.
+           Any other value throws a <exceptionname>ValueError</exceptionname>.
+          </simpara>
          </listitem>
         </varlistentry>
         <varlistentry>
@@ -131,7 +138,7 @@
           <simpara>
            Informs the SCM what it should do when it detects a problem with
            the service.  The default is
-           <constant>WIN32_SERVER_ERROR_IGNORE</constant>.  Changing this
+           <constant>WIN32_SERVICE_ERROR_IGNORE</constant>.  Changing this
            value is not yet fully supported.
           </simpara>
          </listitem>
@@ -167,6 +174,7 @@
            The <parameter>base_priority</parameter> can be set to one of the
            constants define in
            <link linkend="win32service.constants.basepriorities">Win32 Base Priority Classes</link>.
+           If omitted, the default value is <constant>WIN32_NORMAL_PRIORITY_CLASS</constant>.
           </simpara>
          </listitem>
         </varlistentry>
@@ -304,13 +312,17 @@
 
  <refsect1 role="errors">
   &reftitle.errors;
+  <simpara>
+   A <exceptionname>ValueError</exceptionname> is thrown if the value of one
+   of the string keys of <parameter>details</parameter> contains a null byte.
+  </simpara>
   <simpara>
    A <exceptionname>ValueError</exceptionname> is thrown if the
-   value of <parameter>service</parameter> parameter is empty.
+   value of <parameter>service</parameter> key is empty or shorter than 2 characters.
   </simpara>
   <simpara>
    A <exceptionname>ValueError</exceptionname> is thrown if the
-   value of <parameter>path</parameter> parameter is missing or empty.
+   value of <parameter>path</parameter> key is missing.
   </simpara>
   <simpara>
    A <exceptionname>ValueError</exceptionname> is thrown if the
@@ -486,6 +498,7 @@ debug_zval_dump($x);
   <para>
    <simplelist>
     <member><function>win32_delete_service</function></member>
+    <member><function>win32_exists_service</function></member>
     <member><link linkend="win32service.constants.basepriorities">Win32 Base Priority Classes</link></member>
     <member><link linkend="win32service.constants.recovery-action">Win32 Recovery action</link></member>
     <member><link linkend="win32service.constants.errors">Win32 Error Codes</link></member>

reference/win32service/functions/win32-delete-service.xml

@@ -11,7 +11,7 @@
   <methodsynopsis>
    <type>void</type><methodname>win32_delete_service</methodname>
    <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
   </methodsynopsis>
 
   <simpara>
@@ -138,6 +138,7 @@ win32_delete_service('dummyphp');
   <para>
    <simplelist>
     <member><function>win32_create_service</function></member>
+    <member><function>win32_exists_service</function></member>
     <member><link linkend="win32service.constants.errors">Win32 Error Codes</link></member>
    </simplelist>
   </para>

reference/win32service/functions/win32-exists-service.xml

@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- Generated by xml_proto.php v2.3. Found in /scripts directory of phpdoc. -->
+<refentry xml:id="function.win32-exists-service" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>win32_exists_service</refname>
+  <refpurpose>Checks if a service entry exists in the SCM database</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>bool</type><methodname>win32_exists_service</methodname>
+   <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
+  </methodsynopsis>
+
+  <simpara>
+   Checks whether a service exists in the SCM database.
+  </simpara>
+  <note>
+   <simpara>
+    Administrative privileges are required, as the Service Control Manager is
+    opened with full access and the service with the <literal>DELETE</literal>
+    access right. Without them, a <exceptionname>Win32ServiceException</exceptionname>
+    is thrown (access denied) instead of returning &false;.
+   </simpara>
+  </note>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>servicename</parameter></term>
+     <listitem>
+      <simpara>
+       The short name of the service.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>machine</parameter></term>
+     <listitem>
+      <simpara>
+       The optional machine name.  If omitted, the local machine will be used.
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   Returns &true; if the service exists, &false; if it does not exist.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simpara>
+    A <exceptionname>ValueError</exceptionname> is thrown if the
+    value of <parameter>servicename</parameter> parameter is empty.
+  </simpara>
+  <simpara>
+    A <exceptionname>Win32ServiceException</exceptionname> is thrown on any
+    other error, for example when the caller does not have administrative privileges.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>A <function>win32_exists_service</function> example</title>
+    <simpara>
+     Creates the dummyphp service only if it does not already exist.
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+if (!win32_exists_service('dummyphp')) {
+    win32_create_service([
+        'service' => 'dummyphp',
+        'display' => 'sample dummy PHP service',
+        'params'  => __FILE__ . ' run',
+    ]);
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>win32_create_service</function></member>
+    <member><function>win32_delete_service</function></member>
+    <member><link linkend="win32service.constants.errors">Win32 Error Codes</link></member>
+   </simplelist>
+  </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:"~/.phpdoc/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
+-->

reference/win32service/functions/win32-get-last-control-message.xml

@@ -20,8 +20,10 @@
 
   <caution>
    <simpara>
-    Since version 0.2.0, this function work only in "cli" SAPI. On other SAPI
-    this function is disabled.
+    Since version 1.1.0, this function works only when PHP runs in a Windows service context
+    (see the <literal>Run in Windows Service context</literal> line in the <function>phpinfo</function> output),
+    or when the <literal>"embed"</literal> SAPI is used. Running a CLI script from a console is not enough.
+    In other cases this function is disabled and throws a <exceptionname>Win32ServiceException</exceptionname>.
    </simpara>
   </caution>
 
@@ -67,7 +69,12 @@
    <simpara>
     As of version 1.0.0, will throw a
     <exceptionname>Win32ServiceException</exceptionname> if SAPI is not
-    <literal>"cli"</literal>
+    <literal>"cli"</literal>. As of version 1.0.1, the <literal>"embed"</literal> SAPI is also accepted.
+   </simpara>
+   <simpara>
+    As of version 1.1.0, will throw a
+    <exceptionname>Win32ServiceException</exceptionname> if PHP does not run in a Windows service context,
+    unless the SAPI is <literal>"embed"</literal>.
    </simpara>
  </refsect1>
 
@@ -83,6 +90,19 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL win32service 1.1.0</entry>
+       <entry>
+        The function is disabled unless PHP runs in a Windows service context,
+        instead of only depending on the <literal>"cli"</literal> SAPI.
+       </entry>
+      </row>
+      <row>
+       <entry>PECL win32service 1.0.1</entry>
+       <entry>
+        The <literal>"embed"</literal> SAPI is also accepted.
+       </entry>
+      </row>
       <row>
        <entry>PECL win32service 1.0.0</entry>
        <entry>

reference/win32service/functions/win32-pause-service.xml

@@ -11,7 +11,7 @@
   <methodsynopsis>
    <type>void</type><methodname>win32_pause_service</methodname>
    <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
   </methodsynopsis>
 
   <simpara>

reference/win32service/functions/win32-query-service-status.xml

@@ -11,7 +11,7 @@
   <methodsynopsis>
    <type>array</type><methodname>win32_query_service_status</methodname>
    <methodparam><type>string</type><parameter>servicename</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&quot;&quot;</initializer></methodparam>
   </methodsynopsis>
 
   <simpara>