IWMDMMetaData::QueryByName (deprecated)

  • Article
banner art

This is preliminary documentation and subject to change.

This topic documents a feature of the Windows Media Device Manager SDK. We recommend that you migrate your application to use the Windows Portable Devices API. For more information, see the Windows Portable Devices SDK.

The QueryByName method retrieves the value of a property specified by name.

Syntax

HRESULT QueryByName(
  LPCWSTR  pwszTagName,
  WMDM_TAG_DATATYPE*  pType,
  BYTE**  pValue,
  UINT*  pcbLength
);

Parameters

pwszTagName

[in]  Pointer to a wide-character null-terminated string specifying the property name. A list of standard property name constants is given in Metadata Constants.

pType

[out]  An WMDM_TAG_DATATYPE enumerated value describing the type of data retrieved by pValue.

pValue

[out]  Pointer to a pointer to a byte array that receives the content of the value if the method succeeds. Windows Media Device Manager allocates this memory and the caller must free it using CoTaskMemFree.

pcbLength

[out]  Pointer to the size, in bytes, of the byte array ppValue. If the value is a string, this includes the termination character.

Return Values

The method returns an HRESULT. All the interface methods in Windows Media Device Manager can return any of the following classes of error codes:

  • Standard COM error codes
  • Windows error codes converted to HRESULT values
  • Windows Media Device Manager error codes

For an extenstive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Value Description
S_OK The method succeeded.
E_OUTOFMEMORY There is not enough memory to allocate the item.
E_INVALIDARG One or more parameters are invalid. This value is returned if the parameter specified by name is not supported by the service provider.

Example Code

The following C++ code queries for a file name and size.

HRESULT CWMDMController::myGetSpecifiedMetadata(IWMDMStorage* pStorage)
{
    HRESULT hr = S_OK;

    // Get an IWMDMStorage4 interface, which is required to specify metadata by name.
    CComPtr<IWMDMStorage4> pStorage4;
    hr = pStorage->QueryInterface(__uuidof(IWMDMStorage4), (void**)&pStorage4);
    CHECK_HR(hr, "Storage supports IWMDMStorage4 in myGetSpecifiedMetadata","Storage doesn't support IWMDMStorage4 in myGetSpecifiedMetadata");

    // Specify Add values to request. We will request the object name and size.
    LPCWSTR props[] = {g_wszWMDMFileName, g_wszWMDMFileSize};
    CComPtr<IWMDMMetaData> pMetadata;
    hr = pStorage4->GetSpecifiedMetadata(2, props, &pMetadata);
    CHECK_HR(hr, "GetSpecifiedMetadata succeeded in myGetSpecifiedMetadata","GetSpecifiedMetadata failed in myGetSpecifiedMetadata");

    // Now query for each value.
    BYTE* pVal = NULL;
    UINT len = 0;
    WMDM_TAG_DATATYPE datatype;
    hr = pMetadata->QueryByName(g_wszWMDMFileName, &datatype, &pVal, &len);
    if(FAILED(hr))
    {
        // TODO: Display a message that the item doesn't support the file name metadata value.
    }
    else
    {
        // TODO: Display the object name and the length of the string (including termination character).
        CoTaskMemFree(pVal);
        pVal = NULL;
    }

    hr = pMetadata->QueryByName(g_wszWMDMFileSize, &datatype, &pVal, &len);
    if(FAILED(hr))
    {
        // TODO: Display a message indicating that the item doesn't support the file size metadata value.
    }
    else
    {
        DWORD size = (*pVal) >> 10;
        // TODO: Display an message containing the object size in Mb 
        // and the number of bytes returned.
        CoTaskMemFree(pVal);
    }

    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also