Função EnumServicesStatusA (winsvc.h)

Artigo
08/27/2023

Enumera serviços no banco de dados do gerenciador de controle de serviço especificado. O nome e status de cada serviço são fornecidos.

Essa função foi substituída pela função EnumServicesStatusEx . Ele retorna as mesmas informações que EnumServicesStatus retorna, além do identificador de processo e informações adicionais para o serviço. Além disso, EnumServicesStatusEx permite enumerar serviços que pertencem a um grupo especificado.

Sintaxe

BOOL EnumServicesStatusA(
  [in]                SC_HANDLE              hSCManager,
  [in]                DWORD                  dwServiceType,
  [in]                DWORD                  dwServiceState,
  [out, optional]     LPENUM_SERVICE_STATUSA lpServices,
  [in]                DWORD                  cbBufSize,
  [out]               LPDWORD                pcbBytesNeeded,
  [out]               LPDWORD                lpServicesReturned,
  [in, out, optional] LPDWORD                lpResumeHandle
);

Parâmetros

[in] hSCManager

Um identificador para o banco de dados do gerenciador de controle de serviço. Esse identificador é retornado pela função OpenSCManager e deve ter o direito de acesso SC_MANAGER_ENUMERATE_SERVICE. Para obter mais informações, consulte Segurança do Serviço e Direitos de Acesso.

[in] dwServiceType

O tipo de serviços a serem enumerados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SERVICE_DRIVER 0x0000000B	Serviços do tipo SERVICE_KERNEL_DRIVER e SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Serviços de driver do sistema de arquivos.
SERVICE_KERNEL_DRIVER 0x00000001	Serviços de driver.
SERVICE_WIN32 0x00000030	Serviços do tipo SERVICE_WIN32_OWN_PROCESS e SERVICE_WIN32_SHARE_PROCESS.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Serviços executados em seus próprios processos.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Serviços que compartilham um processo com um ou mais outros serviços. Para obter mais informações, consulte Programas de serviço.

[in] dwServiceState

O estado dos serviços a serem enumerados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SERVICE_ACTIVE 0x00000001	Enumera os serviços que estão nos seguintes estados: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING e SERVICE_PAUSED.
SERVICE_INACTIVE 0x00000002	Enumera serviços que estão no estado SERVICE_STOPPED.
SERVICE_STATE_ALL 0x00000003	Combina os seguintes estados: SERVICE_ACTIVE e SERVICE_INACTIVE.

[out, optional] lpServices

Um ponteiro para um buffer que contém uma matriz de estruturas ENUM_SERVICE_STATUS que recebem o nome e o serviço status informações para cada serviço no banco de dados. O buffer deve ser grande o suficiente para manter as estruturas, além das cadeias de caracteres para as quais seus membros apontam.

O tamanho máximo dessa matriz é de 256 K bytes. Para determinar o tamanho necessário, especifique NULL para esse parâmetro e 0 para o parâmetro cbBufSize . A função falhará e GetLastError retornará ERROR_INSUFFICIENT_BUFFER. O parâmetro pcbBytesNeeded receberá o tamanho necessário.

Windows Server 2003 e Windows XP: O tamanho máximo dessa matriz é de 64 K bytes. Esse limite foi aumentado a partir do Windows Server 2003 com SP1 e Windows XP com SP2.

[in] cbBufSize

O tamanho do buffer apontado pelo parâmetro lpServices , em bytes.

[out] pcbBytesNeeded

Um ponteiro para uma variável que recebe o número de bytes necessários para retornar as entradas de serviço restantes, se o buffer for muito pequeno.

[out] lpServicesReturned

Um ponteiro para uma variável que recebe o número de entradas de serviço retornadas.

[in, out, optional] lpResumeHandle

Um ponteiro para uma variável que, na entrada, especifica o ponto de partida da enumeração. Você deve definir esse valor como zero na primeira vez que essa função for chamada. Na saída, esse valor será zero se a função for bem-sucedida. No entanto, se a função retornar zero e a função GetLastError retornar ERROR_MORE_DATA, esse valor será usado para indicar a próxima entrada de serviço a ser lida quando a função for chamada para recuperar os dados adicionais.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Os códigos de erro a seguir podem ser definidos pelo gerenciador de controle de serviço. Outros códigos de erro podem ser definidos pelas funções do Registro que são chamadas pelo gerenciador de controle de serviço.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O identificador não tem o direito de acesso SC_MANAGER_ENUMERATE_SERVICE.
ERROR_INVALID_HANDLE	O identificador especificado é inválido.
ERROR_INVALID_PARAMETER	Um parâmetro especificado é inválido.
ERROR_MORE_DATA	Há mais entradas de serviço do que caberiam no buffer lpServices . O número real de entradas de serviço gravadas em lpServices é retornado no parâmetro lpServicesReturned . O número de bytes necessários para obter as entradas restantes é retornado no parâmetro pcbBytesNeeded . Os serviços restantes podem ser enumerados por chamadas adicionais para EnumServicesStatus com o parâmetro lpResumeHandle indicando o próximo serviço a ser lido.

Comentários

Observação

O cabeçalho winsvc.h define EnumServicesStatus 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


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winsvc.h (incluir Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll