Win32 API 日本語リファレンス
ホームDevices.Enumeration.Pnp › SW_DEVICE_CREATE_INFO

SW_DEVICE_CREATE_INFO

構造体
サイズx64: 72 バイト / x86: 36 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
cbSizeDWORD4+0+0この構造体のサイズ (バイト単位)。バージョンを示すフィールドとして使用します。sizeof(SW_DEVICE_CREATE_INFO) で初期化してください。
pszInstanceIdLPWSTR8/4+8+4デバイスインスタンス ID のうち インスタンス ID の部分を表す文字列です。この値は IRP_MN_QUERY_IDBusQueryInstanceID に使用されます。すべてのソフトウェアデバイスは "UniqueId" デバイスと見なされるため、この文字列はこのソフトウェアデバイス列挙子上のすべてのデバイスにおいて一意の名前でなければなりません。
pszzHardwareIdsLPWSTR8/4+16+8ソフトウェアデバイスの ハードウェア ID を表す文字列のリストです。この値は IRP_MN_QUERY_IDBusQueryHardwareIDs に使用されます。クライアントがこのデバイスにドライバーパッケージがインストールされることを想定している場合は、ハードウェア ID を指定してください。
pszzCompatibleIdsLPWSTR8/4+24+12ソフトウェアデバイスの 互換 ID を表す文字列のリストです。この値は IRP_MN_QUERY_IDBusQueryCompatibleIDs に使用されます。クライアントがこのデバイスにクラスドライバーパッケージがインストールされることを想定している場合は、そのクラスドライバーパッケージに一致する互換 ID を指定します。ドライバーパッケージが不要な場合でも、ソフトウェアデバイスの種類を分類するために互換 ID を指定することをお勧めします。このメンバーで指定した互換 ID に加えて、最も限定的でない互換 ID として SWD\Generic および場合によっては SWD\GenericRaw が常に追加されます。
pContainerIdGUID*8/4+32+16ソフトウェアデバイスの基本コンテナー ID を制御するために使用する値です。この値は IRP_MN_QUERY_IDBusQueryContainerIDs に使用されます。一般的な状況では、このメンバーを NULL に設定し、SWDeviceCapabilitiesRemovable フラグを使用して、デバイスが親のコンテナー ID を継承するか、PnP が新しいランダムなコンテナー ID を割り当てるかを制御することをお勧めします。それがデバイスのコンテナー ID の割り当てにどのように影響するかについて詳しくは、取り外し可能デバイス機能の概要 を参照してください。クライアントがコンテナー ID を明示的に制御する必要がある場合は、このメンバーが指す変数に GUID を指定します。一般に、コンテナー ID に NULL_GUID を指定すべきではありません。コンテナー ID と NULL_GUID が持つ特別な意味について詳しくは、コンテナー ID の概要 を参照してください。
CapabilityFlagsDWORD4+40+20

SW_DEVICE_CAPABILITIES の値をビット単位の OR 演算で組み合わせた値です。組み合わせた結果の値によって、ソフトウェアデバイスの機能を指定します。ソフトウェアデバイスの作成時に指定できる機能は、バスドライバーが DEVICE_CAPABILTIES 構造体で指定できる機能のサブセットです。ソフトウェアのみのデバイスに対して変更を許可することが妥当な機能だけがサポートされます。それ以外の機能には適切な既定値が設定されます。指定できる値は次のとおりです。

Value Meaning
SWDeviceCapabilitiesNone
0x00000000
機能が何も指定されていません。
SWDeviceCapabilitiesRemovable
0x00000001
このビットは、デバイスが親から取り外し可能であることを指定します。このフラグを設定することは、バスドライバーが PDO に対して DEVICE_CAPABILTIES 構造体の Removable メンバーを設定することと同等です。
SWDeviceCapabilitiesSilentInstall
0x00000002
このビットは、インストール中に通常表示される UI を抑制します。このフラグを設定することは、バスドライバーが PDO に対して DEVICE_CAPABILTIES 構造体の SilentInstall メンバーを設定することと同等です。
SWDeviceCapabilitiesNoDisplayInUI
0x00000004
このビットは、一部の UI にデバイスが表示されないようにします。このフラグを設定することは、バスドライバーが PDO に対して DEVICE_CAPABILTIES 構造体の NoDisplayInUI メンバーを設定することと同等です。
SWDeviceCapabilitiesDriverRequired
0x00000008
デバイスにドライバーを読み込ませたい場合で、かつそのドライバーがクライアントの機能を正しく動作させるために必須である場合に、このビットを指定します。

このビットを指定する場合は、pszzHardwareIds または pszzCompatibleIds の少なくとも一方を設定する必要があります。

このビットを指定してもドライバーが見つからない場合、デバイスに問題があることを示すために デバイス マネージャー でそのデバイスに黄色の感嘆符が表示され、トラブルシューティング ツールも問題のあるデバイスとしてフラグを立てます。このビットを設定することは、バスドライバーが PDO に対して DEVICE_CAPABILTIES 構造体の RawDeviceOK メンバーを設定しないことと同等です。

