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

  • Artigo

Reduz um moniker à sua forma mais simples.

Sintaxe

HRESULT Reduce(
  [in]      IBindCtx *pbc,
  [in]      DWORD    dwReduceHowFar,
  [in, out] IMoniker **ppmkToLeft,
  [out]     IMoniker **ppmkReduced
);

Parâmetros

[in] pbc

Um ponteiro para a interface IBindCtx no contexto de associação a ser usado nesta operação de associação. O contexto de associação armazena em cache objetos associados durante o processo de associação, contém parâmetros que se aplicam a todas as operações usando o contexto de associação e fornece os meios pelos quais a implementação do moniker deve recuperar informações sobre seu ambiente.

[in] dwReduceHowFar

Especifica até que ponto esse moniker deve ser reduzido. Esse parâmetro deve ser um dos valores da enumeração MKRREDUCE .

[in, out] ppmkToLeft

Na entrada, um ponteiro para uma variável de ponteiro IMoniker que contém o ponteiro de interface para moniker à esquerda deste moniker. Esse parâmetro é usado principalmente por implementadores de moniker para habilitar a cooperação entre os vários componentes de um moniker composto; Os clientes moniker geralmente podem passar NULL.

No retorno, *ppmkToLeft geralmente é definido como NULL, indicando nenhuma alteração no moniker original à esquerda. Em situações raras, *ppmkToLeft indica um moniker, indicando que o moniker anterior à esquerda deve ser desconsiderado e o moniker retornado por *ppmkToLeft é a substituição. Nessa situação, a implementação deve chamar Release no moniker antigo à esquerda desse moniker e deve chamar AddRef no novo moniker retornado; o chamador deve liberá-lo mais tarde. Se ocorrer um erro, a implementação poderá deixar o ponteiro da interface inalterado ou defini-lo como NULL.

[out] ppmkReduced

Um ponteiro para uma variável de ponteiro IMoniker que recebe o ponteiro de interface para a forma reduzida desse moniker, que pode ser NULL se ocorrer um erro ou se esse moniker for reduzido a nada. Se esse moniker não puder ser reduzido, *ppmkReduced será simplesmente definido como este moniker e o valor retornado será MK_S_REDUCED_TO_SELF. Se *ppmkReduced não for NULL, a implementação deverá chamar AddRef no novo moniker; é responsabilidade do chamador chamar Release. (Isso é verdadeiro mesmo se *ppmkReduced estiver definido como este moniker.)

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_REDUCED_TO_SELF
 Esse moniker não pôde ser reduzido ainda mais, portanto ppmkReduced indica esse moniker.
MK_E_EXCEEDEDDEADLINE
 Não foi possível concluir a operação dentro do limite de tempo especificado pela estrutura de BIND_OPTS do contexto de associação.

Comentários

Esse método destina-se aos seguintes usos:

  • Habilite a construção de macros ou aliases definidos pelo usuário como novos tipos de classes moniker. Quando reduzido, o moniker ao qual a macro é avaliada é retornado.
  • Habilite a construção de um tipo de moniker que rastreia dados à medida que ele se move. Quando reduzido, o moniker dos dados em seu local atual é retornado.
  • Em sistemas de arquivos que dão suporte a um método baseado em identificador de acesso a arquivos independentes de nomes de arquivo; um moniker de arquivo pode ser reduzido a um moniker que contém um desses identificadores.
A intenção dos sinalizadores MKRREDUCE passados no parâmetro dwReduceHowFar é fornecer a capacidade de reduzir programaticamente um moniker para um formulário cujo nome de exibição é reconhecível para o usuário. Por exemplo, caminhos no sistema de arquivos, indicadores em documentos de processamento de palavras e nomes de intervalo em planilhas são todos reconhecíveis para os usuários. Por outro lado, uma macro ou um alias encapsulado em um moniker não são reconhecíveis para os usuários.

Anotações para chamadores

Os cenários descritos acima não são implementados atualmente pelas classes de moniker fornecidas pelo sistema.

Você deve chamar Reduce antes de comparar dois monikers usando o método IMoniker::IsEqual porque um moniker reduzido está em sua forma mais específica. IsEqual pode retornar S_FALSE em dois monikers antes de serem reduzidos e retornar S_OK depois de serem reduzidos.

Anotações aos implementadores

Se o moniker atual puder ser reduzido, sua implementação não deverá reduzir o moniker in-loco. Em vez disso, ele deve retornar um novo moniker que representa o estado reduzido do atual. Dessa forma, o chamador ainda tem a opção de usar o moniker não induzido (por exemplo, enumerando seus componentes). Sua implementação deve reduzir o moniker pelo menos no que for solicitado.

Notas específicas da implementação

Implementação Observações
Anti-moniker Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.
Moniker de classe Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.
Moniker de arquivo Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.
Moniker composto genérico Esse método chama recursivamente Reduzir para cada um de seus monikers de componente. Se qualquer um dos componentes se reduzir, o método retornará S_OK e retornará uma composição dos componentes reduzidos. Se não houver redução, o método retornará o mesmo moniker e retornará MK_S_REDUCED_TO_SELF.
Moniker de item Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.
Moniker OBJREF Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.
Moniker de ponteiro Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.
Moniker de URL Esse método retorna MK_S_REDUCED_TO_SELF e retorna o mesmo moniker.

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