Função NotifyServiceStatusChangeW (winsvc.h)
Permite que um aplicativo receba notificação quando o serviço especificado é criado ou excluído ou quando seu status é alterado.
Sintaxe
DWORD NotifyServiceStatusChangeW(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYW pNotifyBuffer
);
Parâmetros
[in] hService
Um identificador para o serviço ou o gerenciador de controle de serviço. Os identificadores para serviços são retornados pela função OpenService ou CreateService e devem ter o direito de acesso SERVICE_QUERY_STATUS. Os identificadores para o gerenciador de controle de serviço são retornados pela função OpenSCManager e devem ter o acesso SC_MANAGER_ENUMERATE_SERVICE correto. Para obter mais informações, consulte Segurança do serviço e Direitos de Acesso.
Só pode haver uma solicitação de notificação pendente por serviço.
[in] dwNotifyMask
O tipo de status alterações que devem ser relatadas. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Relatar quando o serviço foi criado.
O parâmetro hService deve ser um identificador para o SCM. |
|
Relatar quando o serviço está prestes a continuar.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando um aplicativo tiver especificado o serviço em uma chamada para a função DeleteService . Seu aplicativo deve fechar todos os identificadores do serviço para que ele possa ser excluído.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando o serviço tiver sido excluído. Um aplicativo não poderá receber essa notificação se tiver um identificador aberto para o serviço.
O parâmetro hService deve ser um identificador para o SCM. |
|
Relatar quando o serviço está em pausa.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando o serviço tiver pausado.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando o serviço está em execução.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando o serviço está sendo iniciado.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando o serviço está parando.
O parâmetro hService deve ser um identificador para o serviço. |
|
Relatar quando o serviço for interrompido.
O parâmetro hService deve ser um identificador para o serviço. |
[in] pNotifyBuffer
Um ponteiro para uma estrutura SERVICE_NOTIFY que contém informações de notificação, como um ponteiro para a função de retorno de chamada. Essa estrutura deve permanecer válida até que a função de retorno de chamada seja invocada ou o thread de chamada cancele a solicitação de notificação.
Não faça várias chamadas para NotifyServiceStatusChange com o mesmo parâmetro de buffer até que a função de retorno de chamada da primeira chamada seja concluída com o buffer ou a primeira solicitação de notificação tenha sido cancelada. Caso contrário, não há nenhuma garantia de qual versão do buffer a função de retorno de chamada receberá.
Windows Vista: O endereço da função de retorno de chamada deve estar dentro do intervalo de endereços de um módulo carregado. Portanto, a função de retorno de chamada não pode ser um código gerado em tempo de execução (como código gerenciado gerado pelo compilador JIT) ou código nativo descompactado em tempo de execução. Essa restrição foi removida no Windows Server 2008 e no Windows Vista com SP1.
Retornar valor
Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o serviço tiver sido marcado para exclusão, o valor retornado será ERROR_SERVICE_MARKED_FOR_DELETE e o identificador para o serviço deverá ser fechado. Se a notificação de serviço estiver muito atrasada em relação ao estado do sistema, a função retornará ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. Nesse caso, o cliente deve fechar o identificador para o SCM, abrir um novo identificador e chamar essa função novamente.
Se a função falhar, o valor retornado será um dos códigos de erro do sistema.
Comentários
A função NotifyServiceStatusChange pode ser usada para receber notificações sobre aplicativos de serviço. Ele não pode ser usado para receber notificações sobre serviços de driver.
Quando o serviço status é alterado, o sistema invoca a função de retorno de chamada especificada como uma APC (chamada de procedimento assíncrona) enfileirada para o thread de chamada. O thread de chamada deve inserir uma espera alertável (por exemplo, chamando a função SleepEx ) para receber notificação. Para obter mais informações, consulte Chamadas de procedimento assíncrono.
Se o serviço já estiver em qualquer um dos estados solicitados quando NotifyServiceStatusChange for chamado, a função de retorno de chamada será enfileirada imediatamente. Se o estado do serviço não tiver sido alterado na próxima vez que a função for chamada com o mesmo serviço e estado, a função de retorno de chamada não será enfileirada imediatamente; a função de retorno de chamada é enfileirada na próxima vez que o serviço entrar no estado solicitado.
A função NotifyServiceStatusChange chama a função OpenThread no thread de chamada com o acesso THREAD_SET_CONTEXT direito. Se o thread de chamada não tiver esse acesso correto, NotifyServiceStatusChange falhará. Se o thread de chamada estiver representando outro usuário, talvez ele não tenha permissão suficiente para definir o contexto.
É mais eficiente chamar NotifyServiceStatusChange de um thread que executa uma espera do que criar um thread adicional.
Depois que a função de retorno de chamada for invocada, o chamador deverá chamar NotifyServiceStatusChange para receber notificações adicionais. Observe que determinadas funções na API do Windows, incluindo NotifyServiceStatusChange e outras funções SCM, usam chamadas de procedimento remoto (RPC); essas funções podem executar uma operação de espera alertável, portanto, elas não são seguras para chamar de dentro da função de retorno de chamada. Em vez disso, a função de retorno de chamada deve salvar os parâmetros de notificação e executar qualquer trabalho adicional fora do retorno de chamada.
Para cancelar notificações pendentes, feche o identificador de serviço usando a função CloseServiceHandle . Depois que CloseServiceHandle for bem-sucedido, não haverá mais APCs de notificação na fila. Se o thread de chamada sair sem fechar o identificador de serviço ou aguardar até que o APC seja gerado, poderá ocorrer um vazamento de memória.
Observação
O cabeçalho winsvc.h define NotifyServiceStatusChange como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsvc.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |
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