Compartilhar via


Função EnumServicesStatusExA (winsvc.h)

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, juntamente com dados adicionais com base no nível de informações especificado.

Sintaxe

BOOL EnumServicesStatusExA(
  [in]                SC_HANDLE    hSCManager,
  [in]                SC_ENUM_TYPE InfoLevel,
  [in]                DWORD        dwServiceType,
  [in]                DWORD        dwServiceState,
  [out, optional]     LPBYTE       lpServices,
  [in]                DWORD        cbBufSize,
  [out]               LPDWORD      pcbBytesNeeded,
  [out]               LPDWORD      lpServicesReturned,
  [in, out, optional] LPDWORD      lpResumeHandle,
  [in, optional]      LPCSTR       pszGroupName
);

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] InfoLevel

Os atributos de serviço que devem ser retornados. Use SC_ENUM_PROCESS_INFO para recuperar o nome e as informações de status de serviço para cada serviço no banco de dados. O parâmetro lpServices é um ponteiro para um buffer que recebe uma matriz de estruturas ENUM_SERVICE_STATUS_PROCESS . O buffer deve ser grande o suficiente para manter as estruturas, bem como as cadeias de caracteres para as quais seus membros apontam.

Atualmente, nenhum outro nível de informação é definido.

[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 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 estados SERVICE_ACTIVE e SERVICE_INACTIVE .

[out, optional] lpServices

Um ponteiro para o buffer que recebe as informações de status. O formato desses dados depende do valor do parâmetro InfoLevel .

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_MORE_DATA. 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 a função EnumServicesStatusEx 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 indicará a próxima entrada de serviço a ser lida quando a função EnumServicesStatusEx for chamada para recuperar os dados adicionais.

[in, optional] pszGroupName

O nome do grupo de ordem de carga. Se esse parâmetro for uma cadeia de caracteres, os únicos serviços enumerados serão aqueles que pertencem ao grupo que tem o nome especificado pela cadeia de caracteres. Se esse parâmetro for uma cadeia de caracteres vazia, somente os serviços que não pertencem a nenhum grupo serão enumerados. Se esse parâmetro for NULL, a associação de grupo será ignorada e todos os serviços serão enumerados.

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 erros a seguir podem ser retornados.

Código de retorno Descrição
ERROR_ACCESS_DENIED
O identificador não tem o direito de acesso SC_MANAGER_ENUMERATE_SERVICE.
ERROR_MORE_DATA
O buffer é muito pequeno. Nem todos os dados no banco de dados ativo podem ser retornados. O parâmetro pcbBytesNeeded contém o número de bytes necessários para receber as entradas restantes.
ERROR_INVALID_PARAMETER
Um valor de parâmetro inválido foi usado.
ERROR_INVALID_HANDLE
O manipulador é inválido.
ERROR_INVALID_LEVEL
O parâmetro InfoLevel contém um valor sem suporte.
ERROR_SHUTDOWN_IN_PROGRESS
O sistema está sendo desligado; essa função não pode ser chamada.

Comentários

Se o chamador não tiver o direito de acesso SERVICE_QUERY_STATUS a um serviço, o serviço será silenciosamente omitido da lista de serviços retornados ao cliente.

Observação

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

Confira também

ENUM_SERVICE_STATUS_PROCESS

Funções de serviço

Instalação, remoção e enumeração de serviço