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

Artigo
03/02/2024

Resolve o local de destino de uma pasta de biblioteca, mesmo que a pasta tenha sido movida ou renomeada.

Sintaxe

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

Parâmetros

[in] psiFolderToResolve

Tipo: IShellItem*

Um objeto IShellItem que representa a pasta de biblioteca a ser localizada.

[in] dwTimeout

Tipo: DWORD

O tempo máximo, em milissegundos, o método tentará localizar a pasta antes de retornar. Se a pasta não puder ser localizada antes do tempo especificado passar, um erro será retornado.

[in] riid

Tipo: REFIID

Uma referência ao IID da interface a ser obtido em ppv que representará o local de destino resolvido. Esse valor normalmente é IID_IShellItem, mas também pode ser IID_IShellItem2 ou o IID de qualquer outra interface implementada pelo CShellItem.

[out] ppv

Tipo: void**

Um ponteiro para a interface solicitada no riid.

Retornar valor

Tipo: HRESULT

Esse método pode retornar um desses valores.

Código de retorno	Descrição
S_OK	A pasta de destino foi localizada e retornada em ppv; no entanto, a biblioteca foi atualizada para que IShellLibrary::Commit ou IShellLibrary::Save seja chamado para persistir essas alterações.
S_FALSE	A pasta de destino foi localizada e retornada em ppv.
E_	Esse método pode retornar outros valores de erro.

Comentários

Esse método é uma chamada de bloqueio que pode bloquear o thread de chamada, desde que o tempo especificado no parâmetro dwTimeout antes de retornar. Como ele bloqueia o thread do qual ele é chamado, ele não deve ser chamado de um thread que também manipula as interações da interface do usuário.

Esse método não solicitará que o usuário localize manualmente a pasta se não puder resolve o local.

Para sua conveniência, SHResolveFolderPathInLibrary pode ser usado no lugar desse método.

É recomendável que você use a macro IID_PPV_ARGS , definida em Objbase.h, para empacotar os parâmetros riid e ppv . Essa macro fornece o IID correto com base na interface apontada pelo valor em ppv, o que elimina a possibilidade de um erro de codificação.

Exemplos

O exemplo de código a seguir mostra a função auxiliar SHResolveFolderPathInLibrary, que encapsula esse 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	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shobjidl_core.h (inclua Shobjidl.h)