WSAStartup 関数 (winsock.h)

  • [アーティクル]

WSAStartup 関数は、プロセスによって Winsock DLL の使用を開始します。

構文

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

パラメーター

[in] wVersionRequired

呼び出し元が使用できる Windows ソケット仕様の最上位バージョン。 上位バイトはマイナー バージョン番号を指定します。下位バイトはメジャー バージョン番号を指定します。

[out] lpWSAData

Windows ソケットの実装の詳細を受け取る WSADATA データ構造へのポインター。

戻り値

成功した場合、 WSAStartup 関数は 0 を返します。 それ以外の場合は、次に示すエラー コードのいずれかを返します。

WSAStartup 関数は、この関数の戻り値で拡張エラー コードを直接返します。 WSAGetLastError 関数の呼び出しは必要なく、使用しないでください。

エラー コード 意味
WSASYSNOTREADY
 基になるネットワーク サブシステムは、ネットワーク通信の準備ができていません。
WSAVERNOTSUPPORTED
 要求された Windows ソケット のサポートのバージョンは、この特定の Windows ソケットの実装では提供されません。
WSAEINPROGRESS
 Windows Sockets 1.1 のブロック操作が進行中です。
WSAEPROCLIM
 Windows ソケットの実装でサポートされるタスクの数の制限に達しました。
WSAEFAULT
 lpWSAData パラメーターが有効なポインターではありません。

注釈

WSAStartup 関数は、アプリケーションまたは DLL によって呼び出される最初の Windows ソケット関数である必要があります。 これにより、アプリケーションまたは DLL で必要な Windows ソケットのバージョンを指定し、特定の Windows ソケット実装の詳細を取得できます。 アプリケーションまたは DLL は、 WSAStartup を正常に呼び出した後にのみ、さらに Windows ソケット関数を発行できます。

最新バージョンの Windows ソケット仕様と機能的な違いを持つ可能性のあるさまざまな Windows ソケットの実装とアプリケーションをサポートするために、 WSAStartup でネゴシエーションが行われます。 WSAStartup の呼び出し元は、wVersionRequested パラメーターを、アプリケーションがサポートする Windows ソケット仕様の最上位バージョンを渡します。 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 ソケット仕様に完全に準拠している必要があります。 Winsock 2 サポート用の Winsock2.h ヘッダー ファイルは、Microsoft Windows ソフトウェア開発キット (Windows SDK) (SDK) に含まれています。

Windows ソケット バージョン 2.2 は、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 95 と Windows Socket 2 Update。 これらのプラットフォーム上のアプリケーションでは、通常、 wVersionRequested パラメーターを適宜設定して Winsock 2.2 を要求する必要があります。

Windows 95 および Windows NT 3.51 以前のバージョンでは、Windows ソケット バージョン 1.1 がサポートされている Windows ソケット仕様の最上位バージョンです。

WsAStartup 関数を使用してこの下位バージョンを正常にネゴシエートするには、Winsock DLL でサポートされている下位バージョンの Windows ソケット仕様を使用するように記述されたアプリケーションまたは DLL が有効であり、可能です。 たとえば、アプリケーションは、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 ソケットを使用するアプリケーションまたは DLL と Winsock DLL の両方で、さまざまな Windows ソケット バージョンをサポートできます。 アプリケーションまたは DLL は、バージョン範囲に重複がある場合に Winsock DLL を使用できます。 Windows ソケットの実装に関する詳細情報は、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 1.0 を使用する
1.0 1.0 1.1 1.0 1.0 1.1 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 2.2 を使用する
 

アプリケーションまたは DLL が WSAStartup 呼び出しに成功すると、必要に応じて他の Windows ソケット呼び出しを行うことができます。 Winsock DLL のサービスの使用が完了したら、アプリケーションは WSACleanup を呼び出して、Winsock DLL がアプリケーションで使用される内部 Winsock リソースを解放できるようにする必要があります。

アプリケーションは、WSADATA 構造体情報を複数回取得する必要がある場合に、WSAStartup を複数回呼び出すことができます。 このような呼び出しのたびに、アプリケーションは Winsock DLL でサポートされている任意のバージョン番号を指定できます。

WSAStartup 関数を使用すると、通常、プロトコル固有のヘルパー DLL が読み込まれます。 その結果、アプリケーション DLL の DllMain 関数から WSAStartup 関数を呼び出さないでください。 これにより、デッドロックが発生する可能性があります。 詳細については、 DLL のメイン関数に関するページを参照してください。

アプリケーションは、 WSAStartup 関数が呼び出されるたびに WSACleanup 関数を呼び出す必要があります。 つまり、たとえば、アプリケーションが WSAStartup を 3 回呼び出す場合は、 WSACleanup を 3 回呼び出す必要があります。 WSACleanup への最初の 2 つの呼び出しは、内部カウンターをデクリメントする以外は何も行わない。タスクの最後の WSACleanup 呼び出しでは、タスクに必要なすべてのリソース割り当て解除が行われます。

メモWSAStartup 関数が失敗した場合や、Windows ソケット関数を呼び出す前に WSAStartup 関数が呼び出されなかった場合でも、アプリケーションは WSAGetLastError 関数を呼び出して、他の Windows ソケット関数の拡張エラー コードを判別できます。 WSAGetLastError 関数は、WSAStartup エラーの場合に呼び出すことができる Winsock 2.2 DLL の唯一の関数の 1 つです。
 

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 リファレンス

送信

Sendto