Función WPUCompleteOverlappedRequest (ws2spi.h)

  • Artículo

La función WPUCompleteOverlappedRequest realiza una notificación de finalización de E/S superpuesta para las operaciones de E/S superpuestas.

Sintaxis

int WPUCompleteOverlappedRequest(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  DWORD           dwError,
  [in]  DWORD           cbTransferred,
  [out] LPINT           lpErrno
);

Parámetros

[in] s

Socket del proveedor de servicios creado por WPUCreateSocketHandle.

[in] lpOverlapped

Puntero a una estructura WSAOVERLAPPED asociada a la operación de E/S superpuesta cuya finalización se va a notificar.

[in] dwError

Estado de finalización de la operación de E/S superpuesta cuya finalización se va a notificar.

[in] cbTransferred

El número de bytes transferidos a o desde búferes de cliente (la dirección de la transferencia depende de la naturaleza de envío o recepción de la operación de E/S superpuesta cuya finalización se va a notificar).

[out] lpErrno

Puntero al código de error resultante de la ejecución de esta función.

Valor devuelto

Si no se produce ningún error, WPUCompleteOverlappedRequest devuelve cero y notifica a la finalización de la operación de E/S superpuesta según el mecanismo seleccionado por el cliente (indica un evento encontrado en la estructura WSAOVERLAPPED a la que hace referencia lpOverlapped o pone en cola un informe de estado de finalización al puerto de finalización asociado al socket si está asociado un puerto de finalización). De lo contrario, WPUCompleteOverlappedRequest devuelve SOCKET_ERROR y un código de error específico está disponible en lpErrno.

Código de error Significado
WSAEINVAL
 El socket pasado en el parámetro s no es un socket creado por WPUCreateSocketHandle.

Comentarios

La función WPUCompleteOverlappedRequest realiza una notificación de finalización de E/S superpuesta para operaciones de E/S superpuestas en las que el mecanismo de finalización especificado por el cliente es algo distinto de la llamada a procedimiento asincrónico del modo de usuario (APC). Esta función solo se puede usar para los identificadores de socket creados por WPUCreateSocketHandle.

**Nota** Esta función es diferente de otras funciones con el prefijo "WPU" en el que no se tiene acceso a través de la tabla upcall. En su lugar, se exporta directamente mediante Ws2_32.dll. Los proveedores de servicios que necesitan llamar a esta función deben vincularse con WS2_32.lib o usar las funciones del sistema operativo adecuadas, como LoadLibrary y GetProcAddress para recuperar el puntero de función.
 
Los proveedores de servicios que no implementan la función **WPUCompleteOverlappedRequest** usan la función **WPUCompleteOverlappedRequest** que no implementan la funcionalidad del sistema de archivos instalable (IFS) directamente para los identificadores de socket que exponen. Realiza una notificación de finalización para cualquier solicitud de E/S superpuesta para la que la notificación de finalización especificada no sea un APC en modo de usuario. **WPUCompleteOverlappedRequest** solo se admite para los identificadores de socket creados por WPUCreateSocketHandle y no para los sockets creados por un proveedor de servicios directamente.

Si el cliente selecciona un APC en modo de usuario como método de notificación, el proveedor de servicios debe usar WPUQueueApc u otra función de sistema operativo adecuada para realizar la notificación de finalización. Si el cliente no selecciona APC en modo de usuario, un proveedor de servicios que no implementa la funcionalidad IFS directamente no puede determinar si el cliente ha asociado o no un puerto de finalización con el identificador de socket. Por lo tanto, no puede determinar si el método de notificación de finalización debe poner en cola un registro de estado de finalización en un puerto de finalización o indicar un evento encontrado en la estructura WSAOVERLAPPED . La arquitectura de Windows Socket 2 realiza un seguimiento de cualquier asociación de puerto de finalización con un socket creado por WPUCreateSocketHandle y puede tomar una decisión correcta entre la notificación basada en puertos de finalización o la notificación basada en eventos.

Cuando WPUCompleteOverlappedRequest pone en cola una indicación de finalización, establece el miembro InternalHigh de la estructura WSAOVERLAPPED en el recuento de bytes transferidos. A continuación, establece el miembro Interno en algún valor dependiente del sistema operativo distinto del valor especial WSS_OPERATION_IN_PROGRESS. Puede haber algún ligero retraso después de que WPUCompleteOverlappedRequest devuelva antes de que aparezcan estos valores, ya que el procesamiento puede producirse de forma asincrónica. Sin embargo, se garantiza que el valor InternalHigh (recuento de bytes) se establece en el momento en que se establece Internal.

WPUCompleteOverlappedRequest funciona como se indica (realiza la notificación de finalización solicitada por el cliente) si el controlador de socket se ha asociado o no a un puerto de finalización.

Interacción con WSPGetOverlappedResult

El comportamiento de WPUCompleteOverlappedRequest coloca algunas restricciones sobre cómo un proveedor de servicios implementa WSPGetOverlappedResult , ya que solo los miembros Offset y OffsetHigh de la estructura WSAOVERLAPPED se controlan exclusivamente por el proveedor de servicios, pero el proveedor de servicios debe recuperar tres valores (recuento de bytes, marcas y errores) de la estructura mediante WSPGetOverlappedResult. Un proveedor de servicios puede hacerlo de cualquier manera que elija siempre que interactúe con el comportamiento de WPUCompleteOverlappedRequest correctamente. Sin embargo, una implementación típica es la siguiente:

  • Al principio del procesamiento superpuesto, el proveedor de servicios establece Internal en WSS_OPERATION_IN_PROGRESS.
  • Cuando se ha completado la operación de E/S, el proveedor establece OffsetHigh en el código de error de Windows Socket 2 resultante de la operación, establece Offset en las marcas resultantes de la operación de E/S y llama a WPUCompleteOverlappedRequest, pasando el recuento de bytes de transferencia como uno de los parámetros. WPUCompleteOverlappedRequest finalmente establece InternalHigh en el recuento de bytes de transferencia y, a continuación, establece Internal en un valor distinto de WSS_OPERATION_IN_PROGRESS.
  • Cuando se llama a WSPGetOverlappedResult , el proveedor de servicios comprueba Interno. Si es WSS_OPERATION_IN_PROGRESS, el proveedor espera el identificador de eventos en el miembro hEvent o devuelve un error, en función de la configuración de la marca FWAIT de WSPGetOverlappedResult. Si no está en curso o después de la finalización de la espera, el proveedor devuelve los valores de InternalHigh, OffsetHigh y Offset como recuento de transferencias, código de error de resultado de la operación y marcas, respectivamente.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado ws2spi.h

Consulte también

WPUCreateSocketHandle

WPUQueueApc

WSAOVERLAPPED

WSPGetOverlappedResult