WSAStartup 函式 (winsock.h)

發行項
08/08/2024

WSAStartup 函式會由進程起始 Winsock DLL 的使用。

語法

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

參數

[in] wVersionRequired

呼叫端可以使用的最高 Windows 套接字規格版本。高序位元組會指定次要版本號碼;低序位元組會指定主要版本號碼。

[out] lpWSAData

WSADATA 數據結構的指標，用來接收 Windows Sockets 實作的詳細數據。

傳回值

如果成功， WSAStartup 函式會傳回零。否則，它會傳回下列其中一個錯誤碼。

WSAStartup 函式會直接傳回此函式傳回值中的擴充錯誤碼。不需要呼叫 WSAGetLastError 函式，不應使用。

錯誤碼	意義
WSASYSNOTREADY	基礎網路子系統尚未準備好進行網路通訊。
WSAVERNOTSUPPORTED	這個特定的 Windows Sockets 實作並未提供所要求的 Windows Sockets 支援版本。
WSAEINPROGRESS	正在封鎖 Windows Sockets 1.1 作業。
WSAEPROCLIM	已達到 Windows Sockets 實作所支援工作數目的限制。
WSAEFAULT	lpWSAData 參數不是有效的指標。

備註

WSAStartup 函式必須是應用程式或 DLL 所呼叫的第一個 Windows Sockets 函式。它可讓應用程式或 DLL 指定所需的 Windows 套接字版本，並擷取特定 Windows Sockets 實作的詳細數據。應用程式或 DLL 只能在成功呼叫 WSAStartup 之後發出進一步的 Windows Sockets 函式。

為了支援與最新版 Windows Sockets 規格有功能差異的各種 Windows Socket 實作和應用程式， WSAStartup 中會進行交涉。 WSAStartup 的呼叫端會傳入 wVersionRequested 參數中應用程式支援的最高 Windows Sockets 規格版本。 Winsock DLL 指出它可以在其響應中支援的最高 Windows Sockets 規格版本。 Winsock DLL 也會回復其預期呼叫端使用的 Windows Sockets 規格版本。

當應用程式或 DLL 呼叫 WSAStartup 函式時，Winsock DLL 會檢查在 wVersionRequested 參數中傳遞之應用程式所要求的 Windows Sockets 規格版本。如果應用程式所要求的版本等於或高於 Winsock DLL 所支援的最低版本，則呼叫會成功，而 Winsock DLL 會傳回 lpWSAData 參數所指向之 WSADATA 結構中的詳細資訊。 WSADATA 結構的 wHighVersion 成員表示 Winsock DLL 支援的最高 Windows Sockets 規格版本。 WSADATA 結構的 wVersion 成員表示 Winsock DLL 預期呼叫端使用的 Windows Sockets 規格版本。

如果呼叫端無法接受 WSADATA 結構的 wVersion 成員，應用程式或 DLL 應該呼叫 WSACleanup 以釋放 Winsock DLL 資源，而且無法初始化 Winsock 應用程式。為了支援此應用程式或 DLL，必須搜尋更新版本的 Winsock DLL，才能在平台上安裝。

Windows Sockets 規格的目前版本是 2.2 版。目前的 Winsock DLL Ws2_32.dll支援要求下列任何 Windows Sockets 規格版本的應用程式：

若要取得更高版本 Windows Sockets 規格之新語法的完整存取權，應用程式必須交涉此更高版本的語法。在此情況下， wVersionRequested 參數應該設定為要求 2.2 版。應用程式也必須完全符合該更高版本的 Windows 套接字規格，例如針對適當的頭文件進行編譯、與新連結庫連結或其他特殊案例。 Winsock 2 支援的 Winsock2.h 頭文件隨附於 Microsoft Windows 軟體開發套件 (SDK) 。

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP、Windows 2000、Windows NT Service Pack 4 (SP4) 及更新版本、Windows Me、Windows 98 和 Windows 95 OSR2 上支援 Windows Sockets 2.2 版。 Windows Sockets 2.2 版也支援
具有 Windows Socket 2 Update 的 Windows 95。這些平臺上的應用程式通常會藉由據此設定 wVersionRequested 參數來要求 Winsock 2.2。

在 Windows 95 和 Windows NT 3.51 版和更早版本上，Windows Sockets 1.1 版是支援的 Windows Sockets 規格最高版本。

撰寫的應用程式或 DLL 可以使用 Winsock DLL 所支援的較低 Windows Sockets 規格版本，以使用 WSAStartup 函式成功交涉此較低版本是合法且可行的。例如，應用程式可以在具有 Winsock 2.2 DLL 的平台上傳遞至 WSAStartup 函式的 wVersionRequested 參數中要求 1.1 版。在此情況下，應用程式應該只依賴符合所要求版本的功能。不應該使用新的Ioctl程式代碼、現有函式的新行為，以及新的函式。 WSAStartup 所提供的版本交涉主要用來允許針對 Windows 95 和 Windows NT 3.51 和更早版本開發的舊版 Winsock 1.1 應用程式，以在更新版本的 Windows 上以相同的行為執行。 Winsock 1.1 支援的 Winsock.h 頭文件隨附於 Windows SDK。

WSAStartup 函式中的這個交涉允許使用 Windows Sockets 和 Winsock DLL 的應用程式或 DLL 支援各種 Windows Sockets 版本。如果版本範圍有任何重疊，應用程式或 DLL 可以使用 Winsock DLL。 WSAStartup 函式所傳回的 WSADATA 結構中會提供 Windows Sockets 實作的詳細資訊。

下表顯示 WSAStartup 如何與不同的應用程式和 Winsock DLL 版本搭配運作。

呼叫端版本支援	Winsock DLL 版本支援	要求 wVersion	wVersion 傳回	傳回的 wHighVersion	結束結果
1.1	1.1	1.1	1.1	1.1	use 1.1
1.0 1.1	1.0	1.1	1.0	1.0	use 1.0
1.0	1.0 1.1	1.0	1.0	1.1	use 1.0
1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1	1.0	1.1	1.0	1.0	應用程式失敗
1.0	1.1	1.0	—	—	WSAVERNOTSUPPORTED
1.0 1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1 2.0	1.0 1.1	2.0	1.1	1.1	use 1.1
2.0	1.0 1.1 2.0	2.0	2.0	2.0	use 2.0
2.0 2.2	1.0 1.1 2.0	2.2	2.0	2.0	use 2.0
2.2	1.0 1.1 2.0 2.1 2.2	2.2	2.2	2.2	use 2.2

一旦應用程式或 DLL 成功呼叫 WSAStartup， 就可以視需要繼續進行其他 Windows Sockets 呼叫。使用 Winsock DLL 的服務完成時，應用程式必須呼叫 WSACleanup ，讓 Winsock DLL 釋放應用程式所使用的內部 Winsock 資源。

如果應用程式需要多次取得 WSADATA 結構資訊，應用程式可以多次呼叫 WSAStartup。在每個這類呼叫上，應用程式都可以指定 Winsock DLL 支援的任何版本號碼。

WSAStartup 函式通常會導致載入通訊協定特定的協助程式 DLL。因此，不應該從應用程式 DLL 中的 DllMain 函式呼叫 WSAStartup 函式。這可能會造成死結。如需詳細資訊，請參閱 DLL Main 函式。

每次呼叫 WSAStartup 函式成功時，應用程式都必須呼叫 WSACleanup 函式。例如，這表示，如果應用程式呼叫 WSAStartup 三次，它必須呼叫 WSACleanup 三次。前兩次呼叫 WSACleanup 除了遞減內部計數器以外，不會執行任何動作;工作的最終 WSACleanup 呼叫會針對工作執行所有必要的資源解除分配。

注意應用程式可以呼叫 WSAGetLastError 函式，以判斷其他 Windows 套接字函式的擴充錯誤碼，就像在 Windows Sockets 中一樣，即使 WSAStartup 函式失敗，或 WSAStartup 函式在呼叫 Windows Sockets 函式之前未呼叫適當地初始化 Windows Sockets。 WSAGetLastError 函式是 Winsock 2.2 DLL 中唯一可在 WSAStartup 失敗的情況下呼叫的其中一個函式。

Windows Phone 8：Windows Phone Windows Phone 8 和更新版本上的市集應用程式支援此函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援此函式。

範例

下列代碼段示範只支援 2.2 版 Windows Socket 的應用程式如何進行 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();

}

規格需求

需求	值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winsock.h (包含 Winsock2.h)
程式庫	Ws2_32.lib
Dll	Ws2_32.dll