WSPStartup 関数 (ws2spi.h)

WSPStartup 関数は、クライアントによる Windows Sockets サービス プロバイダー インターフェイス (SPI) の使用を開始します。

構文

int WSPStartup(
  [in]  WORD                wVersionRequested,
  [out] LPWSPDATA           lpWSPData,
  [in]  LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in]  WSPUPCALLTABLE      UpcallTable,
  [out] LPWSPPROC_TABLE     lpProcTable
);

パラメーター

[in] wVersionRequested

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

[out] lpWSPData

Windows Sockets サービス プロバイダーに関する情報を受け取る WSPDATA データ構造へのポインター。

[in] lpProtocolInfo

目的のプロトコルの特性を定義する WSAProtocol_Info 構造体へのポインター。 これは、1 つのプロバイダー DLL で複数の異なるサービス プロバイダーをインスタンス化できる場合に特に便利です。

[in] UpcallTable

WSPUpCallTable 構造体で渡された Winsock 2 DLL (Ws2_32.dll) アップコール ディスパッチ テーブル。

[out] lpProcTable

SPI 関数ポインターのテーブルへのポインター。 このテーブルは、 WSPProc_Table 構造体として返されます。

戻り値

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

エラー コード 意味
WSASYSNOTREADY
ネットワーク サブシステムは使用できません。 このエラーは、ネットワーク サービスを提供するために使用する基になるシステムが現在使用できないため、現時点で Windows ソケットの実装が機能できない場合に返されます。
WSAVERNOTSUPPORTED
Winsock.dll バージョンが範囲外です。 このエラーは、要求された Windows Sockets SPI サポートのバージョンがこの特定の Windows Sockets サービス プロバイダーによって提供されていない場合に返されます。
WSAEINPROGRESS
Windows ソケット 1.1 のブロック操作が進行中です。
WSAEPROCLIM
Windows ソケットの実装でサポートされるタスクの数の制限に達しました。
WSAEFAULT
lpWSPData または lpProcTable パラメーターが無効です。

注釈

Windows Sockets 2 トランスポート サービス プロバイダーは、エクスポートされた 1 つのプロシージャ エントリ ポイント WSPStartup を持つ DLL であり、サービス プロバイダーの初期化関数に使用されます。 他のすべてのサービス プロバイダー関数は、 lpProcTable パラメーターで WSPStartup 関数に渡されるサービス プロバイダーのディスパッチ テーブルを使用して、Winsock 2 DLL からアクセスできるようになります。 サービス プロバイダー DLL は、必要な場合にのみ WinSock 2 DLL によってメモリに読み込まれ、サービスが不要になったときにアンロードされます。

サービス プロバイダー インターフェイスでは、トランスポート サービス プロバイダーが Winsock 2 DLL (アップコール) を呼び出して DLL サポート サービスを取得する状況も定義されています。 トランスポート サービス プロバイダーは、WSPStartup 関数に渡される UpcallTable パラメーター内の Winsock 2 DLL のアップコール ディスパッチ テーブルを返します。

WSPStartup 関数は、プロセスごとに Windows Sockets SPI クライアントによって呼び出される最初の Windows ソケット SPI 関数である必要があります。 これにより、クライアントは必要な Windows Sockets SPI のバージョンを指定し、そのアップコール ディスパッチ テーブルを提供できます。 Windows Sockets サービス プロバイダーによって作成されたすべてのアップコール (つまり、WPU でプレフィックスが付いた関数) は、クライアントの upcall ディスパッチ テーブルを介して呼び出されます。 この関数を使用すると、クライアントは特定の Windows ソケット サービス プロバイダーの実装の詳細を取得することもできます。 Windows ソケット SPI クライアントは、 WSPStartup 呼び出しが成功した後にのみ、さらに Windows ソケット SPI 関数を発行できます。 SPI 関数の残りの部分へのポインターのテーブルは、WSPProc_Table構造体を返す lpProcTable パラメーターを介して取得されます。

Winsock 2 DLL は、標準の Windows 動的ライブラリ読み込みメカニズムを使用してサービス プロバイダーのインターフェイス DLL をシステムに読み込み、 WSPStartup 関数を呼び出して初期化します。 これは通常、インターフェイス DLL が現在メモリに読み込まれていないサービス プロバイダーに関連付けられる新しいソケットを作成するために、 ソケット または WSASocket 関数を呼び出すアプリケーションによってトリガーされます。

現在の Windows Sockets SPI と機能的な違いがある可能性がある Windows ソケット SPI とWs2_32.dllの将来のバージョンをサポートするために、 WSPStartup でネゴシエーションが行われます。 WSPStartup の呼び出し元 (Ws2_32.dllまたは階層化されたプロトコル) と Windows Sockets サービス プロバイダーは、サポートできる Windows ソケットの最高バージョンを互いに示し、それぞれが他方の最高バージョンが許容可能であることを確認します。 WSPStartup へのエントリ時に、Windows Sockets サービス プロバイダーはクライアントによって要求されたバージョンを調べます。 このバージョンがサービス プロバイダーでサポートされている最も低いバージョン以上の場合、呼び出しは成功し、サービス プロバイダーは WSPDATA 構造体の wHighVersion メンバーでサポートされている最高バージョンを返し、wVersion メンバーでは wVersionRequested パラメーターで指定された高いバージョンとバージョンの最小値を返します。 その後、Windows Sockets サービス プロバイダーは、Windows Sockets SPI クライアントが wVersion メンバーで指定されたバージョンの Windows ソケットを使用することを前提としています。 WSPDATA 構造体の wVersion メンバーが呼び出し元に受け入れられない場合は、LPWSPCleanup を呼び出して、別の Windows ソケット サービス プロバイダーを検索するか、初期化に失敗する必要があります。

