Função de retorno de chamada LPNSPIOCTL (ws2spi.h)
A função NSPIoctl envia um IOCTL para um provedor de serviços de namespace.
Sintaxe
LPNSPIOCTL Lpnspioctl;
INT Lpnspioctl(
[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,
[in] LPWSATHREADID lpThreadId
)
{...}
Parâmetros
[in] hLookup
O identificador de pesquisa retornado de uma chamada anterior para a função NSPLookupServiceBegin .
[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 tem suporte de vários provedores de namespace da Microsoft, incluindo o provedor de namespace Network Location Awareness (NS_NLA). Esse IOCTL é definido no arquivo de cabeçalho Winsock2.h.
| Valor | Significado |
|---|---|
|
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 NSPLookupServiceBegin para recuperar o parâmetro hLookup . Essas chamadas anteriores também podem incluir chamadas para a função NSPLookupServiceNext 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).
[in] lpThreadId
Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro) até que a função WPUQueueApc retorne.
Valor retornado
Se nenhum erro ocorrer e a operação tiver sido concluída imediatamente, a função NSPIoctl deverá retornar NO_ERROR (zero). Observe que, nesse caso, a rotina de conclusão, se especificada, já terá sido enfileirada.
A função NSPIoctl deverá retornar SOCKET_ERROR (ou seja, 1) se a rotina falhar e precisar definir o código de erro apropriado usando WSASetLastError.
O código de erro WSA_IO_PENDING indica que uma operação sobreposta foi iniciada com êxito e que a conclusão será indicada posteriormente. Qualquer outro código de erro indica que nenhuma operação sobreposta foi iniciada e nenhuma indicação de conclusão ocorrerá.
| Código do erro | Descrição |
|---|---|
| O parâmetro hLookup não era um identificador de consulta válido retornado por NSPLookupServiceBegin. | |
| Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. | |
| 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. | |
| 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. | |
| O subsistema de rede falhou. | |
| 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. | |
|
O recurso está temporariamente indisponível. 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 sondagem) para indicar que um conjunto de consultas permanece válido. |
Comentários
A função NSPIoctl é usada para enviar um código de controle de E/S para um provedor de namespace para definir ou recuperar parâmetros operacionais associados a um identificador de consulta. O parâmetro hLookup é um identificador para a consulta do provedor de namespace retornada anteriormente pela função NSPLookupServiceBegin (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 NSPIoctl , a E/S sobreposta deverá ser usada e o parâmetro lpCompletion deverá apontar para uma estrutura WSACOMPLETION . Para fazer com que uma função NSPIoctl chame nonblocking e retorne imediatamente, defina o membro Type da estrutura WSACOMPLETION como NSP_NOTIFY_IMMEDIATELY.
Se lpCompletion for NULL, a função NSPIoctl será executada como uma chamada de bloqueio. O provedor de namespace deve retornar imediatamente e não deve ser bloqueado. Mas cada provedor de namespace é responsável por impor esse comportamento.
O código IOCTL a seguir tem suporte de vários provedores de namespace da Microsoft:
Os provedores de namespace da Microsoft que dão suporte a este IOCTL incluem o seguinte:
- NS_NLA – o provedor de namespace NLA (Network Location Awareness).
- NS_PNRPNAME – o provedor de namespace PNRP (Peer Name Resolution Protocol).
- NS_PNRPCLOUD – o provedor de namespace de nuvem PNRP (Peer Name Resolution Protocol).
Outros provedores de namespace que não são da Microsoft podem ser instalados que também dão suporte a essa 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 NSPIoctl 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 atualmente são ignorados pelos provedores de namespace da Microsoft.
Para aplicativos de thread único, um método típico para usar a função NSPIoctl é o seguinte. Chame a função NSPIoctl 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 NSPLookupServiceNext para garantir que os dados da consulta ainda sejam válidos. Se os dados se tornarem inválidos, chame a função NSPLookupServiceEnd para fechar o identificador de consulta. Chame a função NSPLookupServiceBegin para recuperar um novo identificador de consulta e iniciar a consulta novamente.
Para aplicativos multithreaded, um método típico para usar a função NSPIoctl é o seguinte. Chame a função NSPIoctl 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 NSPLookupServiceBegin . 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 NSPLookupServiceEnd para fechar o identificador de consulta. Chame as funções NSPLookupServiceBegin e NSPIoctl 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 intensivas em recursos, 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á em 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 NSPLookupServiceEnd 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.
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2spi.h |