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.
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.
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.
[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 |
|---|---|
|
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. |
|
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 |