IMessage::ModifyRecipients

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Adiciona, exclui ou modifica destinatários de mensagens.

HRESULT ModifyRecipients(
  ULONG ulFlags,
  LPADRLIST lpMods
);

Parâmetros

ulFlags

[in] A máscara de bits de sinalizadores que controla as alterações do destinatário. Se zero for passado para o parâmetro ulFlags , ModifiRecipients substituirá todos os destinatários existentes pela lista de destinatários apontada pelo parâmetro lpMods . Os seguintes sinalizadores podem ser definidos para ulFlags:

MODRECIP_ADD

Os destinatários apontados pelo parâmetro lpMods devem ser adicionados à lista de destinatários.

MODRECIP_MODIFY

Os destinatários apontados pelo parâmetro lpMods devem substituir os destinatários existentes. Todas as propriedades existentes são substituídas por aquelas na estrutura ADRENTRY correspondente.

MODRECIP_REMOVE

Os destinatários existentes devem ser removidos da lista de destinatários usando como índice a propriedade PR_ROWID (PidTagRowid) incluída na matriz de valor de propriedade de cada entrada de destinatário no parâmetro lpMods .

lpMods

[in] Ponteiro para uma estrutura ADRLIST que contém uma lista de destinatários a serem adicionados, excluídos ou modificados na mensagem.

Valor de retorno

S_OK

A lista de destinatários foi modificada com êxito.

Comentários

O método IMessage::ModifiRecipients altera a lista de destinatários da mensagem. É dessa lista, mantida em uma estrutura ADRLIST , que a tabela do destinatário é criada.

A estrutura ADRLIST contém uma estrutura ADRENTRY para cada destinatário e cada estrutura ADRENTRY contém uma matriz de valores de propriedade que descrevem as propriedades do destinatário.

Os destinatários na estrutura ADRLIST podem ser resolvidos ou não resolvidos. A diferença está no número e no tipo de propriedades incluídas. Um destinatário não resolvido contém apenas as propriedades PR_DISPLAY_NAME (PidTagDisplayName) e PR_RECIPIENT_TYPE (PidTagRecipientType), enquanto um destinatário resolvido contém essas duas propriedades mais PR_ADDRTYPE (PidTagAddressType) e PR_ENTRYID (PidTagEntryId). Se PR_EMAIL_ADDRESS (PidTagEmailAddress) estiver disponível, ele também poderá ser incluído.

Quando uma mensagem é enviada, ela deve incluir apenas destinatários resolvidos em sua lista de destinatários. Destinatários não resolvidos fazem com que relatórios não confiáveis sejam criados e enviados para o remetente original da mensagem. Para obter mais informações sobre o processo de resolução de nomes na perspectiva do cliente, consulte Resolvendo um Nome. Para obter mais informações da perspectiva do provedor de catálogo de endereços, consulte Implementando a Resolução de Nomes.

Além de destinatários resolvidos e não resolvidos, um destinatário pode ser NULL. O membro cValues da estrutura ADRENTRY para o destinatário está definido como zero e o membro rgPropVals está definido como NULL.

Notas para chamadores

Você pode criar uma lista de destinatários chamando IAddrBook::Address para exibir a caixa de diálogo comum e solicitar que o usuário selecione entradas. A lista de endereços apontada pelo parâmetro lppAdrList para Address pode ser passada para ModifiRecipients como o parâmetro lpMods .

Quando você especifica as propriedades de um destinatário na estrutura ADRLIST , inclua todas as propriedades do destinatário, não apenas as novas ou alteradas. Quando um destinatário é modificado, todas as propriedades não incluídas na estrutura ADRLIST são excluídas. Para recuperar o conjunto atual de propriedades para todos os destinatários de uma mensagem, chame GetRecipientTable e recupere todas as linhas. Como um SRowSet é idêntico na estrutura a um ADRLIST, você pode usá-los de forma intercambiável.

ModifiRecipients substitui todas as entradas na lista de destinatários atual pelas informações apontadas por lpMods quando nenhum dos sinalizadores é definido no parâmetro ulFlags .

Quando você define o sinalizador MODRECIP_MODIFY, ModifyRecipients substitui cada linha inteira do destinatário pela linha associada na estrutura ADRLIST passada em lpMods. Tenha cuidado para especificar todas as propriedades que um destinatário deve ter, independentemente de terem sido alteradas para evitar que sejam excluídas involuntariamente.

A seguir estão algumas regras para definir as propriedades dos destinatários na estrutura ADRLIST :

Não use PT_NULL como um tipo de propriedade. ModifiRecipients retorna um erro ao encontrar esse valor.
Não use PT_ERROR como um tipo de propriedade. ModifiRecipients ignora esse valor.
Inclua a propriedade PR_ROWID para todos os destinatários ao definir o sinalizador MODRECIP_REMOVE ou MODRECIP_MODIFY em ulFlags.
Não inclua a propriedade PR_ROWID para nenhum dos destinatários ao definir o sinalizador de MODRECIP_ADD em ulFlags ou quando passar zero em ulFlags.

Se você incluir a propriedade PR_ADDRTYPE ou PR_EMAIL_ADDRESS propriedade para um destinatário e uma ou ambas as propriedades forem inconsistentes com o tipo de endereço e o endereço do destinatário, conforme identificado por PR_ENTRYID, os resultados serão indefinidos. Ou seja, há três possibilidades, dependendo do provedor de serviços:

A mensagem será entregue no endereço descrito pelas propriedades PR_ADDRTYPE e PR_EMAIL_ADDRESS .
A mensagem será entregue ao destinatário identificado por PR_ENTRYID.
A mensagem será declarada não entregue devido à ambiguidade das informações de endereço.

Use as regras de alocação descritas no Gerenciamento de Memória para Estruturas ADRLIST e SRowSet para alocar memória para a lista de destinatários. ModifiRecipients não libera a estrutura ADRLIST nem nenhuma de suas substruturas. A estrutura ADRLIST e cada estrutura SPropValue devem ser alocadas separadamente usando a função MAPIAllocateBuffer de modo que cada uma possa ser liberada individualmente. Se o método exigir espaço adicional para qualquer estrutura SPropValue , ele poderá substituir a estrutura SPropValue por uma nova que poderá ser liberada posteriormente usando MAPIFreeBuffer. A estrutura SPropValue original também deve ser liberada usando MAPIFreeBuffer.