このビットを指定した場合、デバイスのインターフェイスの作成はドライバーが担当するため、そのデバイスに対して SwDeviceInterfaceRegister を呼び出すことはできません。

pszDeviceDescriptionLPWSTR8/4+48+24

UI にデバイス名として表示されるテキストを含む文字列です。この値は IRP_MN_QUERY_DEVICE_TEXTDeviceTextDescription に使用されます。

Note

INF がデバイスに一致した場合、この名前を保持するための対処を行わない限り、INF の名前がこの名前を上書きします。

この文字列には、ローカライズ可能なリソースへの参照を指定することをお勧めします。リソースを参照する構文については、DEVPROP_TYPE_STRING_INDIRECT を参照してください。

pszDeviceLocationLPWSTR8/4+56+28

UI にデバイスの場所として表示されるテキストを含む文字列です。この値は IRP_MN_QUERY_DEVICE_TEXTDeviceTextLocationInformation に使用されます。

Note 場所を指定することはまれです。
pSecurityDescriptorSECURITY_DESCRIPTOR*8/4+64+32ソフトウェアデバイスに関連付けられたセキュリティ情報を含む SECURITY_DESCRIPTOR 構造体へのポインターです。このメンバーが NULL の場合、I/O マネージャー がデバイスに既定のセキュリティ記述子を割り当てます。カスタムのセキュリティ記述子が必要な場合は、自己相対形式のセキュリティ記述子を指定してください。

公式ドキュメント

PnP がソフトウェアデバイスを作成するために使用する情報を記述します。

解説(Remarks)

この情報は作成時にのみ指定できます。作成後に Software Device API を呼び出して、たとえばプロパティを設定するなどしてこの情報を変更することはできません。

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

各言語での定義

#include <windows.h>

