Compartir a través de

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

  • Artículo

Crea un nuevo moniker compuesto combinando el moniker actual con el moniker especificado.

Sintaxis

HRESULT ComposeWith(
  [in]  IMoniker *pmkRight,
  [in]  BOOL     fOnlyIfNotGeneric,
  [out] IMoniker **ppmkComposite
);

Parámetros

[in] pmkRight

Puntero a la interfaz IMoniker del moniker que se va a componer al final de este moniker.

[in] fOnlyIfNotGeneric

Si es TRUE, el autor de la llamada requiere una composición no genérica, por lo que la operación debe continuar solo si pmkRight es una clase de moniker con la que este moniker puede componer de alguna manera aparte de formar una composición genérica. Si es FALSE, el método puede crear una composición genérica si es necesario. La mayoría de los autores de llamadas deben establecer este parámetro en FALSE.

[out] ppmkComposite

Puntero a una variable de puntero IMoniker que recibe el puntero de moniker compuesto. Cuando se ejecuta correctamente, la implementación debe llamar a AddRef en el moniker resultante; es responsabilidad del autor de la llamada llamar a Release. Si se produce un error o si los monikers se componen en nada (por ejemplo, redactar un anti-moniker con un moniker de elemento o un moniker de archivo), *ppmkComposite debe establecerse en NULL.

Valor devuelto

Este método puede devolver los valores devueltos estándar E_OUTOFMEMORY y E_UNEXPECTED, así como los siguientes valores.

Código devuelto Descripción
S_OK
 Los monikers se combinaron correctamente.
MK_E_NEEDGENERIC
 Indica que fOnlyIfNotGeneric era TRUE, pero los monikers no se pudieron componer juntos sin crear un moniker compuesto genérico.

Comentarios

Unir dos monikers juntos se denomina composición. A veces se pueden combinar dos monikers de la misma clase en lo que se denomina composición nogenérica. Por ejemplo, un moniker de archivo que representa una ruta de acceso incompleta y otro moniker de archivo que representa una ruta de acceso relativa se puede combinar para formar un solo moniker de archivo que representa la ruta de acceso completa. La composición no genérica para una clase de moniker determinada solo se puede controlar en la implementación de ComposeWith para esa clase de moniker.

La combinación de dos monikers de cualquier clase se denomina composición genérica, que se puede realizar a través de una llamada a la función CreateGenericComposite .

La composición de monikers es una operación asociativa. Es decir, si A, B y C son monikers, entonces, donde Comp() representa la operación de composición, Comp( Comp( A, B ), C )

siempre es igual a Comp( A, Comp( B, C ) ).

Notas a los autores de llamadas

Para combinar dos monikers, debe llamar a ComposeWith en lugar de llamar a la función CreateGenericComposite para dar al primer moniker una oportunidad para realizar una composición no genérica.

Un objeto que proporciona monikers de elementos para identificar sus objetos llamaría a ComposeWith para proporcionar un moniker que identifica completamente la ubicación del objeto. Esto se aplicaría, por ejemplo, a un servidor que admita la vinculación a partes de un documento o a un contenedor que admita la vinculación a objetos incrustados dentro de sus documentos. En tal situación, haría lo siguiente:

  1. Cree un moniker de elemento que identifique el objeto .
  2. Obtiene un moniker que identifica el contenedor del objeto.
  3. Llame a ComposeWith en el moniker que identifica el contenedor y pase el moniker de elemento como parámetro pmkRight .

Notas para los implementadores

Puede usar composición no genérica o no genérica para componer el moniker actual con el moniker al que apunta pmkRight. Si la clase del moniker indicado por pmkRight es la misma que la del moniker actual, es posible usar el contenido de pmkRight para realizar una composición no genérica más inteligente.

Al escribir una nueva clase de moniker, debe decidir si hay algún tipo de monikers, ya sea de su propia clase u otra clase, a la que desea dar un tratamiento especial. Si es así, implemente ComposeWith para comprobar si pmkRight es un moniker del tipo que debe tener este tratamiento. Para ello, puede llamar al método IPersist::GetClassID del moniker, o bien si ha definido un objeto de moniker que admite una interfaz personalizada, puede llamar a QueryInterface en el moniker de esa interfaz. Un ejemplo de tratamiento especial sería la composición nogenérica de un moniker de archivo absoluto con un moniker de archivo relativo. El caso más común de un moniker especial es el inverso de tu clase de moniker (lo que devuelvas de tu implementación de IMoniker::Inverso).

