IShellLibrary::ResolveFolder-Methode (shobjidl_core.h)

Artikel
03/02/2024

Löst den Zielspeicherort eines Bibliotheksordners auf, auch wenn der Ordner verschoben oder umbenannt wurde.

Syntax

HRESULT ResolveFolder(
  [in]  IShellItem *psiFolderToResolve,
  [in]  DWORD      dwTimeout,
  [in]  REFIID     riid,
  [out] void       **ppv
);

Parameter

[in] psiFolderToResolve

Typ: IShellItem*

Ein IShellItem-Objekt , das den zu suchenden Bibliotheksordner darstellt.

[in] dwTimeout

Art: DWORD

Die maximale Zeit (in Millisekunden) versucht die Methode, den Ordner zu suchen, bevor sie zurückgibt. Wenn der Ordner nicht gefunden werden konnte, bevor die angegebene Zeit verstrichen ist, wird ein Fehler zurückgegeben.

[in] riid

Typ: REFIID

Ein Verweis auf die IID der in ppv abzurufenden Schnittstelle, die den aufgelösten Zielspeicherort darstellt. Dieser Wert ist in der Regel IID_IShellItem, kann aber auch IID_IShellItem2 oder die IID einer anderen Schnittstelle sein, die von CShellItem implementiert wird.

[out] ppv

Typ: void**

Ein Zeiger auf die in riid angeforderte Schnittstelle.

Rückgabewert

Typ: HRESULT

Diese Methode kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Der Zielordner wurde in ppv gefunden und zurückgegeben. die Bibliothek wurde jedoch aktualisiert, sodass IShellLibrary::Commit oder IShellLibrary::Save aufgerufen werden sollte, um diese Änderungen beizubehalten.
S_FALSE	Der Zielordner wurde in ppv gefunden und zurückgegeben.
E_	Diese Methode kann andere Fehlerwerte zurückgeben.

Hinweise

Diese Methode ist ein blockierender Aufruf, der den aufrufenden Thread so lange blockieren kann, wie die im dwTimeout-Parameter angegebene Zeit vor der Rückgabe. Da er den Thread blockiert, von dem aus er aufgerufen wird, sollte er nicht von einem Thread aufgerufen werden, der auch Interaktionen mit der Benutzeroberfläche verarbeitet.

Diese Methode fordert den Benutzer nicht auf, den Ordner manuell zu suchen, wenn der Speicherort nicht aufgelöst werden kann.

Der Einfachheit halber kann SHResolveFolderPathInLibrary anstelle dieser Methode verwendet werden.

Es wird empfohlen, das makro IID_PPV_ARGS zu verwenden, das in Objbase.h definiert ist, um die Parameter riid und ppv zu packen. Dieses Makro stellt die richtige IID basierend auf der Schnittstelle bereit, auf die der Wert in ppv verweist, wodurch die Möglichkeit eines Codierungsfehlers ausgeschlossen wird.

Beispiele

Das folgende Codebeispiel zeigt die Hilfsfunktion SHResolveFolderPathInLibrary, die diese Methode umschließt.

//
// from shobjidl.h
//
__inline HRESULT SHResolveFolderPathInLibrary(
    __in IShellLibrary *plib,
    __in PCWSTR pszFolderPath,
    __in DWORD dwTimeout,
    __deref_out PWSTR *ppszResolvedPath
)
{
    *ppszResolvedPath = NULL;
    PIDLIST_ABSOLUTE pidlFolder = 
      SHSimpleIDListFromPath(pszFolderPath);
    HRESULT hr = pidlFolder ? S_OK : E_INVALIDARG;
    if (SUCCEEDED(hr))
    {
        IShellItem *psiFolder;
        hr = SHCreateItemFromIDList(
          pidlFolder, 
          IID_PPV_ARGS(&psiFolder));

        if (SUCCEEDED(hr))
        {
            IShellItem *psiResolved;
            hr = plib->ResolveFolder(
              psiFolder, 
              dwTimeout, 
              IID_PPV_ARGS(&psiResolved));

            if (SUCCEEDED(hr))
            {
                hr = psiResolved->GetDisplayName(
                  SIGDN_DESKTOPABSOLUTEPARSING, 
                  ppszResolvedPath);
                psiResolved->Release();
            }
            psiFolder->Release();
        }
        CoTaskMemFree(pidlFolder);
    }
    return hr;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shobjidl_core.h (einschließlich Shobjidl.h)