funzione CM_Query_And_Remove_SubTree_ExA (cfgmgr32.h)

[A partire da Windows 8 e Windows Server 2012, questa funzione è stata deprecata. Usare invece CM_Query_And_Remove_SubTree .]

La funzione CM_Query_And_Remove_SubTree_Ex 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_SubTree_ExA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags,
  [in, optional]  HMACHINE       hMachine
);

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 all'handle del computer fornito da hMachine.

[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

(Facoltativo.) 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 .

[in, optional] hMachine

Handle del computer fornito dal chiamante a cui è associato l'handle dell'istanza del chiamante fornito dal chiamante.

Valore restituito

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

Commenti

Lo scopo della funzione CM_Query_And_Remove_SubTree_Ex è consentire a un'applicazione di preparare un dispositivo per la rimozione sicura da un computer remoto. 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_Ex anziché CM_Query_And_Remove_SubTree_Ex.

CM_Query_And_Remove_SubTree_Ex 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:

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

Le applicazioni di installazione del dispositivo che non richiedono l'operazione a basso livello di CM_Query_And_Remove_SubTree_Ex devono usare la richiesta di DIF_PROPERTYCHANGE per disabilitare un dispositivo anziché usareCM_Query_And_Remove_SubTree_Ex 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 a un computer locale o remoto, vedere CM_Get_Child_Ex.

La funzionalità per accedere ai computer remoti è stata rimossa in Windows 8 e Windows Server 2012 e sistemi operativi successivi, pertanto non è possibile accedere ai computer remoti quando vengono eseguiti in queste versioni di Windows.

Requisiti

Vedi anche

CM_Get_Child_Ex
CM_Query_And_Remove_SubTree
CM_Reenumerate_DevNode
CM_Request_Device_Eject_Ex
CM_Setup_DevNode
DIF_PROPERTYCHANGE