WSAStartup 函数 (winsock.h)

  • 项目

WSAStartup 函数通过进程启动对 Winsock DLL 的使用。

语法

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

参数

[in] wVersionRequired

调用方可以使用的最高版本的 Windows 套接字规范。 高位字节指定次要版本号;低位字节指定主版本号。

[out] lpWSAData

指向 WSADATA 数据结构的指针，该结构用于接收 Windows 套接字实现的详细信息。

返回值

如果成功， WSAStartup 函数返回零。 否则，它将返回下面列出的错误代码之一。

WSAStartup 函数直接返回此函数的返回值中的扩展错误代码。 不需要调用 WSAGetLastError 函数，也不应使用。

错误代码 含义
WSASYSNOTREADY
 基础网络子系统尚未准备好进行网络通信。
WSAVERNOTSUPPORTED
 此特定 Windows 套接字实现不提供所请求的 Windows 套接字支持版本。
WSAEINPROGRESS
 阻止 Windows 套接字 1.1 操作正在进行。
WSAEPROCLIM
 已达到 Windows 套接字实现支持的任务数限制。
WSAEFAULT
 lpWSAData 参数不是有效的指针。

注解

WSAStartup 函数必须是应用程序或 DLL 调用的第一个 Windows 套接字函数。 它允许应用程序或 DLL 指定所需的 Windows 套接字版本，并检索特定 Windows 套接字实现的详细信息。 应用程序或 DLL 只能在成功调用 WSAStartup 后发出更多 Windows 套接字函数。

为了支持与最新版本的 Windows 套接字规范具有功能差异的各种 Windows 套接字实现和应用程序，在 WSAStartup 中进行了协商。 WSAStartup 的调用方将应用程序支持的最高版本的 Windows 套接字规范传入 wVersionRequested 参数。 Winsock DLL 指示它可以在其响应中支持的 Windows 套接字规范的最高版本。 Winsock DLL 还会回复它希望调用方使用的 Windows 套接字规范版本。

当应用程序或 DLL 调用 WSAStartup 函数时，Winsock DLL 检查在 wVersionRequested 参数中传递的应用程序请求的 Windows 套接字规范的版本。 如果应用程序请求的版本等于或高于 Winsock DLL 支持的最低版本，则调用成功，并且 Winsock DLL 将在 lpWSAData 参数指向的 WSADATA 结构中返回详细信息。 WSADATA 结构的 wHighVersion 成员指示 Winsock DLL 支持的 Windows 套接字规范的最高版本。 WSADATA 结构的 wVersion 成员指示 Winsock DLL 希望调用方使用的 Windows 套接字规范的版本。

如果 调用 方无法接受 WSADATA 结构的 wVersion 成员，则应用程序或 DLL 应调用 WSACleanup 来释放 Winsock DLL 资源，并且无法初始化 Winsock 应用程序。 为了支持此应用程序或 DLL，需要搜索要安装在平台上的 Winsock DLL 的更新版本。

Windows 套接字规范的当前版本为版本 2.2。 当前的 Winsock DLL Ws2_32.dll支持请求以下任一版本的 Windows 套接字规范的应用程序：

  • 1.0
  • 1.1
  • 2.0
  • 2.1
  • 2.2

若要完全访问更高版本的 Windows 套接字规范的新语法，应用程序必须协商此更高版本。 在这种情况下， wVersionRequested 参数应设置为请求版本 2.2。 应用程序还必须完全符合更高版本的 Windows 套接字规范，例如针对适当的头文件进行编译、与新库链接或其他特殊情况。 Microsoft Windows 软件开发工具包 (Windows SDK) (SDK) 随附了 Winsock 2 支持的 Winsock2.h 头文件。

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 套接字版本 2.2。 在 上也支持 Windows 套接字版本 2.2
带有 Windows 套接字 2 更新的 Windows 95。 这些平台上的应用程序通常应相应地设置 wVersionRequested 参数来请求 Winsock 2.2。

在 Windows 95 和 Windows NT 3.51 及更早版本中，Windows 套接字版本 1.1 是受支持的 Windows 套接字规范的最高版本。

为使用 Winsock DLL 支持的较低版本的 Windows 套接字规范编写的应用程序或 DLL 可以使用 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 套接字和 Winsock DLL 的应用程序或 DLL 支持一系列 Windows 套接字版本。 如果版本范围有任何重叠，应用程序或 DLL 可以使用 Winsock DLL。 WSAStartup 函数返回的 WSADATA 结构中提供了有关 Windows 套接字实现的详细信息。

下表显示了 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 使用 2.0
2.0 2.2 1.0 1.1 2.0 2.2 2.0 2.0 使用 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 套接字调用。 使用完 Winsock DLL 的服务后，应用程序必须调用 WSACleanup ，以允许 Winsock DLL 释放应用程序使用的内部 Winsock 资源。

如果需要多次获取 WSADATA 结构信息，应用程序可以多次调用 WSAStartup 。 每次调用此类时，应用程序都可以指定 Winsock DLL 支持的任何版本号。

WSAStartup 函数通常会导致加载特定于协议的帮助程序 DLL。 因此，不应从应用程序 DLL 中的 DllMain 函数调用 WSAStartup 函数。 这可能会导致死锁。 有关详细信息，请参阅 DLL 主函数。

每次成功调用 WSAStartup 函数时，应用程序都必须调用 WSACleanup 函数。 这意味着，例如，如果应用程序调用 WSAStartup 三次，则必须调用 WSACleanup 三次。 对 WSACleanup 的前两个调用除了递减内部计数器外，什么都不做;任务的最终 WSACleanup 调用会为任务执行所有必要的资源解除分配。

注意 应用程序可以调用 WSAGetLastError 函数来确定其他 Windows 套接字函数的扩展错误代码，就像在 Windows 套接字中一样，即使 WSAStartup 函数失败或未调用 WSAStartup 函数来正确初始化 Windows 套接字，然后再调用 Windows 套接字函数。 WSAGetLastError 函数是 Winsock 2.2 DLL 中唯一可以在 WSAStartup 失败时调用的函数之一。
 

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持此函数。

示例

以下代码片段演示仅支持 2.2 版 Windows 套接字的应用程序如何进行 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)
Library Ws2_32.lib
DLL Ws2_32.dll

另请参阅

MAKEWORD

WSACleanup

WSAGetLastError

Winsock 函数

Winsock 参考

send

sendto