funzione CM_Query_And_Remove_SubTreeW (cfgmgr32.h)

Articolo
02/23/2024

La funzione CM_Query_And_Remove_SubTree verifica se un'istanza del dispositivo e i relativi elementi figlio possono essere rimossi e, in tal caso, li rimuove.

Sintassi

CMAPI CONFIGRET CM_Query_And_Remove_SubTreeW(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPWSTR         pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags
);

Parametri

[in] dnAncestor

Handle dell'istanza del dispositivo fornita dal chiamante al dispositivo nella radice del sottoalbero da rimuovere. Questo handle di istanza del dispositivo è associato al computer locale.

[out, optional] pVetoType

(Facoltativo) Se il chiamante non passa NULL e la richiesta di rimozione viene veto (ovvero, la funzione restituisce CR_REMOVE_VETOED), in questo modo viene restituito un valore PNP_VETO_TYPE tipizzato che indica il motivo del veto.

[out, optional] pszVetoName

(Facoltativo) Se il chiamante non passa NULL e la richiesta di rimozione viene veto (ovvero, la funzione restituisce CR_REMOVE_VETOED), in questo modo viene restituita una stringa di testo associata al tipo veto. Il tipo di informazioni fornite da questa stringa dipende dal valore ricevuto da pVetoType. Per informazioni su queste stringhe, vedere PNP_VETO_TYPE.

[in] ulNameLength

Valore fornito dal chiamante che rappresenta la lunghezza (numero di caratteri) del buffer stringa fornito da pszVetoName. Questa opzione deve essere impostata su MAX_PATH.

[in] ulFlags

Or bit per bit delle costanti del flag fornito dal chiamante descritte nella sezione Osservazioni .

Valore restituito

Se l'operazione ha esito positivo, la funzione restituisce CR_SUCCESS. In caso contrario, restituisce uno degli altri codici di errore con prefisso CR_ definiti in Cfgmgr32.h.

Commenti

Lo scopo della funzione CM_Query_And_Remove_SubTree è consentire a un'applicazione di preparare un dispositivo per la rimozione sicura dal computer locale. Usare questa funzione per rimuovere i dispositivi solo se un driver non ha impostato il membro SurpriseRemovalOK di DEVICE_CAPABILITIES. Se un driver ha impostato SurpriseRemovalOK, l'applicazione deve chiamare CM_Request_Device_Eject anziché CM_Query_And_Remove_SubTree.

CM_Query_And_Remove_SubTree supporta l'impostazione del parametro flag ulFlags con uno dei due flag seguenti; questi flag si applicano solo se Windows o un programma di installazione ha veto la rimozione di un dispositivo:

Flag	Descrizione
CM_REMOVE_UI_OK	La funzione consente di visualizzare una finestra di dialogo dell'utente per indicare il motivo del veto. Si tratta dell'impostazione del flag predefinito.
CM_REMOVE_UI_NOT_OK	La funzione elimina la visualizzazione di una finestra di dialogo dell'utente che indica il motivo del veto.

A partire da Windows XP, CM_Query_And_Remove_SubTree supporta anche l'impostazione del flag aggiuntivo seguente; questo flag si applica solo se la funzione rimuove correttamente l'istanza del dispositivo:

Flag	Descrizione
CM_REMOVE_NO_RESTART	Se questo flag è impostato, la funzione configura lo stato del dispositivo in modo che il dispositivo non possa essere riavviato fino a quando lo stato del dispositivo non viene reimpostato.

Lo stato del dispositivo viene reimpostato da uno dei seguenti elementi:

Chiamata CM_Setup_DevNode per il dispositivo e specificare CM_SETUP_DEVNODE_RESET. Dopo aver reimpostato lo stato del dispositivo in questo modo, il dispositivo può essere riavviato chiamando CM_Reenumerate_DevNode per l'istanza del dispositivo. Dopo aver reimpostato lo stato del dispositivo, qualsiasi altra operazione che enumera il dispositivo riavvierà anche il dispositivo, ad esempio se il Gestione dispositivi viene usato per rinumerare i dispositivi.
Il dispositivo viene scollegato e riattaccato oppure il computer viene riavviato. In questo caso, lo stato del dispositivo verrà reimpostato e il dispositivo verrà riavviato.
Se questo flag non è impostato, lo stato del dispositivo non deve essere reimpostato. È possibile riavviare il dispositivo rimosso chiamando CM_Setup_DevNode per il dispositivo e specificando CM_SETUP_DEVNODE_READY. Qualsiasi altra operazione che rinumera il dispositivo riavvierà anche il dispositivo. Un esempio di operazione che rinumera un dispositivo sta chiamando CM_Reenumerate_DevNode per il dispositivo, scollegando e ricollegando il dispositivo o riavviando il computer. |

Le applicazioni Windows che non richiedono l'operazione di basso livello CM_Query_And_Remove_SubTree devono usare la richiesta di DIF_PROPERTYCHANGE per disabilitare un dispositivo anziché usare CM_Query_And_Remove_SubTree per rimuovere un dispositivo. La richiesta di DIF_PROPERTYCHANGE può essere usata per abilitare, disabilitare, riavviare, arrestare o modificare le proprietà di un dispositivo.

I chiamanti di questa funzione devono avere SeLoadDriverPrivilege. I privilegi sono descritti nella documentazione di Microsoft Windows SDK.

Per informazioni sull'uso degli handle di istanza del dispositivo associati al computer locale, vedere CM_Get_Child.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
Piattaforma di destinazione	Universale
Intestazione	cfgmgr32.h (include Cfgmgr32.h)
Libreria	Cfgmgr32.lib