fungsi shutdown (winsock.h)

Artikel
03/15/2023

Fungsi matikan menonaktifkan pengiriman atau penerimaan pada soket.

Sintaks

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

Parameter

[in] s

Deskriptor yang mengidentifikasi soket.

[in] how

Bendera yang menjelaskan jenis operasi apa yang tidak akan lagi diizinkan. Nilai yang mungkin untuk bendera ini tercantum dalam file header Winsock2.h .

Nilai	Makna
SD_RECEIVE 0	Operasi terima matikan.
SD_SEND 1	Matikan operasi pengiriman.
SD_BOTH 2	Matikan operasi kirim dan terima.

Nilai kembali

Jika tidak ada kesalahan yang terjadi, pematian mengembalikan nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan	Makna
WSAECONNABORTED	Sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya. Aplikasi harus menutup soket karena tidak lagi dapat digunakan. Kesalahan ini hanya berlaku untuk soket berorientasi koneksi.
WSAECONNRESET	Sirkuit virtual diatur ulang oleh sisi jarak jauh yang mengeksekusi penutupan yang keras atau abortif. Aplikasi harus menutup soket karena tidak lagi dapat digunakan. Kesalahan ini hanya berlaku untuk soket berorientasi koneksi.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINVAL	Bagaimana parameter tidak valid, atau tidak konsisten dengan jenis soket. Misalnya, SD_SEND digunakan dengan jenis soket UNI_RECV.
WSAENETDOWN	Subsistem jaringan gagal.
WSAENOTCONN	Soket tidak tersambung. Kesalahan ini hanya berlaku untuk soket berorientasi koneksi.
WSAENOTSOCK	Catatan Deskriptor bukan soket.
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.

Keterangan

Fungsi matikan digunakan pada semua jenis soket untuk menonaktifkan penerimaan, transmisi, atau keduanya.

Jika bagaimana parameter SD_RECEIVE, panggilan berikutnya ke fungsi recv pada soket akan dilarang. Ini tidak berpengaruh pada lapisan protokol yang lebih rendah. Untuk soket TCP, jika masih ada data yang diantrekan pada soket yang menunggu untuk diterima, atau data tiba kemudian, koneksi diatur ulang, karena data tidak dapat dikirimkan kepada pengguna. Untuk soket UDP, datagram masuk diterima dan diantrekan. Tidak akan ada paket kesalahan ICMP yang dihasilkan.

Jika bagaimana parameter SD_SEND, panggilan berikutnya ke fungsi kirim tidak diizinkan. Untuk soket TCP, FIN akan dikirim setelah semua data dikirim dan diakui oleh penerima.

Mengatur cara SD_BOTH menonaktifkan pengiriman dan penerimaan seperti yang dijelaskan di atas.

Fungsi matikan tidak menutup soket. Sumber daya apa pun yang terpasang pada soket tidak akan dikosongkan sampai closesocket dipanggil.

Untuk memastikan bahwa semua data dikirim dan diterima pada soket yang terhubung sebelum ditutup, aplikasi harus menggunakan matikan untuk menutup koneksi sebelum memanggil closesocket. Satu metode untuk menunggu pemberitahuan bahwa ujung jarak jauh telah mengirim semua datanya dan memulai pemutusan sambungan dengan baik menggunakan fungsi WSAEventSelect sebagai berikut:

Hubungi WSAEventSelect untuk mendaftar pemberitahuan FD_CLOSE.
Matikan panggilan dengan how=SD_SEND.
Ketika FD_CLOSE diterima, panggil recv atau WSARecv hingga fungsi selesai dengan sukses dan menunjukkan bahwa nol byte diterima. Jika SOCKET_ERROR dikembalikan, maka pemutusan sambungan yang anggun tidak dimungkinkan.
Hubungi closesocket.

Metode lain untuk menunggu pemberitahuan bahwa ujung jarak jauh telah mengirim semua datanya dan memulai pemutusan sambungan dengan baik menggunakan panggilan terima yang tumpang tindih berikut:

Matikan panggilan dengan how=SD_SEND.
Panggil recv atau WSARecv hingga fungsi selesai dengan sukses dan menunjukkan nol byte diterima. Jika SOCKET_ERROR dikembalikan, maka pemutusan sambungan yang anggun tidak dimungkinkan.
Hubungi closesocket.

Catatan Fungsi matikan tidak memblokir terlepas dari pengaturan SO_LINGER pada soket.

Untuk informasi selengkapnya, lihat bagian tentang Graceful Shutdown, Linger Options, dan Socket Closure.

Setelah fungsi matikan dipanggil untuk menonaktifkan kirim, terima, atau keduanya, tidak ada metode untuk mengaktifkan kembali kirim atau terima untuk koneksi soket yang ada.

Aplikasi tidak boleh mengandalkan untuk dapat menggunakan kembali soket setelah dimatikan. Secara khusus, penyedia Windows Sockets tidak diperlukan untuk mendukung penggunaan koneksi pada soket yang telah dimatikan.

Jika aplikasi ingin menggunakan kembali soket, maka fungsi DisconnectEx harus dipanggil dengan parameter dwFlags yang diatur ke TF_REUSE_SOCKET untuk menutup koneksi pada soket dan menyiapkan handel soket untuk digunakan kembali. Ketika permintaan DisconnectEx selesai, handel soket dapat diteruskan ke fungsi AcceptEx atau ConnectEx .

Jika aplikasi ingin menggunakan kembali soket, fungsi TransmitFile atau TransmitPackets dapat dipanggil dengan parameter dwFlags yang diatur dengan TF_DISCONNECT dan TF_REUSE_SOCKET untuk memutuskan sambungan setelah semua data diantrekan untuk transmisi dan menyiapkan handel soket untuk digunakan kembali. Ketika permintaan TransmitFile selesai, handel soket dapat diteruskan ke panggilan fungsi yang sebelumnya digunakan untuk membuat koneksi, seperti AcceptEx atau ConnectEx. Ketika fungsi TransmitPackets selesai, handel soket dapat diteruskan ke fungsi AcceptEx .

Catatan Pemutusan tingkat soket tunduk pada perilaku transportasi yang mendasar. Misalnya, soket TCP dapat tunduk pada status TIME_WAIT TCP, menyebabkan panggilan DisconnectEx, TransmitFile, atau TransmitPackets tertunda.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti matikan, Winsock mungkin perlu menunggu peristiwa jaringan sebelum panggilan selesai. Winsock melakukan penantian yang dapat diperingatkan dalam situasi ini, yang dapat terganggu oleh panggilan prosedur asinkron (APC) yang dijadwalkan pada utas yang sama. Mengeluarkan panggilan Winsock pemblokiran lain di dalam APC yang mengganggu panggilan Winsock pemblokiran yang sedang berlangsung pada utas yang sama akan menyebabkan perilaku yang tidak terdefinisi, dan tidak boleh dicoba oleh klien Winsock.

Catatan untuk ATM

Ada masalah penting yang terkait dengan robekan koneksi saat menggunakan Mode Transfer Asinkron (ATM) dan Windows Sockets 2. Untuk informasi selengkapnya tentang pertimbangan penting ini, lihat bagian berjudul Catatan untuk ATM di bagian Keterangan referensi fungsi closesocket .

Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8.1, Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winsock.h (termasuk Winsock2.h, Webhost.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll