Функция WSAStartup (winsock.h)

Статья
08/27/2023

Функция 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 должна быть первой функцией Windows Sockets, вызванной приложением или библиотекой DLL. Это позволяет приложению или библиотеке DLL указать требуемую версию сокетов Windows и получить сведения о конкретной реализации сокетов Windows. Приложение или библиотека DLL могут выдавать дополнительные функции сокетов Windows только после успешного вызова WSAStartup.

Для поддержки различных реализаций и приложений windows Sockets, которые могут иметь функциональные отличия от последней версии спецификации сокетов Windows, согласование выполняется в WSAStartup. Вызывающий объект WSAStartup передает параметру wVersionRequested самую высокую версию спецификации сокетов Windows, которую поддерживает приложение. Библиотека DLL Winsock указывает самую высокую версию спецификации сокетов Windows, которую она может поддерживать в своем ответе. Библиотека DLL Winsock также отвечает версией спецификации windows Sockets, которую ожидает вызывающий объект.

Когда приложение или библиотека DLL вызывает функцию WSAStartup , библиотека DLL Winsock проверяет версию спецификации сокетов Windows, запрошенную приложением, переданным в параметре wVersionRequested . Если версия, запрошенная приложением, равна или выше самой низкой версии, поддерживаемой библиотекой DLL Winsock, вызов выполняется успешно, а библиотека DLL Winsock возвращает подробные сведения в структуре WSADATA , на которую указывает параметр lpWSAData . Элемент wHighVersion структуры WSADATA указывает самую высокую версию спецификации сокетов Windows, которую поддерживает библиотека DLL Winsock. Элемент wVersion структуры WSADATA указывает версию спецификации сокетов Windows, которую библиотека Winsock ожидает использовать вызывающий объект.

Если элемент wVersion структуры WSADATA недопустим для вызывающего объекта, приложение или библиотека DLL должны вызвать WSACleanup , чтобы освободить ресурсы Библиотеки DLL Winsock и не инициализировать приложение Winsock. Для поддержки этого приложения или библиотеки DLL необходимо найти обновленную версию библиотеки DLL Winsock для установки на платформе.

Текущая версия спецификации сокетов Windows — версия 2.2. Текущая библиотека DLL Winsock, Ws2_32.dll, поддерживает приложения, которые запрашивают любую из следующих версий спецификации сокетов Windows:

Чтобы получить полный доступ к новому синтаксису более поздней версии спецификации сокетов Windows, приложение должно согласовать эту более позднюю версию. В этом случае для параметра wVersionRequested следует задать запрос версии 2.2. Приложение также должно полностью соответствовать этой более поздней версии спецификации сокета Windows, например компиляция по соответствующему файлу заголовка, связывание с новой библиотекой или другие особые случаи. Файл заголовка Winsock2.h для поддержки Winsock 2 входит в состав microsoft пакет средств разработки программного обеспечения для Windows (SDK).

Сокеты Windows версии 2.2 поддерживаются в Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 с пакетом обновления 4 (SP4) и более поздних версий, Windows Me, Windows 98 и Windows 95 OSR2. Сокеты Windows версии 2.2 также поддерживаются в
Windows 95 с обновлением Windows Socket 2. Приложения на этих платформах обычно должны запрашивать Winsock 2.2, задавая параметр wVersionRequested соответствующим образом.

В Windows 95 и версиях Windows NT 3.51 и более ранних версиях сокеты Windows версии 1.1 является самой высокой поддерживаемой версией спецификации сокетов Windows.

Приложение или библиотека DLL, написанные для использования более ранней версии спецификации Windows Sockets, поддерживаемой библиотекой DLL Winsock, является законным и может успешно согласовать эту более раннюю версию с помощью функции WSAStartup . Например, приложение может запросить версию 1.1 в параметре wVersionRequested, переданном функции WSAStartup на платформе с библиотекой DLL Winsock 2.2. В этом случае приложение должно полагаться только на функции, которые соответствуют запрошенной версии. Не следует использовать новые коды Ioctl, новое поведение существующих функций и новые функции. Согласование версий, предоставляемое WSAStartup, в основном использовалось для того, чтобы старые приложения Winsock 1.1, разработанные для Windows 95 и Windows NT 3.51 и более ранних версий, могли работать с тем же поведением в более поздних версиях Windows. Файл заголовка Winsock.h для поддержки Winsock 1.1 входит в состав Windows SDK.

Это согласование в функции WSAStartup позволяет приложению или библиотеке DLL, использующим сокеты Windows, и winsock DLL поддерживать диапазон версий сокетов Windows. Приложение или библиотека DLL могут использовать библиотеку DLL Winsock, если диапазоны версий перекрываются. Подробные сведения о реализации сокетов Windows приведены в структуре WSADATA , возвращаемой функцией WSAStartup .

В следующей таблице показано, как 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

После успешного вызова WSAStartup приложением или библиотекой DLL можно при необходимости выполнить другие вызовы сокетов Windows. Завершив использование служб библиотеки DLL Winsock, приложение должно вызвать WSACleanup , чтобы библиотека Winsock DLL освобождала внутренние ресурсы Winsock, используемые приложением.

Приложение может вызывать WSAStartup несколько раз, если ему нужно получить сведения о структуре WSADATA несколько раз. При каждом таком вызове приложение может указать любой номер версии, поддерживаемый библиотекой DLL Winsock.

Функция WSAStartup обычно приводит к загрузке вспомогательных библиотек DLL для конкретного протокола. В результате функция WSAStartup не должна вызываться из функции DllMain в библиотеке DLL приложения. Это может привести к взаимоблокировкам. Дополнительные сведения см. в разделе Функция DLL Main.

Приложение должно вызывать функцию WSACleanup при каждом успешном вызове функции WSAStartup . Это означает, например, что если приложение вызывает WSAStartup три раза, оно должно вызвать WSACleanup три раза. Первые два вызова WSACleanup не выполняют никаких действий, кроме уменьшения внутреннего счетчика; последний вызов WSACleanup для задачи выполняет все необходимые действия по освобождению ресурсов для задачи.

Примечание Приложение может вызвать функцию WSAGetLastError , чтобы определить расширенный код ошибки для других функций сокетов Windows, как это обычно делается в сокетах Windows, даже если функция WSAStartup завершается сбоем или функция WSAStartup не была вызвана для правильной инициализации сокетов Windows перед вызовом функции Сокеты Windows. Функция WSAGetLastError является одной из единственных функций в библиотеке DLL Winsock 2.2, которую можно вызвать в случае сбоя WSAStartup .

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone Windows Phone 8 и более поздних версий.

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Примеры

В следующем фрагменте кода показано, как приложение, поддерживающее только сокеты Windows версии 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
Header	winsock.h (включая Winsock2.h)
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll