Bagikan melalui


Fungsi WSASend (winsock2.h)

Fungsi WSASend mengirim data pada soket yang terhubung.

Sintaks

int WSAAPI WSASend(
  [in]  SOCKET                             s,
  [in]  LPWSABUF                           lpBuffers,
  [in]  DWORD                              dwBufferCount,
  [out] LPDWORD                            lpNumberOfBytesSent,
  [in]  DWORD                              dwFlags,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tersambung.

[in] lpBuffers

Penunjuk ke array struktur WSABUF . Setiap struktur WSABUF berisi penunjuk ke buffer dan panjangnya, dalam byte, dari buffer. Untuk aplikasi Winsock, setelah fungsi WSASend dipanggil, sistem memiliki buffer ini dan aplikasi mungkin tidak mengaksesnya. Array ini harus tetap valid selama durasi operasi pengiriman.

[in] dwBufferCount

Jumlah struktur WSABUF dalam array lpBuffers .

[out] lpNumberOfBytesSent

Penunjuk ke nomor, dalam byte, yang dikirim oleh panggilan ini jika operasi I/O segera selesai.

Gunakan NULL untuk parameter ini jika parameter lpOverlapped bukan NULL untuk menghindari hasil yang berpotensi salah. Parameter ini dapat berupa NULL hanya jika parameter lpOverlapped bukan NULL.

[in] dwFlags

Bendera yang digunakan untuk mengubah perilaku panggilan fungsi WSASend . Untuk informasi selengkapnya, lihat Menggunakan dwFlags di bagian Keterangan.

[in] lpOverlapped

Penunjuk ke struktur WSAOVERLAPPED . Parameter ini diabaikan untuk soket yang tidak tumpang tindih.

[in] lpCompletionRoutine

Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi pengiriman telah selesai. Parameter ini diabaikan untuk soket yang tidak tumpang tindih.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi dan operasi pengiriman telah segera selesai, WSASend mengembalikan nol. Dalam hal ini, rutinitas penyelesaian akan dijadwalkan untuk dipanggil setelah utas panggilan berada dalam status yang dapat diperingatkan. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError. Kode kesalahan WSA_IO_PENDING menunjukkan bahwa operasi yang tumpang tindih telah berhasil dimulai dan penyelesaian tersebut akan ditunjukkan di lain waktu. Kode kesalahan lainnya menunjukkan bahwa operasi yang tumpang tindih tidak berhasil dimulai dan tidak ada indikasi penyelesaian yang akan terjadi.

Kode kesalahan Makna
WSAECONNABORTED
Sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya.
WSAECONNRESET
Untuk soket aliran, sirkuit virtual direset oleh sisi jarak jauh. Aplikasi harus menutup soket karena tidak lagi dapat digunakan. Untuk soket datagram UDP, kesalahan ini akan menunjukkan bahwa operasi pengiriman sebelumnya menghasilkan pesan "Port Unreachable" ICMP.
WSAEFAULT
Parameter lpBuffers, lpNumberOfBytesSent, lpOverlapped, lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
WSAEINTR
Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall.
WSAEINPROGRESS
Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINVAL
Soket belum terikat dengan ikatan atau soket tidak dibuat dengan bendera tumpang tindih.
WSAEMSGSIZE
Soket berorientasi pesan, dan pesan lebih besar dari maksimum yang didukung oleh transportasi yang mendasar.
WSAENETDOWN
Subsistem jaringan gagal.
WSAENETRESET
Untuk soket aliran, koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung. Untuk soket datagram, kesalahan ini menunjukkan bahwa waktu hidup telah kedaluwarsa.
WSAENOBUFS
Penyedia Windows Sockets melaporkan kebuntuan buffer.
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, MSG_PARTIAL tidak didukung, atau soket tidak langsung dan hanya mendukung operasi penerimaan.
WSAESHUTDOWN
Soket telah dimatikan; tidak dimungkinkan untuk WSASend pada soket setelah pematian dipanggil dengan cara diatur ke SD_SEND atau SD_BOTH.
WSAEWOULDBLOCK
Windows NT:

Soket yang tumpang tindih: Ada terlalu banyak permintaan I/O yang tumpang tindih. Soket yang tidak tumpang tindih: Soket ditandai sebagai nonblocking dan operasi pengiriman tidak dapat segera diselesaikan.

WSANOTINITIALISED
Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSA_IO_PENDING
Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED
Operasi yang tumpang tindih telah dibatalkan karena penutupan soket, eksekusi perintah "SIO_FLUSH" di WSAIoctl, atau utas yang memulai permintaan yang tumpang tindih keluar sebelum operasi selesai. Untuk informasi selengkapnya, lihat bagian Keterangan.

Keterangan

Fungsi WSASend menyediakan fungsionalitas di atas dan di atas fungsi pengiriman standar di dua area penting:

  • Ini dapat digunakan bersama dengan soket yang tumpang tindih untuk melakukan operasi pengiriman yang tumpang tindih.
  • Ini memungkinkan beberapa buffer pengiriman ditentukan sehingga berlaku untuk jenis I/O yang tersebar/kumpulkan.
Fungsi WSASend digunakan untuk menulis data keluar dari satu atau beberapa buffer pada soket berorientasi koneksi yang ditentukan oleh s. Namun, ini juga dapat digunakan pada soket tanpa koneksi yang memiliki alamat serekan default yang ditetapkan yang ditetapkan melalui fungsi sambungkan atau WSAConnect .

Soket yang dibuat oleh fungsi soket akan memiliki atribut yang tumpang tindih sebagai default. Soket yang dibuat oleh fungsi WSASocket dengan parameter dwFlags yang diteruskan ke WSASocket dengan set bit WSA_FLAG_OVERLAPPED akan memiliki atribut yang tumpang tindih. Untuk soket dengan atribut yang tumpang tindih, WSASend menggunakan I/O yang tumpang tindih kecuali parameter lpOverlapped dan lpCompletionRoutine adalah NULL. Dalam hal ini, soket diperlakukan sebagai soket yang tidak tumpang tindih. Indikasi penyelesaian akan terjadi, memanggil penyelesaian rutinitas atau pengaturan objek peristiwa, ketika buffer telah dikonsumsi oleh transportasi. Jika operasi tidak segera selesai, status penyelesaian akhir diambil melalui rutinitas penyelesaian atau WSAGetOverlappedResult.

Jika lpOverlapped dan lpCompletionRoutineADALAH NULL, soket dalam fungsi ini akan diperlakukan sebagai soket yang tidak tumpang tindih.

Untuk soket yang tidak tumpang tindih, dua parameter terakhir (lpOverlapped, lpCompletionRoutine) diabaikan dan WSASend mengadopsi semantik pemblokiran yang sama seperti yang dikirim. Data disalin dari buffer ke dalam buffer transportasi. Jika soket tidak memblokir dan berorientasi aliran, dan tidak ada ruang yang cukup dalam buffer transportasi, WSASend akan kembali dengan hanya sebagian dari buffer aplikasi yang telah dikonsumsi. Mengingat situasi buffer yang sama dan soket pemblokiran, WSASend akan memblokir sampai semua konten buffer aplikasi telah dikonsumsi.

Catatan Opsi soket SO_RCVTIMEO dan SO_SNDTIMEO hanya berlaku untuk memblokir soket.
 
Jika fungsi ini selesai dengan cara yang tumpang tindih, penyedia layanan Winsock bertanggung jawab untuk menangkap struktur WSABUF sebelum kembali dari panggilan ini. Ini memungkinkan aplikasi untuk membangun array WSABUF berbasis tumpukan yang diacu oleh parameter lpBuffers .

Untuk soket berorientasi pesan, jangan melebihi ukuran pesan maksimum penyedia yang mendasar, yang dapat diperoleh dengan mendapatkan nilai opsi soket SO_MAX_MSG_SIZE. Jika data terlalu panjang untuk diteruskan secara atomik melalui protokol yang mendasar, kesalahan WSAEMSGSIZE dikembalikan, dan tidak ada data yang dikirimkan.

Windows Me/98/95: Fungsi WSASend tidak mendukung lebih dari 16 buffer.

Catatan Keberhasilan penyelesaian WSASend tidak menunjukkan bahwa data berhasil dikirimkan.
 

Menggunakan dwFlags

Parameter dwFlags dapat digunakan untuk memengaruhi perilaku pemanggilan fungsi di luar opsi yang ditentukan untuk soket terkait. Artinya, semantik fungsi ini ditentukan oleh opsi soket dan parameter dwFlags . Yang terakhir dibangun dengan menggunakan operator bitwise OR dengan salah satu nilai yang tercantum dalam tabel 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 Kirim data OOB pada soket bergaya stream seperti SOCK_STREAM saja.
MSG_PARTIAL Menentukan bahwa lpBuffers hanya berisi pesan parsial. Ketahuilah bahwa kode kesalahan WSAEOPNOTSUPP akan dikembalikan oleh transportasi yang tidak mendukung transmisi pesan parsial.
 
Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti WSASend dengan parameter lpOverlapped diatur ke NULL, 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.
 

I/O Soket Tumpang Tindih

Jika operasi yang tumpang tindih segera selesai, WSASend mengembalikan nilai nol dan parameter lpNumberOfBytesSent diperbarui dengan jumlah byte yang dikirim. Jika operasi yang tumpang tindih berhasil dimulai dan akan selesai nanti, WSASend mengembalikan SOCKET_ERROR dan menunjukkan kode kesalahan WSA_IO_PENDING. Dalam hal ini, lpNumberOfBytesSent tidak diperbarui. Ketika operasi yang tumpang tindih menyelesaikan jumlah data yang ditransfer ditunjukkan baik melalui parameter cbTransferred dalam rutinitas penyelesaian (jika ditentukan), atau melalui parameter lpcbTransfer di WSAGetOverlappedResult.
Catatan Semua I/O yang dimulai oleh utas tertentu dibatalkan ketika utas tersebut keluar. Untuk soket yang tumpang tindih, operasi asinkron yang tertunda dapat gagal jika utas ditutup sebelum operasi selesai. Untuk informasi selengkapnya, lihat ExitThread.
 
Fungsi WSASend menggunakan I/O yang tumpang tindih dapat dipanggil dari dalam rutinitas penyelesaian fungsi WSARecv, WSARecvFrom, WSASend, atau WSASendTo sebelumnya. Ini memungkinkan transmisi data sensitif waktu terjadi sepenuhnya dalam konteks preemptive.

Parameter lpOverlapped harus valid selama durasi operasi yang tumpang tindih. Jika beberapa operasi I/O secara bersamaan luar biasa, masing-masing harus mereferensikan struktur WSAOVERLAPPED terpisah.

Jika parameter lpCompletionRoutine adalah NULL, parameter hEventdari lpOverlapped diberi sinyal ketika operasi yang tumpang tindih selesai jika berisi handel objek peristiwa yang valid. Aplikasi dapat menggunakan WSAWaitForMultipleEvents atau WSAGetOverlappedResult untuk menunggu atau melakukan polling pada objek peristiwa.

Jika lpCompletionRoutine bukan NULL, parameter hEvent diabaikan dan dapat digunakan oleh aplikasi untuk meneruskan informasi konteks ke rutinitas penyelesaian. Penelepon yang melewati lpCompletionRoutinenon-NULL dan kemudian memanggil WSAGetOverlappedResult untuk permintaan I/O yang tumpang tindih yang sama mungkin tidak mengatur parameter fWait untuk pemanggilan WSAGetOverlappedResult ke TRUE. Dalam hal ini penggunaan parameter hEvent tidak terdefinisi, dan mencoba menunggu parameter hEvent akan menghasilkan hasil yang tidak dapat diprediksi.

Rutinitas penyelesaian mengikuti aturan yang sama seperti yang ditetapkan untuk rutinitas penyelesaian I/O file Windows. Rutinitas penyelesaian tidak akan dipanggil sampai utas berada dalam status tunggu yang dapat diperingatkan seperti dapat terjadi ketika fungsi WSAWaitForMultipleEvents dengan parameter fAlertable diatur ke TRUE dipanggil.

Penyedia transportasi memungkinkan aplikasi untuk memanggil operasi kirim dan terima dari dalam konteks rutinitas penyelesaian I/O soket, dan menjamin bahwa, untuk soket tertentu, rutinitas penyelesaian I/O tidak akan ditumpuk. Ini memungkinkan transmisi data sensitif waktu terjadi sepenuhnya dalam konteks preemptive.

Contoh kode C++ berikut adalah prototipe dari rutinitas penyelesaian.


void CALLBACK CompletionROUTINE(
  IN DWORD dwError,
  IN DWORD cbTransferred,
  IN LPWSAOVERLAPPED lpOverlapped,
  IN DWORD dwFlags
);

Fungsi CompletionRoutine adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi atau yang ditentukan pustaka. Parameter dwError menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh lpOverlapped. cbTransferred menentukan jumlah byte yang dikirim. Saat ini tidak ada nilai bendera yang ditentukan dan dwFlags akan menjadi nol. Fungsi ini tidak mengembalikan nilai.

Mengembalikan dari fungsi ini memungkinkan pemanggilan rutinitas penyelesaian lain yang tertunda untuk soket ini. Semua rutinitas penyelesaian menunggu dipanggil sebelum penantian utas yang dapat diperingatkan terpenuhi dengan kode pengembalian WSA_IO_COMPLETION. Rutinitas penyelesaian dapat dipanggil dalam urutan apa pun, tidak harus dalam urutan yang sama operasi yang tumpang tindih selesai. Namun, buffer yang diposting dijamin akan dikirim dalam urutan yang sama dengan yang ditentukan.

Urutan panggilan yang dilakukan ke WSASend juga merupakan urutan di mana buffer ditransmisikan ke lapisan transportasi. WSASend 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.

Contoh Kode

Contoh kode berikut menunjukkan cara menggunakan fungsi WSASend dalam mode I/O yang tumpang tindih.
#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")

#define DATA_BUFSIZE 4096
#define SEND_COUNT   10

int __cdecl main()
{
    WSADATA wsd;

    struct addrinfo *result = NULL;
    struct addrinfo hints;
    WSAOVERLAPPED SendOverlapped;

    SOCKET ListenSocket = INVALID_SOCKET;
    SOCKET AcceptSocket = INVALID_SOCKET;

    WSABUF DataBuf;
    DWORD SendBytes;
    DWORD Flags;

    char buffer[DATA_BUFSIZE];

    int err = 0;
    int rc, i;

    // Load Winsock
    rc = WSAStartup(MAKEWORD(2, 2), &wsd);
    if (rc != 0) {
        printf("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 obtain the 
    // wildcard bind address for IPv4
    hints.ai_family = AF_INET;
    hints.ai_socktype = SOCK_STREAM;
    hints.ai_protocol = IPPROTO_TCP;
    hints.ai_flags = AI_PASSIVE;

    rc = getaddrinfo(NULL, "27015", &hints, &result);
    if (rc != 0) {
        printf("getaddrinfo failed with error: %d\n", rc);
        return 1;
    }

    ListenSocket = socket(result->ai_family,
                          result->ai_socktype, result->ai_protocol);
    if (ListenSocket == INVALID_SOCKET) {
        printf("socket failed with error: %d\n", WSAGetLastError());
        freeaddrinfo(result);
        return 1;
    }

    rc = bind(ListenSocket, result->ai_addr, (int) result->ai_addrlen);
    if (rc == SOCKET_ERROR) {
        printf("bind failed with error: %d\n", WSAGetLastError());
        freeaddrinfo(result);
        closesocket(ListenSocket);
        return 1;
    }

    rc = listen(ListenSocket, 1);
    if (rc == SOCKET_ERROR) {
        printf("listen failed with error: %d\n", WSAGetLastError());
        freeaddrinfo(result);
        closesocket(ListenSocket);
        return 1;
    }
    // Accept an incoming connection request
    AcceptSocket = accept(ListenSocket, NULL, NULL);
    if (AcceptSocket == INVALID_SOCKET) {
        printf("accept failed with error: %d\n", WSAGetLastError());
        freeaddrinfo(result);
        closesocket(ListenSocket);
        return 1;
    }

    printf("Client Accepted...\n");

    // Make sure the SendOverlapped struct is zeroed out
    SecureZeroMemory((PVOID) & SendOverlapped, sizeof (WSAOVERLAPPED));

    // Create an event handle and setup the overlapped structure.
    SendOverlapped.hEvent = WSACreateEvent();
    if (SendOverlapped.hEvent == NULL) {
        printf("WSACreateEvent failed with error: %d\n", WSAGetLastError());
        freeaddrinfo(result);
        closesocket(ListenSocket);
        closesocket(AcceptSocket);
        return 1;
    }

    DataBuf.len = DATA_BUFSIZE;
    DataBuf.buf = buffer;

    for (i = 0; i < SEND_COUNT; i++) {

        rc = WSASend(AcceptSocket, &DataBuf, 1,
                     &SendBytes, 0, &SendOverlapped, NULL);
        if ((rc == SOCKET_ERROR) &&
            (WSA_IO_PENDING != (err = WSAGetLastError()))) {
            printf("WSASend failed with error: %d\n", err);
            break;
        }

        rc = WSAWaitForMultipleEvents(1, &SendOverlapped.hEvent, TRUE, INFINITE,
                                      TRUE);
        if (rc == WSA_WAIT_FAILED) {
            printf("WSAWaitForMultipleEvents failed with error: %d\n",
                   WSAGetLastError());
            break;
        }

        rc = WSAGetOverlappedResult(AcceptSocket, &SendOverlapped, &SendBytes,
                                    FALSE, &Flags);
        if (rc == FALSE) {
            printf("WSASend failed with error: %d\n", WSAGetLastError());
            break;
        }

        printf("Wrote %d bytes\n", SendBytes);

        WSAResetEvent(SendOverlapped.hEvent);

    }

    WSACloseEvent(SendOverlapped.hEvent);
    closesocket(AcceptSocket);
    closesocket(ListenSocket);
    freeaddrinfo(result);

    WSACleanup();

    return 0;
}


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

Lihat juga

WSABUF

WSACloseEvent

WSAConnect

WSACreateEvent

WSAGetOverlappedResult

WSAOVERLAPPED

WSASocket

WSAWaitForMultipleEvents

Fungsi Winsock

Referensi Winsock

sambungkan

Mengirim

soket