Função MkParseDisplayName (objbase.h)

Converte uma cadeia de caracteres em um moniker que identifica o objeto chamado pela cadeia de caracteres.

Essa função é o inverso da operação IMoniker::GetDisplayName , que recupera o nome de exibição associado a um moniker.

Sintaxe

HRESULT MkParseDisplayName(
  [in]  LPBC      pbc,
  [in]  LPCOLESTR szUserName,
  [out] ULONG     *pchEaten,
  [out] LPMONIKER *ppmk
);

Parâmetros

[in] pbc

Um ponteiro para a interface IBindCtx no objeto de contexto de associação a ser usado nesta operação de associação.

[in] szUserName

Um ponteiro para o nome de exibição a ser analisado.

[out] pchEaten

Um ponteiro para o número de caracteres de szUserName que foram consumidos. Se a função for bem-sucedida, *pchEaten será o comprimento de szUserName; caso contrário, é o número de caracteres analisados com êxito.

[out] ppmk

O endereço da variável de ponteiro IMoniker* que recebe o ponteiro de interface para o moniker que foi criado a partir de szUserName. Quando bem-sucedida, a função chamou AddRef no moniker e o chamador é responsável por chamar Release. Se ocorrer um erro, o ponteiro de interface especificado conterá o máximo de moniker que o método foi capaz de criar antes do erro ocorrer.

Retornar valor

Essa função pode retornar o valor de retorno padrão E_OUTOFMEMORY, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	A operação de análise foi bem-sucedida e o moniker foi criado.
MK_E_SYNTAX	Erro na sintaxe de um nome de arquivo ou um erro na sintaxe do moniker composto resultante.

 

Essa função também pode retornar qualquer um dos valores de erro retornados por IMoniker::BindToObject, IOleItemContainer::GetObject ou IParseDisplayName::P arseDisplayName.

Comentários

A função MkParseDisplayName analisa um nome legível por humanos em um moniker que pode ser usado para identificar uma fonte de link. O moniker resultante pode ser um moniker simples (como um moniker de arquivo), ou pode ser uma composição genérica composta pelas peças de moniker do componente. Por exemplo, o nome de exibição "c:\mydir\somefile!item 1"

pode ser analisado no seguinte moniker composto genérico: FileMoniker com base em "c:\mydir\somefile") + (ItemMoniker baseado em "item 1").

O uso mais comum de MkParseDisplayName está na implementação da caixa de diálogo Links padrão, que permite que um usuário final especifique a origem de um objeto vinculado digitando em uma cadeia de caracteres. Talvez você também precise chamar MkParseDisplayName se o aplicativo der suporte a uma linguagem de macro que permita referências remotas (referência a elementos fora do documento).

A análise de um nome de exibição geralmente requer a ativação dos mesmos objetos que seriam ativados durante uma operação de associação, para que ele possa ser tão caro (em termos de desempenho) quanto a associação. Objetos associados durante a operação de análise são armazenados em cache no contexto de associação passado para a função. Se você planeja associar o moniker retornado por MkParseDisplayName, é melhor fazê-lo imediatamente após o retorno da função, usando o mesmo contexto de associação, o que remove a necessidade de ativar objetos uma segunda vez.

MkParseDisplayName analisa tanto o nome de exibição quanto ele entende em um moniker. Em seguida, a função chama IMoniker::P arseDisplayName no moniker recém-criado, passando o restante do nome de exibição. O moniker retornado por ParseDisplayName é composto no final do moniker existente e, se qualquer um dos nomes de exibição permanecer desparsado, ParseDisplayName será chamado no resultado da composição. Esse processo é repetido até que todo o nome de exibição tenha sido analisado.

MkParseDisplayName tenta as seguintes estratégias para analisar o início do nome de exibição, usando o primeiro que é bem-sucedido:

1. A função procura na Tabela de Objetos em Execução os monikers de arquivo correspondentes a todos os prefixos do nome de exibição que consistem apenas em caracteres de nome de arquivo válidos. Essa estratégia pode identificar documentos que ainda não foram salvos.
2. A função verifica o prefixo máximo do nome de exibição, que consiste apenas em caracteres de nome de arquivo válidos, para ver se um documento OLE 1 está registrado por esse nome. Nesse caso, o moniker retornado é um moniker interno fornecido pela camada de compatibilidade OLE 1 do OLE 2.
3. A função consulta o sistema de arquivos para marcar se um prefixo do nome de exibição corresponde a um arquivo existente. O nome do arquivo pode ser absoluto, relativo à unidade, relativo ao diretório de trabalho ou começar com um nome de compartilhamento de rede explícito. Este é o caso comum.
4. Se o caractere inicial do nome de exibição for '@', a função encontrará a cadeia de caracteres mais longa imediatamente após ela que está em conformidade com a sintaxe progID legal. A função converte essa cadeia de caracteres em um CLSID usando a função CLSIDFromProgID . Se o CLSID representar uma classe OLE 2, a função carregará o objeto de classe correspondente e solicitará um ponteiro de interface IParseDisplayName . A interface IParseDisplayName resultante recebe a cadeia de caracteres inteira a ser analisada, começando com '@'. Se o CLSID representar uma classe OLE 1, a função tratará a cadeia de caracteres seguindo o ProgID como um designador de link OLE1/DDE com sintaxe deitem de nome de arquivo|.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	objbase.h
Biblioteca	Ole32.lib
DLL	Ole32.dll
Conjunto de APIs	ext-ms-win-com-ole32-l1-1-1 (introduzido em Windows 8.1)

Confira também

IMoniker::GetDisplayName

IMoniker::P arseDisplayName

Iparsedisplayname