ホーム › Networking.WinSock › WSCGetApplicationCategory

WSCGetApplicationCategory

関数

アプリケーションのLSPカテゴリ許可を取得する。

DLLWS2_32.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// WS2_32.dll
#include <windows.h>

INT WSCGetApplicationCategory(
    LPCWSTR Path,
    DWORD PathLength,
    LPCWSTR Extra,   // optional
    DWORD ExtraLength,
    DWORD* pPermittedLspCategories,
    INT* lpErrno
);

パラメーター

名前	型	方向	説明
Path	LPCWSTR	in	アプリケーションの実行可能イメージへのロードパスを含む Unicode 文字列へのポインター。この文字列は通常のパス解決規則に従い、埋め込みの環境文字列 (%SystemRoot% など) を含めることができます。
PathLength	DWORD	in	Path パラメーターの長さ (文字数)。この長さには終端の NULL は含まれません。
Extra	LPCWSTR	inoptional	Path パラメーターで指定されたアプリケーションを起動する際に使用されるコマンドライン引数を表す Unicode 文字列へのポインター。Extra パラメーターは、一貫したコマンドラインで起動されたアプリケーションの複数の異なるインスタンスを区別するために使用されます。これは、Svchost.exe や Rundll32.exe の異なるインスタンスに対して異なるアプリケーション分類をサポートするためのものです。Path パラメーターのみで十分であり、アプリケーションのインスタンスをさらに区別するためのコマンドライン引数が不要な場合は、Extra パラメーターを NULL に設定してください。
ExtraLength	DWORD	in	Extra パラメーターの長さ (文字数)。この長さには終端の NULL は含まれません。
pPermittedLspCategories	DWORD*	out	このアプリケーションのすべてのインスタンスに対して許可される LSP カテゴリを示す DWORD 値へのポインター。アプリケーションは Path パラメーターと Extra パラメーターの値の組み合わせによって識別されます。
lpErrno	INT*	out	関数が失敗した場合のエラーコードへのポインター。

戻り値の型: INT

公式ドキュメント

アプリケーションに関連付けられた階層化サービスプロバイダー (LSP) のカテゴリを取得します。

戻り値

エラーが発生しなかった場合、WSCGetApplicationCategory は ERROR_SUCCESS (ゼロ) を返します。それ以外の場合は SOCKET_ERROR を返し、lpErrno パラメーターに特定のエラーコードが返されます。

エラーコード	意味
WSAEFAULT	引数のうち 1 つ以上が、ユーザーアドレス空間の有効な部分にありません。
WSAEINVAL	引数のうち 1 つ以上が無効です。
WSASERVICE_NOT_FOUND	Path パラメーターと Extra パラメーターに基づいてサービスが見つかりませんでした。クエリ対象のアプリケーションがレジストリに存在しない場合にも、このエラーが返されることがあります。この場合、エラーはアプリケーションが現在分類されていないことを示します。
WSANO_RECOVERY	回復不能なエラーが発生しました。このエラーは、次を含むいくつかの条件下で返されます。すなわち、ユーザーに Winsock レジストリへのアクセスに必要な管理者権限がない場合、または Winsock カタログエントリやアプリケーション ID エントリを開く際に障害が発生した場合です。

解説(Remarks)

WSCGetApplicationCategory は、アプリケーションインスタンスに関連付けられた LSP カテゴリフラグを取得するために使用されます。アプリケーションは、自身のコンテキスト内でどの LSP の動作が許容されるかを判断できます。したがって、許可される LSP カテゴリを指定することで、アプリケーションは許容可能な動作を実装する階層化サービスプロバイダーのみをロードするように許可できます。

Extra パラメーターは、同一の実行可能ファイル内でホストされるアプリケーションまたはサービスの異なるインスタンスを区別するためにコマンドラインを使用する場合に必要です。各インスタンスは異なるアプリケーション分類の要件を持つ可能性があります。Svchost.exe と Rundll32.exe は、異なるプロセスインスタンスを区別するためにコマンドラインが必要となる 2 つの例です。SvcHost.exe の場合、-k <svcinstance> スイッチがプロセスインスタンスを定義します。

サービスの場合、サービス名を使用するだけでは不十分です。Winsock カタログは特定のプロセスに対してグローバルであり、1 つのプロセスが複数のサービスをホストする可能性があるためです。

Windows ソケットは、最初の WSAStartup 呼び出し時にアプリケーションの ID を判定し、許可される LSP カテゴリを取得します。これがアプリケーションインスタンスの期間を通じて適用される、許可される LSP カテゴリのセットとなります。特定のアプリケーション ID に対する許可される LSP カテゴリの後続の変更は、アプリケーションの次のインスタンスまで反映されません。許可される LSP カテゴリは、アプリケーションインスタンスの存続期間中は変更できません。

