Поделиться через

Класс CAtlServiceModuleT

  • Статья

Этот класс реализует службу.

Внимание

Этот класс и его члены нельзя использовать в приложениях, выполняемых в среде выполнения Windows.

Синтаксис

template <class T, UINT nServiceNameID>
class ATL_NO_VTABLE CAtlServiceModuleT : public CAtlExeModuleT<T>

Параметры

T
Класс, производный от CAtlServiceModuleT.

nServiceNameID
Идентификатор ресурса службы.

Участники

Открытые конструкторы

Имя Описание
CAtlServiceModuleT::CAtlServiceModuleT Конструктор.

Открытые методы

Имя Описание
CAtlServiceModuleT::Handler Подпрограмма обработчика для службы.
CAtlServiceModuleT::InitializeSecurity Предоставляет параметры безопасности по умолчанию для службы.
CAtlServiceModuleT::Install Устанавливает и создает службу.
CAtlServiceModuleT::IsInstalled Подтверждает, что служба установлена.
CAtlServiceModuleT::LogEvent Записывает в журнал событий.
CAtlServiceModuleT::OnContinue Переопределите этот метод, чтобы продолжить службу.
CAtlServiceModuleT::OnInterrogate Переопределите этот метод для допроса службы.
CAtlServiceModuleT::OnPause Переопределите этот метод, чтобы приостановить работу службы.
CAtlServiceModuleT::OnShutdown Переопределите этот метод, чтобы завершить работу службы
CAtlServiceModuleT::OnStop Переопределите этот метод, чтобы остановить службу
CAtlServiceModuleT::OnUnknownRequest Переопределите этот метод для обработки неизвестных запросов к службе
CAtlServiceModuleT::P arseCommandLine Анализирует командную строку и выполняет регистрацию при необходимости.
CAtlServiceModuleT::P reMessageLoop Этот метод вызывается непосредственно перед вводом цикла сообщений.
CAtlServiceModuleT::RegisterAppId Регистрирует службу в реестре.
CAtlServiceModuleT::Run Запускает службу.
CAtlServiceModuleT::ServiceMain Метод, вызываемый диспетчером управления службой.
CAtlServiceModuleT::SetServiceStatus Обновляет состояние службы.
CAtlServiceModuleT::Start CAtlServiceModuleT::WinMain Вызывается при запуске службы.
CAtlServiceModuleT::Uninstall Останавливает и удаляет службу.
CAtlServiceModuleT::Unlock Уменьшает количество блокировок службы.
CAtlServiceModuleT::UnregisterAppId Удаляет службу из реестра.
CAtlServiceModuleT::WinMain Этот метод реализует код, необходимый для запуска службы.

Открытые члены данных

Имя Описание
CAtlServiceModuleT::m_bService Флаг, указывающий, что программа выполняется как услуга.
CAtlServiceModuleT::m_dwThreadID Переменная-член, сохраняющая идентификатор потока.
CAtlServiceModuleT::m_hServiceStatus Переменная-член, сохраняющая дескриптор в структуре сведений о состоянии текущей службы.
CAtlServiceModuleT::m_status Переменная-член, сохраняющая структуру сведений о состоянии для текущей службы.
CAtlServiceModuleT::m_szServiceName Имя зарегистрированной службы.

Замечания

CAtlServiceModuleT, производный от CAtlExeModuleT, реализует модуль службы ATL. CAtlServiceModuleT предоставляет методы для обработки командной строки, установки, регистрации и удаления. Если требуется дополнительная функциональность, эти и другие методы можно переопределить.

Этот класс заменяет устаревший класс CComModule, используемый в более ранних версиях ATL. Дополнительные сведения см. в разделе "Классы модулей ATL".

Иерархия наследования

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

Требования

Заголовок: atlbase.h

CAtlServiceModuleT::CAtlServiceModuleT

Конструктор.

CAtlServiceModuleT() throw();

Замечания

Инициализирует элементы данных и задает начальное состояние службы.

CAtlServiceModuleT::Handler

Подпрограмма обработчика для службы.

void Handler(DWORD dwOpcode) throw();

Параметры

dwOpcode
Переключатель, определяющий операцию обработчика. Дополнительные сведения см. в примечаниях.

Замечания

Это код, который вызывает диспетчер управления службой (SCM), чтобы получить состояние службы и инструкции по проблеме, такие как остановка или приостановка. SCM передает код операции, показанный ниже, чтобы Handler указать, что должна делать служба.

Код операции Значение
SERVICE_CONTROL_STOP останавливает службу. Переопределите метод CAtlServiceModuleT::OnStop в atlbase.h, чтобы изменить поведение.
SERVICE_CONTROL_PAUSE Пользователь реализован. Переопределите пустой метод CAtlServiceModuleT::OnPause в atlbase.h, чтобы приостановить работу службы.
SERVICE_CONTROL_CONTINUE Пользователь реализован. Переопределите пустой метод CAtlServiceModuleT::OnContinue в atlbase.h, чтобы продолжить службу.
SERVICE_CONTROL_INTERROGATE Пользователь реализован. Переопределите пустой метод CAtlServiceModuleT::OnInterrogate в atlbase.h для допроса службы.
SERVICE_CONTROL_SHUTDOWN Пользователь реализован. Переопределите пустой метод CAtlServiceModuleT::OnShutdown в atlbase.h, чтобы завершить работу службы.

Если код операции не распознается, вызывается метод CAtlServiceModuleT::OnUnknownRequest .

Созданная по умолчанию служба ATL обрабатывает только инструкцию остановки. Если SCM передает инструкцию остановки, служба сообщает SCM, что программа будет остановиться. Затем служба вызывает PostThreadMessage сообщение о выходе из себя. Это завершает цикл сообщений, и служба в конечном итоге закрывается.

CAtlServiceModuleT::InitializeSecurity

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

HRESULT InitializeSecurity() throw();

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

Возвращает S_OK при успешном выполнении или ошибку HRESULT при сбое.

Замечания

Любой класс, производный от CAtlServiceModuleT этого метода, должен реализовываться в производном классе.

Используйте проверку подлинности на уровне PKT, уровень олицетворения RPC_C_IMP_LEVEL_IDENTIFY и соответствующий дескриптор безопасности, отличный от NULL, в вызове CoInitializeSecurity.

Для проектов служб, созданных мастером, не являющихся атрибутами, это будет в

class CNonAttribServiceModule : public CAtlServiceModuleT< CNonAttribServiceModule, IDS_SERVICENAME >
{
public :
   DECLARE_LIBID(LIBID_NonAttribServiceLib)
   DECLARE_REGISTRY_APPID_RESOURCEID(IDR_NONATTRIBSERVICE, "{29160736-339F-4A1C-ABEF-C320CE103E12}")
   HRESULT InitializeSecurity() throw()
   {
      // TODO : Call CoInitializeSecurity and provide the appropriate security settings for 
      // your service
      // Suggested - PKT Level Authentication, 
      // Impersonation Level of RPC_C_IMP_LEVEL_IDENTIFY 
      // and an appropriate Non NULL Security Descriptor.

      return S_OK;
   }
};

Для проектов служб с атрибутами это будет в

[ module(SERVICE, uuid = "{D3103322-7B70-4581-8E59-12769BD9A62B}", 
   name = "AttribService", 
   helpstring = "AttribService 1.0 Type Library", 
   resource_name="IDS_SERVICENAME") ]
class CAttribServiceModule
{
public:
   HRESULT InitializeSecurity() throw()
   {
      // TODO : Call CoInitializeSecurity and provide the appropriate security settings for 
      // your service
      // Suggested - PKT Level Authentication, 
      // Impersonation Level of RPC_C_IMP_LEVEL_IDENTIFY 
      // and an appropriate Non NULL Security Descriptor.

      return S_OK;
   }
};

CAtlServiceModuleT::Install

Устанавливает и создает службу.

