WSCInstallProvider 関数 (ws2spi.h)
構文
int WSCInstallProvider(
[in] LPGUID lpProviderId,
[in] const WCHAR *lpszProviderDllPath,
[in] const LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out] LPINT lpErrno
);
パラメーター
[in] lpProviderId
プロバイダーのグローバル一意識別子 (GUID) へのポインター。
[in] lpszProviderDllPath
プロバイダー DLL への読み込みパスを含む Unicode 文字列へのポインター。 この文字列は、パス解決の通常の規則を監視し、埋め込み環境文字列 ( %SystemRoot%など) を含めることができます。 このような環境文字列は、Ws2_32.dll が後でアプリケーションの代わりにプロバイダー DLL を読み込む必要がある場合に展開されます。 埋め込まれた環境文字列が展開されると、Ws2_32.dll は結果の文字列を LoadLibrary 関数に渡して、プロバイダーをメモリに読み込みます。 詳細については、「 LoadLibrary」を参照してください。
[in] lpProtocolInfoList
WSAProtocol_Info構造体の配列へのポインター。 各構造体は、プロバイダーでサポートされるプロトコル、アドレス ファミリ、ソケットの種類を定義します。
[in] dwNumberOfEntries
lpProtocolInfoList 配列内のエントリの数。
[out] lpErrno
関数が失敗した場合のエラー コードへのポインター。
戻り値
WSCInstallProvider が成功すると、0 が返されます。 それ以外の場合は 、SOCKET_ERRORを返し、 lpErrno パラメーターに特定のエラー コードが返されます。
| エラー コード | 意味 |
|---|---|
| 1 つ以上の引数が、ユーザー・アドレス・スペースの有効な部分にありません。 | |
| 1 つ以上の引数が無効です。 | |
| バッファーにメモリを割り当てることはできません。 | |
| 回復不可能なエラーが発生しました。 このエラーは、プロバイダーが既にインストールされている、ユーザーが Winsock レジストリに書き込むのに必要な管理特権がない、カタログ エントリを作成またはインストールするときにエラーが発生したなど、いくつかの条件で返されます。 | |
| 失敗しないシステム呼び出しが失敗しました。 | |
| メモリが不足していました。 このエラーは、新しいカタログ エントリを割り当てるためのメモリが不足している場合に返されます。 |
解説
WSCInstallProvider は、1 つのトランスポート サービス プロバイダーをインストールするために使用されます。 このルーチンは、指定されたプロバイダーに必要な一般的な Windows ソケット 2 構成情報を作成します。 これは、基本プロトコル、階層型プロトコル、およびプロトコル チェーンに適用されます。 レイヤード サービス プロバイダーがインストールされている場合は、 WSCInstallProviderAndChains を使用する必要があります。 WSCInstallProviderAndChains では、1 つの関数呼び出しを使用して、レイヤード プロトコルと 1 つ以上のプロトコル チェーンをインストールできます。 WSCInstallProvider を使用して同じ作業を実行するには、複数の関数呼び出しが必要になります。
Winsock 2 は、階層化されたプロトコルに対応しています。 階層型プロトコルは、リモート エンドポイントとのデータの実際の交換に基づくトランスポート スタックに依存しながら、より高いレベルの通信機能のみを実装するプロトコルです。 レイヤー化されたプロトコルの例としては、認証を実行し、相互に合意された暗号化スキームを確立するために、接続確立プロセスにプロトコルを追加するセキュリティ層があります。 このようなセキュリティ プロトコルでは、一般に、TCP や SPX などの基になる信頼性の高いトランスポート プロトコルのサービスが必要になります。 基本プロトコルという用語は、リモート エンドポイントとのデータ通信を実行できる TCP や SPX などのプロトコルを指します。 階層化プロトコルという用語は、単独で立つことができないプロトコルを記述するために使用されます。 その後、プロトコル チェーンは、1 つ以上の階層化されたプロトコルとして定義され、ベース プロトコルによって連結され、固定されます。 基本プロトコルには、WSAProtocol_Info 構造体の ChainLen メンバーが BASE_PROTOCOL に設定されており、1 と定義されています。 階層型プロトコルでは、WSAPROTOCOL_INFO構造体の ChainLen メンバーが LAYERED_PROTOCOL に設定され、0 として定義されます。 プロトコル チェーンには、WSAPROTOCOL_INFO 構造体の ChainLen メンバーが 1 より大きい値に設定されています。
lpProtocolInfoList パラメーターには、インストールするプロトコル エントリの一覧が含まれています。 WSCInstallProvider の呼び出し元は、適切なプロトコル エントリを設定する必要があります。 lpProtocolInfoList パラメーターは NULL にすることはできません。
この呼び出しが正常に完了すると、 その後 WSAEnumProtocols または WSCEnumProtocols を呼び出すと、新しく作成されたプロトコル エントリが返されます。 Windows 環境では、WSCInstallProvider が正常に完了した後に WSAStartup を呼び出して作成された Ws_32.dll のインスタンスにのみ、WSAEnumProtocols と WSCEnumProtocols が返されるときに新しいエントリが含まれることに注意してください。
成功すると、 WSCInstallProvider は、 WSAProviderConfigChange を呼び出すことによって、変更の通知を登録したすべての関心のあるアプリケーションにアラートを送信しようとします。
WSCInstallProvider 関数は、Administrators グループのメンバーとしてログオンしているユーザーのみが呼び出すことができます。 Administrators グループのメンバーではないユーザーによって WSCInstallProvider が呼び出された場合、関数呼び出しは失敗し、lpErrno パラメーターでWSANO_RECOVERYが返されます。 Windows Vista または Windows Server 2008 を実行しているコンピューターの場合、ユーザー アカウント制御 (UAC) が原因でこの関数が失敗する可能性もあります。 この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、 requestedExecutionLevel が requireAdministrator に設定されたマニフェスト ファイルでアプリケーションがマークされていない限り、この呼び出しは失敗します。 Windows Vista または Windows Server 2008 上のアプリケーションにこのマニフェスト ファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーは、この関数を成功させるために、組み込みの管理者 (RunAs 管理者) として拡張シェルでアプリケーションを実行する必要があります。
ファイルのインストールまたはサービス プロバイダー固有の構成は、呼び出し元が実行する必要があります。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | ws2spi.h |
| Library | Ws2_32.lib |
| [DLL] | Ws2_32.dll |