Método IShellFolder::P arseDisplayName (shobjidl_core.h)

  • Artigo

Converte o nome de exibição de um objeto de arquivo ou uma pasta em uma lista de identificadores de item.

Sintaxe

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

Parâmetros

[in] hwnd

Digite: HWND

Um identificador de janela. O cliente deverá fornecer um identificador de janela se exibir uma caixa de diálogo ou mensagem. Caso contrário, defina hwnd como NULL.

[in] pbc

Tipo: IBindCtx*

Opcional. Um ponteiro para um contexto de associação usado para passar parâmetros como entradas e saídas para a função de análise. Esses parâmetros passados geralmente são específicos da fonte de dados e são documentados pelos proprietários da fonte de dados. Por exemplo, a fonte de dados do sistema de arquivos aceita o nome que está sendo analisado (como uma estrutura WIN32_FIND_DATA ), usando o parâmetro de contexto de associação STR_FILE_SYS_BIND_DATA . STR_PARSE_PREFER_FOLDER_BROWSING pode ser passado para indicar que as URLs são analisadas usando a fonte de dados do sistema de arquivos quando possível. Construa um objeto de contexto de associação usando CreateBindCtx e preencha os valores usando IBindCtx::RegisterObjectParam. Consulte Associar chaves de cadeia de caracteres de contexto para obter uma lista completa dessas chaves.

Se nenhum dado estiver sendo passado ou recebido da função de análise, esse valor poderá ser NULL.

[in] pszDisplayName

Tipo: LPWSTR

Uma cadeia de caracteres Unicode terminada em nulo com o nome de exibição. Como cada pasta shell define sua própria sintaxe de análise, o formulário que essa cadeia de caracteres pode tomar pode variar. A pasta da área de trabalho, por exemplo, aceita caminhos como "C:\My Docs\My File.txt". Ele também aceitará referências a itens no namespace que têm um GUID associado a eles usando a sintaxe "::{GUID}". Por exemplo, para recuperar uma lista de identificadores totalmente qualificados para o painel de controle da pasta da área de trabalho, você pode usar o seguinte:

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

Tipo: ULONG*

Um ponteiro para um valor ULONG que recebe o número de caracteres do nome de exibição que foi analisado. Se o aplicativo não precisar dessas informações, defina pchEaten como NULL e nenhum valor será retornado.

[out] ppidl

Tipo: PIDLIST_RELATIVE*

Quando esse método retorna, contém um ponteiro para o PIDL para o objeto . A lista de identificadores de item retornado especifica o item relativo à pasta de análise. Se o objeto associado a pszDisplayName estiver dentro da pasta de análise, a lista de identificadores de item retornado conterá apenas uma estrutura SHITEMID . Se o objeto estiver em uma subpasta da pasta de análise, a lista de identificadores de item retornado conterá várias estruturas SHITEMID . Se ocorrer um erro, NULL será retornado neste endereço.

Quando ele não é mais necessário, é responsabilidade do chamador liberar esse recurso chamando CoTaskMemFree.

[in, out] pdwAttributes

Tipo: ULONG*

O valor usado para consultar atributos de arquivo. Se não for usado, ele deverá ser definido como NULL. Para consultar um ou mais atributos, inicialize esse parâmetro com os sinalizadores SFGAO que representam os atributos de interesse. No retorno, os atributos que são verdadeiros e solicitados serão definidos.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Algumas pastas shell podem não implementar IShellFolder::P arseDisplayName. Cada pasta que o fizer definirá sua própria sintaxe de análise.

Não se espera que ParseDisplayName manipule o caminho relativo ou os indicadores de pasta pai ("." ou ".."). Cabe ao chamador removê-los adequadamente.

Não use o sinalizador SFGAO_VALIDATE em pdwAttributes para verificar a existência do item cujo nome está sendo analisado. IShellFolder::P arseDisplayName valida implicitamente a existência do item, a menos que esse comportamento seja substituído por um parâmetro de contexto de associação especial.

A consulta de alguns atributos pode ser relativamente lenta e usar quantidades significativas de memória. Por exemplo, para determinar se um arquivo é compartilhado, o Shell carregará componentes de rede. Esse procedimento pode exigir o carregamento de várias DLLs. A finalidade de pdwAttributes é permitir que você restrinja a consulta apenas a essas informações necessárias. O fragmento de código a seguir ilustra como descobrir se um arquivo é compactado.

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

Como pdwAttributes é um parâmetro de entrada/saída, ele sempre deve ser inicializado. Se você passar um valor não inicializado, alguns dos bits poderão ser inadvertidamente definidos. IShellFolder::P arseDisplayName consultará os atributos correspondentes, o que pode levar a atrasos indesejáveis ou demandas de memória. Se você não quiser consultar atributos, defina pdwAttributes como NULL para evitar comportamento imprevisível.

Esse método é semelhante ao método IParseDisplayName::P arseDisplayName .

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shobjidl_core.h (inclua Shobjidl.h)
DLL Shell32.dll (versão 4.0 ou posterior)

Confira também

Ishellfolder

IShellFolder2

IShellFolder::GetAttributesOf

IShellLink