Función WSARecv (winsock2.h)
La función WSARecv recibe datos de un socket conectado o de un socket sin conexión enlazado.
Sintaxis
int WSAAPI WSARecv(
[in] SOCKET s,
[in, out] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesRecvd,
[in, out] LPDWORD lpFlags,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Parámetros
[in] s
Descriptor que identifica un socket conectado.
[in, out] lpBuffers
Puntero a una matriz de estructuras WSABUF . Cada estructura WSABUF contiene un puntero a un búfer y la longitud, en bytes, del búfer.
[in] dwBufferCount
Número de estructuras WSABUF en la matriz lpBuffers .
[out] lpNumberOfBytesRecvd
Puntero al número, en bytes, de datos recibidos por esta llamada si la operación de recepción se completa inmediatamente.
Use NULL para este parámetro si el parámetro lpOverlapped no es NULL para evitar resultados potencialmente erróneos. Este parámetro solo puede ser NULL si el parámetro lpOverlapped no es NULL.
[in, out] lpFlags
Puntero a marcas usadas para modificar el comportamiento de la llamada de función WSARecv . Para obtener más información, vea la sección Comentarios.
[in] lpOverlapped
Puntero a una estructura WSAOVERLAPPED (omitida para sockets no superpuestos).
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Puntero a la rutina de finalización a la que se llama cuando se ha completado la operación de recepción (se omite para sockets no superpuestos).
Valor devuelto
Si no se produce ningún error y la operación de recepción se ha completado inmediatamente, WSARecv devuelve cero. En este caso, la rutina de finalización ya se habrá programado para llamarse una vez que el subproceso que realiza la llamada esté en estado de alerta. De lo contrario, se devuelve un valor de SOCKET_ERROR y se puede recuperar un código de error específico mediante una llamada a WSAGetLastError. El código de error WSA_IO_PENDING indica que la operación superpuesta se ha iniciado correctamente y que la finalización se indicará más adelante. Cualquier otro código de error indica que la operación superpuesta no se inició correctamente y no se producirá ninguna indicación de finalización.
| Código de error | Significado |
|---|---|
| Se finalizó el circuito virtual debido a un tiempo de espera agotado u otro error. | |
| En el caso de un socket de flujo, el circuito virtual se restableció por el lado remoto. La aplicación debería cerrar el socket porque ya no se puede usar. En el caso de un socket de datagrama UDP, este error indicaría que una operación de envío anterior dio lugar a un mensaje icMP "Puerto inaccesible". | |
| Socket s está orientado a mensajes y el circuito virtual se cerró correctamente por el lado remoto. | |
| El parámetro lpBuffers no está completamente contenido en una parte válida del espacio de direcciones del usuario. | |
| Una llamada de Bloqueo de Windows Sockets 1.1 está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada. | |
| La función WSACancelBlockingCall canceló la llamada (bloqueo). | |
| El socket no se ha enlazado (por ejemplo, con enlace). | |
| El mensaje era demasiado grande para caber en el búfer especificado y (solo para protocolos no confiables) se ha descartado cualquier parte final del mensaje que no cabe en el búfer. | |
| Error en el subsistema de red. | |
| En el caso de un socket orientado a la conexión, este error indica que la conexión se ha interrumpido debido a la actividad de mantenimiento activo que detectó un error mientras la operación estaba en curso. Para un socket de datagrama, este error indica que expiró el tiempo de vida. | |
| El socket no está conectado. | |
| El descriptor no es un socket. | |
| MSG_OOB se especificó, pero el socket no es de tipo SOCK_STREAM, los datos de OOB no se admiten en el dominio de comunicación asociado a este socket o el socket es unidireccional y solo admite operaciones de envío. | |
| El socket se ha apagado; no es posible llamar a WSARecv en un socket después de que se haya invocado el apagado con cómo se establece en SD_RECEIVE o SD_BOTH. | |
| Se interrumpió la conexión debido a un error de red o porque el sistema del mismo nivel no respondió. | |
|
Windows NT: Sockets superpuestos: hay demasiadas solicitudes de E/S superpuestas pendientes. Sockets no superpuestos: el socket se marca como no desbloqueado y la operación de recepción no se puede completar inmediatamente. |
|
| Debe producirse una llamada WSAStartup correcta antes de usar esta función. | |
| Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior. | |
| La operación superpuesta se ha cancelado debido al cierre del socket. |
Comentarios
La función WSARecv proporciona algunas características adicionales en comparación con la función recv estándar en tres áreas importantes:
- Se puede usar junto con sockets superpuestos para realizar operaciones de recv superpuestas.
- Permite especificar varios búferes de recepción, por lo que es aplicable al tipo de dispersión y recopilación de E/S.
- El parámetro lpFlags se usa en la entrada y se devuelve en la salida, lo que permite a las aplicaciones detectar el estado de salida del bit de marca de MSG_PARTIAL . Sin embargo, el bit de marca de MSG_PARTIAL no es compatible con todos los protocolos.
En el caso de sockets conectados sin conexión, esta función restringe las direcciones de las que se aceptan los mensajes recibidos. La función solo devuelve mensajes de la dirección remota especificada en la conexión. Los mensajes de otras direcciones se descartan (silenciosamente).
En el caso de los sockets superpuestos, WSARecv se usa para publicar uno o varios búferes en los que se colocarán los datos entrantes a medida que estén disponibles, después de lo cual se produce la indicación de finalización especificada por la aplicación (invocación de la rutina de finalización o configuración de un objeto de evento). Si la operación no se completa inmediatamente, el estado de finalización final se recupera a través de la rutina de finalización o WSAGetOverlappedResult.
En el caso de los sockets no superpuestos, la semántica de bloqueo es idéntica a la de la función recv estándar y se omiten los parámetros lpOverlapped y lpCompletionRoutine . Los datos que ya se hayan recibido y almacenado en búfer por el transporte se copiarán en los búferes de usuario especificados. En el caso de un socket de bloqueo sin datos recibidos actualmente y almacenados en búfer por el transporte, la llamada se bloqueará hasta que se reciban los datos. Windows Sockets 2 no define ningún mecanismo de tiempo de espera de bloqueo estándar para esta función. En el caso de los protocolos que actúan como protocolos de flujo de bytes, la pila intenta devolver tantos datos como sea posible sujeto al espacio de búfer disponible y a la cantidad de datos recibidos disponibles. Sin embargo, la recepción de un solo byte es suficiente para desbloquear el autor de la llamada. No hay ninguna garantía de que se devuelva más de un solo byte. En el caso de los protocolos que actúan como orientados a mensajes, se requiere un mensaje completo para desbloquear al autor de la llamada.
| XP1_MESSAGE_ORIENTED | XP1_PSEUDO_STREAM | MSG_PARTIAL | Actúa como |
|---|---|---|---|
| Sin establecer | * | * | Secuencia de bytes |
| * | Set | * | Secuencia de bytes |
| set | Sin establecer | set | Secuencia de bytes |
| set | Sin establecer | Sin establecer | Orientado a mensajes |
Los búferes se rellenan en el orden en que aparecen en la matriz a la que apuntan lpBuffers, y los búferes se empaquetan para que no se creen agujeros.
Si esta función se completa de forma superpuesta, es responsabilidad del proveedor de servicios winsock capturar las estructuras WSABUF antes de volver de esta llamada. Esto permite a las aplicaciones compilar matrices WSABUF basadas en pila a las que apunta el parámetro lpBuffers .
En el caso de los sockets de estilo de secuencia de bytes (por ejemplo, el tipo SOCK_STREAM), los datos entrantes se colocan en los búferes hasta que se rellenan los búferes, se cierra la conexión o se agotan los datos almacenados internamente en búfer. Independientemente de si los datos entrantes rellenan o no todos los búferes, la indicación de finalización se produce para sockets superpuestos.
En el caso de los sockets orientados a mensajes (por ejemplo, el tipo SOCK_DGRAM), se coloca un mensaje entrante en los búferes hasta el tamaño total de los búferes y la indicación de finalización se produce para sockets superpuestos. Si el mensaje es mayor que los búferes, los búferes se rellenan con la primera parte del mensaje. Si el proveedor de servicios subyacente admite la característica MSG_PARTIAL , la marca MSG_PARTIAL se establece en lpFlags y las operaciones de recepción posteriores recuperarán el resto del mensaje. Si no se admite MSG_PARTIAL pero el protocolo es confiable, WSARecv genera el error WSAEMSGSIZE y se puede usar una operación de recepción posterior con un búfer mayor para recuperar todo el mensaje. De lo contrario, (es decir, el protocolo no es confiable y no admite MSG_PARTIAL), se pierden los datos excesivos y WSARecv genera el error WSAEMSGSIZE.
En el caso de los sockets orientados a la conexión, WSARecv puede indicar la terminación correcta del circuito virtual de una de estas dos maneras que dependen de si el socket es un flujo de bytes o orientado a mensajes. En el caso de las secuencias de bytes, se han leído cero bytes (como se indica en un valor devuelto cero para indicar que se ha realizado correctamente y el valor lpNumberOfBytesRecvd de cero) indica un cierre correcto y que nunca se leerán más bytes. En el caso de los sockets orientados a mensajes, donde a menudo se permite un mensaje de bytes cero, se usa un error con un código de error de WSAEDISCON para indicar un cierre correcto. En cualquier caso, se ha producido un código de error devuelto de WSAECONNRESET .
El parámetro lpFlags se puede usar para influir en el comportamiento de la invocación de función más allá de las opciones especificadas para el socket asociado. Es decir, la semántica de esta función viene determinada por las opciones de socket y el parámetro lpFlags . Este último se construye mediante el operador OR bit a bit con cualquiera de los valores enumerados en la tabla siguiente.
| Valor | Significado |
|---|---|
| MSG_PEEK |
Examina los datos entrantes. Los datos se copian en el búfer, pero no se quitan de la cola de entrada.
Esta marca solo es válida para sockets no superpuestos. |
| MSG_OOB | Procesa los datos de OOB. |
| MSG_PARTIAL |
Esta marca es solo para sockets orientados a mensajes. En la salida, esta marca indica que los datos especificados son una parte del mensaje transmitido por el remitente. Las partes restantes del mensaje se especificarán en las operaciones de recepción posteriores. Una operación de recepción posterior con la marca MSG_PARTIAL desactivada indica el final del mensaje del remitente.
Como parámetro de entrada, esta marca indica que la operación de recepción debe completarse aunque solo el proveedor de transporte haya recibido parte de un mensaje. |
| MSG_PUSH_IMMEDIATE |
Esta marca es solo para sockets orientados a flujos. Esta marca permite que una aplicación que use sockets de flujo indique al proveedor de transporte que no retrase la finalización de solicitudes de recepción pendientes parcialmente rellenadas. Se trata de una sugerencia al proveedor de transporte de que la aplicación está dispuesta a recibir los datos entrantes lo antes posible sin esperar necesariamente el resto de los datos que podrían seguir en tránsito. Lo que constituye una solicitud de recepción pendiente parcialmente rellena es una cuestión específica del transporte.
En el caso de TCP, esto hace referencia al caso de los segmentos TCP entrantes que se colocan en el búfer de datos de solicitud de recepción donde ninguno de los segmentos TCP indicó un valor de bit PUSH de 1. En este caso, TCP puede contener la solicitud de recepción parcialmente rellena un poco más para permitir que el resto de los datos lleguen con un segmento TCP que tenga el bit PUSH establecido en 1. Esta marca indica a TCP que no contenga la solicitud de recepción, sino que la complete inmediatamente. No se recomienda usar esta marca para transferencias de bloques grandes, ya que el procesamiento de bloques parciales a menudo no es óptimo. Esta marca solo es útil para los casos en los que recibir y procesar los datos parciales ayuda a reducir la latencia de procesamiento. Esta marca es una sugerencia en lugar de una garantía real. Esta marca se admite en Windows 8.1, Windows Server 2012 R2 y versiones posteriores. |
| MSG_WAITALL |
La solicitud de recepción solo se completará cuando se produzca uno de los siguientes eventos:
Tenga en cuenta que si el proveedor de transporte subyacente no admite MSG_WAITALL, o si el socket está en modo de no bloqueo, esta llamada producirá un error con WSAEOPNOTSUPP. Además, si se especifica MSG_WAITALL junto con MSG_OOB, MSG_PEEK o MSG_PARTIAL, se producirá un error en esta llamada con WSAEOPNOTSUPP. Esta marca no se admite en sockets de datagramas o sockets orientados a mensajes. |
En el caso de los sockets orientados a mensajes, el bit de MSG_PARTIAL se establece en el parámetro lpFlags si se recibe un mensaje parcial. Si se recibe un mensaje completo, MSG_PARTIAL se borra en lpFlags. En el caso de la finalización retrasada, el valor al que apunta lpFlags no se actualiza. Cuando se haya indicado la finalización, la aplicación debe llamar a WSAGetOverlappedResult y examinar las marcas indicadas por el parámetro lpdwFlags .
E/S de socket superpuesta
Si una operación superpuesta se completa inmediatamente, WSARecv devuelve un valor de cero y el parámetro lpNumberOfBytesRecvd se actualiza con el número de bytes recibidos y los bits de marca indicados por el parámetro lpFlags también se actualizan. Si la operación superpuesta se inicia correctamente y se completará más adelante, WSARecv devuelve SOCKET_ERROR e indica el código de error WSA_IO_PENDING. En este caso, lpNumberOfBytesRecvd y lpFlags no se actualizan. Cuando se completa la operación superpuesta, la cantidad de datos transferidos se indica a través del parámetro cbTransferred en la rutina de finalización (si se especifica) o mediante el parámetro lpcbTransfer en WSAGetOverlappedResult. Los valores de marca se obtienen examinando el parámetro lpdwFlags de WSAGetOverlappedResult.Se puede llamar a la función WSARecv mediante E/S superpuesta desde dentro de la rutina de finalización de una función WSARecv, WSARecvFrom, WSASend o WSASendTo anterior. Para un socket determinado, las rutinas de finalización de E/S no se anidarán. Esto permite que las transmisiones de datos sensibles al tiempo se produzcan por completo dentro de un contexto preferente.
El parámetro lpOverlapped debe ser válido durante la operación superpuesta. Si hay varias operaciones de E/S pendientes simultáneamente, cada una debe hacer referencia a una estructura WSAOVERLAPPED independiente.
Si el parámetro lpCompletionRoutine es NULL, el parámetro hEvent de lpOverlapped se señala cuando se completa la operación superpuesta si contiene un identificador de objeto de evento válido. Una aplicación puede usar WSAWaitForMultipleEvents o WSAGetOverlappedResult para esperar o sondear en el objeto de evento.
Si lpCompletionRoutine no es NULL, el parámetro hEvent se omite y la aplicación puede usar para pasar información de contexto a la rutina de finalización. Un llamador que pasa un lpCompletionRoutine no NULL y, posteriormente, llama a WSAGetOverlappedResult para la misma solicitud de E/S superpuesta no puede establecer el parámetro fWait para esa invocación de WSAGetOverlappedResult en TRUE. En este caso, el uso del parámetro hEvent no está definido y el intento de esperar en el parámetro hEvent produciría resultados imprevisibles.
La rutina de finalización sigue las mismas reglas que se estipulan para las rutinas de finalización de E/S de archivos de Windows. La rutina de finalización no se invocará hasta que el subproceso se encuentra en un estado de espera alertable, como puede ocurrir cuando se invoca la función WSAWaitForMultipleEvents con el parámetro fAlertable establecido en TRUE .
El prototipo de la rutina de finalización es el siguiente:
void CALLBACK CompletionROUTINE(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine es un marcador de posición para un nombre de función definido por la aplicación o definido por la biblioteca. DwError especifica el estado de finalización de la operación superpuesta, como se indica en lpOverlapped. El parámetro cbTransferred especifica el número de bytes recibidos. El parámetro dwFlags contiene información que habría aparecido en lpFlags si la operación de recepción se hubiera completado inmediatamente. Esta función no devuelve ningún valor.
La devolución de esta función permite la invocación de otra rutina de finalización pendiente para este socket. Cuando se usa WSAWaitForMultipleEvents, se llama a todas las rutinas de finalización en espera antes de que la espera del subproceso alertable esté satisfecho con un código de retorno de WSA_IO_COMPLETION. Se puede llamar a las rutinas de finalización en cualquier orden, no necesariamente en el mismo orden en que se completan las operaciones superpuestas. Sin embargo, se garantiza que los búferes publicados se rellenen en el mismo orden en el que se especifican.
Si usa puertos de finalización de E/S, tenga en cuenta que el orden de las llamadas realizadas a WSARecv también es el orden en que se rellenan los búferes. No se debe llamar a WSARecv en el mismo socket simultáneamente desde diferentes subprocesos, ya que puede dar lugar a un orden de búfer imprevisible.
Código de ejemplo
En el ejemplo siguiente se muestra cómo usar la función WSARecv en modo de E/S superpuesta.#ifndef UNICODE
#define UNICODE
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <Windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <stdlib.h>
// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")
#pragma warning(disable: 4127) // Conditional expression is a constant
#define DATA_BUFSIZE 4096
int __cdecl main(int argc, char **argv)
{
WSADATA wsd;
struct addrinfo *result = NULL, *ptr = NULL, hints;
WSAOVERLAPPED RecvOverlapped;
SOCKET ConnSocket = INVALID_SOCKET;
WSABUF DataBuf;
DWORD RecvBytes, Flags;
char buffer[DATA_BUFSIZE];
int err = 0;
int rc;
if (argc != 2) {
wprintf(L"usage: %s server-name\n", argv[0]);
return 1;
}
// Load Winsock
rc = WSAStartup(MAKEWORD(2, 2), &wsd);
if (rc != 0) {
wprintf(L"Unable to load Winsock: %d\n", rc);
return 1;
}
// Make sure the hints struct is zeroed out
SecureZeroMemory((PVOID) & hints, sizeof (struct addrinfo));
// Initialize the hints to retrieve the server address for IPv4
hints.ai_family = AF_INET;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
rc = getaddrinfo(argv[1], "27015", &hints, &result);
if (rc != 0) {
wprintf(L"getaddrinfo failed with error: %d\n", rc);
return 1;
}
for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {
ConnSocket = socket(ptr->ai_family, ptr->ai_socktype, ptr->ai_protocol);
if (ConnSocket == INVALID_SOCKET) {
wprintf(L"socket failed with error: %d\n", WSAGetLastError());
freeaddrinfo(result);
return 1;
}
rc = connect(ConnSocket, ptr->ai_addr, (int) ptr->ai_addrlen);
if (rc == SOCKET_ERROR) {
if (WSAECONNREFUSED == (err = WSAGetLastError())) {
closesocket(ConnSocket);
ConnSocket = INVALID_SOCKET;
continue;
}
wprintf(L"connect failed with error: %d\n", err);
freeaddrinfo(result);
closesocket(ConnSocket);
return 1;
}
break;
}
if (ConnSocket == INVALID_SOCKET) {
wprintf(L"Unable to establish connection with the server!\n");
freeaddrinfo(result);
return 1;
}
wprintf(L"Client connected...\n");
// Make sure the RecvOverlapped struct is zeroed out
SecureZeroMemory((PVOID) & RecvOverlapped, sizeof (WSAOVERLAPPED));
// Create an event handle and setup an overlapped structure.
RecvOverlapped.hEvent = WSACreateEvent();
if (RecvOverlapped.hEvent == NULL) {
wprintf(L"WSACreateEvent failed: %d\n", WSAGetLastError());
freeaddrinfo(result);
closesocket(ConnSocket);
return 1;
}
DataBuf.len = DATA_BUFSIZE;
DataBuf.buf = buffer;
// Call WSARecv until the peer closes the connection
// or until an error occurs
while (1) {
Flags = 0;
rc = WSARecv(ConnSocket, &DataBuf, 1, &RecvBytes, &Flags, &RecvOverlapped, NULL);
if ((rc == SOCKET_ERROR) && (WSA_IO_PENDING != (err = WSAGetLastError()))) {
wprintf(L"WSARecv failed with error: %d\n", err);
break;
}
rc = WSAWaitForMultipleEvents(1, &RecvOverlapped.hEvent, TRUE, INFINITE, TRUE);
if (rc == WSA_WAIT_FAILED) {
wprintf(L"WSAWaitForMultipleEvents failed with error: %d\n", WSAGetLastError());
break;
}
rc = WSAGetOverlappedResult(ConnSocket, &RecvOverlapped, &RecvBytes, FALSE, &Flags);
if (rc == FALSE) {
wprintf(L"WSARecv operation failed with error: %d\n", WSAGetLastError());
break;
}
wprintf(L"Read %d bytes\n", RecvBytes);
WSAResetEvent(RecvOverlapped.hEvent);
// If 0 bytes are received, the connection was closed
if (RecvBytes == 0)
break;
}
WSACloseEvent(RecvOverlapped.hEvent);
closesocket(ConnSocket);
freeaddrinfo(result);
WSACleanup();
return 0;
}
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
| 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 |
| Library | Ws2_32.lib |
| Archivo DLL | Ws2_32.dll |