Obtention des fonctionnalités de format via IWMDMDevice3
IWMDMDevice3::GetFormatCapability est la méthode préférée pour demander à un appareil quels formats il prend en charge. Les étapes suivantes montrent comment utiliser cette méthode pour interroger un appareil pour connaître ses fonctionnalités de format :
- L’application doit déterminer les formats pris en charge par un appareil et ceux qui sont intéressants. Pour ce faire, l’application peut demander une liste des formats pris en charge par l’appareil en appelant IWMDMDevice3::GetProperty.
- L’application effectue une boucle dans tous les formats pris en charge et demande les fonctionnalités de format d’un appareil pour un format spécifique (tel que WMA ou WMV) en appelant IWMDMDevice3::GetFormatCapability et en spécifiant un format à l’aide de l’énumération WMDM_FORMATCODE . Cette méthode récupère une structure WMDM_FORMAT_CAPABILITY .
- Parcourez toutes les structures WMDM_PROP_CONFIG dans la structure WMDM_FORMAT_CAPABILITY récupérée. Chaque structure WMDM_PROP_CONFIG contient un groupe de propriétés avec des valeurs prises en charge, représentant une configuration pour ce format. Chaque configuration a un numéro de préférence, où un nombre inférieur indique une préférence plus grande de la part de l’appareil.
- Parcourez toutes les structures de WMDM_PROP_DESC dans le WMDM_PROP_CONFIG récupéré. Chaque WMDM_PROP_DESC contient une liste de paires propriété/valeur prises en charge.
- Récupérez les noms et les valeurs des propriétés à partir de la structure WMDM_PROP_DESC . Les propriétés incluent le débit binaire, le codec et la taille d’image. Les noms de propriétés sont définis dans le fichier d’en-tête mswmdm.h ; la liste de la plupart de ces constantes est donnée dans Constantes de métadonnées. Trois types de valeurs de propriété sont possibles :
- Une valeur unique, WMDM_ENUM_PROP_VALID_VALUES_ANY, indiquant la prise en charge de toutes les valeurs de cette propriété.
- Plage de valeurs, définie par une valeur maximale, une valeur minimale et un intervalle.
- Liste de valeurs discrètes.
- Effacez les valeurs stockées. La mémoire pour ces valeurs est allouée par Windows Media Gestionnaire de périphériques ; votre appareil est responsable de libérer la mémoire. La procédure à suivre est décrite à la fin de cette rubrique.
Quand vous répondez à GetFormatCapability, un appareil peut signaler WMDM_ENUM_PROP_VALID_VALUES_ANY pour WMDM_FORMAT_CAPABILITY. WMDM_PROP_CONFIG. WMDM_PROP_DESC. ValidValuesForm pour revendiquer la prise en charge de toutes les valeurs pour le débit binaire, les canaux, etc. Toutefois, vous devez traiter cette revendication avec prudence, car les appareils peuvent parfois signaler la prise en charge de toutes les valeurs alors qu’en fait, ils ne prennent pas en charge tous les débits binaires ou les tailles d’image. Vous pouvez envisager de faire en sorte que votre application transcode des fichiers extrêmement volumineux ou à débit élevé vers des versions plus petites ou des versions moins gourmandes en mémoire et en processeur lors de leur envoi à des appareils destinés à lire ces fichiers.
La fonction C++ suivante montre comment demander la prise en charge du format d’appareil pour un format spécifique.
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;
}
Effacement de la mémoire allouée
Après avoir récupéré les fonctionnalités de format d’un appareil, l’application doit libérer la mémoire allouée pour contenir la description. GetFormatSupport et GetFormatSupport2 ont des tableaux de structures simples qui peuvent être effacés en appelant simplement CoTaskMemFree avec le tableau. Toutefois, GetFormatCapability a une structure de données plus complexe avec une mémoire allouée dynamiquement qui doit être effacée en effectuant une boucle entre tous les éléments et en les libérant individuellement.
Le code C++ suivant montre comment une application peut libérer la mémoire allouée pour une structure 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;
}
Interrogation de tous les formats pris en charge
En règle générale, une application interroge un appareil pour un format spécifique, car elle souhaite envoyer un fichier spécifique à l’appareil. Toutefois, si vous souhaitez interroger une application pour tous ses formats pris en charge, vous pouvez appeler IWMDMDevice3::GetProperty et passer g_wszWMDMFormatsSupported pour récupérer une liste complète.
Si un appareil ne retourne qu’un seul élément, WMDM_FORMATCODE_UNDEFINED, cela signifie généralement que l’appareil ne prend pas en charge les codes de format. L’appel de GetFormatCapability avec WMDM_FORMATCODE_UNDEFINED peut récupérer des fonctionnalités, mais ces propriétés peuvent être assez génériques (telles que le nom, la taille du fichier, la date de la dernière modification, etc.).
Les étapes suivantes montrent comment rechercher une liste de tous les formats pris en charge :
- Demandez la liste de tous les codes de format pris en charge en appelant IWMDMDevice3::GetProperty et en transmettant g_wszWMDMFormatsSupported. Cette opération retourne un PROPVARIANT contenant un SAFEARRAY de formats pris en charge.
- Parcourez les éléments en appelant SafeArrayGetElement. Chaque élément est une énumération WMDM_FORMATCODE .
- Demandez les fonctionnalités pour chaque format, libérant la mémoire pour chaque élément WMDM_FORMAT_CAPABILITY une fois que vous l’avez terminé.
- Effacez le PROPVARIANT récupéré à l’étape 1 en appelant PropVariantClear.
L’exemple de code C++ suivant récupère une liste de formats pris en charge pour un appareil.
// 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;
}
Rubriques connexes