Compartilhar via


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.

Confira também

IMAPIProp::GetProps

IMAPIFolder : IMAPIContainer

MFCMAPI como exemplo de código