Winsock 2 は階層化プロトコルに対応しています。階層化プロトコルとは、より高レベルの通信機能のみを実装し、リモートエンドポイントとの実際のデータ交換については下位のトランスポートスタックに依存するプロトコルです。階層化プロトコルまたは階層化サービスプロバイダーの例としては、認証を実行し相互に合意した暗号化方式を確立するために、接続確立プロセスにプロトコルを追加するセキュリティ層が挙げられます。このようなセキュリティプロトコルは、一般に TCP や SPX などの下位の信頼性のあるトランスポートプロトコルのサービスを必要とします。ベースプロトコルという用語は、リモートエンドポイントとのデータ通信を実行できる TCP や SPX などのプロトコルを指します。階層化プロトコルという用語は、単独では成立しないプロトコルを表すために使用されます。

LSP の初期化中、LSP は多数の Winsock SPI 関数へのポインターを提供する必要があります。これらの関数は、LSP の直上の層 (別の LSP または Ws2_32.DLL) による通常の処理中に呼び出されます。

インストール可能ファイルシステム (IFS) を実装する LSP は、自身が実装する関数へのポインターを提供するか、LSP の直下の層が提供するポインターをそのまま返すかを選択的に選ぶことができます。非 IFS LSP は、独自のハンドルを提供するため、すべての Winsock SPI 関数を実装する必要があります。これは、各 SPI が、LSP が作成したすべてのソケットハンドルを下位プロバイダー (別の LSP またはベースプロトコル) のソケットハンドルにマップすることを要求するためです。

ただし、すべての LSP は、Winsock SPI 関数のサブセットに対してのみ追加処理を行うことで、その固有の作業を実行します。

LSP が実装する SPI 関数のサブセットと、それらの各関数に対して実行される追加処理の性質に基づいて、LSP カテゴリを定義することが可能です。

LSP を分類し、さらに Winsock ソケットを使用するアプリケーションを分類することで、実行時に特定のプロセスに LSP を関与させるべきかどうかを選択的に判断できるようになります。

Windows Vista 以降では、LSP は Windows ソケットの呼び出しおよびデータとどのように相互作用するかに基づいて分類できます。LSP カテゴリは、Winsock SPI 関数のサブセットに対する識別可能な動作のグループです。たとえば、HTTP コンテンツフィルターはデータインスペクター (LSP_INSPECTOR カテゴリ) として分類されます。LSP_INSPECTOR カテゴリは、データ転送 SPI 関数のパラメーターを検査します (ただし変更はしません)。アプリケーションは LSP のカテゴリをクエリし、LSP カテゴリとアプリケーションの許可される LSP カテゴリのセットに基づいて、その LSP をロードしないことを選択できます。

次の表は、LSP を分類できるカテゴリの一覧です。

LSP カテゴリ	説明
LSP_CRYPTO_COMPRESS	LSP は暗号化またはデータ圧縮プロバイダーです。
LSP_FIREWALL	LSP はファイアウォールプロバイダーです。
LSP_LOCAL_CACHE	LSP はローカルキャッシュプロバイダーです。
LSP_INBOUND_MODIFY	LSP は受信データを変更します。
LSP_INSPECTOR	LSP はデータを検査またはフィルタリングします。
LSP_OUTBOUND_MODIFY	LSP は送信データを変更します。
LSP_PROXY	LSP はプロキシとして動作し、パケットをリダイレクトします。
LSP_REDIRECTOR	LSP はネットワークリダイレクターです。
LSP_SYSTEM	LSP はサービスおよびシステムプロセスでの使用が許容されます。

1 つの LSP は複数のカテゴリに属することができます。たとえば、ファイアウォール/セキュリティ LSP は、インスペクター (LSP_INSPECTOR) カテゴリとファイアウォール (LSP_FIREWALL) カテゴリの両方に属することができます。

LSP にカテゴリが設定されていない場合、その LSP は「その他すべて (All Other)」カテゴリに属するとみなされます。この LSP カテゴリは、サービスやシステムプロセス (たとえば lsass、winlogon、および多くの svchost プロセス) ではロードされません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// WS2_32.dll
#include <windows.h>

INT WSCGetApplicationCategory(
    LPCWSTR Path,
    DWORD PathLength,
    LPCWSTR Extra,   // optional
    DWORD ExtraLength,
    DWORD* pPermittedLspCategories,
    INT* lpErrno
);

[DllImport("WS2_32.dll", ExactSpelling = true)]
static extern int WSCGetApplicationCategory(
    [MarshalAs(UnmanagedType.LPWStr)] string Path,   // LPCWSTR
    uint PathLength,   // DWORD
    [MarshalAs(UnmanagedType.LPWStr)] string Extra,   // LPCWSTR optional
    uint ExtraLength,   // DWORD
    out uint pPermittedLspCategories,   // DWORD* out
    out int lpErrno   // INT* out
);

