Função EnumServicesStatusExW (winsvc.h)

Artigo
11/20/2024

Enumera serviços no banco de dados do gerenciador de controle de serviço especificado. O nome e o status de cada serviço são fornecidos, juntamente com dados adicionais com base no nível de informações especificado.

Sintaxe

BOOL EnumServicesStatusExW(
  [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]      LPCWSTR      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 acesso SC_MANAGER_ENUMERATE_SERVICE correto. Para obter mais informações, consulte de Direitos de Acesso e Segurança do Serviço.

[in] InfoLevel

Os atributos de serviço que devem ser retornados. Use SC_ENUM_PROCESS_INFO para recuperar as informações de status do nome e do 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 de ENUM_SERVICE_STATUS_PROCESS. O buffer deve ser grande o suficiente para manter as estruturas, bem como as cadeias de caracteres às quais seus membros apontam.

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

[in] dwServiceType

O tipo de serviço a ser enumerado. Esse parâmetro pode ser um ou mais 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, consulteprogramas de serviço .

[in] dwServiceState

O estado dos serviços a serem enumerados. Esse parâmetro pode ser 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_PENDINGe 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 pcbBytesNeededed 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 inicial 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 de retorno

Se a função for bem-sucedida, o valor retornado não será 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 acesso SC_MANAGER_ENUMERATE_SERVICE correto.
ERROR_MORE_DATA	O buffer é muito pequeno. Nem todos os dados no banco de dados ativo podem ser retornados. O parâmetro pcbBytesNeededed contém o número de bytes necessários para receber as entradas restantes.
ERROR_INVALID_PARAMETER	Um valor de parâmetro ilegal foi usado.
ERROR_INVALID_HANDLE	O identificador é 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.

Observações

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.

Nota

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. 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 XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [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

Consulte também

ENUM_SERVICE_STATUS_PROCESS

Funções de serviço

de Instalação, Remoção e Enumeração do Serviço

Compartilhar via