WSAStartup 関数 (winsock.h)

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

構文

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

パラメーター

wVersionRequired

TBD

[out] lpWSAData

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

戻り値

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

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 の呼び出し元は、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 ソフトウェア開発キット (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 requested 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 1.1 を使用する
1.1 2.0 1.0 1.1 2.0 1.1 1.1 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 ソケット関数を呼び出す前に 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 ストア アプリでサポートされています。

次のコード フラグメントは、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
ヘッダー winsock.h (Winsock2.h を含む)
Library Ws2_32.lib
[DLL] Ws2_32.dll

こちらもご覧ください

MAKEWORD

WSACleanup

WSAGetLastError

Winsock 関数

Winsock リファレンス

送信

Sendto