IWMDMStorage4::GetReferences (deprecated)
.gif) |
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 GetReferences method retrieves an array of pointers to IWMDMStorage objects pointed to by this storage. An abstract album or playlist is typically stored as a collection of references on an MTP device.
Syntax
HRESULT GetReferences(
DWORD* pdwRefs,
IWMDMStorage*** pppIWMDMStorage
);
Parameters
pdwRefs
[out] Pointer to the count of values retrieved by pppIWMDMStorage. If the object has no references, this will return zero, and the function will return S_OK.
pppIWMDMStorage
[out] Pointer to a pointer to the array of IWMDMStorage interface pointers that represent references in a storage. Such references can, for example, represent items in a playlist or album. The retrieved array is in the same order as they appear in the object itself. Memory for this array is allocated by Windows Media Device Manager. When the calling application has finished accessing this array, it must first call Release on all of the interface pointers, and then free the array memory using CoTaskMemFree.
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. If the method fails with an error, it returns a standard error code.
| Return code | Description |
| S_OK | The method succeeded. |
| S_FALSE | The method succeeded. However, one or more items referenced by the storage on the device side have been deleted since the last call to SetReferences. |
| E_INVALIDARG | Either pointer pdwRefs or pppIWMDMStorage is NULL. |
| E_OUTOFMEMORY | Method could not be completed due to insufficient memory. |
| WMDM_E_INTERFACEDEAD | The storage interface represented by this IWMDMStorage4 interface has been deleted. |
Remarks
Windows Media Device Manager delegates to the underlying service provider the task of adding and removing the references on a storage. Objects with references refers to abstract objects such as abstract playlists or albums; folders are not considered as having references.
There are two types of asynchronous deletions that can occur and cause errors in this method. If a reference to a storage has been deleted since the application retrieved it, and the application tries to use the reference, the method call will return WMDM_E_INTERFACEDEAD. If the file the reference refers to has been deleted, S_FALSE is returned.
Example Code
The following C++ code queries for the references of a storage (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);
}
Requirements
Header: Defined in mswmdm.h.
Library: mssachlp.lib
See Also