Função SetAddrInfoExA (ws2tcpip.h)

A função SetAddrInfoEx registra ou desregistro 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 um cadeia de caracteres nullterminada que contém um nome no 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 um nulo opcionalcadeia de caracteres terminada 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 com o provedor de namespace.

[in] dwAddressCount

O número de endereços passados em 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 com o 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 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. No momento, esse parâmetro está reservado e deve ser definido como NULL, uma vez que 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.

Valor de retorno

Com êxito, SetAddrInfoEx retorna NO_ERROR (0). A falha retorna um código de erro de soquetes do Windows diferente de zero, conforme encontrado node erros de soquetes do Windows .

Observações

A função SetAddrInfoEx fornece um método independente de protocolo para registrar ou desregister um nome e um ou mais endereços com um provedor de namespace. O provedor de namespace NS_EMAIL no Windows Vista e posterior dá suporte ao registro e ao cancelamento do registro de endereços. Os provedores de namespace padrão NS_DNS, NS_PNRPNAME e NS_PNRPNAME atualmente não dão suporte ao registro de nome.

Se a função SetAddrInfoEx for chamada com NS_ALL definido como o parâmetro dwNameSpace e o parâmetro lpNspId não especificado, SetAddrInfoEx tentará registrar ou desregister o nome e os endereços associados com todos os namespaces instalados e ativos. A função SetAddrInfoEx retornará êxito se algum 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 é 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 .

Informações registradas com um provedor de namespace podem ser retornadas chamando as funções GetAddrInfoEx, getaddrinfoou 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 no Windows 8.1, Windows Server 2012 R2 e posterior.

Requisitos

Consulte também

GetAddrInfoEx

GetAddrInfoW

WSAEnumNameSpaceProviders

WSAGetLastError

códigos de erro de soquetes do Windows

getaddrinfo