IMAPIFolder::CreateFolder

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Crea una subcarpeta.

HRESULT CreateFolder(
  ULONG ulFolderType,
  LPSTR lpszFolderName,
  LPSTR lpszFolderComment,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPMAPIFOLDER FAR * lppFolder
);

Parameters

ulFolderType

[in] Tipo de carpeta que se va a crear. Se pueden establecer las siguientes marcas:

FOLDER_GENERIC

Se debe crear una carpeta genérica.

FOLDER_SEARCH

Se debe crear una carpeta de resultados de búsqueda.

lpszFolderName

[in] Puntero a una cadena que contiene el nombre de la nueva carpeta. Este nombre es la base de la propiedad PR_DISPLAY_NAME (PidTagDisplayName) de la nueva carpeta.

lpszFolderComment

[in] Puntero a una cadena que contiene un comentario asociado a la nueva carpeta. Esta cadena se convierte en el valor de la propiedad PR_COMMENT (PidTagComment) de la nueva carpeta. Si se pasa NULL, la carpeta no tiene ningún comentario inicial.

lpInterface

[in] Puntero al identificador de interfaz (IID) que representa la interfaz que se va a usar para acceder a la nueva carpeta. Pasar NULL hace que el proveedor del almacén de mensajes devuelva la interfaz de carpeta estándar, IMAPIFolder : IMAPIContainer. Los clientes deben pasar NULL. Otros autores de llamadas pueden establecer el parámetro lpInterface en IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer o IID_IMAPIFolder.

ulFlags

[in] Máscara de bits de marcas que controla cómo se crea la carpeta. Se pueden establecer las siguientes marcas:

MAPI_DEFERRED_ERRORS

Permite que CreateFolder devuelva correctamente, posiblemente antes de que la nueva carpeta esté totalmente disponible para el cliente que realiza la llamada. Si la nueva carpeta no está disponible, realizar una llamada posterior a ella puede producir un error.

MAPI_UNICODE

El nombre de la carpeta está en formato Unicode. Si no se establece la marca de MAPI_UNICODE, el nombre de la carpeta está en formato ANSI.

OPEN_IF_EXISTS

Permite que el método se realice correctamente incluso si la carpeta denominada en el parámetro lpszFolderName ya existe abriendo la carpeta existente que tiene ese nombre. Tenga en cuenta que es posible que los proveedores de almacén de mensajes que permiten que las carpetas del mismo nivel tengan el mismo nombre no abran una carpeta existente si existe más de una con el nombre proporcionado.

lppFolder

[out] Puntero a un puntero a la carpeta recién creada.

Valor devuelto

S_OK

La nueva carpeta se ha creado o abierto correctamente, si se ha establecido la marca de OPEN_IF_EXISTS.

MAPI_E_BAD_CHARWIDTH

Se estableció la marca de MAPI_UNICODE y la implementación no admite Unicode, o MAPI_UNICODE no se estableció y la implementación solo admite Unicode.

MAPI_E_COLLISION

Ya existe una carpeta que tiene el nombre especificado en el parámetro lpszFolderName . Los nombres de carpeta deben ser únicos.

Comentarios

El método IMAPIFolder::CreateFolder crea una subcarpeta en la carpeta actual y asigna un identificador de entrada a la nueva carpeta.

Notas para los llamadores

Cuando createfolder devuelve, tenga en cuenta que es posible que el identificador de entrada de la nueva carpeta no esté disponible. Algunos proveedores de almacén de mensajes no hacen que los identificadores de entrada estén disponibles hasta que haya llamado al método IMAPIProp::SaveChanges de la nueva carpeta para guardarlo permanentemente. Esto es especialmente cierto si ha establecido la marca de MAPI_DEFERRED_ERRORS.

Tenga en cuenta que algunos proveedores de almacén de mensajes siempre apuntan el parámetro lppFolder a la interfaz estándar de la carpeta, independientemente del valor que pase para el parámetro lpInterface . Dado que es posible que el puntero de interfaz devuelto no sea del tipo que espera, llame al método IMAPIProp::GetProps de la nueva carpeta para recuperar la propiedad PR_OBJECT_TYPE (PidTagObjectType). Si es necesario, convierta el puntero a un tipo más adecuado antes de realizar otras llamadas.

La mayoría de los proveedores de almacén de mensajes requieren que el nombre de la nueva carpeta sea único con respecto a los nombres de sus carpetas del mismo nivel. Puede controlar el valor de error MAPI_E_COLLISION, que se devuelve si no se sigue esta regla.

Para determinar el identificador de entrada de la carpeta recién creada, llame al método IMAPIProp::GetProps de la nueva carpeta para recuperar su propiedad PR_ENTRYID (PidTagEntryId).