ホーム>プログラミング関連>Delphi のソースコード
ダウンロード

NtUtils ライブラリ

NtUtilsは、Delphi での Windows システム プログラミング用のフレームワークで、通常の Winapi/Ntapi ヘッダーよりも優れたエラー処理と言語統合を備えた一連の関数を、頻繁に使用されるコード スニペットとインテリジェントなデータ型と組み合わせて提供します。

専用のリポジトリにサンプル コードがいくつかあります。

依存関係

ライブラリの構造

ライブラリは、合計 3 つのレイヤーからなる階層構造になっています。

  • ヘッダー層は、Windows およびネイティブ API からのデータ型と注釈付き関数プロトタイプを定義します。依存関係はゼロで、コードはほとんど含まれません。このライブラリは自己完結型であり、Delphi に含まれるWinapi ユニットはインポートされないことに注意してください。組み込みのWinapi.*.pasとライブラリNtapi.*.pasヘッダーをプログラム内で混在させることができます。ただし、名前が競合する場合には、名前空間プレフィックスを明示的に指定する必要がある場合があります。
  • NtUtilsレイヤーは、OS API のさまざまなカテゴリに何百ものラッパーを提供することで、ライブラリのほとんどの機能を提供します。これはヘッダー層のみに依存し、 System.SysUtils にも依存しないため、コンパイルされた実行可能ファイルのサイズはほとんど増加しません。
  • NtUiLibレイヤーは、エンドユーザー向けのリフレクティブ データ表現のサポートを追加します。これは、 NtUtils、 System.SysUtils 、 System.Rtti 、およびSystem.Generics.Collectionsに依存します。

したがって、必要なものはすべて、Delphi の最新の無料バージョンにすでに含まれています。おまけに、RTTI (別名リフレクション) なしでコンソール アプリケーションをコンパイルすると、非常に小さな実行可能ファイルが生成されます。詳細については、例を参照してください。

ユニットの自動検出

ライブラリのすべてのファイルをプロジェクトに含めるのは通常冗長であるため、ファイルの自動検出用に Delphi を設定できます。このようにして、 usesセクションでユニットを指定すると、Delphi はそのユニットとその依存関係をプロジェクトに自動的に含めます。 Delphi が検索を実行するフォルダーを設定するには、[プロジェクト] -> [オプション] -> [ビルド] -> [Delphi Compiler] に移動し、次の行を検索パスに追加します。 

 .NtUtilsLibrary
.NtUtilsLibraryHeaders
.NtUtilsLibraryNtUiLib

プロジェクトのフォルダー名または場所が異なる場合は、これらの行をそれに応じて調整する必要があります。

エラー処理

TNtxステータス

ライブラリは、失敗したTNtxStatus値を返すことによって呼び出し元に失敗を示します。 TNtxStatus (NtUtils.pas で定義) は、エラー コード ( NTSTATUS 、 HRESULT 、および Win32 エラーと互換性があります) に加えて、失敗の場所、スタックトレース、および試行された操作の性質に関するメタデータを格納する構造です。オープン呼び出しの予期/要求されたアクセス マスクやクエリ/セット呼び出しの情報クラス値などのその他の詳細。 TNtxStatusが成功したかどうかを確認するには、そのIsSuccessメソッドを使用します。基になるエラー コードにアクセスまたは設定するには (タイプと呼び出し元の設定に応じて)、 Status 、 HResult 、 HResultAllowFalse 、 Win32Error 、 Win32ErrorOrSuccess 、 IsHResult 、 IsWin32などのプロパティを使用します。

例外

例外を使用したい場合は、指定されたTNtxStatusに対していつでもRaiseOnError()を呼び出すことができます。 System.SysUtilsをインポートせずに例外を使用したい場合を除き (これは可能です)、専用のENtError例外クラス (組み込みのEOSErrorから派生) をもたらす NtUiLib.Exceptions を含めることをお勧めします。

エラーの表現

NtUiLib.Errors は、 TNtxStatus値を文字列として表現するための 4 つのメソッドをアタッチします。たとえば、値0xC0000061のエラーがトークンのセッション ID を変更しようとして発生した場合、これらのメソッドは次の情報を返します。

方法返された文字列
Name STATUS_PRIVILEGE_NOT_HELD
Description A required privilege is not held by the client
Summary Privilege Not Held
ToString NtSetInformationToken returned STATUS_PRIVILEGE_NOT_HELD

さらに進んで、ユーザーにわかりやすいメッセージ ボックスを表示したい場合は、 NtUiLib.Errors.Dialog がShowNtxStatus()を提供します。さらに、NtUiLib.Exceptions.Dialog を含めると、必要なリフレクション サポートが提供され、ダイアログがさらに充実します。以下にその例を示します。

例外

スタック トレースとデバッグ シンボル

TNtxStatusスタック トレースのキャプチャをサポートしています (デフォルトでは無効)。これを有効にするには、 NtUtils.CaptureStackTraces True に設定します。意味のある方法でスタック トレースを表示するには、実行可能ファイルのデバッグ シンボルの生成を構成する必要があることに注意してください。残念ながら、Delphi は.mapファイル ([プロジェクト] -> [オプション] -> [ビルド] -> [Delphi コンパイラ] -> [リンク] -> [マップ ファイル] で設定) しか出力できませんが、これでは一般に十分ではありません。シンボル API が理解できるように、それらを.dbgファイルに変換するには、サードパーティのmap2dbgツールが必要です。 .dbgファイルで十分かもしれませんが、 cv2pdbを介して最新の.pdbに変換してさらに処理することをお勧めします。

デバッグ シンボルを自動的に生成するには、次のビルド後のイベントをプロジェクトに追加します。 

 map2dbg.exe $(OUTPUTPATH)
cv2pdb64.exe -n -s. -p$(OUTPUTNAME).pdb $(OUTPUTPATH)

自動ライフタイム管理

メモリ

Delphi にはガベージ コレクターが含まれていないため、すぐに使用できるのはレコード、文字列、動的配列、インターフェイスなどの少数の型だけです。一方、クラスとポインタは明示的なクリーンアップを必要とし、(安全な形式では) try-finallyブロックを使用する必要があるため、プログラムが大幅に複雑になります。この問題に対処するために、ライブラリには、DelphiUtils.AutoObjects に実装された、メモリおよびその他のリソースの自動有効期間管理機能が含まれています。このモジュールの型を使用することで、参照をカウントし、関数エピローグでオブジェクトを自動的に解放するための例外安全なコードを自動的に生成するようにコンパイラーに指示します。このモジュールは、クリーンアップが必要な可能性のあるさまざまなタイプのリソース用のいくつかのインターフェイスを定義します。次の階層が導入されます。 

グラフLR。
  サブグラフ ID1[任意のリソース]
    IAutoReleaseable
  終わり
  サブグラフ ID2[A THandle 値]
    Iハンドル
  終わり
  サブグラフ id3[Delphi クラス]
    IAutoObject[IAutoObject&ltT&gt]
  終わり
  サブグラフ ID4[ポインタ]
    IAutoPointer[IAutoPointer&ltP&gt]
  終わり
  サブグラフ ID5[メモリ領域]
    Iメモリ[IMメモリ&ltP&gt]
  終わり
  IAutoReleasable --> IHandle;
  IAutoReleasable --> IAutoObject;
  IAutoReleasable --> IAutoPointer;
  IAutoPointer --> IMemory;
読み込み中

IAutoReleasable 、(自動) クリーンアップのアクションを実行する必要があるすべてのリソースの基本タイプです。 IHandle THandle 値によって定義されたリソースのラッパーとして機能します。 IAutoObject<T>は、Delphi クラス (TObject から派生したもの) を自動的に解放するための汎用ラッパーです。 IAutoPointer<P>動的に割り当てられたポインターを解放するための同様のインターフェイスを定義します (領域のサイズは無関係です)。 IMemory<P> 、マネージドおよびアンマネージドのボックス化レコードなど、型付きポインターを介してアクセスできる既知のサイズのメモリ領域のラッパーを提供します。

この機能を使用するためのレシピは次のとおりです。

  1. いずれかのインターフェイスを使用して、オブジェクトに対する (潜在的に共有された) 所有権を維持する必要があるすべての変数を定義します。

    • クラスの場合は、 IAutoObject<TMyClass>を使用します。
    • ポインターを介してアクセスできる動的メモリの場合は、 IMemory<Pointer>とも呼ばれるIMemoryを使用します。
    • (管理された) ボックス化されたレコードの場合は、 IMemory<PMyRecord>を使用します。

  2. 自動オブジェクトの割り当て、コピー、キャプチャにはAutoヘルパーを使用します。

    • Auto.From<TMyClass>(...)を使用して、TObject から派生したクラス オブジェクトの所有権を取得します。
    • アンマネージ構造にはAuto.AllocateDynamic(...)およびAuto.CopyDynamic(...)を使用します。
    • マネージド ボックス レコードをヒープに保存するには、 Auto.Allocate<TMyRecord>(...)とAuto.Copy<TMyRecord>(...)を使用します。

  3. 必要に応じて、型情報の重複を回避し、構文を短縮できる左側キャストを使用します。

たとえば、従来のアプローチを使用して TStringList を操作するための安全なコードを次に示します。 

 var
  x: TStringList;
begin
  x := TStringList.Create;
  try
    x.Add( ' Hi there ' );
    x.SaveToFile( ' test.txt ' );
  finally
    x.Free;
  end ;
end ;

ご想像のとおり、この関数でより多くのオブジェクトを使用すると、関数の複雑さが非線形的に大幅に増加します。あるいは、 IAutoObject を使用してより適切にスケールアップする同等のコードを次に示します。 

 uses
  DelphiUtils.AutoObjects;
var
  x: IAutoObject<TStringList>;
begin
  x := Auto.From(TStringList.Create);
  x.Self.Add( ' Hi there ' );
  x.Self.SaveToFile( ' test.txt ' );
end ;

コンパイラは必要なクリーンアップ コードを関数エピローグに出力し、例外が発生した場合でも確実に実行されるようにします。さらに、このアプローチでは、基になるオブジェクトに対する共有所有権を維持できるため、現在の関数よりも存続できる参照を保存できます (たとえば、匿名関数でキャプチャして返すことによって)。この機能が不要で、関数の終了時にオブジェクトを解放する単一の所有者を維持したい場合は、構文をさらに簡素化できます。 

 uses
  NtUtils;
var
  x: TStringList;
begin
  x := Auto.From(TStringList.Create).Self;
  x.Add( ' Hi there ' );
  x.SaveToFile( ' test.txt ' );
end ;

このコードはまだ最初のコードと同等です。内部的には、インターフェイスを格納する隠しローカル変数を作成し、後でオブジェクトを解放します。

動的メモリ割り当てを操作する場合、次のように左側のキャストを使用すると便利です。 

 var
  x: IMemory<PByteArray>;
begin
  IMemory(x) := Auto.AllocateDynamic( 100 );
  x.Data[ 15 ] := 20 ;
end ;

また、値型を参照型であるかのように共有できる、ボックス化された (ヒープ上に割り当てられた) マネージド レコードを作成することもできます。 Delphi 文字列や動的配列などのマネージド フィールドも含めることができることに注意してください。コンパイラは、それらを自動的に解放するためのコードを生成します。 

 type
  TMyRecord = record
    MyInteger: Integer;
    MyArray: TArray<Integer>;
  end ;                   
  PMyRecord = ^TMyRecord;

var
  x: IMemory<PMyRecord>;
begin
  IMemory(x) := Auto.Allocate<TMyRecord>;
  x.Data.MyInteger := 42 ;
  x.Data.MyArray := [ 1 , 2 , 3 ];
end ;

Delphi は参照カウントを使用するため、2 つのオブジェクトに循環依存関係がある場合、メモリ リークが発生する可能性があります。弱い参照を使用すると、この問題の発生を防ぐことができます。このような参照は生存期間の延長にはカウントされず、対象のオブジェクトが破棄されると、それらを格納する変数は自動的にnilになります。使用する前に、弱い参照を強い参照にアップグレードする必要があります。詳細については、DelphiUtils.AutoObjects のWeak<I>を参照してください。

一般的に使用される可変サイズのポインター型に使用できるエイリアスがいくつかあります。いくつかの例を次に示します。

  • IAutoPointer = IAutoPointer<ポインタ>;
  • IMemory = IMemory<ポインタ>;
  • ISid = IAutoPointer<PSid>;
  • IAcl = IAutoPointer<PAcl>;
  • ISecurityDescriptor = IAutoPointer<PSecurityDescriptor>;
  • 等

ハンドル

ハンドルはIHandleタイプ (DelphiUtils.AutoObjects を参照) を使用します。これは上記のロジックに従うため、明示的に閉じる必要はありません。 IHandle のエイリアス (IScmHandle、ISamHandle、ILsaHandle など) もいくつかあります。これらはコードを読みやすくするためにのみ使用できます。

ハンドル値の所有権を IHandle に取得する必要がある場合は、このインターフェイスを実装し、基になるリソースを解放する方法を知っているクラスが必要です。たとえば、 NtUtils.Objects は、 NtClose呼び出しを必要とするカーネル オブジェクトのクラスを定義します。また、ヘルパー メソッドをAutoにアタッチし、 Auto.CaptureHandle(...)を介して値によってカーネル ハンドルをキャプチャできるようにします。所有しない IHandle を作成するには、 Auto.RefHandle(...)を使用します。

命名規則

レコード、クラス、および列挙の名前はTで始まり、CamelCase を使用します (例: TTokenStatistics )。レコードまたは他の値型へのポインターはPで始まります (例: PTokenStatistics )。インターフェイスの名前はIで始まります (例: ISid )。定数には ALL_CAPITALS が使用されます。既知の正式名 (Windows SDK で定義された型など) を持つヘッダー レイヤーのすべての定義は、この名前を指定するSDKName属性でマークされます。

ほとんどの関数は、末尾にxが付くサブシステムのプレフィックス (Ntx、Ldrx、Lsax、Samx、Scmx、Wsx、Usrx など) + アクション + ターゲット/オブジェクト タイプなどの名前規則を使用します。関数名にも CamelCase が使用されます。

OSのバージョン

このライブラリは、Windows 7 以降の 32 ビット エディションと 64 ビット エディションの両方を対象としています。ただし、一部の機能は、最新の 64 ビット バージョンの Windows 11 でのみ利用できる場合があります。例としては、AppContainers や ntdll syscall アンフックなどがあります。ライブラリ関数が Windows 7 に存在しない可能性のある API に依存している場合、遅延インポートを使用し、実行時に可用性をチェックします。

リフレクション (別名 RTTI)

Delphi には、ライブラリがNtUiLib層内で利用する豊富なリフレクション システムが付属しています。ヘッダーレイヤーで定義されている型のほとんどは、これを実現するためにカスタム属性 (DelphiApi.Reflection を参照) で装飾されています。これらの装飾は、ライブラリが実行時に複雑なデータ型 (PEB、TEB、USER_SHARED_DATA など) を正確に表現し、1 行のコードで驚くべきレポートを生成するのに役立つ有用なメタデータを生成します。

NtUiLib.Reflection.Types を使用した Ntapi.NtSecApi からのTSecurityLogonSessionDataの表現例を次に示します。

RTTIベースのレポート

ユニット概要

