Função EnumDependentServicesA (winsvc.h)

Artigo
11/20/2024

Recupera o nome e o 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 acesso SERVICE_ENUMERATE_DEPENDENTS correto. Para obter mais informações, consulte de Direitos de Acesso e Segurança do 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 seguintes estados: SERVICE_ACTIVE e SERVICE_INACTIVE.

[out, optional] lpServices

Um ponteiro para uma matriz de estruturas de ENUM_SERVICE_STATUS que recebe o nome e as informações de status do 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 às quais seus membros apontam.

A ordem dos serviços nessa matriz é o inverso da ordem inicial 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 pcbBytesNeededed 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 receberá esse valor somente 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 pcbBytesNeededed é indefinido.

[out] lpServicesReturned

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

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 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 acesso SERVICE_ENUMERATE_DEPENDENTS correto.
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.

Observações

As entradas de serviços retornados são ordenadas na ordem inversa da ordem inicial, 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 Parar um serviço.

Nota

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

CreateService

ENUM_SERVICE_STATUS

EnumServicesStatusEx

openservice

Funções de serviço

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

Compartilhar via