Función SwDeviceCreate (swdevice.h)
Inicia la enumeración de un dispositivo de software.
Sintaxis
HRESULT SwDeviceCreate(
[in] PCWSTR pszEnumeratorName,
[in] PCWSTR pszParentDeviceInstance,
[in] const SW_DEVICE_CREATE_INFO *pCreateInfo,
[in] ULONG cPropertyCount,
[in, optional] const DEVPROPERTY *pProperties,
[in] SW_DEVICE_CREATE_CALLBACK pCallback,
[in, optional] PVOID pContext,
[out] PHSWDEVICE phSwDevice
);
Parámetros
[in] pszEnumeratorName
Cadena que asigna un nombre al enumerador del dispositivo de software. Elija un nombre que represente el componente que enumera los dispositivos.
[in] pszParentDeviceInstance
Cadena que especifica el identificador de instancia de dispositivo del dispositivo que es el elemento primario del dispositivo de software.
Puede ser HTREE\ROOT\0, pero se recomienda mantener los elementos secundarios del dispositivo raíz como mínimo. También se recomienda que el elemento primario preferido de un dispositivo de software sea un dispositivo real para el que el dispositivo de software amplíe la funcionalidad. En situaciones en las que un dispositivo de software no tiene un elemento primario natural, cree un dispositivo como un elemento secundario de la raíz que pueda recopilar todos los dispositivos de software que un componente enumerará; a continuación, enumere los dispositivos de software reales como elementos secundarios de este nodo de agrupación de dispositivos. Esto mantiene los elementos secundarios del dispositivo raíz en un número administrable.
[in] pCreateInfo
Puntero a una estructura de SW_DEVICE_CREATE_INFO que describe la información que PnP usa para crear el dispositivo.
[in] cPropertyCount
Número de estructuras DEVPROPERTY en la matriz pProperties .
[in, optional] pProperties
Matriz opcional de estructuras DEVPROPERTY . Estas propiedades se establecen en el dispositivo después de crearse, pero antes de que se envíe una notificación de que se ha creado el dispositivo. Para obtener más información, consulta Comentarios. Este puntero puede ser NULL.
[in] pCallback
La SW_DEVICE_CREATE_CALLBACK función de devolución de llamada a la que el sistema operativo llama después de que PnP enumera el dispositivo.
[in, optional] pContext
Contexto de cliente opcional que el sistema operativo pasa a la función de devolución de llamada. Este puntero puede ser NULL.
[out] phSwDevice
Puntero a una variable que recibe el identificador HSWDEVICE que representa el dispositivo. Llame a SwDeviceClose para cerrar este identificador después de que la aplicación cliente quiera que PnP quite el dispositivo.
DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;
Valor devuelto
S_OK se devuelve si la enumeración del dispositivo se inició correctamente. Esto no significa que el dispositivo se haya enumerado correctamente. Compruebe el parámetro CreateResult de la función de devolución de llamada SW_DEVICE_CREATE_CALLBACK para determinar si el dispositivo se ha enumerado correctamente.
Comentarios
SwDeviceCreate devuelve un identificador que representa el dispositivo. Una vez cerrado este identificador, PnP quitará el dispositivo.
El proceso de llamada debe tener acceso de administrador para iniciar la enumeración de un dispositivo de software.
PnP forma el identificador de instancia de dispositivo de un dispositivo de software como "SWD< pszEnumeratorName>< pszInstanceId>", pero esta cadena podría cambiar o PnP podría decorar el nombre. Obtenga siempre el identificador de instancia del dispositivo de la función de devolución de llamada.
Hay una diferencia sutil entre las propiedades que se establecen como parte de una llamada SwDeviceCreate y las propiedades que se establecen más adelante llamando a SwDevicePropertySet. Las propiedades que se establecen como parte de SwDeviceCreate se almacenan en la memoria; Si el dispositivo se desinstala o un controlador nulo borra los almacenes de propiedades, la característica API de dispositivo de software vuelve a escribir estas propiedades cuando PnP vuelve a enumerar los dispositivos. Todo esto es transparente para el cliente. Las propiedades que se establecen mediante SwDevicePropertySet después de la enumeración no se conservan en la memoria. Sin embargo, si establece una propiedad mediante SwDeviceCreate, puede actualizar el valor con SwDevicePropertySet y esta actualización se aplica al valor en memoria, así como al almacén persistente.
Se recomienda especificar todas las propiedades como parte de la llamada a SwDeviceCreate siempre que sea posible y que se especifiquen estas propiedades para cada llamada a SwDeviceCreate.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 8 |
| Servidor mínimo compatible | Windows Server 2012 |
| Plataforma de destino | Universal |
| Encabezado | swdevice.h |
| Library | Swdevice.lib; OneCoreUAP.lib en Windows 10 |
| Archivo DLL | Cfgmgr32.dll |