Query di supporto di base per le proprietà audio

Quando si specificano i dati per una richiesta di proprietà set a un filtro, un pin o un nodo, il client deve spesso conoscere gli intervalli di dati validi per il valore o i valori specificati per la proprietà. Gli intervalli possono variare da dispositivo a dispositivo e possibilmente anche da nodo a nodo all'interno dello stesso dispositivo.

Alcune proprietà sono definite per consentire alle richieste di proprietà set di specificare valori non compresi nell'intervallo, ma i driver miniport bloccano automaticamente tali valori all'intervallo supportato (ad esempio, vedere KSPROPERTY_AUDIO_VOLUMELEVEL). Una richiesta get successiva per la stessa proprietà recupera le impostazioni effettive del driver per il valore o i valori, che potrebbero essere versioni bloccate dei valori specificati dal client nella richiesta set.

Tuttavia, un client potrebbe dover conoscere l'intervallo per un valore di proprietà anziché semplicemente affidarsi al driver miniport per bloccare automaticamente un valore non compreso nell'intervallo. Ad esempio, un'applicazione con finestra che presenta un dispositivo di scorrimento del controllo del volume per un dispositivo audio potrebbe dover conoscere l'intervallo di volumi del dispositivo per eseguire il mapping di tale intervallo alla lunghezza completa del dispositivo di scorrimento.

La routine del gestore del driver per una determinata proprietà deve essere in grado di fornire informazioni sull'intervallo in risposta a una richiesta di proprietà di supporto di base (KSPROPERTY_TYPE_BASICSUPPORT). Quando si invia una richiesta di proprietà di supporto di base a un driver, un client fornisce un buffer di valori in cui il gestore della proprietà scrive le informazioni di supporto di base, costituito da una struttura KSPROPERTY_DESCRIPTION che potrebbe essere seguita da dati specifici della proprietà. Questi dati sono in genere costituiti da specifiche per uno o più intervalli di parametri, a seconda della proprietà .

In generale, il client non sa in anticipo quanto deve essere grande questo buffer di valori e deve inviare una o due richieste preliminari al gestore della proprietà per determinare le dimensioni del valore. Il formato per queste richieste preliminari è ben definito. I client prevedono che i driver seguano queste convenzioni durante la gestione di una richiesta di supporto di base:

• Se la richiesta specifica le dimensioni del valore come sizeof(ULONG), il gestore della proprietà deve scrivere il valore del membro AccessFlags della struttura KSPROPERTY_DESCRIPTION nel buffer dei valori di dimensioni ULONG. Il gestore imposta il bit del flag KSPROPERTY_TYPE_BASICSUPPORT se fornisce ulteriore supporto per le richieste di proprietà di supporto di base.

• Se la richiesta specifica le dimensioni del valore come sizeof(KSPROPERTY_DESCRIPTION), il gestore deve scrivere una struttura KSPROPERTY_DESCRIPTION nel buffer dei dati. Il gestore imposta il campo DescriptionSize della struttura uguale alle dimensioni della struttura e le dimensioni di tutte le informazioni aggiuntive specifiche della proprietà disponibili per il caricamento nel buffer di dati dopo la struttura. Si tratta delle dimensioni del buffer dei valori che il client deve allocare per contenere le informazioni di base sul supporto della proprietà.

• Se la richiesta specifica una dimensione del valore sufficientemente grande da contenere sia la struttura KSPROPERTY_DESCRIPTION che le informazioni specifiche della proprietà, il gestore deve scrivere la struttura KSPROPERTY_DESCRIPTION all'inizio del buffer e deve scrivere le informazioni specifiche della proprietà nella parte del buffer di dati che segue la fine della struttura KSPROPERTY_DESCRIPTION. Quando si scrive la struttura KSPROPERTY_DESCRIPTION, il gestore deve impostare il campo DescriptionSize sulle dimensioni di tale struttura più le dimensioni delle informazioni specifiche della proprietà che seguono la struttura.

Se la richiesta specifica una dimensione del valore che non corrisponde a uno di questi tre casi, il gestore della proprietà rifiuta la richiesta e restituisce il codice di stato STATUS_BUFFER_TOO_SMALL.

Le informazioni specifiche della proprietà che il gestore scrive nel buffer dei valori di valore possono includere intervalli di dati per i valori delle proprietà. Il membro MembersSize di KSPROPERTY_MEMBERSHEADER indica se sono inclusi intervalli di dati:

• MembersSize è zero se non sono necessari intervalli. Questo è il caso, ad esempio, se i valori delle proprietà sono di tipo BOOL.

• MembersSize è diverso da zero se la struttura KSPROPERTY_MEMBERSHEADER è seguita dai descrittori di intervallo per uno o più valori di proprietà.

Per un valore della proprietà di tipo BOOL, non è necessario alcun descrittore di intervallo perché l'intervallo è implicitamente limitato ai valori TRUE e FALSE. Tuttavia, i descrittori di intervallo sono necessari per specificare gli intervalli di valori delle proprietà con tipi integer.

Ad esempio, la richiesta di supporto di base per una proprietà KSPROPERTY_AUDIO_VOLUMELEVEL in un nodo del volume (KSNODETYPE_VOLUME) recupera le impostazioni del volume minimo e massimo per tale nodo. In questo caso, il client deve allocare un buffer di valori sufficientemente grande da contenere le strutture seguenti:

KSPROPERTY_DESCRIPTION

KSPROPERTY_MEMBERSLIST

KSPROPERTY_STEPPING_LONG

Le tre strutture vengono compresse in posizioni adiacenti nel buffer nell'ordine indicato nell'elenco precedente. Quando si gestisce la richiesta, il driver miniport scrive i livelli di volume minimo e massimo nel membro Bounds della struttura KSPROPERTY_STEPPING_LONG.

Per un esempio di richiesta di supporto di base con una matrice di descrittori di intervallo, vedere la figura in Esposizione di nodi multicanale. Per altre informazioni sulle richieste di proprietà di supporto di base, vedere Proprietà KS. Per esempi di codice, vedere le implementazioni del gestore di proprietà nei driver audio di esempio in Microsoft Windows Driver Kit (WDK).