BOOL Install() throw();

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

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Устанавливает службу в базу данных Service Control Manager (SCM), а затем создает объект службы. Если не удалось создать службу, отображается окно сообщения, а метод возвращает ЗНАЧЕНИЕ FALSE.

CAtlServiceModuleT::IsInstalled

Подтверждает, что служба установлена.

BOOL IsInstalled() throw();

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

Возвращает значение TRUE, если служба установлена, значение FALSE в противном случае.

CAtlServiceModuleT::LogEvent

Записывает в журнал событий.

void __cdecl LogEvent(LPCTSTR pszFormat, ...) throw();

Параметры

pszFormat
Строка для записи в журнал событий.

...
Необязательные дополнительные строки для записи в журнал событий.

Замечания

Этот метод записывает сведения в журнал событий с помощью функции ReportEvent. Если служба не запущена, строка отправляется в консоль.

CAtlServiceModuleT::m_bService

Флаг, указывающий, что программа выполняется как услуга.

BOOL m_bService;

Замечания

Используется для отличия EXE службы от EXE приложения.

CAtlServiceModuleT::m_dwThreadID

Переменная-член, сохраняющая идентификатор потока службы.

DWORD m_dwThreadID;

Замечания

Эта переменная хранит идентификатор потока текущего потока.

CAtlServiceModuleT::m_hServiceStatus

Переменная-член, сохраняющая дескриптор в структуре сведений о состоянии текущей службы.

SERVICE_STATUS_HANDLE m_hServiceStatus;

Замечания

Структура SERVICE_STATUS содержит сведения о службе.

CAtlServiceModuleT::m_status

Переменная-член, сохраняющая структуру сведений о состоянии для текущей службы.

SERVICE_STATUS m_status;

Замечания

Структура SERVICE_STATUS содержит сведения о службе.

CAtlServiceModuleT::m_szServiceName

Имя зарегистрированной службы.

TCHAR [256] m_szServiceName;

Замечания

Строка, завершающаяся значением NULL, в которой хранится имя службы.

CAtlServiceModuleT::OnContinue

Переопределите этот метод, чтобы продолжить службу.

void OnContinue() throw();

CAtlServiceModuleT::OnInterrogate

Переопределите этот метод для допроса службы.

void OnInterrogate() throw();

CAtlServiceModuleT::OnPause

Переопределите этот метод, чтобы приостановить работу службы.

void OnPause() throw();

CAtlServiceModuleT::OnShutdown

Переопределите этот метод, чтобы завершить работу службы.

void OnShutdown() throw();

CAtlServiceModuleT::OnStop

Переопределите этот метод, чтобы остановить службу.

void OnStop() throw();

CAtlServiceModuleT::OnUnknownRequest

Переопределите этот метод для обработки неизвестных запросов к службе.

void OnUnknownRequest(DWORD /* dwOpcode*/) throw();

Параметры

dwOpcode
Зарезервировано.

CAtlServiceModuleT::P arseCommandLine

Анализирует командную строку и выполняет регистрацию при необходимости.

bool ParseCommandLine(LPCTSTR lpCmdLine, HRESULT* pnRetCode) throw();

Параметры

lpCmdLine
командная строка.

pnRetCode
HRESULT, соответствующий регистрации (если это произошло).

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

Возвращает значение true при успешном выполнении или значение false, если не удалось зарегистрировать файл RGS, предоставленный в командной строке.

Замечания

Анализирует командную строку и регистрирует или отменяет регистрацию предоставленного файла RGS при необходимости. Этот метод вызывает CAtlExeModuleT::P arseCommandLine, чтобы проверить наличие /RegServer и /UnregServer. Добавление аргумента -/Service зарегистрирует службу.

CAtlServiceModuleT::P reMessageLoop

Этот метод вызывается непосредственно перед вводом цикла сообщений.

HRESULT PreMessageLoop(int nShowCmd) throw();

Параметры

nShowCmd
Этот параметр передается в CAtlExeModuleT::P reMessageLoop.

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

Возвращает S_OK при успешном выполнении или ошибку HRESULT при сбое.

Замечания

Переопределите этот метод, чтобы добавить пользовательский код инициализации для службы.

