Classe CAtlServiceModuleT

  • Artigo

Essa classe implementa um serviço.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

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

Parâmetros

T
Sua classe derivada de CAtlServiceModuleT.

nServiceNameID
O identificador de recurso do serviço.

Membros

Construtores públicos

Nome Descrição
CAtlServiceModuleT::CAtlServiceModuleT O construtor .

Métodos públicos

Nome Descrição
CAtlServiceModuleT::Handler A rotina do manipulador para o serviço.
CAtlServiceModuleT::InitializeSecurity Fornece as configurações de segurança padrão para o serviço.
CAtlServiceModuleT::Install Instala e cria o serviço.
CAtlServiceModuleT::IsInstalled Confirma se o serviço foi instalado.
CAtlServiceModuleT::LogEvent Grava no log de eventos.
CAtlServiceModuleT::OnContinue Substitua esse método para continuar o serviço.
CAtlServiceModuleT::OnInterrogate Substitua esse método para interrogar o serviço.
CAtlServiceModuleT::OnPause Substitua esse método para pausar o serviço.
CAtlServiceModuleT::OnShutdown Substitua esse método para desligar o serviço
CAtlServiceModuleT::OnStop Substitua esse método para interromper o serviço
CAtlServiceModuleT::OnUnknownRequest Substitua esse método para lidar com solicitações desconhecidas para o serviço.
CAtlServiceModuleT::ParseCommandLine Analisa a linha de comando e executa o registro, se necessário.
CAtlServiceModuleT::PreMessageLoop Esse método é chamado imediatamente antes de inserir o loop de mensagens.
CAtlServiceModuleT::RegisterAppId Registra o serviço no registro.
CAtlServiceModuleT::Run Executa o serviço.
CAtlServiceModuleT::ServiceMain O método chamado pelo Gerenciador de Controle de Serviço.
CAtlServiceModuleT::SetServiceStatus Atualiza o status do serviço.
CAtlServiceModuleT::Start Chamado por CAtlServiceModuleT::WinMain quando o serviço é iniciado.
CAtlServiceModuleT::Uninstall Para e remove o serviço.
CAtlServiceModuleT::Unlock Diminui a contagem de bloqueios do serviço.
CAtlServiceModuleT::UnregisterAppId Remove o serviço do registro.
CAtlServiceModuleT::WinMain Esse método implementa o código necessário para executar o serviço.

Membros de Dados Públicos

Nome Descrição
CAtlServiceModuleT::m_bService Sinalizador indicando que o programa está em execução como um serviço.
CAtlServiceModuleT::m_dwThreadID Variável de membro que armazena o identificador de thread.
CAtlServiceModuleT::m_hServiceStatus Variável de membro que armazena um identificador para a estrutura de informações de status do serviço atual.
CAtlServiceModuleT::m_status Variável de membro que armazena a estrutura de informações de status do serviço atual.
CAtlServiceModuleT::m_szServiceName O nome do serviço que está sendo registrado.

Comentários

CAtlServiceModuleT, derivado de CAtlExeModuleT, implementa um módulo do Serviço ATL. CAtlServiceModuleT fornece métodos para processamento, instalação, registro e remoção de linha de comando. Se a funcionalidade extra for necessária, esses e outros métodos poderão ser substituídos.

Essa classe substitui a classe obsoleta CComModule usada em versões anteriores da ATL. Confira Classes de módulo da ATL para obter mais detalhes.

Hierarquia de herança

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

Requisitos

Cabeçalho: atlbase.h

CAtlServiceModuleT::CAtlServiceModuleT

O construtor .

CAtlServiceModuleT() throw();

Comentários

Inicializa os membros de dados e define o status inicial do serviço.

CAtlServiceModuleT::Handler

A rotina do manipulador para o serviço.

void Handler(DWORD dwOpcode) throw();

Parâmetros

dwOpcode
Um comutador que define a operação do manipulador. Para obter detalhes, confira os Comentários.

Comentários

Esse é o código que o SCM (Gerenciador de Controle de Serviço) chama para recuperar o status do serviço e emitir instruções, como parar ou pausar. O SCM passa um código de operação, mostrado abaixo, para Handler indicar o que o serviço deve fazer.

