Регистрирует скрипт в Диспетчере управления службами, чтобы он действовал как служба с заданным именем

# win32_start_service_ctrl_dispatcher

(PECL win32service >=0.1.0)

win32_start_service_ctrl_dispatcher — Регистрирует скрипт в Диспетчере управления службами, чтобы он действовал как служба с заданным именем

### Описание

function win32_start_service_ctrl_dispatcher(string `$name`, bool `$gracefulMode` = true): void

При запуске через Диспетчер управления службами (англ. Service Control Manager, SCM) процессу службы требуется «отметиться» в диспетчере, чтобы установить средства мониторинга службы и связи с ней. Функция выполняет такую регистрацию, для чего создаёт поток для обработки низкоуровневой связи с Диспетчером управления службами.

После запуска процесс службы выполняет два действия. Первое — сообщает Диспетчеру управления службами, что служба запустилась. Для этого вызывают функцию win32_set_service_status() с константой `WIN32_SERVICE_RUNNING`. Функцию вызывают с константой `WIN32_SERVICE_START_PENDING`, когда требуется выполнить какой-то длительный процесс до фактического запуска службы. Второе — продолжает «отмечаться» в Диспетчере управления службами, чтобы диспетчер определял, требуется ли прекратить работу службы. Для этого периодически вызывают функцию win32_get_last_control_message() и правильно обрабатывают кода возврата.

Предостережение

С версии 0.2.0 функция работает только через SAPI-интерфейс CLI. Через другие SAPI-интерфейсы функция не работает.

### Список параметров

`name`

  Короткое имя службы, которое зарегистрировали функцией win32_create_service().

`gracefulMode`

  Значение `true` указывают для изящного выхода, а значение `false` для выхода с ошибкой. Описание функции win32_set_service_exit_mode() даёт больше информации о режимах выхода.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

До версии 1.0.0 Функция возвращает `WIN32_NO_ERROR` в случае успешного завершения , `false`, если возникла проблема с параметрами, или код ошибки Win32, если возникла ошибка.

### Ошибки

До версии 1.0.0 при вызове не через SAPI-интерфейс `CLI` функция выдаёт ошибку уровня `E_ERROR`.

С версии 1.0.0 при вызове не через SAPI-интерфейс CLI функция выбрасывает исключение Win32ServiceException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль win32service 1.0.0 | Функция выбрасывает исключение ValueError при недопустимых данных в параметрах, раньше возвращалось `false`.
PECL-модуль win32service 1.0.0 | Функция выбрасывает исключение Win32ServiceException, если возникла ошибка, раньше возвращался код ошибки Win32.
PECL-модуль win32service 1.0.0 | Тип значения, которое возвращает функция, теперь void, раньше был mixed.
PECL win32service 0.4.0 | Добавили параметр `gracefulMode`.
PECL win32service 0.2.0 | Функция работает только через SAPI-интерфейс `CLI`.

### Примеры

Пример #1 Пример использования функции win32_start_service_ctrl_dispatcher()

Проверим, запустили ли сервис в Диспетчере управления службами.

    <?php

    if (!win32_start_service_ctrl_dispatcher('dummyphp')) {
        die("Меня, вероятно, не запустили в Диспетчере управления службами");
    }

    win32_set_service_status(WIN32_SERVICE_START_PENDING);

    // Какой-то длительный процесс для обработки и запуска службы

    win32_set_service_status(WIN32_SERVICE_RUNNING);

    while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) {
        # Здесь выполняются какие-то действия, которые не занимают больше 30 секунд
        # перед переходом в цикл
    }

    ?>

### Смотрите также

- win32_set_service_status() - Обновляет статус службы
- win32_get_last_control_message() - Возвращает последнее управляющее сообщение, которое отправили этой службе
- win32_set_service_exit_mode() - Определяет или возвращает режим выхода для текущей запущенной службы
- win32_set_service_exit_code() - Определяет или возвращает код выхода для текущей запущенной службы
- Коды Ошибок Win32

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open