Compartilhar via


Função GetServiceA (nspapi.h)

A função GetService recupera informações sobre um serviço de rede no contexto de um conjunto de namespaces padrão ou um namespace especificado. O serviço de rede é especificado por seu tipo e nome. As informações sobre o serviço são obtidas como um conjunto de estruturas de dados NS_SERVICE_INFO.

Nota A função GetService é uma extensão específica da Microsoft para a especificação do Windows Sockets 1.1. Essa função está obsoleta. Para a conveniência dos desenvolvedores do Windows Sockets 1.1, esse material de referência está incluído.
 
Nota As funções detalhadas na Resolução de Nomes Independentes de Protocolo fornecem funcionalidade equivalente no Windows Sockets 2.
 

Sintaxe

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

Parâmetros

[in] dwNameSpace

O namespace ou um conjunto de namespaces padrão que o sistema operacional deve consultar para obter informações sobre o serviço de rede especificado.

Use uma das constantes a seguir para especificar um namespace.

Valor Significado
NS_DEFAULT
Um conjunto de namespaces padrão. O sistema operacional consulta cada namespace dentro desse conjunto. O conjunto de namespaces padrão normalmente inclui todos os namespaces instalados no sistema. No entanto, os administradores do sistema podem excluir namespaces específicos do conjunto. NS_DEFAULT é o valor que a maioria dos aplicativos deve usar para dwNameSpace.
NS_DNS
O Sistema de Nomes de Domínio usado na Internet para resolução de nomes de host.
NS_NETBT
A camada NetBIOS sobre TCP/IP. Todos os sistemas operacionais registram seus nomes de computador com NetBIOS. Esse namespace é usado para resolve um nome de computador em um endereço IP usando esse registro. Observe que NS_NETBT pode acessar um servidor WINS para executar a resolução.
NS_SAP
O Protocolo de Publicidade do Serviço NetWare. Isso pode acessar a associação NetWare, se apropriado. NS_SAP é um namespace dinâmico que permite o registro de serviços.
NS_TCPIP_HOSTS
Pesquisa nomes de host e endereços IP no <arquivo systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL
Mecanismos de resolução de nomes TCP/IP locais, incluindo comparações com o nome do host local e pesquisa nomes de host e endereços IP em cache de mapeamentos de endereço IP para host.
 

A maioria das chamadas para GetService deve usar o valor especial NS_DEFAULT. Isso permite que um cliente se ausente sem saber os namespaces disponíveis em uma internetwork. O administrador do sistema determina o acesso ao namespace. Os namespaces podem ir e vir sem que o cliente precise estar ciente das alterações.

[in] lpGuid

Um ponteiro para um GUID (identificador global exclusivo) que especifica o tipo do serviço de rede. O arquivo de cabeçalho Svcguid.h inclui tipos de serviço GUID de muitos serviços conhecidos dentro dos namespaces DNS e SAP.

O arquivo de cabeçalho Svcguid.h não é incluído automaticamente pelo arquivo de cabeçalho Winsock2.h .

[in] lpServiceName

Um ponteiro para uma cadeia de caracteres terminada em zero que representa exclusivamente o nome do serviço. Por exemplo, "MY SNA SERVER".

[in] dwProperties

Um conjunto de sinalizadores de bits que especificam as informações de serviço que a função recupera. Cada uma dessas constantes de sinalizador de bits, exceto PROP_ALL, corresponde a um membro específico da estrutura de dados SERVICE_INFO . Se o sinalizador estiver definido, a função colocará informações no membro correspondente das estruturas de dados armazenadas em *lpBuffer. Os sinalizadores de bit a seguir são definidos.

Valor Significado
PROP_COMMENT
Se esse sinalizador for definido, a função armazenará dados no membro lpComment das estruturas de dados armazenadas em *lpBuffer.
PROP_LOCALE
Se esse sinalizador estiver definido, a função armazenará dados no membro lpLocale das estruturas de dados armazenadas em *lpBuffer.
PROP_DISPLAY_HINT
Se esse sinalizador estiver definido, a função armazenará dados no membro dwDisplayHint das estruturas de dados armazenadas em *lpBuffer.
PROP_VERSION
Se esse sinalizador for definido, a função armazenará dados no membro dwVersion das estruturas de dados armazenadas em *lpBuffer.
PROP_START_TIME
Se esse sinalizador estiver definido, a função armazenará dados no membro dwTime das estruturas de dados armazenadas em *lpBuffer.
PROP_MACHINE
Se esse sinalizador for definido, a função armazenará dados no membro lpMachineName das estruturas de dados armazenadas em *lpBuffer.
PROP_ADDRESSES
Se esse sinalizador estiver definido, a função armazenará dados no membro lpServiceAddress das estruturas de dados armazenadas em *lpBuffer.
PROP_SD
Se esse sinalizador for definido, a função armazenará dados no membro ServiceSpecificInfo das estruturas de dados armazenadas em *lpBuffer.
PROP_ALL
Se esse sinalizador for definido, a função armazenará dados em todos os membros das estruturas de dados armazenadas em *lpBuffer.

[out] lpBuffer

Um ponteiro para um buffer para receber uma matriz de estruturas de NS_SERVICE_INFO e informações de serviço associadas. Cada estrutura NS_SERVICE_INFO contém informações de serviço no contexto de um namespace específico. Observe que, se dwNameSpace for NS_DEFAULT, a função armazenará mais de uma estrutura no buffer; caso contrário, apenas uma estrutura é armazenada.

Cada estrutura NS_SERVICE_INFO contém uma estrutura SERVICE_INFO . Os membros dessas estruturas SERVICE_INFO conterão dados válidos com base nos sinalizadores de bits definidos no parâmetro dwProperties . Se o sinalizador de bit correspondente de um membro não estiver definido em dwProperties, o valor do membro será indefinido.

A função armazena as estruturas NS_SERVICE_INFO em uma matriz consecutiva, começando no início do buffer. Os ponteiros nas estruturas de SERVICE_INFO contidas apontam para informações armazenadas no buffer entre o final das estruturas de NS_SERVICE_INFO e o final do buffer.

[in, out] lpdwBufferSize

Um ponteiro para uma variável que, na entrada, contém o tamanho, em bytes, do buffer apontado por lpBuffer. Na saída, essa variável contém o número de bytes necessários para armazenar as informações solicitadas. Se esse valor de saída for maior que o valor de entrada, a função falhará devido ao tamanho insuficiente do buffer.

[in, optional] lpServiceAsyncInfo

Reservado para uso futuro. Deve ser definido como NULL.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o número de estruturas de NS_SERVICE_INFO armazenadas em *lpBuffer. Zero indica que nenhuma estrutura foi armazenada.

Se a função falhar, o valor retornado será SOCKET_ERROR ( – 1). Para obter informações de erro estendidas, chame GetLastError, que retorna um dos seguintes valores de erro estendidos.

Código do erro Significado
ERROR_INSUFFICIENT_BUFFER
O buffer apontado por lpBuffer é muito pequeno para receber todas as informações solicitadas. Chame a função com um buffer pelo menos tão grande quanto o valor retornado em *lpdwBufferSize.
ERROR_SERVICE_NOT_FOUND
O serviço especificado não foi encontrado ou o namespace especificado não está em uso. O valor retornado da função é zero nesse caso.

Comentários

Observação

O cabeçalho nspapi.h define GetService 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

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho nspapi.h
Biblioteca Mswsock.lib
DLL Mswsock.dll

Confira também

NS_SERVICE_INFO

SERVICE_INFO

SetService

Funções Winsock

Referência de Winsock