Função WSANSPIoctl (winsock2.h)

Artigo
08/27/2023

A função WSANSPIoctl do Windows Sockets permite que os desenvolvedores façam chamadas de controle de E/S para um namespace registrado.

Sintaxe

INT WSAAPI WSANSPIoctl(
  [in]      HANDLE          hLookup,
  [in]      DWORD           dwControlCode,
  [in]      LPVOID          lpvInBuffer,
  [in, out] DWORD           cbInBuffer,
  [out]     LPVOID          lpvOutBuffer,
  [in]      DWORD           cbOutBuffer,
  [out]     LPDWORD         lpcbBytesReturned,
  [in]      LPWSACOMPLETION lpCompletion
);

Parâmetros

[in] hLookup

O identificador de pesquisa retornado de uma chamada anterior para a função WSALookupServiceBegin .

[in] dwControlCode

O código de controle da operação a ser executada.

Os valores que podem ser usados para o parâmetro dwControlCode são determinados pelo provedor de namespace.

O valor a seguir é compatível com vários provedores de namespace da Microsoft, incluindo o provedor de namespace de Reconhecimento de Local de Rede (NS_NLA). Esse IOCTL é definido no arquivo de cabeçalho Winsock2.h.

Valor	Significado
SIO_NSP_NOTIFY_CHANGE	Essa operação verifica se os resultados retornados com chamadas anteriores usando o parâmetro hLookup ainda são válidos. Essas chamadas anteriores incluem a chamada inicial para a função WSALookupServiceBegin para recuperar o parâmetro hLookup . Essas chamadas anteriores também podem incluir chamadas para a função WSALookupServiceNext usando o parâmetro hLookup .

[in] lpvInBuffer

Um ponteiro para o buffer de entrada.

[in, out] cbInBuffer

O tamanho, em bytes, do buffer de entrada.

[out] lpvOutBuffer

Um ponteiro para o buffer de saída.

[in] cbOutBuffer

O tamanho, em bytes, do buffer de saída.

[out] lpcbBytesReturned

Um ponteiro para o número de bytes retornados.

[in] lpCompletion

Um ponteiro para uma estrutura WSACOMPLETION , usada para processamento assíncrono. Defina lpCompletion como NULL para forçar a execução de bloqueio (síncrono).

Retornar valor

O sucesso retorna NO_ERROR. A falha retorna SOCKET_ERROR e um código de erro específico pode ser recuperado chamando a função WSAGetLastError . A tabela a seguir descreve os códigos de erro.

Código do erro	Descrição
WSA_INVALID_HANDLE	O parâmetro hLookup não era um identificador de consulta válido retornado por WSALookupServiceBegin.
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente.
WSAEFAULT	O argumento lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer ou lpCompletion não está totalmente contido em uma parte válida do espaço de endereço do usuário. Como alternativa, o argumento cbInBuffer ou cbOutBuffer é muito pequeno e o argumento é modificado para refletir o tamanho de alocação necessário.
WSAEINVAL	Um parâmetro fornecido não é aceitável ou a operação retorna inadequadamente os resultados de vários namespaces quando não faz sentido para a operação especificada.
WSAENETDOWN	O subsistema de rede falhou.
WSAEOPNOTSUPP	A operação não tem suporte. Esse erro será retornado se o provedor de namespace não implementar essa função. Esse erro também poderá ser retornado se o dwControlCode especificado for um comando não reconhecido.
WSAEWOULDBLOCK	O soquete não está usando E/S sobreposta (processamento assíncrono), mas o parâmetro lpCompletion não é NULL. Esse erro é usado como uma notificação especial para o SIO_NSP_NOTIFY_CHANGE IOCTL quando o parâmetro lpCompletion é NULL (uma votação) para indicar que um conjunto de consultas permanece válido.

Comentários

A função WSANSPIoctl é usada para definir ou recuperar parâmetros operacionais associados a um identificador de consulta para um provedor de namespace. O parâmetro hLookup é um identificador para a consulta do provedor de namespace retornada anteriormente pela função WSALookupServiceBegin (não um identificador de soquete).

Qualquer IOCTL enviado a um provedor de namespace pode ser bloqueado indefinidamente, dependendo da implementação do namespace. Se um aplicativo não puder tolerar o bloqueio em uma chamada de função WSANSPIoctl , a E/S sobreposta deverá ser usada e o parâmetro lpCompletion deverá apontar para uma estrutura WSACOMPLETION . Para fazer uma chamada de função WSANSPIoctl não ser desbloqueado e retornar imediatamente, defina o membro Type da estrutura WSACOMPLETION como NSP_NOTIFY_IMMEDIATELY.

Se lpCompletion for NULL, a função WSANSPIoctl será executada como uma chamada de bloqueio. O provedor de namespace deve retornar imediatamente e não deve ser bloqueado. Mas cada namespace é responsável por impor esse comportamento.

O seguinte código IOCTL tem suporte de vários provedores de espaço de nome da Microsoft:

SIO_NSP_NOTIFY_CHANGE

