Função SetAddrInfoExA (ws2tcpip.h)
A função SetAddrInfoEx registra ou desregistra um nome, um nome de serviço e endereços associados a um provedor de namespace específico.
Sintaxe
INT WSAAPI SetAddrInfoExA(
[in] PCSTR pName,
[in] PCSTR pServiceName,
[in, out] SOCKET_ADDRESS *pAddresses,
[in] DWORD dwAddressCount,
[in, optional] LPBLOB lpBlob,
[in] DWORD dwFlags,
[in] DWORD dwNameSpace,
[in, optional] LPGUID lpNspId,
[in, optional] timeval *timeout,
[in, optional] LPOVERLAPPED lpOverlapped,
[in, optional] LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
[out, optional] LPHANDLE lpNameHandle
);
Parâmetros
[in] pName
Um ponteiro para uma cadeia de caracteres terminada em NULL que contém um nome sob o qual os endereços devem ser registrados ou desregistrados. A interpretação desse parâmetro específico para o provedor de namespace.
[in] pServiceName
Um ponteiro para uma cadeia de caracteres opcional terminada em NULL que contém o nome do serviço associado ao nome que está sendo registrado. A interpretação desse parâmetro é específica para o provedor de namespace.
[in, out] pAddresses
Um ponteiro para uma lista opcional de endereços a serem registrados no provedor de namespace.
[in] dwAddressCount
O número de endereços passados no parâmetro pAddresses . Se esse parâmetro for zero, o parâmetro pName será desregistrado do provedor de namespace.
[in, optional] lpBlob
Um ponteiro opcional para dados usados para definir informações de namespace específicas do provedor associadas ao parâmetro pName além de uma lista de endereços. Qualquer informação que não possa ser passada no parâmetro pAddresses pode ser passada no parâmetro lpBlob . O formato dessas informações é específico para o provedor de namespace.
[in] dwFlags
Um conjunto de sinalizadores que controlam como os parâmetros pName e pServiceName devem ser registrados no provedor de namespace. A interpretação dessas informações é específica para o provedor de namespace.
[in] dwNameSpace
Um identificador de namespace que determina com qual provedor de namespace registrar essas informações. Passar um identificador de namespace específico resultará no registro dessas informações somente com os provedores de namespace que dão suporte ao namespace especificado. Especificar NS_ALL resultará no registro das informações com todos os provedores de namespace instalados e ativos.
As opções para o parâmetro dwNameSpace estão listadas no arquivo de inclusão Winsock2.h . Vários provedores de namespace são incluídos no Windows Vista e posterior. Outros provedores de namespace podem ser instalados, portanto, os valores possíveis a seguir são apenas aqueles comumente disponíveis. Muitos outros são possíveis.
[in, optional] lpNspId
Um ponteiro para um GUID opcional de um provedor de namespace específico para registrar essas informações no caso em que vários provedores de namespace são registrados em um único namespace, como NS_DNS. Passar o GUID para um provedor de namespace específico resultará no registro das informações apenas com o provedor de namespace especificado. A função WSAEnumNameSpaceProviders pode ser chamada para recuperar o GUID de um provedor de namespace.
[in, optional] timeout
Um parâmetro opcional que indica o tempo, em milissegundos, para aguardar uma resposta do provedor de namespace antes de anular a chamada. Esse parâmetro está reservado no momento e deve ser definido como NULL , pois não há suporte para uma opção de tempo limite .
[in, optional] lpOverlapped
Um ponteiro opcional para uma estrutura sobreposta usada para operação assíncrona. No momento, esse parâmetro está reservado e deve ser definido como NULL , pois não há suporte para operações assíncronas.
[in, optional] lpCompletionRoutine
Um ponteiro opcional para uma função a ser invocada após a conclusão bem-sucedida para operações assíncronas. No momento, esse parâmetro está reservado e deve ser definido como NULL , pois não há suporte para operações assíncronas.
[out, optional] lpNameHandle
Um ponteiro opcional usado apenas para operações assíncronas. No momento, esse parâmetro está reservado e deve ser definido como NULL , pois não há suporte para operações assíncronas.
Retornar valor
Em caso de êxito, SetAddrInfoEx retorna NO_ERROR (0). Falha retorna um código de erro diferente de zero do Windows Sockets, conforme encontrado nos Códigos de Erro do Windows Sockets.
| Código do erro | Significado |
|---|---|
| Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função. | |
| Ocorreu uma falha temporária na resolução de nomes. | |
| Um parâmetro inválido foi fornecido. Esse erro será retornado se qualquer um dos parâmetros reservados não for NULL. | |
| Espaço em buffer insuficiente está disponível. | |
| Ocorreu uma falha não recuperável na resolução de nomes. | |
| Ocorreu uma falha de alocação de memória. |
Comentários
A função SetAddrInfoEx fornece um método independente de protocolo para registrar ou cancelar o registro de um nome e um ou mais endereços com um provedor de namespace. O NS_EMAIL provedor de namespace no Windows Vista e posterior dá suporte ao registro e ao cancelamento do registro de endereços. Atualmente, os provedores de namespace padrão NS_DNS, NS_PNRPNAME e NS_PNRPNAME não dão suporte ao registro de nome.
Se a função SetAddrInfoEx for chamada com NS_ALL definida como o parâmetro dwNameSpace e o parâmetro lpNspId não especificado, SetAddrInfoEx tentará registrar ou cancelar o registro do nome e dos endereços associados com todos os namespaces instalados e ativos. A função SetAddrInfoEx retornará êxito se qualquer um dos provedores de namespace tiver registrado ou desregistrado o nome com êxito, mas não haverá nenhuma indicação de qual provedor de namespace foi bem-sucedido ou quais falharam na solicitação.
Quando UNICODE ou _UNICODE é definido, SetAddrInfoEx é definido como SetAddrInfoExW, a versão Unicode dessa função. Os parâmetros de cadeia de caracteres são definidos para o tipo de dados PWSTR .
Quando UNICODE ou _UNICODE não está definido, SetAddrInfoEx é definido como SetAddrInfoExA, a versão ANSI dessa função. Os parâmetros de cadeia de caracteres são do tipo de dados PCSTR .
As informações registradas com um provedor de namespace podem ser retornadas chamando as funções GetAddrInfoEx, getaddrinfo ou GetAddrInfoW . A função GetAddrInfoEx é uma versão aprimorada das funções getaddrinfo e GetAddrInfoW .
No Windows Vista e posterior, quando SetAddrInfoEx for chamado de um serviço, se a operação for o resultado de um processo de usuário chamando o serviço, o serviço deverá representar o usuário. Isso é para permitir que os compartimentos de segurança e roteamento sejam aplicados corretamente.
Windows 8.1 e Windows Server 2012 R2: a função SetAddrInfoExW tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posterior.
Observação
O cabeçalho ws2tcpip.h define SetAddrInfoEx 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 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2tcpip.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de