CAtlServiceModuleT::RegisterAppId

Регистрирует службу в реестре.

inline HRESULT RegisterAppId(bool bService = false) throw();

Параметры

bService
Должен иметь значение true для регистрации в качестве службы.

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

Возвращает S_OK при успешном выполнении или ошибку HRESULT при сбое.

CAtlServiceModuleT::Run

Запускает службу.

HRESULT Run(int nShowCmd = SW_HIDE) throw();

Параметры

nShowCmd
Указывает способ отображения окна. Этот параметр может быть одним из значений, рассмотренных в разделе WinMain . Значение по умолчанию — SW_HIDE.

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

Возвращает S_OK при успешном выполнении или ошибку HRESULT при сбое.

Замечания

После вызова вызывается CAtlServiceModuleT::P reMessageLoop, CAtlExeModuleT::RunMessageLoop и CAtlExeModuleT::P ostMessageLoop. Run

CAtlServiceModuleT::ServiceMain

Этот метод вызывается диспетчером управления службами.

void ServiceMain(DWORD dwArgc, LPTSTR* lpszArgv) throw();

Параметры

dwArgc
Аргумент argc.

lpszArgv
Аргумент argv.

Замечания

При открытии приложения служб в панель управления вызовы ServiceMain диспетчера управления службами (SCM) выберите службу и нажмите кнопку "Пуск".

После вызовов ServiceMainSCM служба должна предоставить функцию обработчика SCM. Эта функция позволяет SCM получать состояние службы и передавать определенные инструкции (например, приостановка или остановка). Впоследствии вызывается CAtlServiceModuleT::Run для выполнения основной работы службы. Run продолжает выполняться до остановки службы.

CAtlServiceModuleT::SetServiceStatus

Этот метод обновляет состояние службы.

void SetServiceStatus(DWORD dwState) throw();

Параметры

dwState
Новое состояние. Сведения о возможных значениях см. в разделе SetServiceStatus .

Замечания

Обновляет сведения о состоянии диспетчера управления службами для службы. Он вызывается методом CAtlServiceModuleT::Run, CAtlServiceModuleT::ServiceMain и другими методами обработчика. Состояние также хранится в переменной-члене CAtlServiceModuleT::m_status.

CAtlServiceModuleT::Start

CAtlServiceModuleT::WinMain Вызывается при запуске службы.

HRESULT Start(int nShowCmd) throw();

Параметры

nShowCmd
Указывает способ отображения окна. Этот параметр может быть одним из значений, рассмотренных в разделе WinMain .

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

Возвращает S_OK при успешном выполнении или ошибку HRESULT при сбое.

Замечания

Метод CAtlServiceModuleT::WinMain обрабатывает как регистрацию, так и установку, а также задачи, связанные с удалением записей реестра и удалением модуля. При запуске WinMain службы вызывается Start.

CAtlServiceModuleT::Uninstall

Останавливает и удаляет службу.

BOOL Uninstall() throw();

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

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Останавливает работу службы и удаляет ее из базы данных Service Control Manager.

CAtlServiceModuleT::Unlock

Уменьшает количество блокировок службы.

LONG Unlock() throw();

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

Возвращает количество блокировок, которое может быть полезно для диагностика и отладки.

CAtlServiceModuleT::UnregisterAppId

Удаляет службу из реестра.

HRESULT UnregisterAppId() throw();

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

Возвращает S_OK при успешном выполнении или ошибку HRESULT при сбое.

CAtlServiceModuleT::WinMain

Этот метод реализует код, необходимый для запуска службы.

int WinMain(int nShowCmd) throw();

Параметры

nShowCmd
Указывает способ отображения окна. Этот параметр может быть одним из значений, рассмотренных в разделе WinMain .

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

Возвращает возвращаемое значение службы.

Замечания

Этот метод обрабатывает командную строку (с CAtlServiceModuleT ::P arseCommandLine), а затем запускает службу (с помощью CAtlServiceModuleT::Start).

См. также

Класс CAtlExeModuleT
Общие сведения о классе