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.

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

Confira também

IMoniker::GetDisplayName

IMoniker::P arseDisplayName

Iparsedisplayname