IMessage::ModifyRecipients
Hace referencia a: Outlook 2013 | Outlook 2016
Agrega, elimina o modifica a los destinatarios del mensaje.
HRESULT ModifyRecipients(
ULONG ulFlags,
LPADRLIST lpMods
);
Parameters
ulFlags
[entrada] M�scara de bits de indicadores que controla los cambios de destinatarios. Si se pasa cero para el parámetro ulFlags , ModifyRecipients reemplaza todos los destinatarios existentes por la lista de destinatarios a la que apunta el parámetro lpMods . Las siguientes marcas se pueden establecer para ulFlags:
MODRECIP_ADD
Los destinatarios a los que apunta el parámetro lpMods se deben agregar a la lista de destinatarios.
MODRECIP_MODIFY
Los destinatarios a los que apunta el parámetro lpMods deben reemplazar a los destinatarios existentes. Todas las propiedades existentes se reemplazan por las de la estructura ADRENTRY correspondiente.
MODRECIP_REMOVE
Los destinatarios existentes deben quitarse de la lista de destinatarios utilizando como índice la propiedad PR_ROWID (PidTagRowid) incluida en la matriz de valores de propiedad de cada entrada de destinatario en el parámetro lpMods .
lpMods
[entrada] Puntero a una estructura ADRLIST que contiene una lista de destinatarios para agregar, eliminar o modificar en el mensaje.
Valor devuelto
S_OK
La lista de destinatarios se modific� correctamente.
Comentarios
El m�todo IMessage::ModifyRecipients cambia la lista de destinatarios del mensaje. Es en esta lista, que se celebran en una estructura ADRLIST , que se basa la tabla de destinatarios.
La estructura ADRLIST contiene una estructura ADRENTRY para cada destinatario y cada estructura ADRENTRY contiene una matriz de valores de propiedad que describe las propiedades del destinatario.
Los destinatarios de la estructura ADRLIST se pueden resolver o sin resolver. La diferencia est� en el n�mero y tipo de propiedades que se incluyen. Un destinatario sin resolver contiene solo las propiedades PR_DISPLAY_NAME (PidTagDisplayName) y PR_RECIPIENT_TYPE (PidTagRecipientType), mientras que un destinatario resuelto contiene esas dos propiedades más PR_ADDRTYPE (PidTagAddressType) y PR_ENTRYID (PidTagEntryId). Si PR_EMAIL_ADDRESS (PidTagEmailAddress) está disponible, también se puede incluir.
En el momento en que se env�a un mensaje, deben incluir s�lo los destinatarios resueltos en su lista de destinatarios. Destinatarios sin resolver dar lugar a informes de entrega que se crea y se env�a al remitente del mensaje original. Para obtener m�s informaci�n acerca del proceso de resoluci�n de nombres desde la perspectiva del cliente, vea la resoluci�n de un nombre. Para obtener m�s informaci�n desde la perspectiva de la libreta de direcciones, vea Implementaci�n de resoluci�n de nombres.
Adem�s de los destinatarios resueltos y no resueltos, un destinatario puede ser NULL. El miembro cValues de la estructura de ADRENTRY para el destinatario se establece en cero y el miembro rgPropVals se establece en NULL.
Notas para los llamadores
Puede crear una lista de destinatarios mediante una llamada a IAddrBook::Address para mostrar el cuadro de di�logo com�n y pedir al usuario que seleccione entradas. La lista de direcciones a la que apunta el parámetro lppAdrList a Address se puede pasar a ModifyRecipients como parámetro lpMods .
Al especificar las propiedades para un destinatario de la estructura ADRLIST , incluye todas las propiedades del destinatario, no s�lo los nuevos o modificados. Cuando se modifica un destinatario, se eliminan todas las propiedades que no se incluyen en la estructura de ADRLIST. Para recuperar el conjunto actual de propiedades para todos los destinatarios de un mensaje, llame GetRecipientTable y recuperar todas las filas. Dado que es id�ntico en estructura a un ADRLISTun SRowSet, puede utilizar indistintamente ellos.
ModifyRecipients reemplaza todas las entradas de la lista de destinatarios actual por la información a la que apunta lpMods cuando no se establece ninguna de las marcas en el parámetro ulFlags .
Al establecer la marca de MODRECIP_MODIFY, ModifyRecipients reemplaza cada fila de destinatario completa por la fila asociada en la estructura ADRLIST pasada en lpMods. Tenga cuidado especificar todas las propiedades que debe tener un destinatario independientemente de si han cambiado para impedir que se va a eliminar accidentalmente.
A continuaci�n se muestran algunas reglas para establecer las propiedades de los destinatarios en la estructura de ADRLIST:
No use PT_NULL como un tipo de propiedad. ModifyRecipients devuelve un error al encontrar este valor.
No use PT_ERROR como un tipo de propiedad. ModifyRecipients pasa por alto este valor.
Incluya la propiedad PR_ROWID para todos los destinatarios cuando establezca la marca MODRECIP_REMOVE o MODRECIP_MODIFY en ulFlags.
No incluya la propiedad PR_ROWID para ninguno de los destinatarios cuando establezca la marca de MODRECIP_ADD en ulFlags o cuando pase cero en ulFlags.
Si se incluye la propiedad PR_ADDRTYPE o PR_EMAIL_ADDRESS (propiedad) para un destinatario y uno o ambos de estas propiedades no son coherentes con el tipo de direcci�n y la direcci�n del destinatario como identificado por PR_ENTRYID, los resultados se definen. Es decir, hay tres posibilidades, seg�n el proveedor de servicio:
El mensaje se entregar� en la direcci�n descrita por las propiedades PR_ADDRTYPE y PR_EMAIL_ADDRESS.
El mensaje se entregar� al destinatario identificado por PR_ENTRYID.
El mensaje se va a declarar no se puede entregar debido a la ambig�edad de la informaci�n de direcci�n.
Use las reglas de asignaci�n descritas en Administraci�n de la memoria de ADRLIST y estructuras SRowSet asignar memoria para la lista de destinatarios. ModifyRecipients no libere la estructura ADRLIST ni ninguna de sus subestructuras. La estructura de ADRLIST y cada estructura SPropValue deben asignarse por separado mediante el uso de la funci�n MAPIAllocateBuffer tal que cada uno de ellos se puede liberar individualmente. Si el m�todo requiere espacio adicional para cualquier estructura SPropValue, puede reemplazar la estructura de SPropValue con una nueva que m�s adelante se puede liberar mediante MAPIFreeBuffer. La estructura SPropValue original tambi�n debe liberarse mediante MAPIFreeBuffer.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comentario |
|---|---|---|
| MAPIABFunctions.cpp |
AddRecipient |
MFCMAPI, utiliza el m�todo IMessage::ModifyRecipients para agregar a un nuevo destinatario a un mensaje. |