función shutdown (winsock.h)

Artículo
03/15/2023

La función de apagado deshabilita los envíos o las recibe en un socket.

Sintaxis

int shutdown(
  [in] SOCKET s,
  [in] int    how
);

Parámetros

[in] s

Descriptor que identifica un socket.

[in] how

Marca que describe qué tipos de operación ya no se permitirán. Los valores posibles para esta marca se muestran en el archivo de encabezado Winsock2.h .

Valor	Significado
SD_RECEIVE 0	Cierre las operaciones de recepción.
SD_SEND 1	Cierre las operaciones de envío.
SD_BOTH 2	Apague las operaciones de envío y recepción.

Valor devuelto

Si no se produce ningún error, el apagado devuelve cero. De lo contrario, se devuelve un valor de SOCKET_ERROR y se puede recuperar un código de error específico llamando a WSAGetLastError.

Código de error	Significado
WSAECONNABORTED	Se finalizó el circuito virtual debido a un tiempo de espera agotado u otro error. La aplicación debería cerrar el socket porque ya no se puede usar. Este error solo se aplica a un socket orientado a la conexión.
WSAECONNRESET	El lado remoto que ejecuta un cierre firme o de anulación restableció el circuito virtual. La aplicación debería cerrar el socket porque ya no se puede usar. Este error solo se aplica a un socket orientado a la conexión.
WSAEINPROGRESS	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.
WSAEINVAL	El parámetro how no es válido o no es coherente con el tipo de socket. Por ejemplo, SD_SEND se usa con un tipo de socket UNI_RECV.
WSAENETDOWN	Error en el subsistema de red.
WSAENOTCONN	El socket no está conectado. Este error solo se aplica a un socket orientado a la conexión.
WSAENOTSOCK	Nota El descriptor no es un socket.
WSANOTINITIALISED	Debe producirse una llamada de WSAStartup correcta antes de usar esta función.

Comentarios

La función de apagado se usa en todos los tipos de sockets para deshabilitar la recepción, transmisión o ambos.

Si el parámetro how es SD_RECEIVE, no se permitirán las llamadas posteriores a la función recv en el socket. Esto no tiene ningún efecto en las capas de protocolo inferiores. En el caso de los sockets TCP, si todavía hay datos en cola en el socket que esperan recibirse, o los datos llegan posteriormente, se restablece la conexión, ya que los datos no se pueden entregar al usuario. En el caso de los sockets UDP, se aceptan y ponen en cola los datagramas entrantes. En ningún caso se generará un paquete de error ICMP.

Si el parámetro how es SD_SEND, no se permiten las llamadas posteriores a la función de envío . En el caso de los sockets TCP, el receptor enviará una fin después de que el receptor envíe y confirme todos los datos.

Establecer cómo SD_BOTH deshabilita los envíos y los recibe como se ha descrito anteriormente.

La función shutdown no cierra el socket. Los recursos conectados al socket no se liberarán hasta que se invoque closesocket .

Para asegurarse de que todos los datos se envían y reciben en un socket conectado antes de cerrarse, una aplicación debe usar el apagado para cerrar la conexión antes de llamar a Closesocket. Un método para esperar una notificación de que el extremo remoto ha enviado todos sus datos e iniciado una desconexión correcta usa la función WSAEventSelect como se indica a continuación:

Llame a WSAEventSelect para registrarse para FD_CLOSE notificación.
Llame al apagado con how=SD_SEND.
Cuando FD_CLOSE recibido, llame a la recv o WSARecv hasta que la función se complete correctamente e indique que se recibieron cero bytes. Si se devuelve SOCKET_ERROR, la desconexión correcta no es posible.
Llame a closesocket.

Otro método para esperar una notificación de que el extremo remoto ha enviado todos sus datos e iniciado una desconexión correcta usa llamadas de recepción superpuestas a continuación:

Llame al apagado con how=SD_SEND.
Llame a recv o WSARecv hasta que la función se complete correctamente e indique que se recibieron cero bytes. Si se devuelve SOCKET_ERROR, la desconexión correcta no es posible.
Llame a closesocket.

Nota La función de apagado no se bloquea independientemente de la configuración de SO_LINGER en el socket.

Para obtener más información, vea la sección sobre Cierre correcto, Opciones de persistencia y Cierre de sockets.

Una vez que se llama a la función de apagado para deshabilitar el envío, la recepción o ambos, no hay ningún método para volver a habilitar el envío o la recepción de la conexión de socket existente.

Una aplicación no debe depender de poder reutilizar un socket después de que este se haya apagado. En concreto, no se requiere un proveedor de Windows Sockets para admitir el uso de la conexión en un socket que se ha apagado.

Si una aplicación desea reutilizar un socket, se debe llamar a la función DisconnectEx con el parámetro dwFlags establecido en TF_REUSE_SOCKET para cerrar una conexión en un socket y preparar el identificador de socket que se va a reutilizar. Cuando se completa la solicitud DisconnectEx , el identificador de socket se puede pasar a la función AcceptEx o ConnectEx .

Si una aplicación quiere reutilizar un socket, se puede llamar a las funciones TransmitFile o TransmitPackets con el parámetro dwFlags establecido con TF_DISCONNECT y TF_REUSE_SOCKET para desconectar después de que todos los datos se hayan puesto en cola para la transmisión y preparen el identificador de socket que se va a reutilizar. Cuando se completa la solicitud TransmitFile , el identificador de socket se puede pasar a la llamada de función usada anteriormente para establecer la conexión, como AcceptEx o ConnectEx. Cuando se completa la función TransmitPackets , el identificador de socket se puede pasar a la función AcceptEx .

Nota La desconexión del nivel de socket está sujeta al comportamiento del transporte subyacente. Por ejemplo, un socket TCP puede estar sujeto al estado de TIME_WAIT TCP, lo que hace que la llamada DisconnectEx, TransmitFile o TransmitPackets se retrase.

Nota Al emitir una llamada de Winsock de bloqueo, como apagar, Winsock puede que tenga que esperar a un evento de red antes de que se pueda completar la llamada. Winsock realiza una espera alertable en esta situación, que se puede interrumpir mediante una llamada de procedimiento asincrónica (APC) programada en el mismo subproceso. La emisión de otra llamada winsock de bloqueo dentro de un APC que interrumpió una llamada de Winsock de bloqueo en curso en el mismo subproceso provocará un comportamiento indefinido y los clientes winsock nunca deben intentarlo.

Notas para ATM

Hay problemas importantes asociados con la desmontaje de conexión al usar el modo de transferencia asincrónica (ATM) y Windows Sockets 2. Para obtener más información sobre estas consideraciones importantes, vea la sección titulada Notes for ATM en la sección Comentarios de la referencia de la función closesocket .

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	winsock.h (incluya Winsock2.h, Webhost.h)
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll