BuildSecurityDescriptorA 関数 (aclapi.h)

[アーティクル]
02/23/2024

BuildSecurityDescriptor 関数は、新しいセキュリティ記述子を割り当てて初期化します。この関数は、指定されたセキュリティ情報を既存のセキュリティ記述子の情報とマージすることで、新しいセキュリティ記述子を初期化できます。既存のセキュリティ記述子を指定しない場合、関数は指定されたセキュリティ情報に基づいて新しいセキュリティ記述子を初期化します。

BuildSecurityDescriptor 関数は、自己相対セキュリティ記述子を作成します。自己相対形式により、セキュリティ記述子はストリームに格納するのに適しています。

構文

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

パラメーター

[in, optional] pOwner

新しいセキュリティ記述子の所有者を識別するトラスティ構造体へのポインター。構造体で TRUSTEE_IS_NAME 形式が使用されている場合、 BuildSecurityDescriptor は、指定されたトラスティ名に関連付けられているセキュリティ識別子 (SID) を検索します。

このパラメーターが NULL の場合、関数は pOldSD が指す元のセキュリティ記述子の所有者 SID を使用します。 pOldSD が NULL の場合、または pOldSD の所有者 SID が NULL の場合、所有者 SID は新しいセキュリティ記述子で NULL になります。

[in, optional] pGroup

新しいセキュリティ記述子のプライマリグループ SID を識別するトラスティ構造体へのポインター。構造体で TRUSTEE_IS_NAME フォームが使用されている場合、 BuildSecurityDescriptor は、指定されたトラスティ名に関連付けられている SID を検索します。

このパラメーターが NULL の場合、関数は pOldSD が指す元のセキュリティ記述子のグループ SID を使用します。 pOldSD が NULL の場合、または pOldSD のグループ SID が NULL の場合、新しいセキュリティ記述子のグループ SID は NULL になります。

[in] cCountOfAccessEntries

pListOfAccessEntries 配列内のEXPLICIT_ACCESS構造体の数。

[in, optional] pListOfAccessEntries

新しいセキュリティ記述子の随意アクセス制御リスト (DACL) のアクセス制御情報を記述するEXPLICIT_ACCESS構造体の配列へのポインター。この関数は、配列内の情報を pOldSD の DACL (存在する場合) とマージして、新しい DACL を作成します。 pOldSD が NULL の場合、または pOldSD の DACL が NULL の場合、関数は配列内の情報のみに基づいて新しい DACL を作成します。 EXPLICIT_ACCESS構造体の配列から ACL を作成するための規則の説明については、SetEntriesInAcl 関数を参照してください。

pListOfAccessEntries が NULL の場合、新しいセキュリティ記述子は pOldSD から DACL を取得します。この場合、 pOldSD が NULL の場合、または pOldSD の DACL が NULL の場合、新しい DACL は NULL になります。

[in] cCountOfAuditEntries

pListOfAuditEntries 配列内のEXPLICIT_ACCESS構造体の数。

[in, optional] pListOfAuditEntries

新しいセキュリティ記述子の SACL の監査制御情報を記述する EXPLICIT_ACCESS 構造体の配列へのポインター。この関数は、配列内の情報と pOldSD の SACL (存在する場合) をマージして、新しい SACL を作成します。 pOldSD が NULL の場合、または pOldSD の SACL が NULL の場合、関数は配列内の情報のみに基づいて新しい SACL を作成します。

pListOfAuditEntries が NULL の場合、新しいセキュリティ記述子は pOldSD から SACL を取得します。この場合、 pOldSD が NULL の場合、または pOldSD の SACL が NULL の場合、新しい SACL は NULL になります。

[in, optional] pOldSD

既存の自己相対 SECURITY_DESCRIPTOR 構造とその関連するセキュリティ情報へのポインター。関数は、指定された所有者、グループ、アクセス制御、および監査制御情報をこのセキュリティ記述子の情報とマージすることで、新しいセキュリティ記述子を構築します。このパラメーターは、NULL でもかまいません。

[out] pSizeNewSD

セキュリティ記述子のサイズ (バイト単位) を受け取る変数へのポインター。

[out] pNewSD

新しいセキュリティ記述子へのポインターを受け取る変数へのポインター。関数は、新しいセキュリティ記述子にメモリを割り当てます。返されるバッファーを解放するには、 LocalFree 関数を呼び出す必要があります。

戻り値

関数が成功した場合、関数はERROR_SUCCESSを返します。

関数が失敗した場合、WinError.h で定義されている 0 以外のエラーコードが返されます。

注釈

BuildSecurityDescriptor 関数は、独自のオブジェクトにセキュリティを実装または公開する信頼されたサーバーを対象としています。関数は、信頼されたサーバーが必要とする場合があるため、ストリームへのシリアル化とディスクへの格納に適した自己相対セキュリティ記述子を使用します。

注意

aclapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして BuildSecurityDescriptor を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	aclapi.h
Library	Advapi32.lib
[DLL]	Advapi32.dll