Fungsi WSAStartup (winsock2.h)

Artikel
03/08/2023

Fungsi WSAStartup memulai penggunaan Winsock DLL oleh sebuah proses.

Sintaks

int WSAAPI WSAStartup(
  [in]  WORD      wVersionRequested,
  [out] LPWSADATA lpWSAData
);

Parameter

[in] wVersionRequested

Spesifikasi Windows Sockets versi tertinggi yang dapat digunakan pemanggil. Byte urutan tinggi menentukan nomor versi minor; byte urutan rendah menentukan nomor versi utama.

[out] lpWSAData

Penunjuk ke struktur data WSADATA yang menerima detail implementasi Windows Sockets.

Menampilkan nilai

Jika berhasil, fungsi WSAStartup mengembalikan nol. Jika tidak, kode kesalahan akan menampilkan salah satu kode kesalahan yang tercantum di bawah ini.

Fungsi WSAStartup secara langsung mengembalikan kode kesalahan yang diperluas dalam nilai pengembalian untuk fungsi ini. Panggilan ke fungsi WSAGetLastError tidak diperlukan dan tidak boleh digunakan.

Kode kesalahan	Makna
WSASYSNOTREADY	Subsistem jaringan yang mendasar belum siap untuk komunikasi jaringan.
WSAVERNOTSUPPORTED	Versi dukungan Windows Sockets yang diminta tidak disediakan oleh implementasi Windows Sockets khusus ini.
WSAEINPROGRESS	Operasi Windows Sockets 1.1 yang diblokir sedang berlangsung.
WSAEPROCLIM	Batas jumlah tugas yang didukung oleh implementasi Windows Sockets telah tercapai.
WSAEFAULT	Parameter lpWSAData bukan penunjuk yang valid.

Keterangan

Fungsi WSAStartup harus menjadi fungsi Windows Sockets pertama yang dipanggil oleh aplikasi atau DLL. Ini memungkinkan aplikasi atau DLL untuk menentukan versi Windows Sockets yang diperlukan dan mengambil detail implementasi Windows Sockets tertentu. Aplikasi atau DLL hanya dapat mengeluarkan fungsi Windows Sockets lebih lanjut setelah berhasil memanggil WSAStartup.

Untuk mendukung berbagai implementasi dan aplikasi Windows Sockets yang dapat memiliki perbedaan fungsional dari versi terbaru spesifikasi Windows Sockets, negosiasi terjadi di WSAStartup. Pemanggil WSAStartup meneruskan parameter wVersionRequested versi tertinggi dari spesifikasi Windows Sockets yang didukung aplikasi. Winsock DLL menunjukkan versi tertinggi spesifikasi Windows Sockets yang dapat didukung dalam responsnya. Winsock DLL juga membalas dengan versi spesifikasi Windows Sockets yang diharapkan digunakan pemanggil.

Ketika aplikasi atau DLL memanggil fungsi WSAStartup , Winsock DLL memeriksa versi spesifikasi Windows Sockets yang diminta oleh aplikasi yang diteruskan dalam parameter wVersionRequested . Jika versi yang diminta oleh aplikasi sama dengan atau lebih tinggi dari versi terendah yang didukung oleh Winsock DLL, panggilan berhasil dan Winsock DLL mengembalikan informasi terperinci dalam struktur WSADATA yang diarahkan oleh parameter lpWSAData . Anggota wHighVersion dari struktur WSADATA menunjukkan versi tertinggi dari spesifikasi Windows Sockets yang didukung Winsock DLL. Anggota wVersion dari struktur WSADATA menunjukkan versi spesifikasi Windows Sockets yang diharapkan winsock DLL untuk digunakan pemanggil.

Jika anggota wVersion struktur WSADATA tidak dapat diterima oleh pemanggil, aplikasi atau DLL harus memanggil WSACleanup untuk merilis sumber daya Winsock DLL dan gagal menginisialisasi aplikasi Winsock. Untuk mendukung aplikasi atau DLL ini, perlu mencari versi terbaru Winsock DLL untuk diinstal pada platform.