このネゴシエーションにより、Windows ソケット サービス プロバイダーと Windows Sockets SPI クライアントの両方で、さまざまな Windows ソケット バージョンをサポートできます。 バージョン範囲に重複がある場合、クライアントは Windows Sockets サービス プロバイダーを正常に利用できます。

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

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

Winsock DLL でサポートされている下位バージョンの Windows ソケット仕様を使用するように記述されたアプリケーションまたは DLL が 、WSPStartup 関数を使用してこの下位バージョンを正常にネゴシエートすることは有効であり、可能です。 たとえば、アプリケーションは、Winsock 2.2 DLL を使用するプラットフォーム上の WSPStartup 関数に渡される wVersionRequested パラメーターのバージョン 1.1 を要求できます。 この場合、アプリケーションは、要求されたバージョン内に収まる機能にのみ依存する必要があります。 新しい Ioctl コード、既存の関数の新しい動作、および新しい関数は使用しないでください。 WSPStartup によって提供されるバージョン ネゴシエーションは、主に、Windows 95 および Windows NT 3.51 以前で開発された古い Winsock 1.1 アプリケーションを、新しいバージョンの Windows で同じ動作で実行できるようにするために使用されました。 Winsock 1.1 サポート用の Winsock.h ヘッダー ファイルは、Windows SDK に含まれています。

次のグラフは、 WSPStartup がさまざまなWS2_32.DLLおよび Windows Sockets サービス プロバイダー (SP) バージョンと組み合わせて動作する方法の例を示しています。

[DLL]
 
versions
SP
 
versions
wVersionRequested wVersion wHighVersion 最終結果
1.1 1.1 1.1 1.1 1.1 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 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 DLL が失敗する
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.0 1.1 2.0 1.1 2.0 1.1 1.1 use 1.1
1.0 1.1 2.0 2.0 2.0 2.0 2.0 use 2.0
1.0 1.1 2.0 2.1 2.2 2.2 2.2 2.2 2.2 use 2.2
 

次のコード フラグメントは、Windows ソケット SPI のバージョン 2 のみをサポートする Windows ソケット SPI クライアントが WSPStartup 呼び出しを行う方法を示しています。

WORD wVersionRequested;
WSPDATA WSPData;
 
int err;
 
WSPUPCALLTABLE upcallTable =
{ 
    /* initialize upcallTable with function pointers */
};
 
LPWSPPROC_TABLE lpProcTable =
{ 
    /* allocate memory for the ProcTable */
};
 
wVersionRequested = MAKEWORD( 2, 2 );
 
err = WSPStartup( wVersionRequested, &WSPData, lpProtocolBuffer, upcallTable, lpProcTable );
if ( err != 0 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    return;
}
 
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider 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( WSPData.wVersion ) != 2 ||
         HIBYTE( WSPData.wVersion ) != 2 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    LPWSPCleanup( );
    return;   
}
 
/* The Windows Sockets service provider is acceptable. Proceed. */

このコード フラグメントは、バージョン 2.2 のみをサポートする Windows ソケット サービス プロバイダーが WSPStartup ネゴシエーションを実行する方法を示しています。

/* Make sure that the version requested is >= 2.2.  */
/* The low byte is the major version and the high   */
/* byte is the minor version.                       */
 
if ( (LOBYTE( wVersionRequested ) < 2) ||
     ((LOBYTE( wVersionRequested ) == 2) &&
     (HIBYTE( wVersionRequested ) < 2))) {
    return WSAVERNOTSUPPORTED;
}
 
/* Since we only support 2.2, set both wVersion and  */
/* wHighVersion to 2.2.                              */
 
lpWSPData->wVersion = MAKEWORD( 2, 2 );
lpWSPData->wHighVersion = MAKEWORD( 2, 2 );


Windows ソケット SPI クライアントが WSPStartup 呼び出しを成功させたら、必要に応じて他の Windows ソケット SPI 呼び出しを行うことができます。 Windows ソケット サービス プロバイダーのサービスの使用が完了したら、クライアントが LPWSPCleanup を呼び出して、Windows ソケット サービス プロバイダーがクライアントに割り当てられているリソースを解放できるようにする必要があります。

WSPStartup 関数は、クライアント プロセスごとに少なくとも 1 回呼び出す必要があり、Winsock 2 DLL またはその他のエンティティによって複数回呼び出される場合があります。 WSPStartup 呼び出しが成功するたびに、一致する LPWSPCleanup 関数を呼び出す必要があります。 サービス プロバイダーは、プロセスごとに参照カウントを維持する必要があります。 各 WSPStartup 呼び出しで、呼び出し元は、サービス プロバイダー DLL でサポートされている任意のバージョン番号を指定できます。

