WdmlibIoCreateDeviceSecure 函式 (wdmsec.h)

WdmlibIoCreateDeviceSecure 函式 (或 IoCreateDeviceSecure) 會建立具名裝置物件，並套用指定的安全性設定。

語法

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 PDEVICE_OBJECT   *DeviceObject
);

參數

[in] DriverObject

呼叫端之驅動程序物件的指標。 每個驅動程式都會在其 DriverEntry 例程的參數中接收其驅動程式物件的指標。 WDM 函式和篩選驅動程式也會在其 AddDevice 例程中接收驅動程式對象指標。

[in] DeviceExtensionSize

指定要為 裝置物件的裝置延伸模組 配置驅動程式決定的位元元組數目。 裝置擴充功能的內部結構是驅動程式定義的。

[in, optional] DeviceName

選擇性地指向緩衝區，其中包含命名裝置物件的 Null 終止 Unicode 字串。 字串必須是完整路徑名稱。 如果未提供名稱，FILE_AUTOGENERATED_DEVICE_NAME旗標必須存在於 DeviceCharacteristics 參數中。 (若要建立未命名的裝置物件，請使用 IoCreateDevice 例程.)

[in] DeviceType

指定其中一個系統定義的FILE_DEVICE_XXX 常數，指出裝置 (類型，例如FILE_DEVICE_DISK、FILE_DEVICE_KEYBOARD等) ，或新類型裝置的廠商定義值。 如需詳細資訊，請參閱 指定裝置類型。 (因為總線驅動程式可能沒有裝置類型的相關信息，所以可以在 INF AddReg 指示詞中指定 PDO 的裝置類型值。)

[in] DeviceCharacteristics

指定一或多個系統定義的常數 ORed，以提供驅動程式裝置的其他資訊。 如需可能裝置特性的清單，請參閱 DEVICE_OBJECT。 如需如何指定裝置特性的詳細資訊，請參閱 指定裝置特性。 大部分驅動程式都會為此參數指定FILE_DEVICE_SECURE_OPEN。

[in] Exclusive

指定裝置物件是否代表 獨佔裝置。 大部分驅動程式都會將此值設定為 FALSE。 如需詳細資訊，請參閱 指定裝置對象的獨佔存取權。

[in] DefaultSDDLString

指定裝置物件預設安全性設定的字串表示。 除非系統管理員將覆寫放在 DeviceClassGuid 參數所識別登錄區段中的覆寫，否則套用至裝置物件的安全性衍生自此字串。

安全性設定是在安全性描述項定義語言的子集中指定， (SDDL) 。 也會提供一組預先定義的常數 (SDDL_DEVOBJ_ XXX) 。 如需詳細資訊，請參閱 保護裝置物件。

[in, optional] DeviceClassGuid

GUID 的指標，識別登錄區段，其中包含 DefaultSDDLString、 DeviceType、 DeviceCharacteristics 和 Exclusive 參數的可能覆寫。

DeviceObject

接收新建立 DEVICE_OBJECT 結構指標之變數的指標。 DEVICE_OBJECT 結構是從非分頁集區配置。

傳回值

WdmlibIoCreateDeviceSecure 會在成功時傳回STATUS_SUCCESS，或在失敗時傳回適當的 NTSTATUS 錯誤碼。 此函式可能傳回之失敗碼的部分清單包括：

備註

WdmlibIoCreateDeviceSecure 會 建立具名裝置物件、套用指定的安全性設定，並傳回物件的指標。 呼叫端負責在呼叫 IoDeleteDevice不再需要物件時刪除物件。

此例程不是操作系統的一部分。 驅動程式可以透過連結至 Microsoft Windows 2000 和更新版本的 Windows 上的 Wdmsec.lib 來使用例程。 (Wdmsec.lib 連結庫第一次隨附於 Microsoft Windows XP Service Pack 1 [SP1] 和 Windows Server 2003 版本的驅動程序開發工具包 [DDK]，也隨附於 Windows 驅動程式套件 [WDK].)

任何建立具名裝置對象的驅動程式，不保證 INF 檔案所設定的安全性描述符都必須使用 WdmlibIoCreateDeviceSecure。 如需詳細資訊，請參閱 建立裝置物件。 呼叫端負責設定傳回之裝置物件的特定成員。 如需詳細資訊，請參閱 初始化裝置物件 和裝置類型的特定檔。

請小心指定正確參數中的 DeviceType 和 DeviceCharacteristics 值。 這兩個參數都會使用系統定義的FILE_XXX 常數，而某些驅動程式寫入器會錯誤地指定錯誤參數中的值。

呼叫端負責在傳回的裝置物件中設定特定欄位，例如 [ 旗 標] 欄位，以及使用任何驅動程式定義的資訊初始化裝置擴充功能。 如需新裝置物件上所需的其他作業，請參閱 初始化裝置物件 和裝置類型的特定檔。

DeviceClassGuid 參數指定的 GUID 會決定裝置對象的裝置安裝類別。 (如需裝置設定類別的詳細資訊，請參閱 裝置設定類別。) 呼叫端必須提供值，讓系統管理員可以變更裝置 (的安全性設定，以拒絕存取特定使用者) 。 如需詳細資訊，請參閱 在安裝後設定 Device Object Registry 屬性。

非 WDM 驅動程式會指定新的 GUID，現有裝置安裝類別尚未使用。 使用包含在 Microsoft Windows SDK 中的 GuidGen.exe 工具來產生新的 GUID。

處理原始模式可用裝置的 WDM 總線驅動程式可以指定裝置的裝置設定類別，但只有在該類別保證已建立時。 否則，請建立新的 GUID。

磁碟、磁帶、CD-ROM 和 RAM 磁碟的裝置物件會獲得磁碟區參數區塊 (VPB) 初始化，以指出磁碟區從未掛接在裝置上。

如果驅動程式呼叫 WdmlibIoCreateDeviceSecure 傳回錯誤，驅動程式應該釋放它為該裝置配置的任何資源。

規格需求

另請參閱

DEVICE_OBJECT

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDevice

IoCreateSymbolicLink

IoDeleteDevice