Función WSANSPIoctl (winsock2.h)

Artículo
03/04/2024

La función WSANSPIoctl de Windows Sockets permite a los desarrolladores realizar llamadas de control de E/S a un espacio de nombres registrado.

Sintaxis

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

Identificador de búsqueda devuelto de una llamada anterior a la función WSALookupServiceBegin .

[in] dwControlCode

Código de control de la operación que se va a realizar.

El proveedor de espacios de nombres determina los valores que se pueden usar para el parámetro dwControlCode .

El siguiente valor es compatible con varios proveedores de espacios de nombres de Microsoft, incluido el proveedor de espacio de nombres Reconocimiento de ubicación de red (NS_NLA). Este IOCTL se define en el archivo de encabezado Winsock2.h.

Valor	Significado
SIO_NSP_NOTIFY_CHANGE	Esta operación comprueba si los resultados devueltos con llamadas anteriores mediante el parámetro hLookup siguen siendo válidos. Estas llamadas anteriores incluyen la llamada inicial a la función WSALookupServiceBegin para recuperar el parámetro hLookup . Estas llamadas anteriores también pueden incluir llamadas a la función WSALookupServiceNext mediante el parámetro hLookup .

[in] lpvInBuffer

Puntero al búfer de entrada.

[in, out] cbInBuffer

Tamaño, en bytes, del búfer de entrada.

[out] lpvOutBuffer

Puntero al búfer de salida.

[in] cbOutBuffer

Tamaño, en bytes, del búfer de salida.

[out] lpcbBytesReturned

Puntero al número de bytes devueltos.

[in] lpCompletion

Puntero a una estructura WSACOMPLETION , que se usa para el procesamiento asincrónico. Establezca lpCompletion enNULL para forzar la ejecución del bloqueo (sincrónico).

Valor devuelto

Success devuelve NO_ERROR. Error devuelve SOCKET_ERROR y se puede recuperar un código de error específico mediante una llamada a la función WSAGetLastError . En la tabla siguiente se describen los códigos de error.

Código de error	Descripción
WSA_INVALID_HANDLE	El parámetro hLookup no era un identificador de consulta válido devuelto por WSALookupServiceBegin.
WSA_IO_PENDING	Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior.
WSAEFAULT	El argumento lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer o lpCompletion no está totalmente incluido en una parte válida del espacio de direcciones del usuario. Como alternativa, el argumento cbInBuffer o cbOutBuffer es demasiado pequeño y el argumento se modifica para reflejar el tamaño de asignación necesario.
WSAEINVAL	Un parámetro proporcionado no es aceptable o la operación devuelve incorrectamente resultados de varios espacios de nombres cuando no tiene sentido para la operación especificada.
WSAENETDOWN	Error en el subsistema de red.
WSAEOPNOTSUPP	La operación no es compatible. Este error se devuelve si el proveedor de espacios de nombres no implementa esta función. Este error también se puede devolver si dwControlCode especificado es un comando no reconocido.
WSAEWOULDBLOCK	El socket no usa E/S superpuesta (procesamiento asincrónico), pero el parámetro lpCompletion no es NULL. Este error se usa como una notificación especial para el SIO_NSP_NOTIFY_CHANGE IOCTL cuando el parámetro lpCompletion es NULL (un sondeo) para indicar que un conjunto de consultas sigue siendo válido.

Comentarios

La función WSANSPIoctl se usa para establecer o recuperar parámetros operativos asociados con un identificador de consulta a un proveedor de espacios de nombres. El parámetro hLookup es un identificador de la consulta del proveedor de espacios de nombres que devolvió anteriormente la función WSALookupServiceBegin (no un identificador de socket).

Cualquier IOCTL enviado a un proveedor de espacios de nombres puede bloquearse indefinidamente, dependiendo de la implementación del espacio de nombres. Si una aplicación no puede tolerar el bloqueo en una llamada de función WSANSPIoctl , se debe usar la E/S superpuesta y el parámetro lpCompletion debe apuntar a una estructura WSACOMPLETION . Para que una función WSANSPIoctl llame a nonblocking y devuelva inmediatamente, establezca el miembro Type de la estructura WSACOMPLETIONen NSP_NOTIFY_IMMEDIATELY.

Si lpCompletion es NULL, la función WSANSPIoctl se ejecuta como una llamada de bloqueo. El proveedor de espacios de nombres debe devolverse inmediatamente y no debe bloquearse. Pero cada espacio de nombres es responsable de aplicar este comportamiento.

El siguiente código IOCTL es compatible con varios proveedores de espacio de nombres de Microsoft:

SIO_NSP_NOTIFY_CHANGE

Esta operación comprueba si los resultados devueltos con llamadas anteriores mediante el parámetro hLookup siguen siendo válidos. Estas llamadas anteriores incluyen la llamada inicial a la función WSALookupServiceBegin para recuperar el parámetro hLookup . Estas llamadas anteriores también pueden incluir llamadas a la función WSALookupServiceNext mediante el parámetro hLookup .