ここでは、さまざまなモジュールの目的の概要を説明します。

基本ライブラリモジュール

サポートユニット説明
DelphiUtils.AutoObjectsリソースの有効期間の自動管理
DelphiUtils.AutoEventsマルチサブスクライバーの匿名イベント
DelphiUtils.Arrays TArray ヘルパー
DelphiUtils.Lists遺伝的二重リンクリストプリミティブ
DelphiUtils.Async非同期 I/O サポートの定義
DelphiUtils.ExternalImport Delphi 外部キーワード IAT ヘルパー
DelphiUtils.RangeChecks範囲チェックヘルパー
NtUtils一般的なライブラリの種類
NtUtils.SysUtils文字列操作
NtUtils.Errorsエラーコード変換
NtUiLib.エラーエラーコード名の検索
NtUiLib.Exceptions SysUtils 例外の統合
DelphiUiLib.Strings文字列の整形
DelphiUiLib.Reflection基本RTTIサポート
DelphiUiLib.Reflection.Numeric数値型の RTTI 表現
DelphiUiLib.Reflection.RecordsレコードタイプのRTTI表現
DelphiUiLib.Reflection.Strings RTTI による文字列の整形
NtUiLib.Reflection.Types一般的な型の RTTI 表現
NtUiLib.Consoleコンソール I/O ヘルパー
NtUiLib.TaskDialog TaskDialogベースのGUI
NtUiLib.エラー.ダイアログGUIエラーダイアログ
NtUiLib.Exceptions.ダイアログGUI例外ダイアログ

システム API ラッパー