// SW_DEVICE_CREATE_INFO  (x64 72 / x86 36 バイト)
typedef struct SW_DEVICE_CREATE_INFO {
    DWORD cbSize;
    LPWSTR pszInstanceId;
    LPWSTR pszzHardwareIds;
    LPWSTR pszzCompatibleIds;
    GUID* pContainerId;
    DWORD CapabilityFlags;
    LPWSTR pszDeviceDescription;
    LPWSTR pszDeviceLocation;
    SECURITY_DESCRIPTOR* pSecurityDescriptor;
} SW_DEVICE_CREATE_INFO;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct SW_DEVICE_CREATE_INFO
{
    public uint cbSize;
    public IntPtr pszInstanceId;
    public IntPtr pszzHardwareIds;
    public IntPtr pszzCompatibleIds;
    public IntPtr pContainerId;
    public uint CapabilityFlags;
    public IntPtr pszDeviceDescription;
    public IntPtr pszDeviceLocation;
    public IntPtr pSecurityDescriptor;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure SW_DEVICE_CREATE_INFO
    Public cbSize As UInteger
    Public pszInstanceId As IntPtr
    Public pszzHardwareIds As IntPtr
    Public pszzCompatibleIds As IntPtr
    Public pContainerId As IntPtr
    Public CapabilityFlags As UInteger
    Public pszDeviceDescription As IntPtr
    Public pszDeviceLocation As IntPtr
    Public pSecurityDescriptor As IntPtr
End Structure
import ctypes
from ctypes import wintypes

class SW_DEVICE_CREATE_INFO(ctypes.Structure):
    _fields_ = [
        ("cbSize", wintypes.DWORD),
        ("pszInstanceId", ctypes.c_void_p),
        ("pszzHardwareIds", ctypes.c_void_p),
        ("pszzCompatibleIds", ctypes.c_void_p),
        ("pContainerId", ctypes.c_void_p),
        ("CapabilityFlags", wintypes.DWORD),
        ("pszDeviceDescription", ctypes.c_void_p),
        ("pszDeviceLocation", ctypes.c_void_p),
        ("pSecurityDescriptor", ctypes.c_void_p),
    ]
#[repr(C)]
pub struct SW_DEVICE_CREATE_INFO {
    pub cbSize: u32,
    pub pszInstanceId: *mut core::ffi::c_void,
    pub pszzHardwareIds: *mut core::ffi::c_void,
    pub pszzCompatibleIds: *mut core::ffi::c_void,
    pub pContainerId: *mut core::ffi::c_void,
    pub CapabilityFlags: u32,
    pub pszDeviceDescription: *mut core::ffi::c_void,
    pub pszDeviceLocation: *mut core::ffi::c_void,
    pub pSecurityDescriptor: *mut core::ffi::c_void,
}
import "golang.org/x/sys/windows"

type SW_DEVICE_CREATE_INFO struct {
	cbSize uint32
	pszInstanceId uintptr
	pszzHardwareIds uintptr
	pszzCompatibleIds uintptr
	pContainerId uintptr
	CapabilityFlags uint32
	pszDeviceDescription uintptr
	pszDeviceLocation uintptr
	pSecurityDescriptor uintptr
}
type
  SW_DEVICE_CREATE_INFO = record
    cbSize: DWORD;
    pszInstanceId: Pointer;
    pszzHardwareIds: Pointer;
    pszzCompatibleIds: Pointer;
    pContainerId: Pointer;
    CapabilityFlags: DWORD;
    pszDeviceDescription: Pointer;
    pszDeviceLocation: Pointer;
    pSecurityDescriptor: Pointer;
  end;
const SW_DEVICE_CREATE_INFO = extern struct {
    cbSize: u32,
    pszInstanceId: ?*anyopaque,
    pszzHardwareIds: ?*anyopaque,
    pszzCompatibleIds: ?*anyopaque,
    pContainerId: ?*anyopaque,
    CapabilityFlags: u32,
    pszDeviceDescription: ?*anyopaque,
    pszDeviceLocation: ?*anyopaque,
    pSecurityDescriptor: ?*anyopaque,
};
type
  SW_DEVICE_CREATE_INFO {.bycopy.} = object
    cbSize: uint32
    pszInstanceId: pointer
    pszzHardwareIds: pointer
    pszzCompatibleIds: pointer
    pContainerId: pointer
    CapabilityFlags: uint32
    pszDeviceDescription: pointer
    pszDeviceLocation: pointer
    pSecurityDescriptor: pointer
struct SW_DEVICE_CREATE_INFO
{
    uint cbSize;
    void* pszInstanceId;
    void* pszzHardwareIds;
    void* pszzCompatibleIds;
    void* pContainerId;
    uint CapabilityFlags;
    void* pszDeviceDescription;
    void* pszDeviceLocation;
    void* pSecurityDescriptor;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; SW_DEVICE_CREATE_INFO サイズ: 36 バイト(x86)
dim st, 9    ; 4byte整数×9(構造体サイズ 36 / 4 切り上げ)
; cbSize : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; pszInstanceId : LPWSTR (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; pszzHardwareIds : LPWSTR (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; pszzCompatibleIds : LPWSTR (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; pContainerId : GUID* (+16, 4byte)  varptr(st)+16 を基点に操作(4byte:入れ子/配列)
; CapabilityFlags : DWORD (+20, 4byte)  st.5 = 値  /  値 = st.5   (lpoke/lpeek も可)
; pszDeviceDescription : LPWSTR (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; pszDeviceLocation : LPWSTR (+28, 4byte)  st.7 = 値  /  値 = st.7   (lpoke/lpeek も可)
; pSecurityDescriptor : SECURITY_DESCRIPTOR* (+32, 4byte)  varptr(st)+32 を基点に操作(4byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; SW_DEVICE_CREATE_INFO サイズ: 72 バイト(x64)
dim st, 18    ; 4byte整数×18(構造体サイズ 72 / 4 切り上げ)
; cbSize : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; pszInstanceId : LPWSTR (+8, 8byte)  qpoke st,8,値 / qpeek(st,8)  ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; pszzHardwareIds : LPWSTR (+16, 8byte)  qpoke st,16,値 / qpeek(st,16)  ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; pszzCompatibleIds : LPWSTR (+24, 8byte)  qpoke st,24,値 / qpeek(st,24)  ※IronHSPのみ。3.7/3.8は lpoke st,24,下位 : lpoke st,28,上位
; pContainerId : GUID* (+32, 8byte)  varptr(st)+32 を基点に操作(8byte:入れ子/配列)
; CapabilityFlags : DWORD (+40, 4byte)  st.10 = 値  /  値 = st.10   (lpoke/lpeek も可)
; pszDeviceDescription : LPWSTR (+48, 8byte)  qpoke st,48,値 / qpeek(st,48)  ※IronHSPのみ。3.7/3.8は lpoke st,48,下位 : lpoke st,52,上位
; pszDeviceLocation : LPWSTR (+56, 8byte)  qpoke st,56,値 / qpeek(st,56)  ※IronHSPのみ。3.7/3.8は lpoke st,56,下位 : lpoke st,60,上位
; pSecurityDescriptor : SECURITY_DESCRIPTOR* (+64, 8byte)  varptr(st)+64 を基点に操作(8byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global SW_DEVICE_CREATE_INFO
    #field int cbSize
    #field intptr pszInstanceId
    #field intptr pszzHardwareIds
    #field intptr pszzCompatibleIds
    #field intptr pContainerId
    #field int CapabilityFlags
    #field intptr pszDeviceDescription
    #field intptr pszDeviceLocation
    #field intptr pSecurityDescriptor
#endstruct

stdim st, SW_DEVICE_CREATE_INFO        ; NSTRUCT 変数を確保
st->cbSize = 100
mes "cbSize=" + st->cbSize