IMAPIFolder::CreateMessage
Aplica-se a: Outlook 2013 | Outlook 2016
Cria uma nova mensagem.
HRESULT CreateMessage(
LPCIID lpInterface,
ULONG ulFlags,
LPMESSAGE FAR * lppMessage
);
Parâmetros
lpInterface
[in] Um ponteiro para o IID (identificador de interface) que representa a interface a ser usada para acessar a nova mensagem. Os identificadores de interface válidos incluem IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer e IID_IMAPIFolder. Passar NULL faz com que o provedor do repositório de mensagens retorne a interface de mensagem padrão, IMessage : IMAPIProp.
ulFlags
[in] Um bitmask de sinalizadores que controla como a mensagem é criada. Os seguintes sinalizadores podem ser definidos:
ITEMPROC_FORCE
Indica ao PST (repositório de pastas pessoal) que a mensagem é qualificada para processamento de regras antes que o repositório notifique qualquer cliente ouvinte da chegada da nova mensagem. O processamento de regras só se aplica a novas mensagens criadas em um servidor que não é um Microsoft Exchange Server, pois Exchange Server processa regras para mensagens no servidor. Portanto, o provedor ou cliente que cria a mensagem deve passar esse sinalizador em combinação com salvar uma mensagem com IMAPIPProp::SaveChanges usando NON_EMS_XP_SAVE, o que indica que o servidor não é um Exchange Server.
MAPI_ASSOCIATED
A mensagem a ser criada deve ser incluída na tabela de conteúdo associada em vez da tabela de conteúdo padrão. As mensagens associadas estão ocultas da interação do usuário.
MAPI_DEFERRED_ERRORS
CreateMessage tem permissão para ter êxito mesmo que a operação create não tenha sido totalmente concluída. Isso implica que a nova mensagem pode não estar disponível imediatamente para o chamador.
lppMessage
[out] Um ponteiro para um ponteiro para a mensagem recém-criada.
Valor de retorno
S_OK
A mensagem foi criada com êxito.
Comentários
O método IMAPIFolder::CreateMessage cria uma nova mensagem com conteúdo genérico ou associado e atribui um identificador de entrada. O identificador de entrada consiste em uma parte que representa o provedor do repositório de mensagens e uma parte que representa a mensagem individual.
Observações para implementadores
Você pode escolher se deve definir todas as propriedades de mensagem necessárias no CreateMessage ou no método IMAPIProp::SaveChanges da mensagem. Você não precisa disponibilizar essas propriedades até que uma salvação bem-sucedida tenha ocorrido.
Para obter mais informações sobre como trabalhar com informações associadas, consulte Tabelas de informações associadas à pasta e tabelas de conteúdo.
Notas para chamadores
Alguns provedores do repositório de mensagens permitem que o identificador de entrada da nova mensagem esteja disponível imediatamente após o retorno do CreateMessage ; outros provedores do repositório de mensagens atrasam sua disponibilidade até que a mensagem seja salva. Como nem todos os provedores do repositório de mensagens geram um identificador de entrada para uma nova mensagem até que você tenha chamado o método IMAPIProp::SaveChanges da mensagem, talvez você não possa acessar o identificador de entrada quando CreateMessage retornar. Além disso, a nova mensagem pode não ser incluída na tabela de conteúdo da pasta até que a salvação ocorra.
Espere que o identificador de entrada atribuído à nova mensagem seja exclusivo não apenas no repositório de mensagens atual, mas provavelmente em todos os repositórios de mensagens abertos ao mesmo tempo. Uma exceção a essa regra ocorre quando várias entradas para um repositório de mensagens aparecem no perfil. Isso faz com que o repositório de mensagens seja aberto várias vezes e os identificadores de entrada sejam duplicados.
Para criar uma mensagem de saída, chame o método IMAPIFolder::CreateMessage da pasta Outbox.
Se você excluir uma pasta que contém uma nova mensagem antes da mensagem ser salva, os resultados serão indefinidos.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| FolderDlg.cpp |
CFolder::OnNewMessage |
O MFCMAPI usa o método IMAPIFolder::CreateMessage para criar e salvar uma nova mensagem. |