Função NotifyServiceStatusChangeA (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 NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA 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 do OpenService ou CreateService e devem ter o acesso SERVICE_QUERY_STATUS correto. 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 de Direitos de Acesso e Segurança do Serviço.
Só pode haver uma solicitação de notificação pendente por serviço.
[in] dwNotifyMask
O tipo de alterações de status que devem ser relatadas. Esse parâmetro pode ser um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
Relatar quando o serviço tiver sido criado.
O parâmetro hService deve ser um identificador para o SCM. |
|
Informe 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 seja cancelada. Caso contrário, não há 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.
Valor de retorno
Se a função for bem-sucedida, 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 do 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 .
Observações
A função
Quando o status do serviço é alterado, o sistema invoca a função de retorno de chamada especificada como uma APC (chamada de procedimento assíncrono) enfileirada no thread de chamada. O thread de chamada deve inserir uma espera alertável (por exemplo, chamando a função SleepEx) para receber a 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 à direita. Se o thread de chamada não tiver esse acesso correto, NotifyServiceStatusChange falhar. Se o thread de chamada estiver representando outro usuário, ele poderá não ter 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 for encerrado sem fechar o identificador de serviço ou aguardar até que o APC seja gerado, poderá ocorrer um vazamento de memória.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Vista [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2008 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winsvc.h (incluir Windows.h) |
| biblioteca | Advapi32.lib |
| de DLL |
Advapi32.dll |