Los proveedores de espacios de nombres de Microsoft que admiten este IOCTL incluyen lo siguiente:

NS_NLA: proveedor de espacio de nombres reconocimiento de ubicación de red (NLA).
NS_PNRPNAME: proveedor de espacio de nombres del Protocolo de resolución de nombres del mismo nivel (PNRP).
NS_PNRPCLOUD: proveedor de espacio de nombres en la nube del Protocolo de resolución de nombres del mismo nivel (PNRP).

Es posible que otros proveedores de espacios de nombres que no sean de Microsoft estén instalados que también admitan este IOCTL.

Cuando el parámetro lpCompletion es NULL, este IOCTL implementa un comportamiento especial. Si el parámetro lpCompletion es NULL para este IOCTL, esta operación es un sondeo y devuelve inmediatamente. Si el conjunto de consultas sigue siendo válido, WSAEWOULDBLOCK se devuelve como notificación de que el conjunto de consultas sigue siendo válido. Si el conjunto de consultas ha cambiado y no es válido, se devuelve NO_ERROR que indica que el sondeo se ha realizado correctamente para la invalidación del conjunto de consultas.

Si el parámetro lpCompletion no es NULL y apunta a una estructura WSACOMPLETION , la función WSANSPIoctl devuelve WSA_IO_PENDING si la operación superpuesta se inició correctamente y la finalización se indicará más adelante. El método especificado en la estructura WSACOMPLETION se usa para notificar a la aplicación si el conjunto de consultas sigue siendo válido.

No todos los protocolos de resolución de nombres son capaces de admitir esta característica y, por lo tanto, esta llamada de función puede producir un error con WSAEOPNOTSUPP. Una consulta que contiene datos de varios proveedores no puede llamar a este IOCTL y devolverá WSAEINVAL.

Los proveedores de espacios de nombres de Microsoft ignoran los parámetros lpvInBuffer, cbInBuffer, cbInBuffer, cbInBuffer y cbOutBuffer.

En el caso de las aplicaciones de un solo subproceso, un método típico para usar la función WSANSPIoctl es el siguiente. Llame a la función WSANSPIoctl con el parámetro dwControlCode establecido en SIO_NSP_NOTIFY_CHANGE sin rutina de finalización (el parámetro lpCompletion establecido en NULL) después de cada llamada de función WSALookupServiceNext para asegurarse de que los datos de consulta siguen siendo válidos. Si los datos no son válidos, llame a la función WSALookupServiceEnd para cerrar el identificador de consulta. Llame a la función WSALookupServiceBegin para recuperar un nuevo identificador de consulta y volver a iniciar la consulta.

En el caso de las aplicaciones multiproceso, un método típico para usar la función WSANSPIoctl es el siguiente. Llame a la función WSANSPIoctl con el parámetro dwControlCode establecido en SIO_NSP_NOTIFY_CHANGE con una rutina de finalización después de la llamada inicial a la función WSALookupServiceBegin . La aplicación usaría el mecanismo para la notificación especificada en la rutina de finalización para recibir notificaciones cuando los datos ya no son válidos. Un mecanismo común consiste en usar un evento especificado en la rutina de finalización. Si los datos no son válidos, llame a la función WSALookupServiceEnd para cerrar el identificador de consulta. Llame a las funciones WSALookupServiceBegin y WSANSPIoctl para recuperar un nuevo identificador de consulta y volver a iniciar la consulta.

Algunos protocolos pueden simplemente almacenar en caché la información localmente e invalidarla después de algún tiempo, en cuyo caso se puede emitir una notificación para indicar que se ha invalidado la caché local.

En el caso de los protocolos de resolución de nombres en los que los cambios son poco frecuentes, es posible que un proveedor de espacios de nombres indique un evento de cambio global que puede no ser aplicable a la consulta en la que se solicitó y emitió la notificación de cambio.

Las operaciones de sondeo inmediato suelen ser mucho menos costosas, ya que no requieren un objeto de notificación. En la mayoría de los casos, esto se implementa como una comprobación de variable booleana simple. Sin embargo, la notificación asincrónica puede requerir la creación de subprocesos de trabajo dedicados o canales de comunicación entre procesos, en función de la implementación del servicio del proveedor de espacios de nombres, y incurrirá en una sobrecarga de procesamiento relacionada con el objeto de notificación implicado en la señalización del evento de cambio.

Para cancelar una solicitud de notificación asincrónica, finalice la consulta original con una llamada de función WSALookupServiceEnd en el identificador de consulta afectado. La cancelación de la notificación asincrónica para LUP_NOTIFY_HWND no publicará ningún mensaje; sin embargo, se completará una operación superpuesta y se entregará la notificación con el error WSA_OPERATION_ABORTED.

Nota Todas las E/S iniciadas por un subproceso determinado se cancelan cuando se cierra ese subproceso. En el caso de los sockets superpuestos, las operaciones asincrónicas pendientes pueden producir un error si el subproceso está cerrado antes de que se completen las operaciones. Consulte ExitThread para obtener más información.

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winsock2.h