Recupero delle funzionalità di formato tramite IWMDMDevice3
IWMDMDevice3::GetFormatCapability è il metodo preferito per chiedere a un dispositivo i formati supportati. I passaggi seguenti illustrano come usare questo metodo per eseguire query su un dispositivo per le relative funzionalità di formato:
- L'applicazione deve determinare quali formati supportano un dispositivo e quali sono di interesse. A tale scopo, l'applicazione può richiedere un elenco di formati supportati dal dispositivo chiamando IWMDMDevice3::GetProperty.
- L'applicazione esegue un ciclo attraverso tutti i formati supportati e richiede le funzionalità di formato di un dispositivo per un formato specifico (ad esempio WMA o WMV) chiamando IWMDMDevice3::GetFormatCapability e specificando un formato usando l'enumerazione WMDM_FORMATCODE . Questo metodo recupera una struttura WMDM_FORMAT_CAPABILITY .
- Scorrere tutte le strutture WMDM_PROP_CONFIG nella struttura WMDM_FORMAT_CAPABILITY recuperata. Ogni struttura WMDM_PROP_CONFIG contiene un gruppo di proprietà con valori supportati, che rappresentano una configurazione per tale formato. Ogni configurazione ha un numero di preferenza, dove un numero inferiore indica una preferenza maggiore per il dispositivo.
- Scorrere in ciclo tutte le strutture WMDM_PROP_DESC nel WMDM_PROP_CONFIG recuperato. Ogni WMDM_PROP_DESC contiene un elenco di coppie proprietà/valore supportate.
- Recuperare i nomi e i valori delle proprietà dalla struttura WMDM_PROP_DESC . Le proprietà includono velocità in bit, codec e dimensioni dei fotogrammi. I nomi delle proprietà sono definiti nel file di intestazione mswmdm.h; In Costanti metadati viene fornito un elenco della maggior parte di queste costanti. Sono possibili tre tipi di valori di proprietà:
- Valore singolo, WMDM_ENUM_PROP_VALID_VALUES_ANY, che indica il supporto per qualsiasi valore per questa proprietà.
- Intervallo di valori, definito da un valore massimo, un valore minimo e un intervallo.
- Elenco di valori discreti.
- Cancellare i valori archiviati. La memoria per questi valori viene allocata da Windows Media Gestione dispositivi; il dispositivo è responsabile della liberazione della memoria. Come eseguire questa operazione è descritta alla fine di questo argomento.
Quando risponde a GetFormatCapability, un dispositivo può segnalare WMDM_ENUM_PROP_VALID_VALUES_ANY per WMDM_FORMAT_CAPABILITY. WMDM_PROP_CONFIG. WMDM_PROP_DESC. ValidValuesForm per richiedere il supporto per qualsiasi valore per velocità in bit, canali e così via. Tuttavia, è consigliabile considerare questa attestazione con cautela, perché i dispositivi possono talvolta segnalare il supporto per qualsiasi valore quando in realtà non supportano tutte le frequenze di bit o le dimensioni delle immagini. È possibile prendere in considerazione la transcodifica dell'applicazione con file estremamente grandi o ad alta velocità in versioni più piccole o con un uso meno intensivo della memoria e della CPU durante l'invio a dispositivi destinati a riprodurre questi file.
La funzione C++ seguente illustra come richiedere il supporto del formato del dispositivo per un formato specifico.
HRESULT GetFormatCaps(WMDM_FORMATCODE formatCode, IWMDMDevice3* pDevice)
{
HRESULT hr = S_OK;
// Get a list of supported configurations for the format.
WMDM_FORMAT_CAPABILITY formatCapList;
hr = pDevice->GetFormatCapability(formatCode, &formatCapList);
if (FAILED(hr)) return E_FAIL;
// TODO: Display the format name.
// Loop through the configurations and examine each one.
for (UINT iConfig = 0; iConfig < formatCapList.nPropConfig; iConfig++)
{
WMDM_PROP_CONFIG formatConfig = formatCapList.pConfigs[iConfig];
// Preference level for this configuration (lower number means more preferred).
// TODO: Display the preference level for this format configuration.
// Loop through all properties for this configuration and get supported
// values for the property. Values can be a single value, a range,
// or a list of enumerated values.
for (UINT iDesc = 0; iDesc < formatConfig.nPropDesc; iDesc++)
{
WMDM_PROP_DESC propDesc = formatConfig.pPropDesc[iDesc];
// TODO: Display the property name.
// Three ways a value can be represented: any, a range, or a list.
switch (propDesc.ValidValuesForm)
{
case WMDM_ENUM_PROP_VALID_VALUES_ANY:
// TODO: Display a message indicating that all values are valid.
break;
case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
{
// List these in the docs as the propvariants set.
WMDM_PROP_VALUES_RANGE rng =
propDesc.ValidValues.ValidValuesRange;
// TODO: Display the min, max, and step values.
}
break;
case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
{
// TODO: Display a banner for the list of valid values.
WMDM_PROP_VALUES_ENUM list = propDesc.ValidValues.EnumeratedValidValues;
PROPVARIANT pVal;
for (UINT iValue = 0; iValue < list.cEnumValues; iValue++)
{
pVal = list.pValues[iValue];
// TODO: Display each valid value.
PropVariantClear(&pVal);
PropVariantInit(&pVal);
}
}
break;
default:
return E_FAIL,
break;
}
}
}
// Now clear the memory used by WMDM_FORMAT_CAPABILITY.
FreeFormatCapability(formatCapList);
return hr;
}
Cancellazione della memoria allocata
Dopo aver recuperato le funzionalità di formato da un dispositivo, l'applicazione deve liberare la memoria allocata per contenere la descrizione. GetFormatSupport e GetFormatSupport2 hanno matrici di strutture semplici che possono essere cancellate semplicemente chiamando CoTaskMemFree con la matrice. GetFormatCapability ha tuttavia una struttura di dati più complessa con memoria allocata dinamicamente che deve essere cancellata eseguendo un ciclo tra tutti gli elementi e liberandoli singolarmente.
Il codice C++ seguente illustra come un'applicazione può liberare la memoria allocata per una struttura di WMDM_FORMAT_CAPABILITY .
void CWMDMController::FreeFormatCapability(WMDM_FORMAT_CAPABILITY formatCap)
{
// Loop through all configurations.
for (UINT i = 0; i < formatCap.nPropConfig; i++)
{
// Loop through all descriptions of a configuration and delete
// the values particular to that description type.
for (UINT j=0; j < formatCap.pConfigs[i].nPropDesc; j++)
{
switch (formatCap.pConfigs[i].pPropDesc[j].ValidValuesForm)
{
case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
for (UINT k=0; k < formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.cEnumValues; k++)
{
PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.pValues[k]));
}
CoTaskMemFree(formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.pValues);
break;
case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeMin));
PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeMax));
PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeStep));
break;
case WMDM_ENUM_PROP_VALID_VALUES_ANY:
// No dynamically allocated memory for this value.
default:
break;
}
// Free the memory for the description name.
CoTaskMemFree(formatCap.pConfigs[i].pPropDesc[j].pwszPropName);
}
// Free the memory holding the array of description items for this configuration.
CoTaskMemFree(formatCap.pConfigs[i].pPropDesc);
}
// Free the memory pointing to the array of configurations.
CoTaskMemFree(formatCap.pConfigs);
formatCap.nPropConfig = 0;
}
Esecuzione di query per tutti i formati supportati
In genere, un'applicazione esegue una query su un dispositivo per un formato specifico, perché è interessato a inviare un file specifico al dispositivo. Tuttavia, se si vuole eseguire una query su un'applicazione per tutti i formati supportati, è possibile chiamare IWMDMDevice3::GetProperty e passare g_wszWMDMFormatsSupported per recuperare un elenco completo.
Se un dispositivo restituisce un solo elemento, WMDM_FORMATCODE_UNDEFINED, questo significa in genere che il dispositivo non supporta i codici di formato. La chiamata a GetFormatCapability con WMDM_FORMATCODE_UNDEFINED potrebbe recuperare funzionalità, ma queste proprietà potrebbero essere piuttosto generiche, ad esempio nome, dimensioni del file, data dell'ultima modifica e così via.
I passaggi seguenti illustrano come eseguire una query per un elenco di tutti i formati supportati:
- Richiedere un elenco di tutti i codici di formato supportati chiamando IWMDMDevice3::GetProperty e passando g_wszWMDMFormatsSupported. Viene restituito un VALORE PROPVARIANT contenente un SAFEARRAY di formati supportati.
- Scorrere gli elementi chiamando SafeArrayGetElement. Ogni elemento è un'enumerazione WMDM_FORMATCODE .
- Richiedere le funzionalità per ogni formato, liberando la memoria per ogni elemento WMDM_FORMAT_CAPABILITY al termine dell'operazione.
- Cancellare il valore PROPVARIANT recuperato nel passaggio 1 chiamando PropVariantClear.
Il codice di esempio C++ seguente recupera un elenco di formati supportati per un dispositivo.
// Query a device for supported configurations for each media or format type.
HRESULT CWMDMController::GetCaps(IWMDMDevice3* pDevice)
{
HRESULT hr = S_OK;
// Request the "formats supported" property to get a list of supported formats.
PROPVARIANT pvFormatsSupported;
PropVariantInit(&pvFormatsSupported);
hr = pDevice->GetProperty(g_wszWMDMFormatsSupported, &pvFormatsSupported);
HANDLE_HR(hr, "Got a property list in GetCaps", "Couldn't get a property list in GetCaps.");
// Loop through the retrieved format list.
// For each format, get a list of format configurations.
SAFEARRAY* formatList = pvFormatsSupported.parray;
WMDM_FORMATCODE formatCode = WMDM_FORMATCODE_NOTUSED;
for (LONG iCap = 0; iCap < formatList->rgsabound[0].cElements; iCap++)
{
// Get a format from the SAFEARRAY of retrieved formats.
SafeArrayGetElement(formatList, &iCap, &formatCode);
// Call a custom function to request the format capabilities.
if (formatCode != WMDM_FORMATCODE_NOTUSED)
myGetFormatCaps(formatCode, pDevice);
}
e_Exit:
// Clear out the memory we used.
PropVariantClear(&pvFormatsSupported);
return hr;
}
Argomenti correlati