Utilisation de marqueurs

[La fonctionnalité associée à cette page, le Kit de développement logiciel (SDK) Windows Media Format 11, est une fonctionnalité héritée. Il a été remplacé par lecteur source et enregistreur récepteur. Le lecteur source et l’enregistreur récepteur ont été optimisés pour Windows 10 et Windows 11. Microsoft recommande vivement que le nouveau code utilise le lecteur source et l’enregistreur récepteur au lieu du Kit de développement logiciel (SDK) Windows Media Format 11, lorsque cela est possible. Microsoft suggère que le code existant qui utilise les API héritées soit réécrit pour utiliser les nouvelles API si possible.]

Un marqueur est un point nommé dans un fichier ASF. Chaque marqueur se compose d’un nom et d’une heure associée, mesurée sous forme de décalage par rapport au début du fichier. Une application peut utiliser des marqueurs pour attribuer des noms à différents points du contenu, afficher ces noms à l’utilisateur, puis rechercher les positions du marqueur. Une application peut ajouter ou supprimer des marqueurs d’un fichier ASF existant.

L’interface IWMHeaderInfo contient des méthodes permettant d’utiliser des marqueurs. L’objet éditeur de métadonnées prend en charge l’ajout et la suppression de marqueurs. Les objets enregistreur et lecteur peuvent récupérer des marqueurs, mais ne peuvent pas ajouter ou supprimer des marqueurs.

Ajout de marqueurs

Pour ajouter un marqueur, interrogez l’éditeur de métadonnées pour l’interface IWMHeaderInfo . Appelez ensuite la méthode IWMHeaderInfo::AddMarker , en spécifiant le nom du marqueur sous forme de chaîne de caractères larges et l’heure en unités de 100 nanosecondes. Le temps ne doit pas dépasser la durée du fichier. Deux marqueurs peuvent avoir la même heure.

L’exemple suivant ajoute plusieurs marqueurs à un fichier :

IWMMetadataEditor *pEdit = 0;
IWMHeaderInfo     *pInfo = 0;

// Create the metadata editor object.

WMCreateEditor(&pEdit);
pEdit->Open(L"C:\\example.wmv");
pEdit->QueryInterface(IID_IWMHeaderInfo, (void**)&pInfo);

// Add the markers. Note that we add the last ones first. Do this when possible
// for improved performance when writing the markers to the file.
hr = pInfo->AddMarker(L"End",  520000000);   // 52 sec.
hr = pInfo->AddMarker(L"Segue",  350000000); // 35 sec.
hr = pInfo->AddMarker(L"Intro",  15000000);  // 1.5 sec.

// Commit changes and clean up.

pEdit->Flush();
pEdit->Close(); 
pInfo->Release();
pEdit->Release();

Suppression de marqueurs

Pour supprimer un marqueur, appelez IWMHeaderInfo::RemoveMarker, en spécifiant l’index du marqueur à supprimer. Les marqueurs étant triés automatiquement dans l’ordre de temps croissant, l’index 0 est toujours le premier marqueur. Notez que l’appel de RemoveMarker modifie les numéros d’index des marqueurs qui suivent. Le code suivant, où pInfo est un pointeur vers une interface IWMHeaderInfo , supprime tous les marqueurs d’un fichier :

WORD count = 0;
pInfo->GetMarkerCount(&count);
while (count--)
{
    pInfo->RemoveMarker(0);
}

Récupération des marqueurs

Pour récupérer le nom et l’heure d’un marqueur, procédez comme suit :

1. Appelez la méthode IWMHeaderInfo::GetMarkerCount pour déterminer le nombre de marqueurs que contient le fichier.
2. Récupérez la taille de la chaîne nécessaire pour contenir le nom du marqueur. Pour ce faire, appelez la méthode IWMHeaderInfo::GetMarker . Spécifiez l’index du marqueur à récupérer et NULL pour la mémoire tampon de chaîne (paramètre pwszMarkerName ). La méthode retourne la longueur de la chaîne, y compris le caractère « \0 » de fin, dans le paramètre pcchMarkerNameLen .
3. Allouez une chaîne à caractères larges pour recevoir le nom.
4. Appelez à nouveau GetMarker , mais cette fois passez l’adresse de la chaîne dans le paramètre pwszMarkerName . La méthode écrit le nom du marqueur dans la chaîne et retourne l’heure du marqueur dans le paramètre pcnsMarkerTime .

Le code suivant effectue une boucle à travers chaque marqueur dans l’ordre et récupère le nom et l’heure :

WORD cMarkers = 0;
HRESULT hr = pInfo->GetMarkerCount(&cMarkers);

WCHAR *wszName = 0;
WORD  len = 0;
for (WORD iMarker = 0; iMarker < cMarkers; ++iMarker)
{
    QWORD rtTime = 0;
    WORD req_len = 0;
    hr = pInfo->GetMarker(iMarker, 0, &req_len, &rtTime);
    
    // Reallocate if necessary.
    if (len < req_len)
    {
        delete[] wszName;
        wszName = new WCHAR[req_len];
        len = req_len;
    }
    hr = pInfo->GetMarker(iMarker, wszName, &req_len, &rtTime);
    // Display the name...
}
delete[] wszName;

Recherche d’un marqueur

Pour démarrer la lecture à partir d’un emplacement de marqueur, appelez la méthode IWMReaderAdvanced2::StartAtMarker de l’objet lecteur, en spécifiant l’index du marqueur. Les paramètres restants sont identiques à ceux de la méthode IWMReader::Start . L’exemple suivant interroge le lecteur pour l’interface IWMReaderAdvanced2 et recherche le premier marqueur.

IWMReaderAdvanced2 *pReader2 = 0
WORD iMarkerIndex = 0;
hr = pReader->QueryInterface(IID_IWMReaderAdvanced2, (void**)&pReader2);
if (SUCCEEDED(hr))
{
    hr = pPlayer2->StartAtMarker(iMarkerIndex, 0, 1.0, 0);
    pPlayer2->Release();
}

Rubriques connexes

IWMHeaderInfo Interface

IWMReaderAdvanced2::StartAtMarker

Utilisation des métadonnées