PCHANGE_BANDWIDTH_ALLOCATION funzione di callback (hdaudio.h)

Articolo
08/07/2023

La ChangeBandwidthAllocation routine modifica l'allocazione della larghezza di banda di un motore DMA nel collegamento audio HD.

Il tipo di puntatore a funzione per una ChangeBandwidthAllocation routine è definito come segue.

Sintassi

PCHANGE_BANDWIDTH_ALLOCATION PchangeBandwidthAllocation;

NTSTATUS PchangeBandwidthAllocation(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parametri

[in] _context

Specifica il valore di contesto dal membro Context della struttura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 o HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Gestire l'identificazione del motore DMA. Questo valore handle è stato ottenuto da una chiamata precedente a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

[in] StreamFormat

Specifica il formato del flusso richiesto. Questo parametro punta a una struttura allocata dal chiamante di tipo HDAUDIO_STREAM_FORMAT che specifica un formato di dati per il flusso.

[out] ConverterFormat

Recupera il formato del convertitore. Questo parametro punta a una struttura allocata dal chiamante di tipo HDAUDIO_CONVERTER_FORMAT in cui la routine scrive il formato codificato. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

ChangeBandwidthAllocation restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, la routine restituisce un codice di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore restituiti.

Codice restituito	Descrizione
STATUS_UNSUCCESSFUL	Indica che il chiamante è in esecuzione in un runtime di integrazione troppo elevato.
STATUS_INVALID_HANDLE	Indica che il valore del parametro handle non è valido.
STATUS_INVALID_PARAMETER	Indica che uno dei valori dei parametri non è corretto (un puntatore non valido o un formato di flusso non valido).
STATUS_BUFFER_TOO_SMALL	Indica che il motore DMA non è in grado di allocare spazio di archiviazione FIFO interno sufficiente per supportare il formato del flusso richiesto.
STATUS_INSUFFICIENT_RESOURCES	Indica che è disponibile una larghezza di banda insufficiente per soddisfare la richiesta.
STATUS_INVALID_DEVICE_REQUEST	Indica che il flusso non è nello stato di reimpostazione o che un buffer è ancora allocato per il motore DMA.

Commenti

Il chiamante ottiene un'allocazione iniziale della larghezza di banda per un motore DMA chiamando AllocateCaptureDmaEngine o AllocateRenderDmaEngine. Successivamente, il chiamante può modificare l'allocazione della larghezza di banda chiamando ChangeBandwidthAllocation.

Tramite il parametro converterFormat , la routine restituisce un valore descrittore di flusso che il chiamante può usare per programmare i convertitori di input o di output. La routine codifica le informazioni dal parametro streamFormat in un numero intero a 16 bit. Per altre informazioni, vedere HDAUDIO_CONVERTER_FORMAT.

Questa routine ha esito negativo e restituisce il codice di errore STATUS_INVALID_DEVICE_REQUEST in una delle circostanze seguenti:

Qualsiasi buffer DMA allocato in precedenza non è stato liberato (chiamando FreeDmaBuffer o FreeContiguousDmaBuffer).
Il flusso è in uno stato diverso da reset.

Se la ChangeBandwidthAllocation chiamata non riesce, la prenotazione della larghezza di banda esistente rimane attiva. L'allocazione della larghezza di banda cambia solo se la chiamata ha esito positivo.

In Windows Vista e versioni successive, un driver miniport wave chiama questa routine durante l'esecuzione del relativo metodo SetFormat (dopo aver chiamato una delle routine AllocateXxxDmaEngine in HD Audio DDI). Per altre informazioni, vedere IMiniportWavePciStream::SetFormat.