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

Artículo
08/28/2023

La función LPWSPGetOverlappedResult devuelve los resultados de una operación superpuesta en el socket especificado.

Sintaxis

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Parámetros

[in] s

Identifica el socket. Este es el mismo socket que se especificó cuando se inició la operación superpuesta mediante una llamada a LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo o LPWSPIoctl.

[in] lpOverlapped

Puntero a una estructura WSAOverlapped que se especificó cuando se inició la operación superpuesta.

[out] lpcbTransfer

Puntero a una variable de 32 bits que recibe el número de bytes transferidos realmente por una operación de envío o recepción, o por LPWSPIoctl.

[in] fWait

Especifica si la función debe esperar a que se complete la operación superpuesta pendiente. Si es TRUE, la función no devuelve hasta que se haya completado la operación. Si FALSE y la operación siguen pendientes, la función devuelve FALSE y lpErrno se WSA_IO_INCOMPLETE. El parámetro fWait puede establecerse en TRUE solo si la operación superpuesta seleccionada notificación de finalización basada en eventos.

[out] lpdwFlags

Puntero a una variable de 32 bits que recibirá una o varias marcas que complementan el estado de finalización. Si la operación superpuesta se inició a través de LPWSPRecv o LPWSPRecvFrom, este parámetro contendrá el valor de resultados para el parámetro lpFlags .

[out] lpErrno

Puntero al código de error.

Valor devuelto

Si LPWSPGetOverlappedResult se realiza correctamente, el valor devuelto es TRUE. Esto significa que la operación superpuesta se ha completado correctamente y el valor al que apunta lpcbTransfer se ha actualizado. Si LPWSPGetOverlappedResult devuelve FALSE, esto significa que la operación superpuesta no se ha completado o que la operación superpuesta se ha completado, pero con errores o el estado de finalización no se pudo determinar debido a errores en uno o varios parámetros de LPWSPGetOverlappedResult. Si se produce un error, el valor al que apunta lpcbTransfer no se actualizará. El parámetro lpErrno indica la causa del error (ya sea de LPWSPGetOverlappedResult o de la operación superpuesta asociada).

Código de error	Significado
WSAENETDOWN	Error en el subsistema de red.
WSAENOTSOCK	El descriptor no es un socket.
WSA_INVALID_HANDLE	El miembro hEvent de la estructura WSAOverlapped no contiene un identificador de objeto de evento válido.
WSAEINVAL	Uno de los parámetros es inaceptable.
WSA_IO_INCOMPLETE	El parámetro fWait es FALSE y la operación de E/S aún no se ha completado.

Comentarios

Los resultados notificados por la función LPWSPGetOverlappedResult son los de la última operación superpuesta del socket especificado a la que se proporcionó la estructura WSAOverlapped especificada y para la que estaban pendientes los resultados de la operación. Se indica una operación pendiente cuando la función que inició la operación devuelve SOCKET_ERROR y el lpErrno se WSA_IO_PENDING. Cuando hay una operación de E/S pendiente, la función que inició la operación restablece el miembro hEvent de la estructura WSAOVERLAPPED al estado no asignado. Después, cuando se haya completado la operación pendiente, el sistema establece el objeto de evento en el estado señalado.

Si el parámetro fWait es TRUE, LPWSPGetOverlappedResult determina si la operación pendiente se ha completado bloqueando y esperando a que el objeto de evento esté en estado señalado. Un cliente puede establecer el parámetro fWait en TRUE solo si seleccionó la notificación de finalización basada en eventos cuando se solicitó la operación de E/S. Si se seleccionó otra forma de notificación, el uso del miembro hEvent de la estructura WSAOverlapped es diferente y establecer fWait en TRUE provoca resultados impredecibles.

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.

Interacción con WPUCompleteOverlappedRequest

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

Al principio del procesamiento superpuesto, el proveedor de servicios establece Internal en WSS_OPERATION_IN_PROGRESS.

Una vez completada la operación de E/S, el proveedor establece OffsetHigh en el código de error de Windows Sockets 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 LPWSPGetOverlappedResult , 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 LPWSPGetOverlappedResult. 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]
Encabezado	ws2spi.h