Méthode IShellLibrary ::ResolveFolder (shobjidl_core.h)

Article
03/02/2024

Résout l’emplacement cible d’un dossier de bibliothèque, même si le dossier a été déplacé ou renommé.

Syntaxe

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

Paramètres

[in] psiFolderToResolve

Type : IShellItem*

Objet IShellItem qui représente le dossier de bibliothèque à localiser.

[in] dwTimeout

Type : DWORD

Durée maximale, en millisecondes, de la méthode tente de localiser le dossier avant de revenir. Si le dossier n’a pas pu être localisé avant l’expiration du temps spécifié, une erreur est retournée.

[in] riid

Type : REFIID

Référence à l’IID de l’interface à obtenir dans ppv qui représente l’emplacement cible résolu. Cette valeur est généralement IID_IShellItem, mais elle peut également être IID_IShellItem2 ou l’IID de toute autre interface implémentée par CShellItem.

[out] ppv

Type : void**

Pointeur vers l’interface demandée dans riid.

Valeur retournée

Type : HRESULT

Cette méthode peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	Le dossier cible a été localisé et retourné dans ppv ; Toutefois, la bibliothèque a été mise à jour. IShellLibrary ::Commit ou IShellLibrary ::Save doivent donc être appelés pour conserver ces modifications.
S_FALSE	Le dossier cible a été localisé et retourné dans ppv.
E_	Cette méthode peut retourner d’autres valeurs d’erreur.

Remarques

Cette méthode est un appel bloquant qui peut bloquer le thread appelant tant que le temps spécifié dans le paramètre dwTimeout avant de retourner. Étant donné qu’il bloque le thread à partir duquel il est appelé, il ne doit pas être appelé à partir d’un thread qui gère également les interactions de l’interface utilisateur.

Cette méthode n’invite pas l’utilisateur à localiser manuellement le dossier s’il ne peut pas résoudre l’emplacement.

Pour des raisons pratiques, SHResolveFolderPathInLibrary peut être utilisé à la place de cette méthode.

Il est recommandé d’utiliser la macro IID_PPV_ARGS , définie dans Objbase.h, pour empaqueter les paramètres riid et ppv . Cette macro fournit l’IID correct en fonction de l’interface pointée par la valeur dans ppv, ce qui élimine la possibilité d’une erreur de codage.

Exemples

L’exemple de code suivant montre la fonction d’assistance SHResolveFolderPathInLibrary, qui encapsule cette méthode.

//
// 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;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (incluez Shobjidl.h)