Compartir a través de

Actuar como un proveedor de libreta de direcciones externo

  • Artículo

Hace referencia a: Outlook 2013 | Outlook 2016

Un proveedor externo es un proveedor de libreta de direcciones que:

  • Asigna identificadores de plantilla para sus destinatarios.
  • Admite el método IABLogon::OpenTemplateID .
  • Proporciona código para mantener destinatarios que existen en los contenedores de otros proveedores de libreta de direcciones conocidos como proveedores host. Este código implica un objeto de propiedad, normalmente una implementación de interfaz IMAPIProp , que encapsula un objeto de propiedad del proveedor host.

Actuar como proveedor externo es un rol opcional; no todos los proveedores necesitan admitir identificadores de plantilla y su código relacionado. Implemente el proveedor como proveedor externo si desea mantener el control sobre los destinatarios que los proveedores de hosts crean mediante plantillas proporcionadas por el proveedor.

El formato que el proveedor usa para sus identificadores de entrada también se puede usar para sus identificadores de plantilla. Los identificadores de plantilla deben incluir MAPIUID registrado del proveedor para permitir que MAPI enlace correctamente los destinatarios a los proveedores adecuados.

MAPI llama al método IABLogon::OpenTemplateID del proveedor cuando un proveedor host llama a IMAPISupport::OpenTemplateID. El proveedor de host pasa el identificador de plantilla del destinatario en el parámetro lpTemplateID en su llamada a IMAPISupport::OpenTemplateID. MAPI determina que el identificador de plantilla pertenece al proveedor haciendo coincidir mapiuid en el identificador de plantilla con el MAPIUID que el proveedor registró en el momento del inicio de sesión. A continuación, MAPI reenvía la llamada del proveedor de hosts al proveedor a través del método IABLogon::OpenTemplateID .

El proveedor de hosts también pasa un puntero a su implementación de objeto de propiedad para el destinatario en el parámetro lpMAPIPropData , un identificador de interfaz en el parámetro lpInterface que corresponde al tipo de implementación de interfaz pasada en lpMAPIPropData y una marca opcional, FILL_ENTRY. Se espera que el proveedor devuelva en el parámetro lppMAPIPropNew un puntero a una implementación de objeto de propiedad del tipo especificado en lpInterface. El puntero devuelto puede ser al objeto de propiedad encapsulado implementado por el proveedor o al objeto proporcionado por el proveedor host en lpMAPIPropData. El proveedor debe devolver un puntero de objeto de propiedad ajustada cuando:

  • La tabla para mostrar del destinatario contiene controles de cuadro de lista.
  • La dirección de correo electrónico del destinatario debe ensamblarse a partir de datos en varios controles de tabla para mostrar.
  • Los problemas del proveedor muestran notificaciones de tabla.

La marca de FILL_ENTRY indica al proveedor que el proveedor host requiere que se actualicen todas las propiedades del destinatario. Su proveedor debe cumplir esta solicitud.

Cuando un proveedor host llama al método OpenTemplateID del proveedor, el proveedor podría:

  • Actualice periódicamente los datos de una entrada copiada.
  • Mantenga una entrada copiada sincronizada con su original, como cuando se copia una entrada de libreta de direcciones en la libreta de direcciones personal.
  • Implemente la funcionalidad que no puede implementar el proveedor de hosts, como rellenar dinámicamente cuadros de lista en la tabla de detalles de la entrada copiada a partir de datos de un servidor.
  • Controlar la interacción entre las propiedades de una entrada copiada o una plantilla con instancias. Por ejemplo, la computación PR_EMAIL_ADDRESS de otras propiedades que se muestran en la tabla de detalles.

Los dos primeros elementos son ejemplos de tareas que no requieren que el proveedor proporcione un objeto de propiedad encapsulado, una implementación de IMAPIProp que se basa en la implementación del proveedor host. El proveedor simplemente puede actualizar las propiedades según sea necesario y devolver, estableciendo el parámetro lppMAPIPropNew para que apunte al puntero pasado por el proveedor de hosts en el parámetro lpMAPIPropData .