本体説明
NtUtils.ActCtxアクティベーションコンテキスト
NtUtils.AntiHookingアンフックおよび直接システムコール
NtUtils.Com COM、IDispatch、WinRT
NtUtils.Csr CSRSS/SxS登録
NtUtils.DbgHelp DbgHelp およびデバッグ シンボル
NtUtils.Debugオブジェクトのデバッグ
NtUtils.Dism DISM API
NtUtils.Environment環境変数
NtUtils.Environment.Userユーザー環境変数
NtUtils.Environment.Remote他のプロセスの環境変数
NtUtils.Files Win32/NT ファイル名
NtUtils.Files.Openファイルとパイプを開く/作成する
NtUtils.Files.Operationsファイル操作
NtUtils.Files.Directoriesファイルディレクトリの列挙
NtUtils.Files.FltMgrフィルターマネージャーAPI
NtUtils.Files.Mup複数の UNC プロバイダー
NtUtils.Files. Volumesボリューム操作
NtUtils.Files.Control FSCTLの操作
NtUtils.ImageHlp PE 解析
NtUtils.ImageHlp.Syscallsシステムコール番号の取得
NtUtils.ImageHlp.DbgHelp DbgHelp を使用しないパブリック シンボル
NtUtils.ジョブジョブオブジェクトとサイロ
NtUtils.Jobs.Remoteクロスプロセスジョブオブジェクトクエリ
NtUtils.Ldr LDR ルーチンと解析
NtUtils.Lsa LSA ポリシー
NtUtils.Lsa.Audit監査ポリシー
NtUtils.Lsa.Sid SID ルックアップ
NtUtils.Lsa.Logonログオンセッション
NtUtils.マニフェストFusion/SxS マニフェスト ビルダー
NtUtils.Memoryメモリ操作
NtUtils.MiniDumpsミニダンプ形式の解析
NtUtils.Objectsカーネルオブジェクトとハンドル
NtUtils.Objects.スナップショットスナップショットの処理
NtUtils.Objects.Namespace NT オブジェクト名前空間
NtUtils.Objects.Remoteクロスプロセスハンドル操作
NtUtils.Objects.Compareハンドル比較
NtUtils.Packagesアプリパッケージとパッケージファミリー
NtUtils.Packages.SRCache状態リポジトリ キャッシュ
NtUtils.Packages.WinRT WinRT ベースのパッケージ情報
NtUtils.Power電源関連機能
NtUtils.プロセスプロセスオブジェクト
NtUtils.プロセス.情報処理クエリ/設定情報
NtUtils.Processes.Info.Remoteコードインジェクションによるクエリ/設定の処理
NtUtils.Processes.Modulesクロスプロセス LDR 列挙
NtUtils.Processes.Snapshotsプロセスの列挙
NtUtils.Processes.Create共通のプロセス作成定義
NtUtils.Processes.Create.Win32 Win32プロセスの作成方法
NtUtils.Processes.Create.Shellシェルプロセスの作成方法
NtUtils.Processes.Create.Native NtCreateUserProcess など
NtUtils.Processes.Create.Manual NtCreateProcessEx
NtUtils.Processes.Create.Com COMベースのプロセス作成
NtUtils.Processes.Create.Csr SbApiPortによるプロセス作成
NtUtils.Processes.Create.Packageアプリのアクティベーション
NtUtils.Processes.Create.Remoteコードインジェクションによるプロセス作成
NtUtils.Processes.Create.Cloneプロセスのクローン作成
NtUtils.プロファイルユーザーとAppContainerのプロファイル
NtUtils.Registryレジストリキー
NtUtils.Registry.Offlineオフラインでのハイチ操作
NtUtils.Registry.VRegサイロベースのレジストリ仮想化
NtUtils.Sam SAMデータベース
NtUtils.セクションセクション/メモリ投影オブジェクト
NtUtils.セキュリティセキュリティ記述子
NtUtils.Security.Acl ACL と ACE
NtUtils.Security.Sid SID
NtUtils.Security.AppContainer AppContainer と機能の SID
NtUtils.Shellcodeコードインジェクション
NtUtils.Shellcode.Dll DLLインジェクション
NtUtils.Shellcode.Exe EXEインジェクション
NtUtils.Svc SCMサービス
NtUtils.Svc.SingleTaskSvcサービスの実装
NtUtils.同期同期プリミティブ
NtUtils.Systemシステム情報
NtUtils.TaskSchedulerタスクスケジューラ
NtUtils.Threadsスレッドオブジェクト
NtUtils.Tokens.情報スレッドのクエリ/設定情報
NtUtils.Threads.Workerスレッド ワーカー (スレッド プール)
NtUtils.トークントークンオブジェクト
NtUtils.Tokens.Impersonateトークンのなりすまし
NtUtils.Tokens.Logonユーザーおよび S4U ログオン
NtUtils.Tokens.AppModelトークン AppModel ポリシー
NtUtils.Transactionsトランザクション (TmTx) オブジェクト
NtUtils.Transactions.Remoteプロセスをトランザクションに強制する
NtUtils.UserManagerユーザー マネージャー サービス (Umgr) API
NtUtils.Wim Windows イメージング (*.wim) API
NtUtils.WinSaferより安全な API
NtUtils.WinStationターミナルサーバーAPI
NtUtils.WinUser User32/GUI API
NtUtils.WinUser.WindowAffinityウィンドウアフィニティの変更
NtUtils.WinUser.WinstaLockウィンドウステーションのロックとロック解除
NtUtils.XmlLite XmlLite による XML の解析と作成
NtUiLib.AutoCompletion編集コントロールのオートコンプリート
NtUiLib.AutoCompletion.Namespace NT オブジェクト名前空間の自動補完
NtUiLib.AutoCompletion.Sid SID の自動補完
NtUiLib.AutoCompletion.Sid.Common単純な SID 名のプロバイダー/レコグナイザー
NtUiLib.AutoCompletion.Sid.AppContainer AppContainer およびパッケージ SID プロバイダー/レコグナイザー
NtUiLib.AutoCompletion.Sid.Capabilities機能 SID プロバイダー/レコグナイザー
NtUiLib.WinCred認証情報ダイアログ
拡大する
追加情報
関連アプリ
おすすめ
関連情報 すべて