IWMHeaderInfo::GetAttributeByIndex method (wmsdkidl.h)
[The feature associated with this page, Windows Media Format 11 SDK, is a legacy feature. It has been superseded by Source Reader and Sink Writer. Source Reader and Sink Writer have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Source Reader and Sink Writer instead of Windows Media Format 11 SDK, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
The GetAttributeByIndex method returns a descriptive attribute that is stored in the header section of the ASF file. This method is replaced by IWMHeaderInfo3::GetAttributeByIndexEx and should not be used.
Syntax
HRESULT GetAttributeByIndex(
[in] WORD wIndex,
[in] WORD *pwStreamNum,
[out] WCHAR *pwszName,
[in, out] WORD *pcchNameLen,
[out] WMT_ATTR_DATATYPE *pType,
[out] BYTE *pValue,
[in, out] WORD *pcbLength
);
Parameters
[in] wIndex
WORD containing the index.
[in] pwStreamNum
Pointer to a WORD containing the stream number. Although this parameter is a pointer, the method will not change the value. For file-level attributes, use zero for the stream number.
[out] pwszName
Pointer to a wide-character null-terminated string containing the name. Pass NULL to this parameter to retrieve the required length for the name. Attribute names are limited to 1024 wide characters.
[in, out] pcchNameLen
On input, a pointer to a variable containing the length of the pwszName array in wide characters (2 bytes). On output, if the method succeeds, the variable contains the actual length of the name, including the terminating null character.
[out] pType
Pointer to a variable containing one value from the WMT_ATTR_DATATYPE enumeration type.
[out] pValue
Pointer to a byte array containing the value. Pass NULL to this parameter to retrieve the required length for the value.
[in, out] pcbLength
On input, a pointer to a variable containing the length of the pValue array, in bytes. On output, if the method succeeds, the variable contains the actual number of bytes written to pValue by the method.
Return value
The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.
| Return code | Description |
|---|---|
|
The method succeeded. |
|
The object is not in a valid state, or no profile has been set. |
|
pwStreamNum does not point to a valid stream number, or no data type was supplied. |
|
A pointer supplied in a parameter was not valid. |
|
The method failed for an unspecified reason. |
|
The pValue array is too small to contain the attribute value. |
|
There is no attribute at wIndex. |
Remarks
You should make two calls to GetAttributeByIndex for each attribute you want to retrieve. On the first call, pass NULL for pwszName and pValue. On return, the value pointed to by pcchNameLen is set to the number of wide characters, including the terminating null character, required to hold the attribute name, and the value pointed to by pcbLength is set to the number of bytes required to hold the attribute value. You can then create buffers of the appropriate size to receive pwszName and pValue and pass pointers to them on the second call.
Attributes in MP3 files cannot be stream-specific. When using this method with MP3 files, you must use zero for the stream number.
For a list of all the predefined attributes, see Attributes.
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only],Windows Media Format 7 SDK, or later versions of the SDK |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | wmsdkidl.h (include Wmsdk.h) |
| Library | Wmvcore.lib; WMStubDRM.lib (if you use DRM) |