Uso di marcatori

[La funzionalità associata a questa pagina, Windows Media Format 11 SDK, è una funzionalità legacy. È stata sostituita da Lettore di origine e Writer sink. Lettore di origine e Writer sink sono stati ottimizzati per Windows 10 e Windows 11. Microsoft consiglia vivamente che il nuovo codice usi Lettore di origine e Writer sink anziché Windows Media Format 11 SDK, quando possibile. Microsoft suggerisce che il codice esistente che usa le API legacy venga riscritto per usare le nuove API, se possibile.

Un marcatore è un punto denominato all'interno di un file ASF. Ogni marcatore è costituito da un nome e un tempo associato, misurato come offset dall'inizio del file. Un'applicazione può usare marcatori per assegnare nomi a vari punti all'interno del contenuto, visualizzare tali nomi all'utente e quindi cercare le posizioni del marcatore. Un'applicazione può aggiungere o rimuovere marcatori da un file ASF esistente.

L'interfaccia IWMHeaderInfo contiene metodi per l'uso di marcatori. L'oggetto editor di metadati supporta l'aggiunta e la rimozione di marcatori. Gli oggetti writer e lettore possono recuperare indicatori, ma non possono aggiungere o rimuovere marcatori.

Aggiunta di marcatori

Per aggiungere un marcatore, eseguire una query sull'editor di metadati per l'interfaccia IWMHeaderInfo . Chiamare quindi il metodo IWMHeaderInfo::AddMarker , specificando il nome del marcatore come stringa di caratteri wide e l'ora in unità a 100 nanosecondi. Il tempo non deve superare la durata del file. Due marcatori possono avere lo stesso tempo.

Nell'esempio seguente vengono aggiunti diversi marcatori a un file:

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();

Rimozione di marcatori

Per rimuovere un marcatore, chiamare IWMHeaderInfo::RemoveMarker, specificando l'indice del marcatore da rimuovere. I marcatori vengono ordinati automaticamente in ordine di tempo crescente, quindi l'indice 0 è sempre il primo marcatore. Si noti che la chiamata a RemoveMarker modifica i numeri di indice di tutti i marcatori che seguono. Il codice seguente, dove pInfo è un puntatore a un'interfaccia IWMHeaderInfo , rimuove tutti i marcatori da un file:

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

Recupero di marcatori

Per recuperare il nome e l'ora di un marcatore, seguire questa procedura:

1. Chiamare il metodo IWMHeaderInfo::GetMarkerCount per determinare il numero di marcatori contenuti nel file.
2. Recuperare le dimensioni della stringa necessaria per contenere il nome del marcatore. A tale scopo, chiamare il metodo IWMHeaderInfo::GetMarker . Specificare l'indice del marcatore da recuperare e NULL per il buffer stringa (parametro pwszMarkerName ). Il metodo restituisce la lunghezza della stringa, incluso il carattere di terminazione '\0', nel parametro pcchMarkerNameLen .
3. Allocare una stringa di caratteri wide per ricevere il nome.
4. Chiamare di nuovo GetMarker , ma questa volta passare l'indirizzo della stringa nel parametro pwszMarkerName . Il metodo scrive il nome del marcatore nella stringa e restituisce il tempo di marcatore nel parametro pcnsMarkerTime .

Il codice seguente esegue il ciclo di ogni marcatore nell'ordine e recupera il nome e il tempo:

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;

Ricerca di un marcatore

Per avviare la riproduzione da una posizione dell'indicatore, chiamare il metodo IWMReaderAdvanced2::StartAtMarker , specificando l'indice dell'indicatore. I parametri rimanenti sono identici a quelli per il metodo IWMReader::Start . L'esempio seguente esegue una query sul lettore per l'interfaccia IWMReaderAdvanced2 e cerca il primo marcatore.

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();
}

Argomenti correlati

Interfaccia IWMHeaderInfo

IWMReaderAdvanced2::StartAtMarker

Uso dei metadati