Classe CAtlServiceModuleT
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
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de