Función SetupDiOpenDeviceInterfaceA (setupapi.h)

La función SetupDiOpenDeviceInterface recupera información sobre una interfaz de dispositivo y agrega la interfaz al conjunto de información del dispositivo especificado para un sistema local o un sistema remoto.

Sintaxis

WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parámetros

[in] DeviceInfoSet

Puntero a un conjunto de información del dispositivo que contiene, o contendrá, un elemento de información del dispositivo que representa el dispositivo que admite la interfaz que se va a abrir.

[in] DevicePath

Puntero a una cadena terminada en NULL que proporciona el nombre de la interfaz del dispositivo que se va a abrir. Este nombre es una ruta de acceso del dispositivo Win32 que normalmente se recibe en una estructura de notificación PnP o se obtiene mediante una llamada anterior a SetupDiEnumDeviceInterfaces y sus funciones relacionadas.

[in] OpenFlags

Marcas que determinan cómo se va a abrir el elemento de interfaz del dispositivo. La única marca válida es la siguiente:

DIODI_NO_ADD

Especifica que el elemento de información del dispositivo para el dispositivo subyacente no se creará si ese elemento aún no está presente en el conjunto de información del dispositivo especificado. Para obtener más información, vea la siguiente sección Comentarios .

[out, optional] DeviceInterfaceData

Puntero a una estructura de SP_DEVICE_INTERFACE_DATA inicializada por el autor de la llamada que recibe los datos de interfaz solicitados. Este puntero es opcional y puede ser NULL. Si se proporciona un búfer, el llamador debe establecer el miembro cbSize de la estructura en sizeof(SP_DEVICE_INTERFACE_DATA) antes de llamar a SetupDiOpenDeviceInterface. Para obtener más información, vea la siguiente sección Comentarios .

Valor devuelto

SetupDiOpenDeviceInterface devuelve TRUE si la función se completó sin error. Si la función se completó con un error, devuelve FALSE y el código de error del error se puede recuperar llamando a GetLastError.

Comentarios

Si ya existe un elemento de interfaz de dispositivo para la interfaz en DeviceInfoSet, SetupDiOpenDeviceInterface actualiza las marcas. Por lo tanto, esta función se puede usar para actualizar las marcas de una interfaz de dispositivo. Por ejemplo, una interfaz podría haber estado inactiva cuando se abrió por primera vez, pero posteriormente se ha vuelto activa. Si el elemento de información del dispositivo para el dispositivo subyacente aún no está presente en DeviceInfoSet, esta función crea una y la agrega a DeviceInfoSet.

Si la función abre correctamente la nueva interfaz de dispositivo, pero el autor de la llamada no ha proporcionado una estructura válida en el parámetro DeviceInterfaceData , la función devolverá FALSE y una llamada posterior a GetLastError devolverá ERROR_INVALID_USER_BUFFER. Sin embargo, en esta situación, SetupDiOpenDeviceInterface agrega la interfaz solicitada al conjunto de información del dispositivo.

Si la nueva interfaz de dispositivo se abre correctamente, pero el búfer DeviceInterfaceData proporcionado por el autor de la llamada no es válido, esta función devuelve FALSE y GetLastError devuelve ERROR_INVALID_USER_BUFFER. El error del búfer del autor de la llamada no impide que se abra la interfaz.

Si se especifica la marca DIODI_NO_ADD para el parámetro OpenFlags y un elemento de información del dispositivo para el dispositivo subyacente aún no está presente en el conjunto de información del dispositivo especificado, esta función devuelve FALSE y GetLastError devuelve ERROR_NO_SUCH_DEVICE_INTERFACE.

Cuando la aplicación haya terminado de usar la información que ha recuperado SetupDiOpenDeviceInterface, la aplicación debe llamar a SetupDiDeleteDeviceInterfaceData.

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK atributo se puede pasar como el valor del argumento DevicePath de la función SetupDiOpenDeviceInterface .

Requisitos

Consulte también

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces