diff --git a/reference/win32service/functions/win32-add-right-access-service.xml b/reference/win32service/functions/win32-add-right-access-service.xml index 3aa55e3f9..0760bda0c 100644 --- a/reference/win32service/functions/win32-add-right-access-service.xml +++ b/reference/win32service/functions/win32-add-right-access-service.xml @@ -14,7 +14,7 @@ stringservicename stringusername intright - stringmachine&null; + stringmachine"" Add the rights access for username on servicename @@ -67,7 +67,7 @@ &reftitle.returnvalues; - Return a Win32Service\RightInfo object. + &return.void; @@ -75,11 +75,16 @@ &reftitle.errors; A ValueError is thrown if the - value of service parameter is empty. + value of service parameter is empty or shorter than 2 characters. A ValueError is thrown if the - value of username parameter is empty. + value of username parameter is empty or shorter than 2 characters. + + + A ValueError is thrown if the + value of right parameter is not a positive combination of the + service rights constants. A Win32ServiceException is thrown on error. diff --git a/reference/win32service/functions/win32-add-service-env-var.xml b/reference/win32service/functions/win32-add-service-env-var.xml index be2157a24..5935b89c5 100644 --- a/reference/win32service/functions/win32-add-service-env-var.xml +++ b/reference/win32service/functions/win32-add-service-env-var.xml @@ -12,11 +12,11 @@ voidwin32_add_service_env_var stringservicename - stringvarname - stringvalue + stringvarName + stringvarValue - Add a custom environment variables varname on servicename + Add a custom environment variables varName on servicename service. This function work only for the local computer. Administrative privileges are required for this to succeed. @@ -34,7 +34,7 @@ - varname + varName The environment variable name. @@ -42,7 +42,7 @@ - value + varValue The environment variable value. @@ -68,7 +68,7 @@ A ValueError is thrown if the - value of varname parameter is empty. + value of varName parameter is empty. A Win32ServiceException is thrown on error. diff --git a/reference/win32service/functions/win32-continue-service.xml b/reference/win32service/functions/win32-continue-service.xml index 0c25803a7..47086dd47 100644 --- a/reference/win32service/functions/win32-continue-service.xml +++ b/reference/win32service/functions/win32-continue-service.xml @@ -11,7 +11,7 @@ voidwin32_continue_service stringservicename - stringmachine&null; + stringmachine"" diff --git a/reference/win32service/functions/win32-create-service.xml b/reference/win32service/functions/win32-create-service.xml index e1915781c..b9211a620 100644 --- a/reference/win32service/functions/win32-create-service.xml +++ b/reference/win32service/functions/win32-create-service.xml @@ -12,7 +12,7 @@ voidwin32_create_service arraydetails - stringmachine&null; + stringmachine"" Attempts to add a service into the SCM database. Administrative @@ -72,6 +72,7 @@ The password that corresponds to the user. + If omitted, the default value is an empty string. @@ -80,8 +81,7 @@ 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. @@ -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 ". + If omitted, the default value is an empty string. @@ -113,6 +114,12 @@ WIN32_SERVICE_WIN32_OWN_PROCESS. Don't change this unless you know what you're doing. + + The accepted values are WIN32_SERVICE_WIN32_OWN_PROCESS, + WIN32_SERVICE_INTERACTIVE_PROCESS and + WIN32_SERVICE_WIN32_OWN_PROCESS_INTERACTIVE. + Any other value throws a ValueError. + @@ -131,7 +138,7 @@ Informs the SCM what it should do when it detects a problem with the service. The default is - WIN32_SERVER_ERROR_IGNORE. Changing this + WIN32_SERVICE_ERROR_IGNORE. Changing this value is not yet fully supported. @@ -167,6 +174,7 @@ The base_priority can be set to one of the constants define in Win32 Base Priority Classes. + If omitted, the default value is WIN32_NORMAL_PRIORITY_CLASS. @@ -304,13 +312,17 @@ &reftitle.errors; + + A ValueError is thrown if the value of one + of the string keys of details contains a null byte. + A ValueError is thrown if the - value of service parameter is empty. + value of service key is empty or shorter than 2 characters. A ValueError is thrown if the - value of path parameter is missing or empty. + value of path key is missing. A ValueError is thrown if the @@ -486,6 +498,7 @@ debug_zval_dump($x); win32_delete_service + win32_exists_service Win32 Base Priority Classes Win32 Recovery action Win32 Error Codes diff --git a/reference/win32service/functions/win32-delete-service.xml b/reference/win32service/functions/win32-delete-service.xml index 018131dc2..a3cb90ff1 100644 --- a/reference/win32service/functions/win32-delete-service.xml +++ b/reference/win32service/functions/win32-delete-service.xml @@ -11,7 +11,7 @@ voidwin32_delete_service stringservicename - stringmachine&null; + stringmachine"" @@ -138,6 +138,7 @@ win32_delete_service('dummyphp'); win32_create_service + win32_exists_service Win32 Error Codes diff --git a/reference/win32service/functions/win32-exists-service.xml b/reference/win32service/functions/win32-exists-service.xml new file mode 100644 index 000000000..4e9847fec --- /dev/null +++ b/reference/win32service/functions/win32-exists-service.xml @@ -0,0 +1,130 @@ + + + + + + win32_exists_service + Checks if a service entry exists in the SCM database + + + &reftitle.description; + + boolwin32_exists_service + stringservicename + stringmachine"" + + + + Checks whether a service exists in the SCM database. + + + + Administrative privileges are required, as the Service Control Manager is + opened with full access and the service with the DELETE + access right. Without them, a Win32ServiceException + is thrown (access denied) instead of returning &false;. + + + + + + &reftitle.parameters; + + + + servicename + + + The short name of the service. + + + + + machine + + + The optional machine name. If omitted, the local machine will be used. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the service exists, &false; if it does not exist. + + + + + &reftitle.errors; + + A ValueError is thrown if the + value of servicename parameter is empty. + + + A Win32ServiceException is thrown on any + other error, for example when the caller does not have administrative privileges. + + + + + &reftitle.examples; + + + A <function>win32_exists_service</function> example + + Creates the dummyphp service only if it does not already exist. + + + 'dummyphp', + 'display' => 'sample dummy PHP service', + 'params' => __FILE__ . ' run', + ]); +} +?> +]]> + + + + + + + &reftitle.seealso; + + + win32_create_service + win32_delete_service + Win32 Error Codes + + + + + + + diff --git a/reference/win32service/functions/win32-get-last-control-message.xml b/reference/win32service/functions/win32-get-last-control-message.xml index 6e671aca8..f9acdd041 100644 --- a/reference/win32service/functions/win32-get-last-control-message.xml +++ b/reference/win32service/functions/win32-get-last-control-message.xml @@ -20,8 +20,10 @@ - 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 Run in Windows Service context line in the phpinfo output), + or when the "embed" SAPI is used. Running a CLI script from a console is not enough. + In other cases this function is disabled and throws a Win32ServiceException. @@ -67,7 +69,12 @@ As of version 1.0.0, will throw a Win32ServiceException if SAPI is not - "cli" + "cli". As of version 1.0.1, the "embed" SAPI is also accepted. + + + As of version 1.1.0, will throw a + Win32ServiceException if PHP does not run in a Windows service context, + unless the SAPI is "embed". @@ -83,6 +90,19 @@ + + PECL win32service 1.1.0 + + The function is disabled unless PHP runs in a Windows service context, + instead of only depending on the "cli" SAPI. + + + + PECL win32service 1.0.1 + + The "embed" SAPI is also accepted. + + PECL win32service 1.0.0 diff --git a/reference/win32service/functions/win32-pause-service.xml b/reference/win32service/functions/win32-pause-service.xml index 52560a9a0..42899e14b 100644 --- a/reference/win32service/functions/win32-pause-service.xml +++ b/reference/win32service/functions/win32-pause-service.xml @@ -11,7 +11,7 @@ voidwin32_pause_service stringservicename - stringmachine&null; + stringmachine"" diff --git a/reference/win32service/functions/win32-query-service-status.xml b/reference/win32service/functions/win32-query-service-status.xml index 4b6498e66..940b8a5d0 100644 --- a/reference/win32service/functions/win32-query-service-status.xml +++ b/reference/win32service/functions/win32-query-service-status.xml @@ -11,7 +11,7 @@ arraywin32_query_service_status stringservicename - stringmachine&null; + stringmachine"" diff --git a/reference/win32service/functions/win32-read-all-rights-access-service.xml b/reference/win32service/functions/win32-read-all-rights-access-service.xml index 6c11621ed..0c167eac9 100644 --- a/reference/win32service/functions/win32-read-all-rights-access-service.xml +++ b/reference/win32service/functions/win32-read-all-rights-access-service.xml @@ -12,7 +12,7 @@ arraywin32_read_all_rights_access_service stringservicename - stringmachine&null; + stringmachine"" Read all rights access on servicename @@ -56,7 +56,7 @@ &reftitle.errors; A ValueError is thrown if the - value of service parameter is empty. + value of service parameter is empty or shorter than 2 characters. A Win32ServiceException is thrown on error. diff --git a/reference/win32service/functions/win32-read-right-access-service.xml b/reference/win32service/functions/win32-read-right-access-service.xml index fb380a5cb..7d03f315b 100644 --- a/reference/win32service/functions/win32-read-right-access-service.xml +++ b/reference/win32service/functions/win32-read-right-access-service.xml @@ -13,7 +13,7 @@ Win32Service\RightInfowin32_read_right_access_service stringservicename stringusername - stringmachine&null; + stringmachine"" Read the rights access for username on servicename @@ -65,11 +65,11 @@ &reftitle.errors; A ValueError is thrown if the - value of service parameter is empty. + value of service parameter is empty or shorter than 2 characters. A ValueError is thrown if the - value of username parameter is empty. + value of username parameter is empty or shorter than 2 characters. A Win32ServiceException is thrown on error. diff --git a/reference/win32service/functions/win32-remove-right-access-service.xml b/reference/win32service/functions/win32-remove-right-access-service.xml index b435d9bd4..53b008c96 100644 --- a/reference/win32service/functions/win32-remove-right-access-service.xml +++ b/reference/win32service/functions/win32-remove-right-access-service.xml @@ -13,7 +13,7 @@ voidwin32_remove_right_access_service stringservicename stringusername - stringmachine&null; + stringmachine"" Remove the rights access for username on servicename @@ -65,11 +65,11 @@ &reftitle.errors; A ValueError is thrown if the - value of service parameter is empty. + value of service parameter is empty or shorter than 2 characters. A ValueError is thrown if the - value of username parameter is empty. + value of username parameter is empty or shorter than 2 characters. A Win32ServiceException is thrown on error. diff --git a/reference/win32service/functions/win32-remove-service-env-var.xml b/reference/win32service/functions/win32-remove-service-env-var.xml index 43b34d271..7597661db 100644 --- a/reference/win32service/functions/win32-remove-service-env-var.xml +++ b/reference/win32service/functions/win32-remove-service-env-var.xml @@ -12,10 +12,10 @@ voidwin32_remove_service_env_var stringservicename - stringvarname + stringvarName - Remove a custom environment variables varname on servicename + Remove a custom environment variables varName on servicename service. This function work only for the local computer. Administrative privileges are required for this to succeed. @@ -33,7 +33,7 @@ - varname + varName The environment variable name. @@ -59,7 +59,7 @@ A ValueError is thrown if the - value of varname parameter is empty. + value of varName parameter is empty. A Win32ServiceException is thrown on error. diff --git a/reference/win32service/functions/win32-send-custom-control.xml b/reference/win32service/functions/win32-send-custom-control.xml index 309ce671d..e205f4af9 100644 --- a/reference/win32service/functions/win32-send-custom-control.xml +++ b/reference/win32service/functions/win32-send-custom-control.xml @@ -13,7 +13,7 @@ voidwin32_send_custom_control stringservicename intcontrol - stringmachine&null; + stringmachine"" diff --git a/reference/win32service/functions/win32-set-service-exit-code.xml b/reference/win32service/functions/win32-set-service-exit-code.xml index 21d0bf825..0ad7d2f65 100644 --- a/reference/win32service/functions/win32-set-service-exit-code.xml +++ b/reference/win32service/functions/win32-set-service-exit-code.xml @@ -11,7 +11,7 @@ &reftitle.description; intwin32_set_service_exit_code - intexitCode1 + intexitCode0 Change or return the exit code. The exit code is used only if the exit mode is not graceful. @@ -23,8 +23,10 @@ - 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 Run in Windows Service context line in the phpinfo output), + or when the "embed" SAPI is used. Running a CLI script from a console is not enough. + In other cases this function is disabled and throws a Win32ServiceException. @@ -59,7 +61,12 @@ As of version 1.0.0, will throw a Win32ServiceException if SAPI is not - "cli" + "cli". As of version 1.0.1, the "embed" SAPI is also accepted. + + + As of version 1.1.0, will throw a + Win32ServiceException if PHP does not run in a Windows service context, + unless the SAPI is "embed". @@ -75,6 +82,19 @@ + + PECL win32service 1.1.0 + + The function is disabled unless PHP runs in a Windows service context, + instead of only depending on the "cli" SAPI. + + + + PECL win32service 1.0.1 + + The "embed" SAPI is also accepted. + + PECL win32service 1.0.0 diff --git a/reference/win32service/functions/win32-set-service-exit-mode.xml b/reference/win32service/functions/win32-set-service-exit-mode.xml index be4fffadd..e5c4253bc 100644 --- a/reference/win32service/functions/win32-set-service-exit-mode.xml +++ b/reference/win32service/functions/win32-set-service-exit-mode.xml @@ -11,18 +11,20 @@ &reftitle.description; boolwin32_set_service_exit_mode - boolgracefulModetrue + boolgracefulExittrue - If gracefulMode parameter is provided, the exit mode + If gracefulExit parameter is provided, the exit mode is changed. When the exit mode is not graceful, the exit code used can be set with the win32_set_service_exit_code function. - 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 Run in Windows Service context line in the phpinfo output), + or when the "embed" SAPI is used. Running a CLI script from a console is not enough. + In other cases this function is disabled and throws a Win32ServiceException. @@ -31,7 +33,7 @@ with the win32_set_service_exit_code function. &reftitle.parameters; - gracefulMode + gracefulExit &true; for exit graceful. &false; for exit with error. @@ -58,7 +60,12 @@ with the win32_set_service_exit_code function. As of version 1.0.0, will throw a Win32ServiceException if SAPI is not - "cli" + "cli". As of version 1.0.1, the "embed" SAPI is also accepted. + + + As of version 1.1.0, will throw a + Win32ServiceException if PHP does not run in a Windows service context, + unless the SAPI is "embed". @@ -75,6 +82,19 @@ with the win32_set_service_exit_code function. + + PECL win32service 1.1.0 + + The function is disabled unless PHP runs in a Windows service context, + instead of only depending on the "cli" SAPI. + + + + PECL win32service 1.0.1 + + The "embed" SAPI is also accepted. + + PECL win32service 1.0.0 diff --git a/reference/win32service/functions/win32-set-service-pause-resume-state.xml b/reference/win32service/functions/win32-set-service-pause-resume-state.xml index 2ef14941e..4feabaaf5 100644 --- a/reference/win32service/functions/win32-set-service-pause-resume-state.xml +++ b/reference/win32service/functions/win32-set-service-pause-resume-state.xml @@ -11,17 +11,19 @@ &reftitle.description; boolwin32_set_service_pause_resume_state - boolstatetrue + boolenabletrue - If state parameter is provided, the pause/resume capability + If enable parameter is provided, the pause/resume capability is changed. - This function work only in "cli" SAPI and in the Windows service running context. 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 Run in Windows Service context line in the phpinfo output), + or when the "embed" SAPI is used. Running a CLI script from a console is not enough. + In other cases this function is disabled and throws a Win32ServiceException. @@ -30,11 +32,15 @@ is changed. &reftitle.parameters; - state + enable &true; for enable the service pause/resume capability. &false; for disable the service pause/resume capability. + + The capability can only be changed before win32_start_service_ctrl_dispatcher is called. + Once the control dispatcher is running, call this function without argument to read the current state. + @@ -49,6 +55,11 @@ is changed. &reftitle.errors; + + A ValueError is thrown if enable is provided + while the control dispatcher is already running. Call this function before + win32_start_service_ctrl_dispatcher, or without argument to read the state. + Prior to version 1.0.0, if the SAPI is not "cli", this function emits an E_ERROR level error. @@ -57,7 +68,12 @@ is changed. As of version 1.0.0, will throw a Win32ServiceException if SAPI is not - "cli" + "cli". As of version 1.0.1, the "embed" SAPI is also accepted. + + + As of version 1.1.0, will throw a + Win32ServiceException if PHP does not run in a Windows service context, + unless the SAPI is "embed". @@ -74,6 +90,19 @@ is changed. + + PECL win32service 1.1.0 + + The function is disabled unless PHP runs in a Windows service context, + instead of only depending on the "cli" SAPI. + + + + PECL win32service 1.0.1 + + The "embed" SAPI is also accepted. + + PECL win32service 1.0.0 diff --git a/reference/win32service/functions/win32-set-service-status.xml b/reference/win32service/functions/win32-set-service-status.xml index 1a575e8c6..1419ccf1b 100644 --- a/reference/win32service/functions/win32-set-service-status.xml +++ b/reference/win32service/functions/win32-set-service-status.xml @@ -9,7 +9,7 @@ &reftitle.description; - voidwin32_set_service_status + boolwin32_set_service_status intstatus intcheckpoint0 @@ -20,8 +20,10 @@ - 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 Run in Windows Service context line in the phpinfo output), + or when the "embed" SAPI is used. Running a CLI script from a console is not enough. + In other cases this function is disabled and throws a Win32ServiceException. @@ -71,10 +73,7 @@ &reftitle.returnvalues; - &return.void; - - - Prior to version 1.0.0, &win32service.noerror.false.error; + Returns &true; on success. A Win32ServiceException is thrown on error. @@ -87,7 +86,12 @@ As of version 1.0.0, will throw a Win32ServiceException if SAPI is not - "cli" + "cli". As of version 1.0.1, the "embed" SAPI is also accepted. + + + As of version 1.1.0, will throw a + Win32ServiceException if PHP does not run in a Windows service context, + unless the SAPI is "embed". @@ -103,6 +107,19 @@ + + PECL win32service 1.1.0 + + The function is disabled unless PHP runs in a Windows service context, + instead of only depending on the "cli" SAPI. + + + + PECL win32service 1.0.1 + + The "embed" SAPI is also accepted. + + PECL win32service 1.0.0 @@ -119,12 +136,6 @@ was returned. - - PECL win32service 1.0.0 - - The return type is now void, previously it was mixed. - - PECL win32service 0.2.0 diff --git a/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml b/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml index 7bed1e75b..685ba1b82 100644 --- a/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml +++ b/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml @@ -9,9 +9,9 @@ &reftitle.description; - voidwin32_start_service_ctrl_dispatcher + boolwin32_start_service_ctrl_dispatcher stringname - boolgracefulModetrue + boolgracefulExittrue @@ -36,8 +36,10 @@ - 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 Run in Windows Service context line in the phpinfo output), + or when the "embed" SAPI is used. Running a CLI script from a console is not enough. + In other cases this function is disabled and throws a Win32ServiceException. @@ -56,7 +58,7 @@ - gracefulMode + gracefulExit &true; for exit graceful. &false; for exit with error. See @@ -71,10 +73,7 @@ &reftitle.returnvalues; - &return.void; - - - Prior to version 1.0.0, &win32service.noerror.false.error; + Returns &true; when the control dispatcher has started successfully, or &false; if it did not signal readiness within 30 seconds. A Win32ServiceException is thrown on error. @@ -87,7 +86,12 @@ As of version 1.0.0, will throw a Win32ServiceException if SAPI is not - "cli" + "cli". As of version 1.0.1, the "embed" SAPI is also accepted. + + + As of version 1.1.0, will throw a + Win32ServiceException if PHP does not run in a Windows service context, + unless the SAPI is "embed". @@ -103,6 +107,19 @@ + + PECL win32service 1.1.0 + + The function is disabled unless PHP runs in a Windows service context, + instead of only depending on the "cli" SAPI. + + + + PECL win32service 1.0.1 + + The "embed" SAPI is also accepted. + + PECL win32service 1.0.0 @@ -119,16 +136,10 @@ was returned. - - PECL win32service 1.0.0 - - The return type is now void, previously it was mixed. - - PECL win32service 0.4.0 - The parameter gracefulMode has been added. + The parameter gracefulExit has been added. diff --git a/reference/win32service/functions/win32-start-service.xml b/reference/win32service/functions/win32-start-service.xml index a17c0b70e..d91a3d352 100644 --- a/reference/win32service/functions/win32-start-service.xml +++ b/reference/win32service/functions/win32-start-service.xml @@ -11,7 +11,7 @@ voidwin32_start_service stringservicename - stringmachine&null; + stringmachine"" diff --git a/reference/win32service/functions/win32-stop-service.xml b/reference/win32service/functions/win32-stop-service.xml index c6ac64eab..fd9ab5a44 100644 --- a/reference/win32service/functions/win32-stop-service.xml +++ b/reference/win32service/functions/win32-stop-service.xml @@ -11,7 +11,7 @@ voidwin32_stop_service stringservicename - stringmachine&null; + stringmachine"" diff --git a/reference/win32service/setup.xml b/reference/win32service/setup.xml index df427fee8..5afcdef51 100644 --- a/reference/win32service/setup.xml +++ b/reference/win32service/setup.xml @@ -28,6 +28,18 @@ + +
+ &reftitle.runtime; + + This extension has no &php.ini; directive. As of Win32Service 1.1.0, some functions are disabled + if PHP does not run in a Windows service context (or with the "embed" SAPI). + The state is displayed by phpinfo in the Run in Windows Service context line + of the win32service section. + +
+ +
Security consideration diff --git a/reference/win32service/versions.xml b/reference/win32service/versions.xml index 02c53cf8f..63eb3cc3a 100644 --- a/reference/win32service/versions.xml +++ b/reference/win32service/versions.xml @@ -19,10 +19,12 @@ + + diff --git a/reference/win32service/win32servicerightinfo.xml b/reference/win32service/win32servicerightinfo.xml index 74ac3d6cb..358a314ed 100644 --- a/reference/win32service/win32servicerightinfo.xml +++ b/reference/win32service/win32servicerightinfo.xml @@ -30,6 +30,7 @@ final + readonly Win32Service\RightInfo