Las dos segundas tareas requieren que el proveedor devuelva al proveedor de hosts un objeto de propiedad que ajuste el objeto del proveedor de hosts con funcionalidad adicional, como la capacidad de mostrar una hoja de propiedades para la entrada. Este objeto de propiedad será un usuario de mensajería o una lista de distribución, dependiendo del tipo de objeto pasado por el proveedor de hosts en el parámetro lpMAPIPropData e indicado por el identificador de interfaz en el parámetro lpInterface . Si el parámetro lpMAPIPropData apunta a un usuario de mensajería, el objeto de propiedad encapsulado del proveedor debe ser una implementación IMailUser . Si lpMAPIPropData apunta a una lista de distribución, debe ser una implementación de IDistList .

El objeto de propiedad encapsulado del proveedor intercepta las llamadas al método IMAPIProp para realizar la manipulación específica del contexto del destinatario del proveedor host, el objeto que está ajustando. MAPI solo tiene un requisito para los objetos de propiedad encapsulados: todas las llamadas a IMAPIProp::OpenProperty que solicitan la propiedad PR_DETAILS_TABLE (PidTagDetailsTable) deben pasarse al proveedor host. La implementación del proveedor puede usar la tabla devuelta para interceptar las notificaciones de tabla para mostrar o para agregar las suyas propias si es necesario.

En la lista siguiente se incluyen las tareas que normalmente se implementan en el objeto de propiedad encapsulado implementado por proveedores externos:

  • Preprocesamiento y postprocesamiento de valores de propiedad para el destinatario host en IMAPIProp::GetProps.
  • Los detalles de control muestran controles de tabla, como botones y cuadros de lista, en IMAPIProp::OpenProperty.
  • Validar o manipular valores de propiedad para el destinatario del host en IMAPIProp::SetProps.
  • Calcular las propiedades necesarias, como PR_EMAIL_ADDRESS y comprobar que todas las propiedades necesarias se han establecido antes de guardar el destinatario del host en IMAPIProp::SaveChanges.

Para implementar IABLogon::OpenTemplateID

  1. Compruebe si el identificador de plantilla pasado con el parámetro lpTemplateID es válido y está en un formato que el proveedor reconozca. Si no es así, produzca un error y devuelva MAPI_E_INVALID_ENTRYID.

  2. Cree un objeto del tipo indicado por el identificador de plantilla, ya sea un usuario de mensajería, una lista de distribución o un destinatario único.

  3. Llame al método IUnknown::AddRef en el objeto de propiedad del proveedor host, que es el objeto al que apunta el parámetro lpMAPIPropData .

  4. Si el parámetro ulTemplateFlags está establecido en FILL_ENTRY:

    1. Si el nuevo objeto es un usuario de mensajería o una lista de distribución:

      1. Recupere todas las propiedades del nuevo objeto, posiblemente llamando a su método IMAPIProp::GetProps .

      2. Llame al método IMAPIProp::SetProps del proveedor de hosts para copiar todas las propiedades recuperadas en el objeto de propiedad del proveedor host.

    2. Si el nuevo objeto es un destinatario único, llame al método IMAPIProp::SetProps del proveedor host para establecer las siguientes propiedades:

      • PR_ADDRTYPE (PidTagAddressType) al tipo de dirección controlado por el proveedor.

      • PR_TEMPLATEID (PidTagTemplateid) al identificador de plantilla de los parámetros lpTemplateID y cbTemplateID .

      • PR_DISPLAY_TYPE (PidTagDisplayType) para DT_MAILUSER o DT_DISTLIST, según corresponda.

  5. Establezca el contenido del parámetro lppMAPIPropNew para que apunte al nuevo objeto del proveedor o al objeto de propiedad pasado con el parámetro lpMAPIPropData , en función de si el proveedor determina si es necesario un objeto encapsulado.

  6. Si se produce un error crítico, como un error de red o una condición de memoria insuficiente, devuelve el valor de error adecuado. Este valor debe propagarse al cliente con la estructura MAPIERROR adecuada, una tarea realizada por el proveedor host.