Filtrare, aggiungere e proprietà del nodo
I driver audio WDM (Microsoft Windows Driver Model) rappresentano un dispositivo audio come filtro KS e rappresentano un buffer hardware nel dispositivo come pin nel filtro. Quando un client invia una richiesta di proprietà a uno di questi oggetti filtro o pin, il driver di porta riceve la richiesta e indirizza la richiesta al gestore delle proprietà appropriato nel driver di porta o nel driver miniport.
I dispositivi audio supportano tre tipi di proprietà:
Proprietà del filtro
Una proprietà filter è una proprietà del filtro intera anziché una proprietà di un determinato pin o nodo all'interno del filtro. Le richieste per le proprietà del filtro specificano handle di filtro, ma non specificano gli ID nodo.
Proprietà pin
Una proprietà pin è una proprietà di un'istanza di pin specifica nel filtro. Le richieste per queste proprietà specificano handle di pin, ma non specificano gli ID nodo.
Proprietà del nodo
Una proprietà node è una proprietà di un nodo della topologia all'interno del filtro. Una richiesta per una proprietà node specifica un handle di filtro o un handle di pin, oltre a un ID nodo.
Se una richiesta di proprietà node specifica un handle di filtro o pin dipende dal fatto che il nodo sia univoco per il filtro. Per altre informazioni, vedere la sezione Proprietà nodo seguente.
La figura seguente illustra questi tre tipi di richiesta di proprietà: una richiesta di proprietà pin inviata a un'istanza di pin, una richiesta di proprietà node inviata a un nodo (in un filtro o un'istanza di pin) e una richiesta di proprietà filtro inviata a un'istanza di filtro.
In genere, il driver di porta gestisce la maggior parte delle richieste per le proprietà di filtro e pin e il driver miniport gestisce le richieste per le proprietà del nodo.
Il driver di porta fornisce i propri gestori predefiniti per le proprietà di filtro e pin usate dal driver di sistema SysAudio (vedere KSPROPSETID_Sysaudio e KSPROPSETID_Sysaudio_Pin) e driver di sistema WDMAud. Un driver miniport non deve implementare gestori per le proprietà gestite dal driver di porta. Un tipico driver miniport fornisce pochi gestori per filtrare e aggiungere proprietà. Il driver miniport fornisce i gestori per le proprietà del nodo che rappresentano le funzionalità dipendenti dall'hardware del dispositivo audio. I driver di porta non forniscono alcuna gestione predefinita delle proprietà del nodo, ad eccezione di KSPROPERTY_TOPOLOGY_NAME.
Quando sia il driver di porta che i gestori di fornitura del driver miniport per la stessa proprietà, il driver della porta usa il proprio gestore e ignora il gestore del driver miniport.
Descrittori di filtro
Il driver di porta ottiene puntatori ai gestori delle proprietà del driver miniport chiamando il metodo IMiniport::GetDescription . Tramite questo metodo, il driver di porta recupera un puntatore al descrittore di filtro del driver miniport, ovvero una struttura di tipo PCFILTER_DESCRIPTOR. Questa struttura specifica i gestori delle proprietà del driver miniport per le proprietà filtro, pin e nodo:
Il membro AutomationTable della struttura PCFILTER_DESCRIPTOR punta alla tabella di automazione per il filtro. Questa tabella specifica i gestori delle proprietà del driver miniport per le proprietà del filtro.
Il membro Pins della struttura PCFILTER_DESCRIPTOR contiene le tabelle di automazione per i pin. Ogni tabella specifica i gestori delle proprietà per le proprietà pin di un tipo di pin specifico.
Il membro nodi della struttura PCFILTER_DESCRIPTOR contiene le tabelle di automazione per i nodi della topologia all'interno del filtro. Ogni tabella specifica i gestori delle proprietà per le proprietà del nodo di un tipo di nodo specifico.
Proprietà filtro
Il driver di porta accede ai gestori della proprietà filtro del driver miniport tramite il membro AutomationTable di PCFILTER_DESCRIPTOR. In genere, questa tabella di automazione contiene pochi gestori perché il driver della porta fornisce i propri gestori predefiniti per tutte le proprietà del filtro usate da SysAudio e WDMAud per eseguire query e configurare i dispositivi audio.
Tuttavia, il driver miniport può fornire gestori per le proprietà del filtro, ad esempio KSPROPERTY_GENERAL_COMPONENTID che forniscono informazioni dipendenti dall'hardware che non sono disponibili per il driver della porta. Due dei driver audio di esempio in Microsoft Windows Driver Kit (WDK) gestiscono la proprietà KSPROPERTY_GENERAL_COMPONENTID. Per altre informazioni, vedere le implementazioni del driver miniport nel driver di esempio Sysvad, illustrato in Driver audio di esempio.
Tutti i driver di porta in Portcls.sys forniscono la gestione per i set di proprietà KSPROPSETID_Pin e KSPROPSETID_Topology . Tutte le proprietà di questi set sono proprietà di filtro, ad eccezione di KSPROPERTY_TOPOLOGY_NAME, che è una proprietà node (che usa un handle di filtro, non un handle pin, per specificare la destinazione per la richiesta). I driver di porta supportano il sottoinsieme seguente delle proprietà KSPROPSETID_Pin:
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
Queste proprietà forniscono informazioni sulle pin factory appartenenti a un filtro. In genere, i client eseguono una query sul filtro per queste proprietà prima di creare istanze di pin. I driver di porta supportano tutte e quattro le proprietà KSPROPSETID_Topology, che forniscono informazioni sulla topologia interna del filtro.
Inoltre, il driver di porta DMus fornisce un gestore per la proprietà KSPROPERTY_SYNTH_MASTERCLOCK , ovvero una proprietà get-only di un filtro DirectMusic. KSPROPERTY_SYNTH_MASTERCLOCK è membro del set di proprietà KSPROPSETID_SynthClock .
Proprietà pin
Il driver di porta accede ai gestori di pin-property del driver miniport tramite il membro Pins di PCFILTER_DESCRIPTOR. Questo membro punta a una matrice di descrittori pin e ogni descrittore punta alla tabella di automazione per un tipo di pin (identificato da un ID pin, che è semplicemente l'indice della matrice).
In genere, queste tabelle di automazione contengono poche voci perché il driver della porta fornisce i propri gestori per tutte le proprietà pin usate da SysAudio e WDMAud. Un driver miniport ha la possibilità di fornire gestori per una o più proprietà pin che il driver di porta non gestisce, ma solo i client che conoscono queste proprietà possono inviare richieste di proprietà per loro.
Ad eccezione del driver della porta della topologia, tutti i driver di porta in Portcls.sys forniscono gestori predefiniti per le proprietà del pin seguenti:
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Alcune delle proprietà di questo elenco richiedono informazioni dipendenti dall'hardware dal driver miniport. Quando il driver di porta riceve un'IRP contenente una richiesta per una di queste proprietà, non passa l'IRP al driver miniport. Il driver di porta gestisce invece la richiesta stessa, ma il relativo gestore ottiene le informazioni necessarie chiamando un punto di ingresso nel driver miniport. Ad esempio, il driver della porta fornisce il proprio gestore delle proprietà per le richieste di KSPROPERTY_AUDIO_POSITION. Questo gestore chiama semplicemente il metodo GetPosition del driver miniport (ad esempio IMiniportWavePciStream::GetPosition) per ottenere la posizione corrente.
Proprietà del nodo
Il driver di porta accede ai gestori della proprietà node-property del driver miniport tramite il membro Node di PCFILTER_DESCRIPTOR. Questo membro punta a una matrice di descrittori di nodo e ogni descrittore punta alla tabella di automazione per un tipo di nodo (identificato da un ID nodo, che è semplicemente l'indice della matrice). In genere, tutti o la maggior parte dei gestori di proprietà appartenenti a un driver miniport si trovano nella matrice Nodes . Un driver audio rappresenta i controlli hardware in un dispositivo audio come nodi della topologia e usa il meccanismo di proprietà per fornire ai client l'accesso alle impostazioni di controllo dipendenti dall'hardware.
Come descritto in precedenza, un client invia una richiesta di proprietà filtro a un handle di filtro e una richiesta di proprietà pin a un handle pin. A differenza di un'istanza di filtro o pin, un nodo non è un oggetto kernel e non dispone di un handle. Un client invia una richiesta di proprietà del nodo a un handle pin o a un handle di filtro, ma la richiesta specifica anche un ID nodo per indicare che la richiesta è relativa a una proprietà del nodo anziché a una proprietà pin o filter.
Di seguito sono riportate le regole generali per determinare se una proprietà del nodo deve usare un handle di filtro o un handle di pin:
Se un filtro contiene diverse istanze di un particolare tipo di pin e ogni pin di tale tipo contiene un nodo con un ID nodo specifico, ogni istanza del pin contiene un'istanza del nodo. In questo caso, una richiesta di proprietà del nodo deve specificare un handle pin (anziché solo un handle di filtro) per distinguere tra più istanze dello stesso tipo di nodo. La combinazione di handle pin e ID nodo identifica in modo univoco una particolare istanza del nodo come destinazione per la richiesta.
Se un filtro contiene una sola istanza di un nodo specifico, una richiesta di proprietà del nodo specifica un handle di filtro. La combinazione di handle di filtro e ID nodo è sufficiente per identificare in modo univoco il nodo che è la destinazione per la richiesta.
Prima di implementare un gestore per una determinata proprietà del nodo, tuttavia, il writer del driver deve fare riferimento ai set di proprietà driver audio per verificare se la destinazione per la proprietà deve essere specificata come handle di filtro o handle di pin.
I driver di porta in Portcls.sys attualmente non forniscono la gestione predefinita delle proprietà del nodo, ad eccezione di KSPROPERTY_TOPOLOGY_NAME.
Richieste di proprietà sovraspecificate e underspecified
I driver devono essere preparati a gestire le richieste di proprietà dai client che non seguono le regole precedenti. Le richieste possono essere sovraspecificate o sottospecificate:
Richieste sovraspecificate
Se una richiesta di proprietà richiede solo un handle di filtro, ma il client invia invece la richiesta a un handle pin, la destinazione per la richiesta è sovraspecificata. Tuttavia, i driver considerano in genere la richiesta come valida; ovvero considerano la richiesta come se fosse stata inviata al filtro contenente il pin.
Richieste sottospecificate
Se una richiesta di proprietà richiede un handle pin, ma un client invia invece la richiesta a un handle di filtro, la destinazione per la richiesta è sottospecificata. Ad esempio, se un filtro contiene più istanze di pin con lo stesso tipo di nodo e un client invia una richiesta per una proprietà di tale tipo di nodo a un handle di filtro anziché a un handle di pin, il driver non può determinare quale istanza del nodo deve ricevere la richiesta. In questo caso, il comportamento dipende dal driver. Invece di eseguire automaticamente l'errore di tutte le richieste sottospecificate, alcuni driver considerano una richiesta set-property sottospecificata come valida. In questo caso, l'interpretazione è che la richiesta imposta il valore predefinito per l'ID nodo specificato. Quando una factory di pin crea una nuova istanza del nodo, la proprietà appartenente al nuovo nodo viene inizializzata sul valore predefinito. Una richiesta che modifica il valore predefinito non ha alcun effetto sulle istanze del nodo create prima della richiesta. Inoltre, i driver non soddisfano in modo uniforme le richieste get-property specificate perché il gestore non è in grado di determinare quale istanza del nodo eseguire una query per la proprietà.
Eccezioni alle regole
Per motivi cronologici, alcune proprietà audio hanno strani comportamenti che violano queste regole generali. Alcuni esempi:
Come descritto in Applicazione delle impostazioni di Speaker-Configuration, un client può modificare la configurazione dell'altoparlante di un dispositivo audio impostando la proprietà KSPROPERTY_AUDIO_CHANNEL_CONFIG di un nodo 3D (KSNODETYPE_3D_EFFECTS). L'impostazione di configurazione voce è globale perché modifica la configurazione dell'altoparlante per tutti i flussi che fanno parte della combinazione riprodotta dal dispositivo attraverso gli altoparlanti. In base alla regola generale, una richiesta di proprietà del nodo che influisce sul filtro nel suo complesso deve specificare un handle di filtro (più un ID nodo). Tuttavia, questa particolare proprietà richiede un handle pin anziché un handle di filtro. L'handle pin designa l'istanza del pin contenente il nodo 3D che rappresenta la destinazione della richiesta.
KSPROPERTY_SYNTH_VOLUME e KSPROPERTY_SYNTH_MASTERCLOCK sono proprietà di un nodo synth (KSNODETYPE_SYNTHESIZER). Anche se entrambe sono proprietà del nodo, le richieste per queste proprietà non includono GLI ID nodo. Si noti che il descrittore di proprietà per la richiesta è una struttura di tipo KSPROPERTY, non KSNODEPROPERTY. Questo comportamento viola la regola generale che una proprietà del nodo richiede un ID nodo. Nonostante questa discrepanza, un driver miniport che supporta entrambe le proprietà deve fornire il gestore della proprietà tramite il membro Nodes di PCFILTER_DESCRIPTOR (anziché il membro Pins ).