Método IMoniker::CommonPrefixWith (objidl.h)

  • Artigo

Cria um novo moniker com base no prefixo que esse moniker tem em comum com o moniker especificado.

Sintaxe

HRESULT CommonPrefixWith(
  [in]  IMoniker *pmkOther,
  [out] IMoniker **ppmkPrefix
);

Parâmetros

[in] pmkOther

Um ponteiro para a interface IMoniker em outro moniker a ser comparado com este para determinar se há um prefixo comum.

[out] ppmkPrefix

O endereço de uma variável de ponteiro IMoniker* que recebe o ponteiro de interface para o moniker que é o prefixo comum desse moniker e pmkOther. Quando bem-sucedida, a implementação deve chamar AddRef no moniker resultante; é responsabilidade do chamador chamar Release. Se ocorrer um erro ou se não houver nenhum prefixo comum, a implementação deverá definir *ppmkPrefix como NULL.

Retornar valor

Esse método pode retornar os valores de retorno padrão E_OUTOFMEMORY, bem como os valores a seguir.

Código de retorno Descrição
S_OK
 Existe um prefixo comum que não é nem esse moniker nem pmkOther.
MK_S_NOPREFIX
 Não existe nenhum prefixo comum.
MK_S_HIM
 O pmkOther inteiro é um prefixo desse moniker.
MK_S_US
 Os dois monikers são idênticos.
MK_S_ME
 Esse moniker é um prefixo do moniker pmkOther .
MK_S_NOTBINDABLE
 Esse método foi chamado em um moniker relativo. Não é significativo usar o prefixo comum em um moniker relativo.

Comentários

CommonPrefixWith cria um novo moniker que consiste nos prefixos comuns do moniker neste objeto moniker e outro moniker. Por exemplo, se um moniker representa o caminho "c:\projects\secret\art\pict1.bmp" e outro moniker representa o caminho "c:\projects\secret\docs\chap1.txt", o prefixo comum desses dois monikers seria um moniker que representa o caminho "c:\projects\secret".

Anotações para chamadores

O método CommonPrefixWith é chamado principalmente na implementação do método IMoniker::RelativePathTo . Os clientes que usam um moniker para localizar um objeto raramente precisam chamar esse método.

Chame esse método somente se pmkOther e esse moniker forem monikers absolutos. Um moniker absoluto é um moniker de arquivo ou uma composição genérica cujo componente mais à esquerda é um moniker de arquivo que representa um caminho absoluto. Não chame esse método em monikers relativos porque ele não produziria resultados significativos.

Anotações aos implementadores

Sua implementação deve primeiro determinar se pmkOther é um moniker de uma classe que você reconhece e para a qual você pode fornecer tratamento especial (por exemplo, se for da mesma classe que este moniker). Nesse caso, sua implementação deve determinar o prefixo comum dos dois monikers. Caso contrário, ele deverá passar ambos os monikers em uma chamada para a função MonikerCommonPrefixWith , que manipula corretamente o caso genérico.

Notas específicas da implementação

Implementação Observações
Anti-moniker Se o outro moniker também for um anti-moniker, o método retornará MK_S_US e definirá ppmkPrefix para esse moniker. Caso contrário, o método chamará a função MonikerCommonPrefixWith . Essa função manipula corretamente o caso em que o outro moniker é uma composição genérica.
Moniker de classe Se pmkOther for igual a esse moniker, recuperará um ponteiro para esse moniker e retornará MK_S_US. Se pmkOther for um moniker de classe, mas não for igual a esse moniker, retornará MK_E_NOPREFIX. Caso contrário, retorna o resultado de chamar MonikerCommonPrefixWith consigo mesmo como pmkThis, pmkOther e ppmkPrefix, que manipula o caso em que pmkOther é um moniker composto genérico.
Moniker de arquivo Se ambos os monikers forem monikers de arquivo, esse método retornará um moniker de arquivo baseado nos componentes comuns no início de dois monikers de arquivo. Os componentes de um moniker de arquivo podem ser dos seguintes tipos:
  • Um nome de computador do formulário \\server\share. Um nome de computador é tratado como um único componente, portanto, dois monikers que representam os caminhos "\\myserver\public\work" e "\\myserver\private\games" não têm "\\myserver" como um prefixo comum.
  • Uma designação de unidade (por exemplo, "C:").
  • Um diretório ou nome de arquivo.
Se o outro moniker não for um moniker de arquivo, esse método passará os dois monikers em uma chamada para a função MonikerCommonPrefixWith . Essa função manipula corretamente o caso em que o outro moniker é uma composição genérica.

Esse método retornará MK_E_NOPREFIX se não houver nenhum prefixo comum.
Moniker composto genérico Se o outro moniker for uma composição, esse método comparará os componentes de cada composição da esquerda para a direita. O moniker de prefixo comum retornado também pode ser um moniker composto, dependendo de quantos dos componentes mais à esquerda eram comuns a ambos os monikers. Se o outro moniker não for uma composição, o método simplesmente o comparará com o componente mais à esquerda desse moniker.

Se os monikers forem iguais, o método retornará MK_S_US e definirá ppmkPrefix como este moniker. Se o outro moniker for um prefixo desse moniker, o método retornará MK_S_HIM e definirá ppmkPrefix como o outro moniker. Se esse moniker for um prefixo do outro, esse método retornará MK_S_ME e definirá ppmkPrefix para esse moniker.

Se não houver nenhum prefixo comum, esse método retornará MK_E_NOPREFIX e definirá ppmkPrefix como NULL.
Moniker de item Se o outro moniker for um moniker de item igual a esse moniker, esse método definirá *ppmkPrefix como este moniker e retornará MK_S_US; caso contrário, o método chamará a função MonikerCommonPrefixWith . Essa função manipula corretamente o caso em que o outro moniker é uma composição genérica.
Moniker OBJREF Se os dois monikers forem iguais, esse método retornará MK_S_US e definirá *ppmkPrefix como NULL. Se o outro moniker não for um moniker OBJREF, esse método passará ambos os monikers para a função MonikerCommonPrefixWith . Essa função manipula corretamente o caso em que o outro moniker é uma composição genérica.

Se não houver nenhum prefixo comum, esse método retornará MK_E_NOPREFIX.
Moniker de ponteiro Se os dois monikers forem iguais, esse método retornará MK_S_US e definirá *ppmkPrefix como este moniker. Caso contrário, o método retorna MK_E_NOPREFIX e define *ppmkPrefix como NULL.
Moniker de URL Esse método retorna E_NOTIMPL.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [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 objidl.h

Confira também

Imoniker

MonikerCommonPrefixWith