WSAStartup

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

SOCKET WSAStartup(
    WORD wVersionRequested,
    LPWSADATA lpWSAData
);

WS2_32.DLL

引数

wVersionRequested

呼び出し側が利用することのできるWindows Socketsのうち最も新しいバージョンを指定します。上位バイトにはマイナーバージョン番号を、下位バイトにはメジャーバージョン番号を指定します。

lpWSAData

Windows Sockets実装の詳細を取得するためのWSADATA構造体へのポインタを指定します。

戻り値

成功すると0を返します。

失敗すると以下に示すエラーコードを返します。WSAStartup関数は拡張エラーコードを関数の戻り値として直接返します。WSAGetLastError関数を使用する必要はなく、また使用するべきではありません。

10014 (WSAEFAULT)

lpWSADataパラメータが有効なポインタではありません。

10036 (WSAEINPROGRESS)

ブロッキングWindows Sockets 1.1呼び出しが実行中です。

10067 (WSAEPROCLIM)

Windows Sockets実装でサポートされるタスクの最大数に達しています。

10091 (WSASYSNOTREADY)

基盤となるネットワークサブシステムがネットワーク通信可能な状態になっていません。

10092 (WSAVERNOTSUPPORTED)

要求されたバージョンのWindows Socketsサポートは、このWindows Sockets実装では提供されていません。

解説

アプリケーションまたはDLLは、他のどのWindows Sockets関数よりも先にWSAStartup関数を呼び出さなければなりません。WSAStartup関数の呼び出しにより、アプリケーションまたはDLLは要求されるWindows Socketsのバージョンを指定し、特定のWindows Sockets実装に関する詳細を取得することができます。アプリケーションまたはDLLは、WSAStartup呼び出しが成功した後でのみ、他のWindows Sockets関数を呼び出すことができます。

最新バージョンのWidnows Sockets仕様と間で機能的な違いを持つ可能性のあるさまざまなWindows Sockets実装やアプリケーションに対応するため、WSAStartup関数ではネゴシエーション（情報のやり取り）が実行されます。WSAStartup関数の呼び出し側は、アプリケーションが対応しているWindows Sockets仕様のうち最新のバージョン番号をwVersionRequestedパラメータに渡します。Winsock DLLは、対応可能なWindows Sockets仕様のうち最新のバージョン番号と、呼び出し側が使用すると見込まれるWindows Sockets仕様のバージョン番号を返します。

アプリケーションまたはDLLがWSAStartup関数を呼び出すと、Winsock DLLはwVersionRequestedパラメータに渡されたアプリケーションが要求するWindows Socktes仕様のバージョンを調べます。アプリケーションが要求するバージョンがWindows DLLがサポートする最も低いバージョンと同じかそれより新しい場合には、呼び出しは成功し、Winsock DLLはlpWSADataパラメータが指すWSADATA構造体に詳細な情報を返します。WSADATA構造体のwHighVersionメンバはWinsock DLLがサポートするWidnows Sockets仕様のうち最新のバージョンを示します。WSADATA構造体のwVersionメンバは、呼び出し側が使用すると見込まれるWindows Sockets仕様のバージョンを示します。

WSADATA構造体のwVersionメンバが呼び出し側の条件に合わない場合は、アプリケーションまたはDLLはWSACleanup関数を呼び出してWinsock DLLリソースを解放し、Winsockアプリケーションの初期化失敗とするべきです。このアプリケーションまたはDLLに対応するには、更新されたバージョンのWinsock DLLを探してプラットフォームにインストールする必要があるでしょう。

現在のWindows Sockets仕様のバージョンはバージョン2.2です。現在のWinsock DLL (Ws2_32.dll) は以下のバージョンのWindows Sockets仕様のいずれかを要求するアプリケーションをサポートしています。

• 1.0
• 1.1
• 2.0
• 2.1
• 2.2

