WSAStartup 函式 (winsock2.h)

發行項
08/27/2023

WSAStartup函式會起始處理常式使用 Winsock DLL。

語法

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

參數

[in] wVersionRequested

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

[out] lpWSAData

要接收 Windows Sockets 實作詳細資料的 WSADATA 資料結構的指標。

傳回值

如果成功， 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 Socket 實作與最新版 Windows Sockets 規格有功能差異的應用程式， 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 Socket 規格，例如針對適當的標頭檔進行編譯、與新程式庫連結或其他特殊案例。 Winsock 2 支援的 Winsock2.h 頭檔隨附于 Microsoft Windows 軟體發展工具組 (SDK) 。

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP、Windows 2000、Windows NT 4.0 service Pack 4 (SP4) 及更新版本、Windows Me、Windows 98 和 Windows 95 OSR2 上支援 Windows Sockets 4.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。如需 Windows Sockets 實作的詳細資訊，請參閱WSAStartup函式所傳回的WSADATA結構。

下表顯示 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 8 和更新版本Windows Phone市集應用程式支援此函式。

Windows 8.1和Windows Server 2012 R2：Windows 市集應用程式支援此功能，Windows 8.1、Windows Server 2012 R2 及更新版本。

範例

下列程式碼片段示範僅支援 Windows Sockets 2.2 版的應用程式如何呼叫 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
標頭	winsock2.h (包括 Winsock2.h)
程式庫	Ws2_32.lib
Dll	Ws2_32.dll