Método IWMDMStorage4::GetReferences (mswmdm.h)

Artigo
03/05/2024

O método GetReferences recupera uma matriz de ponteiros para objetos IWMDMStorage apontados por esse armazenamento. Um álbum abstrato ou playlist normalmente é armazenado como uma coleção de referências em um dispositivo MTP.

Sintaxe

HRESULT GetReferences(
  [out] DWORD        *pdwRefs,
  [out] IWMDMStorage ***pppIWMDMStorage
);

Parâmetros

[out] pdwRefs

Ponteiro para a contagem de valores recuperados por pppIWMDMStorage. Se o objeto não tiver referências, isso retornará zero e a função retornará S_OK.

[out] pppIWMDMStorage

Ponteiro para um ponteiro para a matriz de ponteiros da interface IWMDMStorage que representam referências em um armazenamento. Essas referências podem, por exemplo, representar itens em uma playlist ou álbum. A matriz recuperada está na mesma ordem em que aparecem no próprio objeto. A memória dessa matriz é alocada por Gerenciador de Dispositivos do Windows Media. Quando o aplicativo de chamada terminar de acessar essa matriz, ele deverá primeiro chamar Release em todos os ponteiros da interface e liberar a memória da matriz usando CoTaskMemFree.

Retornar valor

O método retorna um HRESULT. Todos os métodos de interface no Windows Media Gerenciador de Dispositivos podem retornar qualquer uma das seguintes classes de códigos de erro:

Códigos de erro COM padrão
Códigos de erro do Windows convertidos em valores HRESULT
Códigos de erro do Windows Media Gerenciador de Dispositivos

Para obter uma lista abrangente de possíveis códigos de erro, consulte Códigos de erro.

Comentários

O Windows Media Gerenciador de Dispositivos delega ao provedor de serviços subjacente a tarefa de adicionar e remover as referências em um armazenamento. Objetos com referências referem-se a objetos abstratos, como playlists abstratas ou álbuns; as pastas não são consideradas como tendo referências.

Há dois tipos de exclusões assíncronas que podem ocorrer e causar erros nesse método. Se uma referência a um armazenamento tiver sido excluída desde que o aplicativo a recuperou e o aplicativo tentar usar a referência, a chamada de método retornará WMDM_E_INTERFACEDEAD. Se o arquivo ao qual a referência se refere tiver sido excluído, S_FALSE será retornado.

Exemplos

O código C++ a seguir consulta as referências de um armazenamento (pStorage).


// Get references.
CComQIPtr<IWMDMStorage4> pStorage4(pStorage);
if (pStorage4 != NULL)
{
    WCHAR name[100];
    DWORD numRefs = 0;
    IWMDMStorage** parrReferences;
    hr = pStorage4->GetReferences(&numRefs, &parrReferences);
    for(int i = 0; i < numRefs; i++)
    {
        ZeroMemory(name, sizeof(name));
        hr = parrReferences[i]->GetName(name, (sizeof(name) / sizeof(WCHAR)) - 1);
        if (hr == S_OK)
            // TODO: Display the name.
        parrReferences[i]->Release();
    }
    // Free the memory.
    if (parrReferences != NULL)
        CoTaskMemFree(parrReferences);
}