Funzione IoGetDeviceObjectPointer (wdm.h)

La routine IoGetDeviceObjectPointer restituisce un puntatore all'oggetto superiore nello stack dell'oggetto dispositivo denominato e un puntatore all'oggetto file corrispondente, se l'accesso richiesto agli oggetti può essere concesso.

Sintassi

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

Parametri

[in] ObjectName

Puntatore a un buffer contenente una stringa Unicode che corrisponde al nome dell'oggetto dispositivo.

[in] DesiredAccess

Specifica il valore ACCESS_MASK che rappresenta l'accesso desiderato. In genere DesiredAccess è FILE_READ_DATA. Raramente, vengono specificati i diritti di accesso FILE_WRITE_DATA o FILE_ALL_ACCESS.

[out] FileObject

Puntatore all'oggetto file che rappresenta l'oggetto dispositivo corrispondente al codice in modalità utente se la chiamata ha esito positivo.

[out] DeviceObject

Puntatore all'oggetto dispositivo che rappresenta il dispositivo logico, virtuale o fisico denominato se la chiamata ha esito positivo.

Valore restituito

IoGetDeviceObjectPointer restituisce STATUS_SUCCESS se ha esito positivo. I valori restituiti di errore possibili includono i codici di stato seguenti:

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

Commenti

IoGetDeviceObjectPointer stabilisce una "connessione" tra il chiamante e il driver di livello inferiore successivo. Un chiamante riuscito può usare il puntatore all'oggetto dispositivo restituito per inizializzare i propri oggetti dispositivo. Può anche essere usato come argomento per IoAttachDeviceToDeviceStack, IoCallDriver e qualsiasi routine che crea i runtime di integrazione per i driver inferiori. Il puntatore restituito è un argomento obbligatorio per IoCallDriver.

Questa routine restituisce anche un puntatore all'oggetto file corrispondente. Durante lo scaricamento, un driver può dereferenziare l'oggetto file come mezzo per dereferenziare indirettamente l'oggetto dispositivo. A tale scopo, il driver chiama ObDereferenceObject dalla routine Unload, passando il puntatore all'oggetto file restituito da IoGetDeviceObjectPointer. L'errore di dereferenziare l'oggetto dispositivo nella routine Scarica di un driver impedisce che il driver successivo venga scaricato. Tuttavia, i driver che chiudono l'oggetto file prima del processo di scaricamento devono rimuovere un riferimento aggiuntivo nell'oggetto dispositivo prima di dereferenziare l'oggetto file. In caso contrario, la dereferenziazione dell'oggetto file può causare un'eliminazione prematura dell'oggetto dispositivo.

Per ottenere un puntatore al driver di livello più elevato nello stack di driver del file system, un driver deve assicurarsi che il file system sia montato; in caso contrario, questa routine attraversa lo stack di dispositivi di archiviazione. Per assicurarsi che il file system sia montato nel dispositivo di archiviazione, il driver deve specificare una maschera di accesso appropriata, ad esempio FILE_READ_DATA o FILE_WRITE_ATTRIBUTES, nel parametro DesiredAccess . Se si specifica FILE_READ_ATTRIBUTES non viene montato il file system.

Dopo che qualsiasi driver di livello superiore si è concatenato su un altro driver chiamando correttamente questa routine, il driver di livello superiore deve impostare il campo StackSize nel relativo oggetto dispositivo su quello dell'oggetto dispositivo del driver di livello inferiore successivo più uno.

I chiamanti di IoGetDeviceObjectPointer devono essere in esecuzione in IRQL = PASSIVE_LEVEL.

Requisiti

Vedi anche

ACCESS_MASK

DEVICE_OBJECT

IoAllocateIrp

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCallDriver

ObDereferenceObject

ObReferenceObjectByPointer