Código de operação Significado
SERVICE_CONTROL_STOP Interrompe o serviço. Substitua o método CAtlServiceModuleT::OnStop em atlbase.h para alterar o comportamento.
SERVICE_CONTROL_PAUSE Usuário implementado. Substitua o método vazio CAtlServiceModuleT::OnPause em atlbase.h para pausar o serviço.
SERVICE_CONTROL_CONTINUE Usuário implementado. Substitua o método vazio CAtlServiceModuleT::OnContinue em atlbase.h para continuar o serviço.
SERVICE_CONTROL_INTERROGATE Usuário implementado. Substitua o método vazio CAtlServiceModuleT::OnInterrogate em atlbase.h para interrogar o serviço.
SERVICE_CONTROL_SHUTDOWN Usuário implementado. Substitua o método vazio CAtlServiceModuleT::OnShutdown em atlbase.h para desligar o serviço.

Se o código de operação não for reconhecido, o método CAtlServiceModuleT::OnUnknownRequest será chamado.

Um serviço padrão gerado pela ATL manipula apenas a instrução de parada. Se o SCM passar a instrução de parada, o serviço informará ao SCM que o programa está prestes a ser interrompido. Em seguida, o serviço chama PostThreadMessage para postar uma mensagem de encerramento para si mesmo. Isso encerra o loop de mensagem e, em última análise, o serviço será fechado.

CAtlServiceModuleT::InitializeSecurity

Fornece as configurações de segurança padrão para o serviço.

HRESULT InitializeSecurity() throw();

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Qualquer classe derivada CAtlServiceModuleT deve implementar esse método na classe derivada.

Use a autenticação no nível PKT, o nível de representação de RPC_C_IMP_LEVEL_IDENTIFY e um descritor de segurança não nulo apropriado na chamada para CoInitializeSecurity.

Para projetos de serviço não atribuído gerados pelo assistente, isso estaria em

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;
   }
};

Para projetos de serviço atribuídos, isso estaria em

[ 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

Instala e cria o serviço.

BOOL Install() throw();

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Instala o serviço no banco de dados do SCM (Service Control Manager) e cria o objeto de serviço. Se o serviço não puder ser criado, uma caixa de mensagem será exibida e o método retornará FALSE.

CAtlServiceModuleT::IsInstalled

Confirma se o serviço foi instalado.

BOOL IsInstalled() throw();

Valor de retorno

Retorna TRUE se o serviço estiver instalado, FALSE caso contrário.

CAtlServiceModuleT::LogEvent

Grava no log de eventos.

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

Parâmetros

pszFormat
A cadeia de caracteres a ser gravada no log de eventos.

...
Cadeias de caracteres extras opcionais a serem gravadas no log de eventos.

Comentários

Esse método grava detalhes em um log de eventos usando a função ReportEvent. Se nenhum serviço estiver em execução, a cadeia de caracteres será enviada para o console.

CAtlServiceModuleT::m_bService

Sinalizador indicando que o programa está em execução como um serviço.

BOOL m_bService;

Comentários

Usado para distinguir um EXE de serviço de um EXE de aplicativo.

CAtlServiceModuleT::m_dwThreadID

Variável de membro armazenando o identificador de thread do Serviço.

DWORD m_dwThreadID;

Comentários

Essa variável armazena o identificador de thread do thread atual.

CAtlServiceModuleT::m_hServiceStatus

Variável de membro que armazena um identificador para a estrutura de informações de status do serviço atual.

SERVICE_STATUS_HANDLE m_hServiceStatus;

Comentários

A estrutura SERVICE_STATUS contém informações sobre um serviço.

CAtlServiceModuleT::m_status

Variável de membro que armazena a estrutura de informações de status do serviço atual.

SERVICE_STATUS m_status;

Comentários

A estrutura SERVICE_STATUS contém informações sobre um serviço.

CAtlServiceModuleT::m_szServiceName

O nome do serviço que está sendo registrado.

TCHAR [256] m_szServiceName;

Comentários

Uma cadeia de caracteres terminada em nulo que armazena o nome do serviço.

CAtlServiceModuleT::OnContinue

Substitua esse método para continuar o serviço.

void OnContinue() throw();

CAtlServiceModuleT::OnInterrogate

Substitua esse método para interrogar o serviço.

void OnInterrogate() throw();

CAtlServiceModuleT::OnPause

Substitua esse método para pausar o serviço.

void OnPause() throw();

CAtlServiceModuleT::OnShutdown

Substitua esse método para interromper o serviço

void OnShutdown() throw();

CAtlServiceModuleT::OnStop

Substitua esse método para interromper o serviço.

void OnStop() throw();

CAtlServiceModuleT::OnUnknownRequest

Substitua esse método para lidar com solicitações desconhecidas para o serviço

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

Parâmetros

dwOpcode
Reservado.

CAtlServiceModuleT::ParseCommandLine

Analisa a linha de comando e executa o registro, se necessário.

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

Parâmetros

lpCmdLine
A linha de comando.

pnRetCode
O HRESULT correspondente ao registro (se ocorreu).

Valor de retorno

Retorna true no êxito ou false se o arquivo RGS fornecido na linha de comando não pôde ser registrado.

Comentários

Analisa a linha de comando e registra ou cancela o registro do arquivo RGS fornecido, se necessário. Esse método chama CAtlExeModuleT::ParseCommandLine para verificar /RegServer e /UnregServer. A adição do argumento -/Service registrará o serviço.

CAtlServiceModuleT::PreMessageLoop

Esse método é chamado imediatamente antes de inserir o loop de mensagens.

HRESULT PreMessageLoop(int nShowCmd) throw();

Parâmetros

nShowCmd
Esse parâmetro é passado para CAtlExeModuleT::PreMessageLoop.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Substitua este método para adicionar código de inicialização personalizada aos objetos.

CAtlServiceModuleT::RegisterAppId

Registra o serviço no registro.

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

Parâmetros

bService
Deve ser true para se registrar como um serviço.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

CAtlServiceModuleT::Run

Executa o serviço.

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

Parâmetros

nShowCmd
Especifica como a janela deve ser mostrada. Esse parâmetro pode ser um dos valores discutidos na seção WinMain. O valor padrão é SW_HIDE.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Depois de ser chamado, Run chamará CAtlServiceModuleT::PreMessageLoop, CAtlExeModuleT::RunMessageLoop e CAtlExeModuleT::PostMessageLoop.

CAtlServiceModuleT::ServiceMain

Esse método é chamado pelo Gerenciador de Controle de Serviço.

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

Parâmetros

dwArgc
O argumento argc.

lpszArgv
O argumento argv.

Comentários

O SCM (Service Control Manager) chama ServiceMain quando você abre o aplicativo Serviços no Painel de Controle, seleciona o serviço e clica em Iniciar.

Após as chamadas ServiceMain do SCM, um serviço deve fornecer ao SCM uma função de manipulador. Essa função permite que o SCM obtenha o status do serviço e passe instruções específicas (como pausar ou parar). Posteriormente, CAtlServiceModuleT::Run é chamado para executar o trabalho principal do serviço. Run continua a ser executado até que o serviço seja interrompido.

CAtlServiceModuleT::SetServiceStatus

Esse método atualiza o status do serviço.

void SetServiceStatus(DWORD dwState) throw();

Parâmetros

dwState
O novo status. Confira os possíveis valores em SetServiceStatus.

Comentários

Atualiza as informações de status do Service Control Manager para o serviço. Ele é chamado por CAtlServiceModuleT::Run, CAtlServiceModuleT::ServiceMain e outros métodos de manipulador. O status também é armazenado na variável de membro CAtlServiceModuleT::m_status.

CAtlServiceModuleT::Start

Chamado por CAtlServiceModuleT::WinMain quando o serviço é iniciado.

HRESULT Start(int nShowCmd) throw();

Parâmetros

nShowCmd
Especifica como a janela deve ser mostrada. Esse parâmetro pode ser um dos valores discutidos na seção WinMain.

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

O método CAtlServiceModuleT::WinMain manipula o registro e a instalação, bem como as tarefas envolvidas na remoção de entradas do Registro e na desinstalação do módulo. Quando o serviço é executado, WinMain chama Start.

CAtlServiceModuleT::Uninstall

Para e remove o serviço.

BOOL Uninstall() throw();

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Impede a execução do serviço e o remove do banco de dados do Service Control Manager.

CAtlServiceModuleT::Unlock

Diminui a contagem de bloqueios do serviço.

LONG Unlock() throw();

Valor de retorno

Retorna a contagem de bloqueios, que pode ser útil para diagnóstico e depuração.

CAtlServiceModuleT::UnregisterAppId

Remove o serviço do registro.

HRESULT UnregisterAppId() throw();

Valor de retorno

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

CAtlServiceModuleT::WinMain

Esse método implementa o código necessário para iniciar o serviço.

int WinMain(int nShowCmd) throw();

Parâmetros

nShowCmd
Especifica como a janela deve ser mostrada. Esse parâmetro pode ser um dos valores discutidos na seção WinMain.

Valor de retorno

Retorna o valor retornado do serviço.

Comentários

Esse método processa a linha de comando (com CAtlServiceModuleT::ParseCommandLine) e inicia o serviço (usando CAtlServiceModuleT::Start).

Confira também

Classe CAtlExeModuleT
Visão geral da aula