Função NotifyServiceStatusChangeA (winsvc.h)

  • Artigo

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.

Valor Significado
SERVICE_NOTIFY_CREATED
0x00000080
 Relatar quando o serviço tiver sido criado.

O parâmetro hService deve ser um identificador para o SCM.
SERVICE_NOTIFY_CONTINUE_PENDING
0x00000010
 Relatar quando o serviço está prestes a continuar.

O parâmetro hService deve ser um identificador para o serviço.
SERVICE_NOTIFY_DELETE_PENDING
0x00000200
 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.
SERVICE_NOTIFY_DELETED
0x00000100
 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.
SERVICE_NOTIFY_PAUSE_PENDING
0x00000020
 Relatar quando o serviço está em pausa.

O parâmetro hService deve ser um identificador para o serviço.
SERVICE_NOTIFY_PAUSED
0x00000040
 Relatar quando o serviço tiver pausado.

O parâmetro hService deve ser um identificador para o serviço.
SERVICE_NOTIFY_RUNNING
0x00000008
 Relatar quando o serviço está em execução.

O parâmetro hService deve ser um identificador para o serviço.
SERVICE_NOTIFY_START_PENDING
0x00000002
 Relatar quando o serviço está sendo iniciado.

O parâmetro hService deve ser um identificador para o serviço.
SERVICE_NOTIFY_STOP_PENDING
0x00000004
 Relatar quando o serviço está parando.

O parâmetro hService deve ser um identificador para o serviço.
SERVICE_NOTIFY_STOPPED
0x00000001
 Relatar quando o serviço tiver parado.

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 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.

Importante Se o thread de chamada estiver em uma DLL e a DLL for descarregada antes que o thread receba a notificação ou chame CloseServiceHandle, a notificação causará resultados imprevisíveis e poderá fazer com que o processo pare de responder.
 

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

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Funções de serviço