IWMHeaderInfo::GetAttributeByName method

The GetAttributeByName method returns a descriptive attribute that is stored in the header section of the ASF file. Now that attribute names can be duplicated in a file, this method is obsolete. To find attributes of a particular name, use IWMHeaderInfo3::GetAttributeIndices.

Syntax


HRESULT GetAttributeByName(
  [in, out] WORD              *pwStreamNum,
  [in]      LPCWSTR           pszName,
  [out]     WMT_ATTR_DATATYPE *pType,
  [out]     BYTE              *pValue,
  [in, out] WORD              *pcbLength
);

Parameters

pwStreamNum [in, out]

Pointer to a WORD containing the stream number, or zero to indicate any stream. Although this parameter is a pointer, the method does not change the value.

pszName [in]

Pointer to a null-terminated string containing the name of the attribute. Attribute names are limited to 1024 wide characters.

pType [out]

Pointer to a variable that receives a value from the WMT_ATTR_DATATYPE enumeration type. The returned value specifies the data type of the attribute.

pValue [out]

Pointer to a byte array that receives the value of the attribute. The caller must allocate the array. To determine the required array size, set this parameter to NULL and check the value returned in the pcbLength parameter.

pcbLength [in, out]

On input, the length of the pValue array, in bytes. On output, if the method succeeds, the actual number of bytes that were written to pValue.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return codeDescription
S_OK

The method succeeded.

ASF_E_NOTFOUND

The specified attribute is not defined in this file.

E_INVALIDARG

pwStreamNum is not a valid stream number, pszName does not point to a wide-character string, or another parameter does not contain a valid value.

E_POINTER

A parameter is not a valid pointer.

E_UNEXPECTED

The method failed for an unspecified reason.

NS_E_INVALID_STATE

The object is not in a configurable state, or no profile has been set.

 

Remarks

Typically, an application should call this method twice for each attribute that it retrieves. On the first call, set the pValue parameter to NULL. The pcbLength parameter receives the buffer size needed to hold the attribute value. Then, allocate a sufficient byte array and call the method again, passing the address of the array in the pType parameter. The method fills the buffer with the value of the attribute. Coerce the buffer to the data type indicated by the value returned in pType.

If the file does not contain the specified attribute, the method might return ASF_E_NOTFOUND. The method can also succeed but return the value zero for pcbLength.

The objects of the Windows Media Format SDK perform type checking on some supported metadata attributes, but not all of them. You should ensure that any attributes you use are set using the data type specified in the Attributes section of this documentation. Likewise, you cannot assume that an attribute set by another application will use the correct data type.

Attributes in MP3 files cannot be specific to a particular stream. For MP3 files, always set the stream number to zero.

For a list of all the predefined attributes, see Attributes.

Examples

The following example code shows how to retrieve the "Title" attribute.



HRESULT hr;
IWMHeaderInfo *pInfo;
WORD wStreamNum = 0;
WMT_ATTR_DATATYPE Type;
WORD cbLength;
//
// First, retrieve the length of the string, and allocate memory.
//
hr = pInfo->GetAttributeByName( &wStreamNum, L"Title", 
                                &Type, NULL, &cbLength );
if( FAILED( hr ) )
{
    return( hr );
}
WCHAR *pwszTitle = (WCHAR *) new BYTE[ cbLength ];
if( !pwszTitle )
{
    return( E_OUTOFMEMORY );
}
//
// Now, retrieve the string itself.
//
hr = pInfo->GetAttributeByName( &wStreamNum, L"Title", &Type, 
                                (BYTE *) pwszTitle, &cbLength );
if( FAILED( hr ) )
{
    return( hr );
}


Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Version

Windows Media Format 7 SDK, or later versions of the SDK

Header

Wmsdkidl.h (include Wmsdk.h)

Library

Wmvcore.lib;
WMStubDRM.lib (if you use DRM)

See also

IWMHeaderInfo2
IWMHeaderInfo3
Attributes
IWMHeaderInfo Interface
IWMHeaderInfo::SetAttribute
WMT_ATTR_DATATYPE

 

 

Show: