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

Artículo
03/15/2023

Resuelve la ubicación de destino de una carpeta de biblioteca, incluso si se ha movido o cambiado el nombre de la carpeta.

Sintaxis

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

Parámetros

[in] psiFolderToResolve

Tipo: IShellItem*

Objeto IShellItem que representa la carpeta de biblioteca que se va a buscar.

[in] dwTimeout

Tipo: DWORD

El tiempo máximo, en milisegundos, el método intentará localizar la carpeta antes de devolverla. Si no se pudo encontrar la carpeta antes de que transcurre el tiempo especificado, se devuelve un error.

[in] riid

Tipo: REFIID

Referencia al IID de la interfaz para obtener en ppv que representará la ubicación de destino resuelta. Este valor suele ser IID_IShellItem, pero también puede ser IID_IShellItem2 o el IID de cualquier otra interfaz implementada por CShellItem.

[out] ppv

Tipo: void**

Puntero a la interfaz solicitada en riid.

Valor devuelto

Tipo: HRESULT

Este método puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	La carpeta de destino se encuentra y se devuelve en ppv; sin embargo, se ha actualizado la biblioteca, por lo que se debe llamar a IShellLibrary::Commit o IShellLibrary::Save para conservar estos cambios.
S_FALSE	La carpeta de destino se encuentra y se devuelve en ppv.
E_	Este método puede devolver otros valores de error.

Comentarios

Este método es una llamada de bloqueo que puede bloquear el subproceso que realiza la llamada siempre que el tiempo especificado en el parámetro dwTimeout antes de devolverlo. Dado que bloquea el subproceso desde el que se llama, no debe llamarse desde un subproceso que también controla las interacciones de la interfaz de usuario.

Este método no pedirá al usuario que busque manualmente la carpeta si no puede resolver la ubicación.

Para mayor comodidad, se puede usar SHResolveFolderPathInLibrary en lugar de este método.

Se recomienda usar la macro IID_PPV_ARGS , definida en Objbase.h, para empaquetar los parámetros riid y ppv . Esta macro proporciona el IID correcto basado en la interfaz a la que apunta el valor de ppv, lo que elimina la posibilidad de un error de codificación.

Ejemplos

En el ejemplo de código siguiente se muestra la función auxiliar SHResolveFolderPathInLibrary, que encapsula este método.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shobjidl_core.h (include Shobjidl.h)