サービス プロバイダーは、WSPStartup 関数によって UpcallTable パラメーターとして受け取られたクライアントの upcall ディスパッチ テーブルへのポインターをプロセスごとに格納する必要があります。 特定のプロセスが WSPStartup を 複数回呼び出す場合、サービス プロバイダーは、最後に指定した upcall ディスパッチ テーブル ポインターのみを使用する必要があります。

Windows ソケット SPI クライアントは、 WSPDATA 構造体情報を複数回取得する必要がある場合に 、WSPStartup を複数回呼び出すことができます。 このような呼び出しのたびに、クライアントはプロバイダーでサポートされている任意のバージョン番号を指定できます。

サード パーティ製 DLL が Windows ソケット プロバイダーを利用できるようにするには、WSPStartup 呼び出しが成功するたびに対応する LPWSPCleanup 呼び出しが 1 つ必要です。 これは、たとえば、 WSPStartup が 3 回呼び出された場合、 対応する LPWSPCleanup の呼び出しが 3 回行われる必要があることを意味します。 LPWSPCleanup への最初の 2 つの呼び出しでは、内部カウンターをデクリメントする以外は何も行われません。最後の LPWSPCleanup 呼び出しでは、必要なすべてのリソース割り当てが解除されます。

この関数 (およびその他のほとんどのサービス プロバイダー関数) は、クライアントが 16 ビット Windows ソケット 1.1 クライアントの場合、16 ビット プロセスとして開始されたスレッドで呼び出すことができます。 16 ビット プロセスの重要な制限の 1 つは、16 ビット プロセスでスレッドを作成できないことです。 これは、実装の一部として内部サービス スレッドを使用する予定のサービス プロバイダーの実装者にとって重要です。

幸いなことに、通常、サービス スレッドの条件が強い領域は 2 つだけです。

これらの領域は、32 ビット プロセスでのみ呼び出すことができる新しい Windows ソケット 2 関数からのみアクセスできます。

次の 2 つの設計規則に慎重に従っている場合は、サービス スレッドを安全に使用できます。

  • サービス スレッドは、16 ビット Windows ソケット 1.1 クライアントで使用できない機能にのみ使用します。
  • オンデマンドでのみサービス スレッドを作成します。

内部サービス スレッドの使用には、他にもいくつかの注意が必要です。 まず、スレッドは通常、パフォーマンスの低下を引き受けます。 できるだけ少なくして、可能な限りスレッド遷移を避けてください。 2 つ目は、スレッドを作成する際のエラーを常にチェックし、( WSAEOPNOTSUPP など) 正常かつ有益に失敗する必要があります。予期しない実行イベントが発生すると、スレッドを必要とするコード パスが実行される 16 ビット プロセスが発生します。

階層化されたサービス プロバイダーは、この関数の実装を提供しますが、 WSPStartup を呼び出してプロトコル チェーン内の次のレイヤーを初期化するときにも、この関数のクライアントです。 次のレイヤーの WSPStartup の呼び出しは、このレイヤーの WSPStartup の実行中に発生する可能性があります。または、 LPWSPSocket が呼び出されたときなど、遅延してオンデマンドで呼び出される可能性があります。 いずれの場合も、プロトコル チェーンのレイヤーを介して伝達されるため、この関数の lpProtocolInfo パラメーターにはいくつかの特別な考慮事項が適用されます。

階層化プロバイダーは、lpProtocolInfo によって参照される構造体の ProtocolChain を検索して、チェーン内の独自の場所 (レイヤーのカタログ エントリ ID を検索して) とチェーン内の次の要素の ID を決定します。 次の要素が別のレイヤーの場合、次のレイヤーの WSPStartup が呼び出されると、このレイヤーは、同じ変更されていないチェーン情報を持つ同じ変更されていないWSAProtocol_Info構造を参照する lpProtocolInfo を次のレイヤーに渡す必要があります。 ただし、次のレイヤーがベース プロトコル (つまり、チェーン内の最後の要素) の場合、このレイヤーは、ベース プロバイダーの WSPStartup を呼び出すときに置換を実行します。 この場合、基本プロバイダーの WSAPROTOCOL_INFO 構造体は lpProtocolInfo パラメーターで参照する必要があります。

このポリシーの重要な利点の 1 つは、基本サービス プロバイダーがプロトコル チェーンを認識する必要がないということです。

この同じ伝達ポリシーは、LPWSPAddressToString、LPWSPDuplicateSocket、LPWSPSocketLPWSPStringToAddress などの他の関数の階層化されたシーケンスを介して、WSAPROTOCOL_INFO構造体を伝達するときに適用されます。

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー ws2spi.h

こちらもご覧ください

WSAProtocol_Info

LPWSPAddressToString

LPWSPStringToAddress

LPWSPCleanup

LPWSPDuplicateSocket

LPWSPEventSelect

WSPProc_Table

LPWSPSend

LPWSPSendTo

LPWSPSocket

WSPUpCallTable