kirim fungsi (winsock2.h)

Artikel
03/08/2023

Fungsi kirim mengirim data pada soket yang terhubung.

Sintaks

int WSAAPI send(
  [in] SOCKET     s,
  [in] const char *buf,
  [in] int        len,
  [in] int        flags
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang terhubung.

[in] buf

Penunjuk ke buffer yang berisi data yang akan dikirimkan.

[in] len

Panjang, dalam byte, dari data dalam buffer yang diacu oleh parameter buf .

[in] flags

Sekumpulan bendera yang menentukan cara panggilan dilakukan. Parameter ini dibangun dengan menggunakan operator bitwise OR dengan salah satu nilai berikut.

Nilai	Makna
MSG_DONTROUTE	Menentukan bahwa data tidak boleh tunduk pada perutean. Penyedia layanan Windows Sockets dapat memilih untuk mengabaikan bendera ini.
MSG_OOB	Mengirim data OOB (soket gaya aliran seperti hanya SOCK_STREAM).

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, kirim mengembalikan jumlah total byte yang dikirim, yang dapat kurang dari angka yang diminta untuk dikirim dalam parameter lensa . Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan	Makna
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEACCES	Alamat yang diminta adalah alamat siaran, tetapi bendera yang sesuai tidak ditetapkan. Panggil setsockopt dengan opsi soket SO_BROADCAST untuk mengaktifkan penggunaan alamat siaran.
WSAEINTR	Panggilan Windows Sockets 1.1 yang diblokir dibatalkan melalui WSACancelBlockingCall.
WSAEINPROGRESS	Panggilan Windows Sockets 1.1 yang diblokir sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEFAULT	Parameter buf tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
WSAENETRESET	Koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia.
WSAENOTCONN	Soket tidak tersambung.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	MSG_OOB ditentukan, tetapi soket tidak bergaya aliran seperti jenis SOCK_STREAM, data OOB tidak didukung di domain komunikasi yang terkait dengan soket ini, atau soket tidak arah dan hanya mendukung operasi penerimaan.
WSAESHUTDOWN	Soket telah dimatikan; tidak dimungkinkan untuk mengirim soket setelah pematian dipanggil dengan cara mengatur ke SD_SEND atau SD_BOTH.
WSAEWOULDBLOCK	Soket ditandai sebagai nonblocking dan operasi yang diminta akan memblokir.
WSAEMSGSIZE	Soket berorientasi pada pesan, dan pesan lebih besar dari maksimum yang didukung oleh transportasi yang mendasar.
WSAEHOSTUNREACH	Host jarak jauh tidak dapat dicapai dari host ini saat ini.
WSAEINVAL	Soket belum terikat dengan ikatan, atau bendera yang tidak diketahui ditentukan, atau MSG_OOB ditentukan untuk soket dengan SO_OOBINLINE diaktifkan.
WSAECONNABORTED	Sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya. Aplikasi harus menutup soket karena tidak lagi dapat digunakan.
WSAECONNRESET	Sirkuit virtual direset oleh sisi jarak jauh yang mengeksekusi penutupan yang keras atau abortif. Untuk soket UDP, host jarak jauh tidak dapat mengirimkan datagram UDP yang dikirim sebelumnya dan merespons dengan paket ICMP "Port Unreachable". Aplikasi harus menutup soket karena tidak lagi dapat digunakan.
WSAETIMEDOUT	Koneksi telah terputus, karena kegagalan jaringan atau karena sistem di ujung lain tidak berfungsi tanpa pemberitahuan.

Keterangan

Fungsi kirim digunakan untuk menulis data keluar pada soket yang terhubung.

Untuk soket berorientasi pesan (keluarga alamat AF_INET atau AF_INET6, jenis SOCK_DGRAM, dan protokol IPPROTO_UDP, misalnya), perawatan harus dilakukan agar tidak melebihi ukuran paket maksimum penyedia yang mendasar. Ukuran paket pesan maksimum untuk penyedia dapat diperoleh dengan memanggil getsockopt dengan parameter optname diatur ke SO_MAX_MSG_SIZE untuk mengambil nilai opsi soket. Jika data terlalu panjang untuk diteruskan secara atomik melalui protokol yang mendasar, kesalahan WSAEMSGSIZE dikembalikan, dan tidak ada data yang dikirimkan.

Keberhasilan penyelesaian fungsi kirim tidak menunjukkan bahwa data berhasil dikirimkan dan diterima kepada penerima. Fungsi ini hanya menunjukkan bahwa data berhasil dikirim.

Jika tidak ada ruang buffer yang tersedia dalam sistem transportasi untuk menahan data yang akan ditransmisikan, kirim akan memblokir kecuali soket telah ditempatkan dalam mode nonblocking. Pada soket berorientasi aliran nonblokir, jumlah byte yang ditulis dapat antara 1 dan panjang yang diminta, tergantung pada ketersediaan buffer pada komputer klien dan server. Fungsi pilih, WSAAsyncSelect atau WSAEventSelect dapat digunakan untuk menentukan kapan mungkin untuk mengirim lebih banyak data.

Panggilan kirim dengan parameter lensa nol diizinkan dan akan diperlakukan oleh implementasi sebagai berhasil. Dalam kasus seperti itu, kirim akan mengembalikan nol sebagai nilai yang valid. Untuk soket berorientasi pesan, datagram transportasi panjang nol dikirim.

Parameter bendera dapat digunakan untuk memengaruhi perilaku fungsi di luar opsi yang ditentukan untuk soket terkait. Semantik fungsi kirim ditentukan oleh opsi apa pun yang sebelumnya diatur pada soket yang ditentukan dalam parameter s dan parameter bendera yang diteruskan ke fungsi kirim .

Urutan panggilan yang dilakukan untuk mengirim juga merupakan urutan di mana buffer ditransmisikan ke lapisan transportasi. kirim tidak boleh dipanggil pada soket berorientasi aliran yang sama secara bersamaan dari utas yang berbeda, karena beberapa penyedia Winsock dapat membagi permintaan pengiriman besar menjadi beberapa transmisi, dan ini dapat menyebabkan data yang tidak diinginkan diselingi dari beberapa permintaan pengiriman bersamaan pada soket berorientasi aliran yang sama.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti kirim, Winsock mungkin perlu menunggu peristiwa jaringan sebelum panggilan dapat 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.

Contoh Kode

Contoh berikut menunjukkan penggunaan fungsi kirim .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

#define DEFAULT_BUFLEN 512
#define DEFAULT_PORT 27015

int main() {

    //----------------------
    // Declare and initialize variables.
    int iResult;
    WSADATA wsaData;

    SOCKET ConnectSocket = INVALID_SOCKET;
    struct sockaddr_in clientService; 

    int recvbuflen = DEFAULT_BUFLEN;
    char *sendbuf = "Client: sending data test";
    char recvbuf[DEFAULT_BUFLEN] = "";

    //----------------------
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2,2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"WSAStartup failed with error: %d\n", iResult);
        return 1;
    }

    //----------------------
    // Create a SOCKET for connecting to server
    ConnectSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ConnectSocket == INVALID_SOCKET) {
        wprintf(L"socket failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    //----------------------
    // The sockaddr_in structure specifies the address family,
    // IP address, and port of the server to be connected to.
    clientService.sin_family = AF_INET;
    clientService.sin_addr.s_addr = inet_addr( "127.0.0.1" );
    clientService.sin_port = htons( DEFAULT_PORT );

    //----------------------
    // Connect to server.
    iResult = connect( ConnectSocket, (SOCKADDR*) &clientService, sizeof(clientService) );
    if (iResult == SOCKET_ERROR) {
        wprintf(L"connect failed with error: %d\n", WSAGetLastError() );
        closesocket(ConnectSocket);
        WSACleanup();
        return 1;
  }

    //----------------------
    // Send an initial buffer
    iResult = send( ConnectSocket, sendbuf, (int)strlen(sendbuf), 0 );
    if (iResult == SOCKET_ERROR) {
        wprintf(L"send failed with error: %d\n", WSAGetLastError());
        closesocket(ConnectSocket);
        WSACleanup();
        return 1;
    }

    printf("Bytes Sent: %d\n", iResult);

    // shutdown the connection since no more data will be sent
    iResult = shutdown(ConnectSocket, SD_SEND);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"shutdown failed with error: %d\n", WSAGetLastError());
        closesocket(ConnectSocket);
        WSACleanup();
        return 1;
    }

    // Receive until the peer closes the connection
    do {

        iResult = recv(ConnectSocket, recvbuf, recvbuflen, 0);
        if ( iResult > 0 )
            wprintf(L"Bytes received: %d\n", iResult);
        else if ( iResult == 0 )
            wprintf(L"Connection closed\n");
        else
            wprintf(L"recv failed with error: %d\n", WSAGetLastError());

    } while( iResult > 0 );


    // close the socket
    iResult = closesocket(ConnectSocket);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"close failed with error: %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    WSACleanup();
    return 0;
}

Contoh Kode

Untuk contoh lain yang menggunakan fungsi kirim , lihat Memulai Winsock.

Catatan untuk Soket IrDA

File header Af_irda.h harus disertakan secara eksplisit.

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	winsock2.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll