lpContext — определяемые пользователем данные, передаваемые обработчику. Благодаря этому обработчик может различать ассоциированные с ним службы, которых может быть несколько.
В случае ошибки возвращаемое функцией значение, которым является объект SEPARARE_STATUS_HANDLE, равно 0, а для анализа ошибок могут быть использованы обычные методы.
Настройка состояния службы
Теперь, когда управляющая программа зарегистрирована, необходимо сразу же перевести службу в состояние SERVICE_START_PENDING, воспользовавшись для этого функцией SetServiceStatus. Функция SetServiceStatus будет применяться еще в других местах для установки различных значений параметра состояния, информируя SCM о текущем состоянии службы. Описания других возможных состояний службы, характеризуемых значениями параметра состояния, отличными от SERVICE_STATUS_PENDING, приведены в табл. 13.3.
Обработчик службы должен устанавливать состояние службы при каждом вызове, даже если ее состояние не менялось.
Далее, любой из потоков службы может в любой момент вызвать функцию SetServiceStatus, чтобы сообщить данные, характеризующие степень выполнения задачи, а также предоставить информацию об ошибках или иную информацию, причем для периодического обновления состояния многие службы часто выделяют отдельный поток. Длительность временного промежутка между вызовами обновления состояния указывается в одном из полей структуры данных, выступающей в качестве параметра. Если в пределах указанного промежутка времени состояние не обновлялось, то SCM может предположить, что произошла ошибка.
BOOL SetServiceStatus(SERVICE_STATUS_HANDLE hServiceStatus, LPSERVICE STATUS lpServiceStatus)
ПараметрыhServiceStatus — дескриптор типа SERVICE_STATUS_HANDLE, возвращенный функцией RegisterCtrlHandlerEx. Поэтому вызову функции SetServiceStatus должен предшествовать вызов функции RegisterCtrlHandlerEx.
lpServiceStatus — указатель на структуру SERVICE_STATUS, содержащую описание свойств, состояния и возможностей службы.
Структура SERVICE_STATUS
Ниже приведено определение структуры SERVICE_STATUS.
typedef struct _SERVICE_STATUS {
DWORD dwServiceType;
DWORD dwCurrentState;
DWORD dwControlsAccepted;
DWORD dwWin32ExitCode;
DWORD dwServiceSpecificExitCode;
DWORD dwCheckPoint;
DWORD dwWaitHint;
} SERVICE_STATUS, *LPSERVICE_STATUS;
ПараметрыdwWin32ExitCode — обычный код завершения потока, используемый логической службой. Служба должна установить этот код равным NO_ERROR в процессе выполнения и при нормальном завершении.
dwServiceSpecificExitCode — может использоваться в качестве кода завершения, когда ошибка возникает при запуске или остановке службы, но это значение игнорируется, если значение параметра dwWin32ExitCode не было установлено равным ERROR_SERVICE_SPECIFIC_ERROR.
dwCheckPoint — служба должна периодически увеличивать значение этого параметра для индикации выполнения на всех стадиях, включая стадии инициализации и остановки. Этот параметр не действует и должен устанавливаться равным 0, если служба не находится в состоянии запуска, остановки, паузы и не выполняет никаких длительных операций.
dwWaitHint — ожидаемая длительность интервалов времени (в миллисекундах) между последовательными вызовами функции SetServiceStatus, осуществляемыми с увеличенным значением параметра dwCheckPoint или измененным значением параметра dwCurrentState. Как уже отмечалось ранее, если на протяжении этого промежутка времени вызова функции SetServiceStatus не происходит, то SCM предполагает, что это вызвано возникновением ошибки.
Остальные элементы структуры SERVICE_STATUS обсуждаются ниже по отдельности.
Тип службыПараметр dwServiceType должен иметь одно из значений, описанных в таблице 13.1.
В наших примерах в качестве типа службы почти всегда будет предполагаться тип SERVICE_WIN32_OWN_PROCESS, но из приведенных в таблице значений видно, что службы могут играть множество различных ролей.
Таблица 13.1. Типы служб
Значение Описание SERVICE WIN32 OWN PROCESS Указывает на службу Windows, выполняющуюся в собственном процессе с собственными ресурсами. Используется в программе 13.2. SERVICE_WIN32_SHARE_PROCESS Указывает на службу Windows, разделяющую процесс с другими службами, в результате чего несколько служб могут совместно использовать одни и те же ресурсы, переменные окружения и так далее. SERVICE_KERNEL_DRIVER Указывает на драйвер устройства Windows. SERVICE_FILE_SYSTEM_DRIVER Определяет драйвер файловой системы Windows. SERVICE_INTERACTIVE_PROCESS Указывает на процесс службы Windows, который может взаимодействовать с пользователем через рабочий стол. Состояние службыЗначение параметра dwCurrentState указывает на текущее состояние службы. Возможные значения этого параметра перечислены в табл. 13.2.