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.

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.

Requisitos

Confira também

GetAddrInfoEx

GetAddrInfoW

WSAEnumNameSpaceProviders

Wsagetlasterror

Códigos de erro do Windows Sockets

Getaddrinfo