WSAStartup
更新日2006年10月25日
参照 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winsock/winsock/wsastartup_2.asp

機能
そのWSAStartup関数はプロセスによるWS2_32.DLLの使用を始めます。

書式
int WSAStartup(
  WORD wVersionRequested,
  LPWSADATA lpWSAData
);
引数
wVersionRequested [入] 呼び出し者が利用可能なウィンドウズ・ソケッツの最大バージョン。 上位バイトにはマイナーバージョン(リビジョン)番号を指定します; 下位バイトにはメジャーバージョン番号を指定します。
lpWSAData [出] ウィンドウズ・ソケッツの詳細情報を受け取るWSADATA構造体へのポインタ
戻り値
WSAStartup関数は成功時にはゼロを戻します。 さもなくば、それは以下のリストからエラーコードを戻します。

WSAStartup失敗後にウィンドウズ・ソケッツが通常終了した時、アプリケーションは、エラーコード決定にWSAGetLastErrorを呼び出す事が出来ない。 最後のエラー情報保存処理時に、クライアントデータ領域を確立出来なかった失敗の場合には、WS2_32.DLLは記憶出来ないでしょう。

エラーコード 意味
WSASYSNOTREADY
基本的なネットワークサブシステムがネットワーク通信の準備ができていないのを示します。
WSAVERNOTSUPPORTED
要求されたバージョン対応は、この特定ウィンドウズ・ソケッツ実装によって提供されません。
WSAEINPROGRESS
ブロッキング・ウィンドウズ・ソケッツ1.1作業は進行中です。
WSAEPROCLIM
ウィンドウズ・ソケッツ実装にて対応されているタスク数限界に達しました。
WSAEFAULT
lpWSADataは妥当なポインタではありません。

注釈

アプリケーションまたはDLLは、Winsock2使用時にWSAStartup関数を最初に呼び出しましょう。 それはアプリケーションまたはDLLが要求するウィンドウズ・ソケッツ・バージョンを指定するのを許可します、 そして、特定のウィンドウズ・ソケッツ実装の詳細を調べます。 そのアプリケーションまたはDLLは、WSAStartup呼び出しが成功した後に限り、さらにウィンドウズ・ソケッツ関数を発行する事が可能になります。

ウィンドウズ・ソケッツ実装とアプリケーションを将来に置いても対応する為に、最新バージョンからの機能差異を持つ事が出来ます、 ネゴシエーションはWSAStartupで行われます。 WSAStartupとWS2_32.DLLの呼び出し者は、対応する事が出来る中で最も高いバージョンを示します、 そして、各自が他の最も高いバージョンが許容できることを確認します。 WSAStartupへエントリィ時に、 WS2_32.DLLはアプリケーションで要求されるバージョンを調べます。 このバージョンがDLLによってサポートされる最も低いバージョンと以上ならば、 呼び出しは成功します、そして、DLLはwHighVersionで対応する最大バージョンとwVersionのその高いバージョンとwVersionRequestedの最小限を返します。 WS2_32.DLLは呼び出し者にとってWSADATA構造体のwVersionパラメタが受け入れられないならアプリケーションがwVersionを使用すると仮定する、 WSACleanupを呼び出し、別のWS2_32.DLLを調べる、または、初期化を失敗します。

高いバージョン番号にネゴシエーション成功する仕様にこちらのバージョンにアプリケーションが書かれるためにルールに乗っ取って可能です。 その場合、 アプリケーションはこのバージョンで定義された構文の中で合うより高いバージョンの機能性への保証付き利用権であるにすぎません、 例えば新しいIoctlコードと既存の機能の新しい作用。 新機能は判り難いかもしれない。 将来のバージョンの新しい構文への完全なアクセスを得ます、 アプリケーションはその将来のバージョンに完全に従わなければなりません、 例えば新しいヘッダファイルを使用して再コンパイルするなど、 新しいライブラリへのリンキング、またはその他の特別な場合。

このネゴシエーションはWS2_32.DLLとさまざまなウィンドウズ・ソケッツ・バージョンに対応する事の両方を許可します。 共通部分がバージョン範囲にあるならばアプリケーションはWS2_32.DLLを使用可能です。 以下の表では異なるアプリケーションとWS2_32.DLLバージョンでWSAStartupがどの様に働くかを示します。


アプリケーション・バージョン DLLバージョン wVersion
requested
wVersion wHigh
version
結果
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.1
2.0
1.1
1.1
use 1.1
2.0
2.0
2.0
2.0
2.0
use 2.0

Example Code
ウィンドウズ・ソケッツ・バージョン2.2に対応する、 アプリケーションがどのようにWSAStartupを呼び出すかを、 以下のコード断片に示します:
WORD wVersionRequested;
WSADATA wsaData;
int err;
 
wVersionRequested = MAKEWORD(2, 2);
 
err = WSAStartup(wVersionRequested, &wsaData);
if (err != 0)
{
    /*
     * 使用可能なWinSock DLLが見つからなかった事をユーザに伝える。
     */
    return;
}

/*
 * WinSock DLLが2.2をサポートすることを確認。
 * もしDLLが2.2より大きいバージョンを対応しているならば、それに注意する
 * それは要求バージョンからwVersionの2.2をまだ戻すでしょう
 */
if (LOBYTE(wsaData.wVersion) != 2 ||
        HIBYTE(wsaData.wVersion) != 2)
{
    /*
     * 使用可能なWinSock DLLが見つからなかった事をユーザに伝える。
     */
    WSACleanup();
    return;
}

/* Winsock DLLは許可できます。前進しましょう。 */

一旦アプリケーションまたはDLLがWSAStartup呼び出しを成功したならば、 それは、必要に応じて他のWindows Sockets呼び出しをし始めることができます。 それがWS2_32.DLLのサービスを利用し終わったとき、 アプリケーションまたはDLLは、WS2_32.DLLがリソース開放するためにWSACleanupを呼ばなければなりません。

実際のWinsows Sockets実装の詳細は、WSADATA構造体にて記述されます。

それが一度ならずWSADATA構造体情報を得る必要があるならば、アプリケーションまたはDLLは一度ならずWSAStartupを呼ぶことができます。 そのような各々の呼び出しに関して、アプリケーションはDLLによってサポートされるどんなバージョン番号でも指定することができます。

アプリケーションは、あらゆる成功した、アプリケーションに代わってWS2_32.DLLを利用するサードパーティのDLLを許可すると言うWSAStartupを要求するひとつのWSACleanupを呼び出さなければなりません。 この手段、たとえば、 もしもアプリケーションが3回WSAStartupを呼び出したならば、 最初の2つのWSACleanup呼び出しは何もせずに、内部カウンターを減少させます; タスクの最後のWSACleaup要求は、タスクのために全ての必要なリソースを割り当て解除します。


要求環境
Client Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95.
Server Requires Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header Declared in Winsock2.h.
Library Use libws2_32.a
DLL Requires Ws2_32.dll.

参照
Winsock Reference
Winsock Functions
send
sendto
WSACleanup