Versi spesifikasi Windows Sockets saat ini adalah versi 2.2. Winsock DLL saat ini, Ws2_32.dll, mendukung aplikasi yang meminta salah satu versi spesifikasi Windows Sockets berikut:

Untuk mendapatkan akses penuh ke sintaks baru dari versi spesifikasi Windows Sockets yang lebih tinggi, aplikasi harus bernegosiasi untuk versi yang lebih tinggi ini. Dalam hal ini, parameter wVersionRequested harus diatur untuk meminta versi 2.2. Aplikasi juga harus sepenuhnya sesuai dengan versi spesifikasi Windows Socket yang lebih tinggi, seperti mengkompilasi terhadap file header yang sesuai, menautkan dengan pustaka baru, atau kasus khusus lainnya. File header Winsock2.h untuk dukungan Winsock 2 disertakan dengan Microsoft Windows Software Development Kit (SDK).

Windows Sockets versi 2.2 didukung pada Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 dengan Paket Layanan 4 (SP4) dan yang lebih baru, Windows Me, Windows 98, dan Windows 95 OSR2. Windows Sockets versi 2.2 juga didukung pada
Windows 95 dengan Windows Socket 2 Update. Aplikasi pada platform ini biasanya harus meminta Winsock 2.2 dengan mengatur parameter wVersionRequested yang sesuai.

Pada Windows 95 dan versi Windows NT 3.51 dan yang lebih lama, Windows Sockets versi 1.1 adalah versi tertinggi dari spesifikasi Windows Sockets yang didukung.

Adalah legal dan mungkin bagi aplikasi atau DLL yang ditulis untuk menggunakan versi spesifikasi Windows Sockets yang lebih rendah yang didukung oleh Winsock DLL agar berhasil menegosiasikan versi yang lebih rendah ini menggunakan fungsi WSAStartup . Misalnya, aplikasi dapat meminta versi 1.1 dalam parameter wVersionRequested yang diteruskan ke fungsi WSAStartup pada platform dengan DLL Winsock 2.2. Dalam hal ini, aplikasi hanya boleh mengandalkan fitur yang sesuai dengan versi yang diminta. Kode Ioctl baru, perilaku baru fungsi yang ada, dan fungsi baru tidak boleh digunakan. Negosiasi versi yang disediakan oleh WSAStartup terutama digunakan untuk memungkinkan aplikasi Winsock 1.1 yang lebih lama dikembangkan untuk Windows 95 dan Windows NT 3.51 dan yang lebih lama untuk berjalan dengan perilaku yang sama pada versi Windows yang lebih baru. File header Winsock.h untuk dukungan Winsock 1.1 disertakan dengan Windows SDK.

Negosiasi dalam fungsi WSAStartup ini memungkinkan aplikasi atau DLL yang menggunakan Windows Sockets dan Winsock DLL untuk mendukung berbagai versi Windows Sockets. Aplikasi atau DLL dapat menggunakan DLL Winsock jika ada tumpang tindih dalam rentang versi. Informasi terperinci tentang implementasi Windows Sockets disediakan dalam struktur WSADATA yang dikembalikan oleh fungsi WSAStartup .

Tabel berikut menunjukkan cara kerja WSAStartup dengan aplikasi yang berbeda dan versi Winsock DLL.

Dukungan versi penelepon	Dukungan versi Winsock DLL	wVersion diminta	wVersion dikembalikan	wHighVersion dikembalikan	Hasil akhir
1.1	1.1	1.1	1.1	1.1	gunakan 1.1
1.0 1.1	1.0	1.1	1.0	1,0	gunakan 1.0
1,0	1.0 1.1	1,0	1.0	1.1	gunakan 1.0
1.1	1.0 1.1	1.1	1.1	1.1	gunakan 1.1
1.1	1.0	1.1	1.0	1,0	Aplikasi gagal
1.0	1.1	1.0	—	—	WSAVERNOTSUPPORTED
1.0 1.1	1.0 1.1	1.1	1.1	1.1	gunakan 1.1
1.1 2.0	1.0 1.1	2.0	1.1	1.1	gunakan 1.1
2.0	1.0 1.1 2.0	2.0	2.0	2.0	gunakan 2.0
2.0 2.2	1.0 1.1 2.0	2.2	2.0	2.0	gunakan 2.0
2.2	1.0 1.1 2.0 2.1 2.2	2.2	2.2	2.2	gunakan 2.2

Setelah aplikasi atau DLL berhasil melakukan panggilan WSAStartup , aplikasi dapat melanjutkan untuk melakukan panggilan Soket Windows lainnya sesuai kebutuhan. Setelah selesai menggunakan layanan Winsock DLL, aplikasi harus memanggil WSACleanup untuk memungkinkan Winsock DLL membebaskan sumber daya Winsock internal yang digunakan oleh aplikasi.

Aplikasi dapat memanggil WSAStartup lebih dari sekali jika perlu mendapatkan informasi struktur WSADATA lebih dari sekali. Pada setiap panggilan tersebut, aplikasi dapat menentukan nomor versi apa pun yang didukung oleh Winsock DLL.

Fungsi WSAStartup biasanya menyebabkan DLL pembantu khusus protokol dimuat. Akibatnya, fungsi WSAStartup tidak boleh dipanggil dari fungsi DllMain dalam DLL aplikasi. Hal ini berpotensi menyebabkan kebuntuan. Untuk informasi selengkapnya, silakan lihat Fungsi Utama DLL.

Aplikasi harus memanggil fungsi WSACleanup untuk setiap kali fungsi WSAStartup berhasil dipanggil. Ini berarti, misalnya, bahwa jika aplikasi memanggil WSAStartup tiga kali, aplikasi harus memanggil WSACleanup tiga kali. Dua panggilan pertama ke WSACleanup tidak melakukan apa pun kecuali menurunkan penghitung internal; panggilan WSACleanup akhir untuk tugas melakukan semua pembatalan alokasi sumber daya yang diperlukan untuk tugas tersebut.

Catatan Aplikasi dapat memanggil fungsi WSAGetLastError untuk menentukan kode kesalahan yang diperluas untuk fungsi soket Windows lainnya seperti yang biasanya dilakukan di Soket Windows bahkan jika fungsi WSAStartup gagal atau fungsi WSAStartup tidak dipanggil untuk menginisialisasi Soket Windows dengan benar sebelum memanggil fungsi Windows Sockets. Fungsi WSAGetLastError adalah salah satu satu fungsi di DLL Winsock 2.2 yang dapat dipanggil dalam kasus kegagalan WSAStartup .

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.

Contoh

Fragmen kode berikut menunjukkan bagaimana aplikasi yang hanya mendukung Windows Sockets versi 2.2 melakukan panggilan WSAStartup :

#define WIN32_LEAN_AND_MEAN

#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")


int __cdecl main()
{

    WORD wVersionRequested;
    WSADATA wsaData;
    int err;

/* Use the MAKEWORD(lowbyte, highbyte) macro declared in Windef.h */
    wVersionRequested = MAKEWORD(2, 2);

    err = WSAStartup(wVersionRequested, &wsaData);
    if (err != 0) {
        /* Tell the user that we could not find a usable */
        /* Winsock DLL.                                  */
        printf("WSAStartup failed with error: %d\n", err);
        return 1;
    }

/* Confirm that the WinSock DLL supports 2.2.*/
/* Note that if the DLL supports versions greater    */
/* than 2.2 in addition to 2.2, it will still return */
/* 2.2 in wVersion since that is the version we      */
/* requested.                                        */

    if (LOBYTE(wsaData.wVersion) != 2 || HIBYTE(wsaData.wVersion) != 2) {
        /* Tell the user that we could not find a usable */
        /* WinSock DLL.                                  */
        printf("Could not find a usable version of Winsock.dll\n");
        WSACleanup();
        return 1;
    }
    else
        printf("The Winsock 2.2 dll was found okay\n");
        

/* The Winsock DLL is acceptable. Proceed to use it. */

/* Add network programming using Winsock here */

/* then call WSACleanup when done using the Winsock dll */
    
    WSACleanup();

}

Persyaratan


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 (termasuk Winsock2.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll