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

Cria um moniker relativo entre esse moniker e o moniker especificado.

Sintaxe

HRESULT RelativePathTo(
  [in]  IMoniker *pmkOther,
  [out] IMoniker **ppmkRelPath
);

Parâmetros

[in] pmkOther

Um ponteiro para a interface IMoniker no moniker para o qual um caminho relativo deve ser tomado.

[out] ppmkRelPath

Um ponteiro para uma variável de ponteiro IMoniker que recebe o ponteiro de interface para o moniker relativo. Quando bem-sucedida, a implementação deve chamar AddRef no novo moniker; é responsabilidade do chamador chamar Release. Se ocorrer um erro, a implementação definirá *ppmkRelPath como NULL.

Retornar valor

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

Código de retorno	Descrição
S_OK	O método foi concluído com sucesso.
MK_S_HIM	Nenhum prefixo comum é compartilhado pelos dois monikers e o moniker retornado em ppmkRelPath é pmkOther.
MK_E_NOTBINDABLE	Esse moniker é um moniker relativo, como um moniker de item. Esse moniker deve ser composto com o moniker de seu contêiner antes que um caminho relativo possa ser determinado.

Comentários

Um moniker relativo é análogo a um caminho relativo (como ".. \backup"). Por exemplo, suponha que você tenha um moniker que representa o caminho "c:\projects\secret\art\pict1.bmp" e outro moniker que representa o caminho "c:\projects\secret\docs\chap1.txt". Chamar RelativePathTo no primeiro moniker, passando o segundo como o parâmetro pmkOther , criaria um moniker relativo representando o caminho ".. \docs\chap1.txt".

Anotações para chamadores

Os clientes moniker normalmente não precisam chamar RelativePathTo. Esse método é chamado principalmente pelo manipulador padrão para objetos vinculados. Os objetos vinculados contêm um moniker absoluto e relativo para identificar a origem do link. (Isso habilita o rastreamento de link se o usuário move uma árvore de diretório que contém os arquivos de contêiner e de origem.) O manipulador padrão chama esse método para criar um moniker relativo do documento de contêiner para a origem do link. (Ou seja, ele chama RelativePathTo no moniker que identifica o documento do contêiner, passando o moniker identificando a origem do link como o parâmetro pmkOther .)

Se você chamar RelativePathTo, chame-o apenas em monikers absolutos, por exemplo, um moniker de arquivo ou um moniker composto cujo componente mais à esquerda é um moniker de arquivo, em que o moniker de arquivo representa um caminho absoluto. Não chame esse método em monikers relativos.

Anotações aos implementadores

Sua implementação de RelativePathTo 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 ele for da mesma classe que este moniker). Nesse caso, sua implementação deve determinar o caminho relativo. Caso contrário, ele deverá passar ambos os monikers em uma chamada para a função MonikerRelativePathTo , que manipula corretamente o caso genérico.

A primeira etapa para determinar um caminho relativo é determinar o prefixo comum desse moniker e pmkOther. A próxima etapa é dividir esse moniker e pmkOther em duas partes cada, digamos (P, myTail) e (P, otherTail), respectivamente, em que P é o prefixo comum. O caminho relativo correto é então o inverso de myTail composto com otherTail:

Comp( Inv( myTail ), otherTail )

em que Comp() representa a operação de composição e Inv() representa a operação inversa.

Para determinados tipos de monikers, você não pode usar o método IMoniker::Inverse para construir o inverso de myTail. Por exemplo, um moniker de arquivo retorna um anti-moniker como um inverso, enquanto seu método RelativePathTo deve usar um ou mais monikers de arquivo que representam cada um o caminho ".." para construir o inverso de myTail.

Notas específicas da implementação

Implementação	Observações
Anti-moniker	Esse método retorna MK_S_HIM e define *ppmkRelPath como o outro moniker.
Moniker de classe	Esse método retorna o resultado de chamar MonikerRelativePathTo com pmkSrc igual a este moniker, pmkOther, ppmkRelPath e TRUE como dwReserved.
Moniker de arquivo	Esse método calcula um moniker que, quando composto à direita desse moniker, produz o outro moniker. Por exemplo, se o caminho desse moniker for "C:\work\docs\report.doc" e se o outro moniker for "C:\work\art\picture.bmp", o caminho do moniker computado será ".. \.. \art\picture.bmp".
Moniker composto genérico	Esse método localiza o prefixo comum dos dois monikers e cria dois monikers que consistem no restante quando o prefixo comum é removido. Em seguida, ele cria o inverso para o restante deste moniker e compõe o restante do outro moniker à direita dele.
Moniker de item	Esse método retorna MK_E_NOTBINDABLE e define *ppmkRelPath como NULL.
Moniker OBJREF	Esse método retorna E_NOTIMPL.
Moniker de ponteiro	Esse método retorna E_NOTIMPL.
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

MonikerRelativePathTo