Función de devolución de llamada LPNSPIOCTL (ws2spi.h)

Artículo
08/28/2023

La función NSPIoctl envía un IOCTL a un proveedor de servicios de espacio de nombres.

Sintaxis

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

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

[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.

Value	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 NSPLookupServiceBegin para recuperar el parámetro hLookup . Estas llamadas anteriores también pueden incluir llamadas a la función NSPLookupServiceNext 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).

[in] lpThreadId

Puntero a una estructura WSATHREADID que va a usar el proveedor en una llamada posterior a WPUQueueApc. El proveedor debe almacenar la estructura WSATHREADID a la que se hace referencia (no el puntero) hasta que se devuelva la función WPUQueueApc .

Valor devuelto

Si no se produce ningún error y la operación se ha completado inmediatamente, la función NSPIoctl debe devolver NO_ERROR (cero). Tenga en cuenta que, en este caso, la rutina de finalización, si se especifica, ya se habrá puesto en cola.

La función NSPIoctl debe devolver SOCKET_ERROR (es decir, 1) si se produce un error en la rutina y debe establecer el código de error adecuado mediante WSASetLastError.

El código de error WSA_IO_PENDING indica que se ha iniciado correctamente una operación superpuesta y que la finalización se indicará más adelante. Cualquier otro código de error indica que no se inició ninguna operación superpuesta y no se producirá ninguna indicación de finalización.

Código de error	Descripción
WSA_INVALID_HANDLE	El parámetro hLookup no era un identificador de consulta válido devuelto por NSPLookupServiceBegin.
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 recurso no está disponible temporalmente. El socket no usa E/S superpuesta (procesamiento asincrónico), pero el parámetro lpCompletion no esNULL. 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.

Observaciones

La función NSPIoctl se usa para enviar un código de control de E/S a un proveedor de espacios de nombres para establecer o recuperar parámetros operativos asociados a un identificador de consulta. El parámetro hLookup es un identificador de la consulta del proveedor de espacios de nombres que devolvió anteriormente la función NSPLookupServiceBegin (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 NSPIoctl , se debe usar la E/S superpuesta y el parámetro lpCompletion debe apuntar a una estructura WSACOMPLETION . Para que una función NSPIoctl llame a nonblocking y devuelva inmediatamente, establezca el miembro Type de la estructura WSACOMPLETIONen NSP_NOTIFY_IMMEDIATELY.

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

El código IOCTL siguiente es compatible con varios proveedores de espacios 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 NSPLookupServiceBegin para recuperar el parámetro hLookup . Estas llamadas anteriores también pueden incluir llamadas a la función NSPLookupServiceNext 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 NSPIoctl 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 NSPIoctl es el siguiente. Llame a la función NSPIoctl 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 NSPLookupServiceNext para asegurarse de que los datos de consulta siguen siendo válidos. Si los datos no son válidos, llame a la función NSPLookupServiceEnd para cerrar el identificador de consulta. Llame a la función NSPLookupServiceBegin 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 NSPIoctl es el siguiente. Llame a la función NSPIoctl 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 NSPLookupServiceBegin . 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 NSPLookupServiceEnd para cerrar el identificador de consulta. Llame a las funciones NSPLookupServiceBegin y NSPIoctl 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 recursos, 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 NSPLookupServiceEnd 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 se cierra antes de que se completen las operaciones. Consulte ExitThread para obtener más información.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2spi.h