Essa operação verifica se os resultados retornados com chamadas anteriores usando o parâmetro hLookup ainda são válidos. Essas chamadas anteriores incluem a chamada inicial para a função WSALookupServiceBegin para recuperar o parâmetro hLookup . Essas chamadas anteriores também podem incluir chamadas para a função WSALookupServiceNext usando o parâmetro hLookup .

Os provedores de namespace da Microsoft que dão suporte a esse IOCTL incluem o seguinte

NS_NLA – o provedor de namespace NLA (Reconhecimento de Local de Rede).
NS_PNRPNAME – o provedor de namespace PNRP (Protocolo de Resolução de Nomes de Par).
NS_PNRPCLOUD – o provedor de namespace de nuvem PNRP (Protocolo de Resolução de Nomes de Par).

Outros provedores de namespace que não são da Microsoft podem ser instalados que também dão suporte a esse IOCTL.

Quando o parâmetro lpCompletion é NULL, esse IOCTL implementa um comportamento especial. Se o parâmetro lpCompletion for NULL para esse IOCTL, essa operação será uma sondagem e retornará imediatamente. Se o conjunto de consultas permanecer válido, WSAEWOULDBLOCK será retornado como notificação de que o conjunto de consultas permanece válido. Se o conjunto de consultas tiver sido alterado e for inválido, NO_ERROR será retornado indicando êxito na sondagem para invalidação do conjunto de consultas.

Se o parâmetro lpCompletion não for NULL e apontar para uma estrutura WSACOMPLETION , a função WSANSPIoctl retornará WSA_IO_PENDING se a operação sobreposta tiver sido iniciada com êxito e a conclusão será indicada posteriormente. O método especificado na estrutura WSACOMPLETION é usado para notificar o aplicativo se o conjunto de consultas ainda for válido.

Nem todos os protocolos de resolução de nomes são capazes de dar suporte a esse recurso e, portanto, essa chamada de função pode falhar com WSAEOPNOTSUPP. Uma consulta que contém dados de vários provedores não pode chamar esse IOCTL e retornará WSAEINVAL.

Os parâmetros lpvInBuffer, cbInBuffer, lpvOutBuffer e cbOutBuffer são atualmente ignorados pelos provedores de namespace da Microsoft.

Para aplicativos de thread único, um método típico para usar a função WSANSPIoctl é o seguinte. Chame a função WSANSPIoctl com o parâmetro dwControlCode definido como SIO_NSP_NOTIFY_CHANGE sem rotina de conclusão (o parâmetro lpCompletion definido como NULL) após cada chamada de função WSALookupServiceNext para garantir que os dados de consulta ainda sejam válidos. Se os dados se tornarem inválidos, chame a função WSALookupServiceEnd para fechar o identificador de consulta. Chame a função WSALookupServiceBegin para recuperar um novo identificador de consulta e iniciar a consulta novamente.

Para aplicativos com vários threads, um método típico para usar a função WSANSPIoctl é o seguinte. Chame a função WSANSPIoctl com o parâmetro dwControlCode definido como SIO_NSP_NOTIFY_CHANGE com uma rotina de conclusão após a chamada inicial para a função WSALookupServiceBegin . O aplicativo usaria o mecanismo de notificação especificado na rotina de conclusão para ser notificado quando os dados não forem mais válidos. Um mecanismo comum é usar um evento especificado na rotina de conclusão. Se os dados se tornarem inválidos, chame a função WSALookupServiceEnd para fechar o identificador de consulta. Chame as funções WSALookupServiceBegin e WSANSPIoctl para recuperar um novo identificador de consulta e iniciar a consulta novamente.

Alguns protocolos podem simplesmente armazenar em cache as informações localmente e invalidá-la após algum tempo, caso em que a notificação pode ser emitida para indicar que o cache local foi invalidado.

Para protocolos de resolução de nomes em que as alterações são pouco frequentes, é possível que um provedor de namespace indique um evento de alteração global que pode não ser aplicável à consulta na qual a notificação de alteração foi solicitada e emitida.

As operações de sondagem imediata geralmente são muito menos caras, pois não exigem um objeto de notificação. Na maioria dos casos, isso é implementado como uma variável booliana simples marcar. No entanto, a notificação assíncrona pode exigir a criação de threads de trabalho dedicados e/ou canais de comunicação entre processos, dependendo da implementação do serviço de provedor de namespace, e incorrerá na sobrecarga de processamento relacionada ao objeto de notificação envolvido na sinalização do evento de alteração.

Para cancelar uma solicitação de notificação assíncrona, encerre a consulta original com uma chamada de função WSALookupServiceEnd no identificador de consulta afetado. O cancelamento da notificação assíncrona para LUP_NOTIFY_HWND não postará nenhuma mensagem, no entanto, uma operação sobreposta será concluída e a notificação será entregue com o erro WSA_OPERATION_ABORTED.

Nota Todas as E/S iniciadas por um determinado thread são canceladas quando esse thread é encerrado. Para soquetes sobrepostos, as operações assíncronas pendentes podem falhar se o thread for fechado antes da conclusão das operações. Consulte ExitThread para obter mais informações.

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

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 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winsock2.h