Windows Sockets仕様のより新しいバージョンの新しい構文をすべて利用できるようにするには、アプリケーションはその新しいバージョンのためのネゴシエーションを行わなければなりません。この場合、wVersionRequestedパラメータは要求バージョン2.2に設定すべきです。また、適切なヘッダファイルに対してコンパイルしたり、新しいライブラリをリンクしたりすることなどにより、アプリケーションはその新しいバージョンのWindows Socket仕様に完全に準拠させなければなりません。Winsock 2に対応したWinsock2.hヘッダファイルはMicrosoft Windows Software Development Kit (SDK) に含まれています。

Windows Socketsバージョン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上でサポートされています。また、Widnows Socket 2 UpdateがインストールされたWindows 95上でもサポートされています。これらのプラットフォーム上のアプリケーションは、通常、wVersionRequestedパラメータにWinsock 2.2を設定してこのバージョンを要求するべきです。

Windows 95およびWindows NT3.51以前のバージョンでは、Windows Socketsバージョン1.1がサポートされているWindows Sockets仕様のもっとも新しいバージョンです。

Winsock DLLがサポートするWindows Sockets仕様のうち、より低いバージョンを使用してアプリケーションまたはDLLを作成することで、WSAStartup関数を使用してその低いバージョンでのネゴシエーションを行うことが認められています。たとえば、Winsock 2.2 DLLが存在するプラットフォーム上においてWSAStartup関数に渡されるwVersionRequestedパラメータでバージョン1.1を要求することができます。この場合は、アプリケーションはその要求したバージョンに適合する機能のみに依存するべきです。新しいIoctlコードや既存の関数の新しい動作や新たに追加された関数を使用すべきではありません。WSAStartup関数が提供するバージョンネゴシエーションは、そもそも、Windows 95やWindows NT3.51以前向けに開発された古いWinsock 1.1アプリケーションが、以降のバージョンのWindowsでも同じ動作で実行することができるように使用されたものです。Winsock 1.1対応のためのWinsock.hヘッダファイルがWindows SDKに含まれています。

WSAStartup関数におけるこのネゴシエーションは、Windows Socketsを使用するアプリケーションまたはDLLとWinsock DLL両方がWindows Socktesバージョンの範囲をサポートすることを可能にします。アプリケーションまたはDLLは、対応可能なバージョンの範囲が重なった場合にWinsock DLLを使用することができます。Windows Sockets実装に関する詳細な情報がWSAStartup関数によって返されるWSADATA構造体で提供されます。

以下の表はWSAStartup関数が様々なアプリケーションのバージョンとWinsock DLLのバージョンでどのように動作するかを示しています。

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

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

一般に、WSAStartup関数ではプロトコル固有のヘルパーDLLをロードすることになります。そのため、アプリケーションDLLではDllMain関数からWSAStartup関数を呼び出すべきではありません。DllMain関数からのWSAStartup関数呼び出しは潜在的にデッドロックを引き起こす可能性があります。

アプリケーションはそれぞれのWSAStartup関数呼び出しの成功に対応してWSACleanup関数を呼び出さなければなりません。すなわち、例えばアプリケーションがWSAStartup関数を3回呼び出した場合には、WSACleanup関数を3回呼び出さなければならないことを示しています。この場合、最初の2回のWSACleanup関数の呼び出しでは内部カウンタをデクリメントする以外は何もしませず、タスクに対する最後のWSACleanup関数呼び出しで、タスクに対するすべての必要なリソース解放が行われます。

注意：アプリケーションは、WSAGetLastError関数を呼び出してほかのWindows Sockets関数に解する拡張エラーコードを決定することができます。そのようなことは、WSAStartup関数が失敗した場合や、Widnows Sockets関数を呼び出す前にWSAStartupを呼び出して適切にWindows Socketsを初期化しなかった場合ですら、Windows Socketsで普通に行われています。WSAGetLastError関数はWSAStartupが失敗した場合に呼び出すことのできるWinsock 2.2 DLLの関数の数少ない関数の1つです。