IMAPIFolder::CreateFolder
Aplica-se a: Outlook 2013 | Outlook 2016
Cria uma nova subpasta.
HRESULT CreateFolder(
ULONG ulFolderType,
LPSTR lpszFolderName,
LPSTR lpszFolderComment,
LPCIID lpInterface,
ULONG ulFlags,
LPMAPIFOLDER FAR * lppFolder
);
Parâmetros
ulFolderType
[in] O tipo de pasta a ser criada. Os seguintes sinalizadores podem ser definidos:
FOLDER_GENERIC
Uma pasta genérica deve ser criada.
FOLDER_SEARCH
Uma pasta de resultados de pesquisa deve ser criada.
lpszFolderName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da nova pasta. Esse nome é a base para a propriedade PR_DISPLAY_NAME (PidTagDisplayName) da nova pasta.
lpszFolderComment
[in] Um ponteiro para uma cadeia de caracteres que contém um comentário associado à nova pasta. Essa cadeia de caracteres se torna o valor da propriedade PR_COMMENT (PidTagComment) da nova pasta. Se NULL for aprovado, a pasta não terá nenhum comentário inicial.
lpInterface
[in] Um ponteiro para o IID (identificador de interface) que representa a interface a ser usada para acessar a nova pasta. Passar NULL faz com que o provedor do repositório de mensagens retorne a interface de pasta padrão, IMAPIFolder : IMAPIContainer. Os clientes devem passar NULL. Outros chamadores podem definir o parâmetro lpInterface como IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer ou IID_IMAPIFolder.
ulFlags
[in] Um bitmask de sinalizadores que controla como a pasta é criada. Os seguintes sinalizadores podem ser definidos:
MAPI_DEFERRED_ERRORS
Permite que CreateFolder retorne com êxito, possivelmente antes que a nova pasta esteja totalmente disponível para o cliente de chamada. Se a nova pasta não estiver disponível, fazer uma chamada subsequente pode causar um erro.
MAPI_UNICODE
O nome da pasta está no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, o nome da pasta estará no formato ANSI.
OPEN_IF_EXISTS
Permite que o método tenha êxito mesmo que a pasta nomeada no parâmetro lpszFolderName já exista abrindo a pasta existente que tem esse nome. Observe que os provedores do repositório de mensagens que permitem que pastas irmãos tenham o mesmo nome podem não abrir uma pasta existente se houver mais de uma com o nome fornecido.
lppFolder
[out] Um ponteiro para um ponteiro para a pasta recém-criada.
Valor de retorno
S_OK
A nova pasta foi criada ou aberta com êxito, se o sinalizador OPEN_IF_EXISTS for definido.
MAPI_E_BAD_CHARWIDTH
O sinalizador MAPI_UNICODE foi definido e a implementação não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e a implementação dá suporte apenas ao Unicode.
MAPI_E_COLLISION
Uma pasta que tem o nome dado no parâmetro lpszFolderName já existe. Os nomes das pastas devem ser exclusivos.
Comentários
O método IMAPIFolder::CreateFolder cria uma subpasta na pasta atual e atribui um identificador de entrada à nova pasta.
Notas para chamadores
Quando CreateFolder retornar, esteja ciente de que o identificador de entrada da nova pasta pode não estar disponível. Alguns provedores do repositório de mensagens não disponibilizam identificadores de entrada até que você tenha chamado o método IMAPIProp::SaveChanges da nova pasta para salvá-lo permanentemente. Isso é especialmente verdade se você tiver definido o sinalizador de MAPI_DEFERRED_ERRORS.
Lembre-se de que alguns provedores do repositório de mensagens sempre apontam o parâmetro lppFolder para a interface padrão da pasta, independentemente do valor que você passa para o parâmetro lpInterface . Como o ponteiro de interface retornado pode não ser do tipo esperado, chame o método IMAPIProp::GetProps da nova pasta para recuperar a propriedade PR_OBJECT_TYPE (PidTagObjectType). Se necessário, selecione o ponteiro para um tipo mais apropriado antes de fazer outras chamadas.
A maioria dos provedores do repositório de mensagens exige que o nome da nova pasta seja exclusivo em relação aos nomes de suas pastas irmãos. Seja capaz de lidar com o valor de erro MAPI_E_COLLISION, que será retornado se essa regra não for seguida.
Para determinar o identificador de entrada da pasta recém-criada, chame o método IMAPIProp::GetProps da nova pasta para recuperar sua propriedade PR_ENTRYID (PidTagEntryId).
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
Arquivo | Função | Comentário |
---|---|---|
MsgStoreDlg.cpp |
CMsgStoreDlg::OnCreateSubFolder |
O MFCMAPI usa o método CMsgStoreDlg::OnCreateSubFolder para criar novas pastas no MFCMAPI. |