Função EnumDependentServicesA (winsvc.h)

Artigo
08/27/2023

Recupera o nome e status de cada serviço que depende do serviço especificado; ou seja, o serviço especificado deve estar em execução antes que os serviços dependentes possam ser executados.

Sintaxe

BOOL EnumDependentServicesA(
  [in]            SC_HANDLE              hService,
  [in]            DWORD                  dwServiceState,
  [out, optional] LPENUM_SERVICE_STATUSA lpServices,
  [in]            DWORD                  cbBufSize,
  [out]           LPDWORD                pcbBytesNeeded,
  [out]           LPDWORD                lpServicesReturned
);

Parâmetros

[in] hService

Um identificador para o serviço. Esse identificador é retornado pela função OpenService ou CreateService e deve ter o direito de acesso SERVICE_ENUMERATE_DEPENDENTS . Para obter mais informações, consulte Segurança do Serviço e Direitos de Acesso.

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

[out, optional] lpServices

Um ponteiro para uma matriz de estruturas ENUM_SERVICE_STATUS que recebe o nome e as informações de status de serviço para cada serviço dependente 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.

A ordem dos serviços nessa matriz é o inverso da ordem de início dos serviços. Em outras palavras, o primeiro serviço na matriz é aquele que seria iniciado por último e o último serviço na matriz é aquele que seria iniciado primeiro.

O tamanho máximo dessa matriz é de 64.000 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.

[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 armazenar a matriz de entradas de serviço. A variável só receberá esse valor se o buffer apontado por lpServices for muito pequeno, indicado por falha de função e o erro ERROR_MORE_DATA ; caso contrário, o conteúdo de pcbBytesNeeded será indefinido.

[out] lpServicesReturned

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

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 SERVICE_ENUMERATE_DEPENDENTS.
ERROR_INVALID_HANDLE	O identificador especificado é inválido.
ERROR_INVALID_PARAMETER	Um parâmetro especificado é inválido.
ERROR_MORE_DATA	O buffer apontado por lpServices não é grande o suficiente. A função define a variável apontada por lpServicesReturned para o número real de entradas de serviço armazenadas no buffer. A função define a variável apontada por pcbBytesNeeded para o número de bytes necessários para armazenar todas as entradas de serviço.

Comentários

As entradas de serviços retornadas são ordenadas na ordem inversa da ordem de início, com a ordem de grupo levada em conta. Se você precisar parar os serviços dependentes, poderá usar a ordem das entradas gravadas no buffer lpServices para interromper os serviços dependentes na ordem adequada.

Exemplos

Para obter um exemplo, consulte Parando um serviço.

Observação

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