IAddrBook::NewEntry
Aplica-se a: Outlook 2013 | Outlook 2016
Adiciona um novo destinatário a um contêiner de catálogo de endereços ou à lista de destinatários de uma mensagem de saída.
HRESULT NewEntry(
ULONG_PTR ulUIParam,
ULONG ulFlags,
ULONG cbEIDContainer,
LPENTRYID lpEIDContainer,
ULONG cbEIDNewEntryTpl,
LPENTRYID lpEIDNewEntryTpl,
ULONG FAR * lpcbEIDNewEntry,
LPENTRYID FAR * lppEIDNewEntry
);
Parâmetros
ulUIParam
[in] Um identificador para a janela pai da caixa de diálogo.
ulFlags
[in] Um bitmask de sinalizadores que controla o tipo do texto que é usado. O seguinte sinalizador pode ser definido:
MAPI_UNICODE
As cadeias de caracteres passadas estão no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres estarão no formato ANSI.
cbEIDContainer
[in] A contagem de bytes no identificador de entrada apontada pelo parâmetro lpEIDContainer .
lpEIDContainer
[in] Um ponteiro para o identificador de entrada do contêiner em que o novo destinatário deve ser adicionado. Se o parâmetro cbEIDContainer for zero, o método NewEntry retornará um identificador de entrada do destinatário e uma lista de modelos como se o método IAddrBook::CreateOneOff fosse chamado.
cbEIDNewEntryTpl
[in] A contagem de bytes no identificador de entrada apontada pelo parâmetro lpEIDNewEntryTpl .
lpEIDNewEntryTpl
[in] Um ponteiro para um modelo único que será usado para criar o novo destinatário. Se cbEIDNewEntryTpl for zero e lpEIDNewEntryTpl for NULL, NewEntry exibirá uma caixa de diálogo com a qual o usuário pode selecionar em uma lista de modelos para adicionar novas entradas.
lpcbEIDNewEntry
[out] Um ponteiro para a contagem de bytes no identificador de entrada apontado pelo parâmetro lppEIDNewEntry .
lppEIDNewEntry
[out] Um ponteiro para um ponteiro para o identificador de entrada do novo destinatário.
Valor de retorno
S_OK
A nova entrada do catálogo de endereços foi criada com êxito.
Comentários
O método NewEntry cria uma nova entrada do catálogo de endereços, a ser adicionada diretamente a um contêiner ou a ser usada para resolver uma mensagem de saída.
Notas para chamadores
Se você quiser que a nova entrada seja adicionada a um contêiner específico, defina lpEIDContainer para o identificador de entrada do contêiner e cbEIDContainer para a contagem de bytes no identificador de entrada.
Se você quiser que a nova entrada seja adicionada à lista de destinatários de uma mensagem de saída, defina lpEIDContainer como NULL e cbEIDContainer como zero.
Se você quiser permitir que o usuário de um aplicativo cliente selecione o tipo de entrada a ser criado, passe zero em cbEIDNewEntryTpl e NULL em lpEIDNewEntryTpl. O método NewEntry exibe a tabela única MAPI, uma lista de modelos com suporte por MAPI e por cada provedor de catálogo de endereços na sessão. Cada modelo pode criar uma entrada de destinatário para um ou mais tipos de endereço.
Se você quiser manter o identificador de entrada da nova entrada, passe ponteiros válidos nos parâmetros lpcbEIDNewEntry e lppEIDNewEntry . Você é responsável por liberar esse identificador de entrada quando terminar com ele chamando a função MAPIFreeBuffer .
Para usar um modelo específico para adicionar uma nova entrada a um contêiner modificável, use o seguinte procedimento:
Chame o método IMAPISession::OpenEntry para abrir o contêiner de destino e defina o parâmetro lpEntryID como o identificador de entrada do contêiner.
Chame o método IMAPIProp::OpenProperty do contêiner de destino e defina o parâmetro ulPropTag como PR_CREATE_TEMPLATES (PidTagCreateTemplates) e o parâmetro lpiid como IID_IMAPITable. O contêiner retornará uma tabela única que lista todos os modelos compatíveis para criar novas entradas.
Recupere a linha que representa o modelo para o tipo específico de entrada que você deseja criar. A coluna PR_ADDRTYPE (PidTagAddressType) indica o tipo de endereço compatível com o modelo.
Chame o método NewEntry e defina lpEIDNewEntryTpl como o identificador de entrada do modelo selecionado. O identificador de entrada será a coluna PR_ENTRYID (PidTagEntryId) da linha do modelo na tabela única. Passe zero em cbEIDContainer e NULL no lpEIDContainer. Passe um ponteiro válido no parâmetro lppEIDNewEntry se quiser manter o identificador de entrada da nova entrada.