Gestori di proprietà audio
Un driver miniport archivia informazioni su ogni proprietà supportata in una struttura PCPROPERTY_ITEM . Questa struttura contiene le informazioni seguenti sulla proprietà:
GUID e ID proprietà del set di proprietà (o indice)
Puntatore di funzione alla routine del gestore per la proprietà
Flag che specificano le operazioni di proprietà supportate dal gestore
Il driver miniport fornisce una tabella di automazione (specificata da una struttura PCAUTOMATION_TABLE ) per il filtro. Il driver fornisce tabelle di automazione aggiuntive per i tipi di pin e i tipi di nodo del filtro: ogni tipo di pin o nodo ha una propria tabella. Ogni tabella di automazione contiene una matrice (possibilmente vuota) di strutture PCPROPERTY_ITEM e ognuna di queste strutture descrive una proprietà del filtro, del pin o del nodo. Quando un client invia una richiesta di proprietà a un filtro, un pin o un nodo, il driver di porta instrada la richiesta tramite la tabella di automazione al gestore delle proprietà appropriato.
Un driver miniport può specificare una routine del gestore delle proprietà univoca per ogni proprietà. Tuttavia, se un driver gestisce diverse proprietà simili, queste possono talvolta essere consolidate in una singola routine del gestore per praticità. Se fornire un gestore univoco per ogni proprietà o consolidare diverse proprietà in un singolo gestore è una decisione di implementazione da prendere dal writer driver e deve essere trasparente ai client che inviano richieste di proprietà.
Un client in modalità utente può inviare una richiesta di proprietà get, set o basic-support chiamando la funzione Microsoft Win32 DeviceIoControl con il parametro di chiamata dwIoControlCode impostato su IOCTL_KS_PROPERTY. Il sistema operativo converte questa chiamata in un'istanza di IRP, che invia al driver di classe. Per altre informazioni, vedere Proprietà KS.
Quando un client invia una richiesta di proprietà KS (ovvero un IOCTL_KS_PROPERTY I/O-control IRP) a un handle di filtro o un handle di pin, il driver di sistema KS (Ks.sys) recapita la richiesta al driver di porta per l'oggetto filtro o l'oggetto pin. Se il driver miniport fornisce un gestore per la proprietà, il driver di porta inoltra la richiesta al gestore. Prima di inoltrare la richiesta, il driver di porta converte le informazioni dalla richiesta di proprietà nel formato specificato dalla struttura PCPROPERTY_REQUEST . Il driver di porta passa questa struttura al gestore del driver miniport.
Il membro MajorTarget di PCPROPERTY_REQUEST punta all'interfaccia del driver miniport principale per il dispositivo audio. Ad esempio, per un dispositivo WavePci, si tratta di un puntatore all'interfaccia IMiniportWavePci dell'oggetto driver miniport.
Nel caso di una richiesta di proprietà KS inviata a un handle di filtro, il membro MinorTarget di PCPROPERTY_REQUEST è NULL. Nel caso di una richiesta inviata a un handle di pin, MinorTarget punta all'interfaccia di flusso per il pin. Ad esempio, per un dispositivo WavePci, si tratta di un puntatore all'interfaccia IMiniportWavePciStream dell'oggetto di flusso.
I membri instance e value di PCPROPERTY_REQUEST puntano rispettivamente ai buffer di input e di output della richiesta della proprietà KS. I buffer vengono specificati dai parametri lpInBuffer e lpOutBuffer della funzione DeviceIoControl . Questi buffer contengono rispettivamente il descrittore della proprietà (dati dell'istanza) e il valore della proprietà (dati dell'operazione), come descritto in Set di proprietà driver audio. Il membro Value punta all'inizio del buffer di output, ma il puntatore istanza è offset dall'inizio del buffer di input.
Il buffer di input inizia con una struttura KSPROPERTY o KSNODEPROPERTY. Il driver di porta copia le informazioni da questa struttura nei membri Node, PropertyItem e Verb della struttura di PCPROPERTY_REQUEST. Se i dati seguono la struttura KSPROPERTY o KSNODEPROPERTY nel buffer, il driver di porta carica il membro dell'istanza con un puntatore a questi dati. In caso contrario, imposta Istanza su NULL.
Se il buffer di input inizia con una struttura KSPROPERTY, che non contiene informazioni sui nodi, il driver della porta imposta il membro node della struttura PCPROPERTY_REQUEST su ULONG(-1). In questo caso, il driver di porta chiama il gestore appropriato dalla tabella di automazione del driver miniport per il filtro o il pin, a seconda che la destinazione per la richiesta di proprietà sia specificata da un handle di filtro o un handle di pin. Se la tabella non specifica un gestore per la proprietà, il driver della porta gestisce invece la richiesta.
Se il buffer di input inizia con una struttura KSNODEPROPERTY, il driver di porta copia l'ID nodo da questa struttura nel membro node della struttura PCPROPERTY_REQUEST e chiama il gestore appropriato dalla tabella di automazione del driver miniport per il nodo. Se la tabella non specifica un gestore per la proprietà, il driver della porta gestisce invece la richiesta.
Il driver di porta controlla il bit di KSPROPERTY_TYPE_TOPOLOGY nei flag di operazione della richiesta di proprietà per determinare quale delle due strutture, KSPROPERTY o KSNODEPROPERTY, risiede all'inizio del buffer di input:
Se questo bit è impostato, la richiesta è per una proprietà node e il buffer di input inizia con una struttura KSNODEPROPERTY.
In caso contrario, il buffer di input inizia con una struttura KSPROPERTY.
Per altre informazioni sulle KSPROPERTY_TYPE_TOPOLOGY, vedere KSPROPERTY.
I membri InstanceSize e ValueSize della struttura PCPROPERTY_REQUEST specificano le dimensioni dei buffer a cui puntano i membri Instance e Value . ValueSize è uguale alle dimensioni del buffer di output della richiesta di proprietà, ma InstanceSize è la dimensione dei dati che segue la struttura KSPROPERTY o KSNODEPROPERTY nel buffer di input. Ovvero , InstanceSize è la dimensione del buffer di input meno le dimensioni della struttura KSPROPERTY o KSNODEPROPERTY. Se non sono presenti dati aggiuntivi, il driver di porta imposta InstanceSize su zero (e Istanza su NULL).
Ad esempio, se il client specifica una struttura KSNODEPROPERTY_AUDIO_CHANNEL come dati dell'istanza nel buffer di input, il driver di porta passa il gestore di una struttura PCPROPERTY_REQUEST il cui membro di istanza punta al membro Canale della struttura KSNODEPROPERTY_AUDIO_CHANNEL e il cui membro InstanceSize contiene il valore
sizeof(KSNODEPROPERTY_AUDIO_CHANNEL) - sizeof(KSNODEPROPERTY)
Prima di inviare una richiesta get-property per recuperare un valore di proprietà, il client deve allocare un buffer di output in cui il gestore delle proprietà del driver miniport può scrivere il valore della proprietà. Per alcune proprietà, le dimensioni del buffer di output sono dipendenti dal dispositivo e il client deve eseguire query sul gestore delle proprietà per le dimensioni del buffer necessarie. In questi casi, il client invia una richiesta di proprietà iniziale con un puntatore del buffer di output nullptr e una lunghezza del buffer di output pari a zero. Il gestore risponde restituendo le dimensioni del buffer necessarie insieme al codice di stato STATUS_BUFFER_OVERFLOW. Il client recupera quindi il valore della proprietà allocando un buffer di output delle dimensioni specificate e inviando questo buffer in una seconda richiesta get-property.
Se la dimensione del buffer specificata è troppo piccola per ricevere una delle informazioni richieste, il metodo restituisce STATUS_BUFFER_TOO_SMALL.
In alcuni casi, i driver di porta PortCls restituiscono STATUS_BUFFER_TOO_SMALL anziché STATUS_BUFFER_OVERFLOW in risposta a una richiesta di proprietà con un indirizzo e dimensioni del buffer di output diverso da zero. Le dimensioni del buffer necessarie non vengono restituite in tali casi.
Per altre informazioni, vedere Uso di valori NTSTATUS e questi post di blog: