funzione CM_Query_And_Remove_SubTreeA (cfgmgr32.h)

Articolo
03/08/2023

La funzione CM_Query_And_Remove_SubTree controlla 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_SubTreeA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          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. L'handle dell'istanza del dispositivo è associato al computer locale.

[out, optional] pVetoType

[out, optional] pszVetoName

(Facoltativo) Se il chiamante non passa NULL e la richiesta di rimozione è veto (vale a dire, la funzione restituisce CR_REMOVE_VETOED), in caso di restituzione di questi punti a 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 di stringa fornito da pszVetoName. Deve essere impostato su MAX_PATH.

[in] ulFlags

OR bit per bit delle costanti flag fornite 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 flags ulFlags con uno dei due flag seguenti; questi flag si applicano solo se Windows o un programma di installazione veta la rimozione di un dispositivo:

Flag	Descrizione
CM_REMOVE_UI_OK	La funzione consente di visualizzare una finestra di dialogo utente per indicare il motivo del veto. Questa è l'impostazione del flag predefinita.
CM_REMOVE_UI_NOT_OK	La funzione elimina la visualizzazione di una finestra di dialogo 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:

Chiamare 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 la reimpostazione dello 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 ricollegato oppure il computer viene riavviato. In questo caso, lo stato del dispositivo verrà reimpostato e il dispositivo verrà riavviato.
Se questo flag non è impostato, non è necessario reimpostare lo stato del dispositivo. È 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 chiama CM_Reenumerate_DevNode per il dispositivo, scollegare e ricollegare il dispositivo o riavviare 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 di 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

Vedi anche

CM_Get_Child
CM_Query_And_Remove_SubTree_Ex
CM_Reenumerate_DevNode
CM_Request_Device_Eject
CM_Setup_DevNode
DIF_PROPERTYCHANGE

Condividi tramite