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 |
|---|---|
|
A operação de análise foi bem-sucedida e o moniker foi criado. |
|
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:
- 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.
- 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.
- 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.
- 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) |