<DllImport("WS2_32.dll", ExactSpelling:=True)>
Public Shared Function WSCGetApplicationCategory(
    <MarshalAs(UnmanagedType.LPWStr)> Path As String,   ' LPCWSTR
    PathLength As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPWStr)> Extra As String,   ' LPCWSTR optional
    ExtraLength As UInteger,   ' DWORD
    <Out> ByRef pPermittedLspCategories As UInteger,   ' DWORD* out
    <Out> ByRef lpErrno As Integer   ' INT* out
) As Integer
End Function

' Path : LPCWSTR
' PathLength : DWORD
' Extra : LPCWSTR optional
' ExtraLength : DWORD
' pPermittedLspCategories : DWORD* out
' lpErrno : INT* out
Declare PtrSafe Function WSCGetApplicationCategory Lib "ws2_32" ( _
    ByVal Path As LongPtr, _
    ByVal PathLength As Long, _
    ByVal Extra As LongPtr, _
    ByVal ExtraLength As Long, _
    ByRef pPermittedLspCategories As Long, _
    ByRef lpErrno As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WSCGetApplicationCategory = ctypes.windll.ws2_32.WSCGetApplicationCategory
WSCGetApplicationCategory.restype = ctypes.c_int
WSCGetApplicationCategory.argtypes = [
    wintypes.LPCWSTR,  # Path : LPCWSTR
    wintypes.DWORD,  # PathLength : DWORD
    wintypes.LPCWSTR,  # Extra : LPCWSTR optional
    wintypes.DWORD,  # ExtraLength : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pPermittedLspCategories : DWORD* out
    ctypes.POINTER(ctypes.c_int),  # lpErrno : INT* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
WSCGetApplicationCategory = Fiddle::Function.new(
  lib['WSCGetApplicationCategory'],
  [
    Fiddle::TYPE_VOIDP,  # Path : LPCWSTR
    -Fiddle::TYPE_INT,  # PathLength : DWORD
    Fiddle::TYPE_VOIDP,  # Extra : LPCWSTR optional
    -Fiddle::TYPE_INT,  # ExtraLength : DWORD
    Fiddle::TYPE_VOIDP,  # pPermittedLspCategories : DWORD* out
    Fiddle::TYPE_VOIDP,  # lpErrno : INT* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ws2_32")]
extern "system" {
    fn WSCGetApplicationCategory(
        Path: *const u16,  // LPCWSTR
        PathLength: u32,  // DWORD
        Extra: *const u16,  // LPCWSTR optional
        ExtraLength: u32,  // DWORD
        pPermittedLspCategories: *mut u32,  // DWORD* out
        lpErrno: *mut i32  // INT* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WS2_32.dll")]
public static extern int WSCGetApplicationCategory([MarshalAs(UnmanagedType.LPWStr)] string Path, uint PathLength, [MarshalAs(UnmanagedType.LPWStr)] string Extra, uint ExtraLength, out uint pPermittedLspCategories, out int lpErrno);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_WSCGetApplicationCategory' -Namespace Win32 -PassThru
# $api::WSCGetApplicationCategory(Path, PathLength, Extra, ExtraLength, pPermittedLspCategories, lpErrno)

#uselib "WS2_32.dll"
#func global WSCGetApplicationCategory "WSCGetApplicationCategory" sptr, sptr, sptr, sptr, sptr, sptr
; WSCGetApplicationCategory Path, PathLength, Extra, ExtraLength, varptr(pPermittedLspCategories), varptr(lpErrno)   ; 戻り値は stat
; Path : LPCWSTR -> "sptr"
; PathLength : DWORD -> "sptr"
; Extra : LPCWSTR optional -> "sptr"
; ExtraLength : DWORD -> "sptr"
; pPermittedLspCategories : DWORD* out -> "sptr"
; lpErrno : INT* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WS2_32.dll"
#cfunc global WSCGetApplicationCategory "WSCGetApplicationCategory" wstr, int, wstr, int, var, var
; res = WSCGetApplicationCategory(Path, PathLength, Extra, ExtraLength, pPermittedLspCategories, lpErrno)
; Path : LPCWSTR -> "wstr"
; PathLength : DWORD -> "int"
; Extra : LPCWSTR optional -> "wstr"
; ExtraLength : DWORD -> "int"
; pPermittedLspCategories : DWORD* out -> "var"
; lpErrno : INT* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WS2_32.dll"
#cfunc global WSCGetApplicationCategory "WSCGetApplicationCategory" wstr, int, wstr, int, sptr, sptr
; res = WSCGetApplicationCategory(Path, PathLength, Extra, ExtraLength, varptr(pPermittedLspCategories), varptr(lpErrno))
; Path : LPCWSTR -> "wstr"
; PathLength : DWORD -> "int"
; Extra : LPCWSTR optional -> "wstr"
; ExtraLength : DWORD -> "int"
; pPermittedLspCategories : DWORD* out -> "sptr"
; lpErrno : INT* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。