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 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 direito de acesso SC_MANAGER_ENUMERATE_SERVICE. 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.

[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 que é 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íncrono) 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 uma 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 será 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 THREAD_SET_CONTEXT direito de acesso. Se o thread de chamada não tiver esse direito de acesso, 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 é invocada, o chamador deve chamar NotifyServiceStatusChange para receber notificações adicionais. Observe que determinadas funções na API do Windows, incluindo NotifyServiceStatusChange e outras funções do SCM, usam RPC (chamadas de procedimento remoto); 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 uma perda de memória.

Requisitos

Confira também

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Funções de serviço