Si pmkRight niega completamente el receptor para que la composición resultante esté vacía, debe devolver NULL en ppmkComposite y devolver el código de estado S_OK.

Si el parámetro pmkRight no es de una clase a la que se da un tratamiento especial, examine fOnlyIfNotGeneric para determinar qué hacer a continuación. Si fOnlyIfNotGeneric es TRUE, devuelva NULL a ppmkComposite y devuelva el código de estado MK_E_NEEDGENERIC. Si fOnlyIfNotGeneric es FALSE, llame a la función CreateGenericComposite para realizar la composición genéricamente.

Notas específicas de la implementación

Implementación Notas
Anti-moniker Si fOnlyIfNotGeneric es TRUE, este método establece ppmkComposite en moniker NULL y devuelve MK_E_NEEDGENERIC; de lo contrario, el método devuelve el resultado de combinar los dos monikers en una composición genérica. Tenga en cuenta que la composición de un moniker de archivo, elemento o puntero a la derecha de un moniker anti-moniker genera una composición genérica en lugar de componer en nada, como sería el caso si se invertira el orden de composición.
Moniker de clase Sigue el contrato y se comporta como un moniker de elemento en que puede devolver E_INVALIDARG y MK_E_NEEDGENERIC, etc.
Moniker de archivo Si pmkRight es un anti-moniker, el moniker devuelto es NULL. Si pmkRight es un compuesto cuyo componente más izquierdo es un anti-moniker, el moniker devuelto es la composición con el anti-moniker más a la izquierda quitado. Si pmkRight es un moniker de archivo, este método contrae los dos monikers en un solo moniker de archivo, si es posible. Si no es posible (por ejemplo, si ambos monikers de archivo representan rutas de acceso absolutas, como en d:\work y e:\reports), el moniker devuelto es NULL y el valor devuelto es MK_E_SYNTAX. Si pmkRight no es un moniker anti-moniker ni un moniker de archivo, el método comprueba el parámetro fOnlyIfNotGeneric ; si es FALSE, el método combina los dos monikers en un compuesto genérico; si es TRUE, el método establece *ppmkComposite en NULL y devuelve MK_E_NEEDGENERIC.
Moniker compuesto genérico Si fOnlyIfNotGeneric es TRUE, este método establece *pmkComposite en NULL y devuelve MK_E_NEEDGENERIC; de lo contrario, el método devuelve el resultado de combinar los dos monikers llamando a la función CreateGenericComposite .
Moniker de elemento Si pmkRight es un anti-moniker, el moniker devuelto es NULL. Si pmkRight es un compuesto cuyo componente más izquierdo es un anti-moniker, el moniker devuelto es el compuesto después de quitar el antimoniker más izquierdo. Si pmkRight no es un anti-moniker, el método combina los dos monikers en un compuesto genérico si fOnlyIfNotGeneric es FALSE; Si fOnlyIfNotGeneric es TRUE, el método devuelve un moniker NULL y un valor devuelto de MK_E_NEEDGENERIC.
OBJREF moniker Si pmkRight es un anti-moniker, el moniker devuelto es NULL. Si pmkRight es un compuesto cuyo componente más izquierdo es un anti-moniker, el moniker devuelto es la composición con el anti-moniker más a la izquierda quitado. Si pmkRight no es un moniker anti-moniker ni un moniker compuesto cuyo componente más izquierdo es un anti-moniker, el método comprueba el parámetro fOnlyIfNotGeneric . Si es FALSE, el método combina los dos monikers en un compuesto genérico; si es TRUE, el método establece *ppmkComposite en NULL y devuelve MK_E_NEEDGENERIC.
Moniker de puntero Si pmkRight es un anti-moniker, el moniker devuelto es NULL. Si pmkRight es un compuesto cuyo componente más izquierdo es un anti-moniker, el moniker devuelto es el compuesto después de quitar el antimoniker más izquierdo. Si fOnlyIfNotGeneric es FALSE, el moniker devuelto es una composición genérica de los dos monikers; de lo contrario, el método establece *ppmkComposite en NULL y devuelve MK_E_NEEDGENERIC.
Moniker de dirección URL Los monikers de dirección URL admiten la composición de dos direcciones URL: una dirección URL base compuesta con una dirección URL relativa. Esta composición se realiza según la RFC en direcciones URL relativas. Si fOnlyIfNotGeneric es TRUE, el método devuelve MK_E_NEEDGENERIC. De lo contrario, este método simplemente devuelve CreateGenericComposite(this, pmkRight, ppmkComposite).

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado objidl.h

Consulte también

CreateGenericComposite

Imoniker