Exchange Provider::CreateFolder

  • Article

The CreateFolder method allows you to create a folder within a Messaging Application Programming Interface (MAPI) top-level hierarchy (TLH) and assign permissions.

Arguments

Input argument Required Description

MdbDN

Yes

The Lightweight directory access protocol (LDAP) path of the Exchange Public Folders store that is part of the MAPI tree.

Folderpath

Yes

The absolute folder path. If the folder is a top-level folder, this parameter should be specified as "/".

Name

Yes

The name of folder.

MaxItemSize

No

A number that represents the maximum size (in KB) of a message. Any negative number passed in with this parameter removes the size limitation.

ProhibitPostLimit

No

A number that represents the maximum size (in KB) to which the folder is allowed to grow. Any negative number will remove the quota from the folder.

Permissions

No

The permissions specification for the folder.

Dd252048.note(en-us,TechNet.10).gifNote
Principals granted permissions to MAPI folders must be mail-enabled.

The Permissions parameter has two modes. The first mode allows you to set the folder Access Control List (ACL) according to input that you specify, while the second mode allows you to modify the ACL. In either case, the default configuration of the Everyone and Anonymous groups in the ACL are not supported. The reason is that these groups can span hosted organizations and open security holes.

The basic format of the <permissions> node is:

<Permissions mode="update"> 
        <Permission role="mapi role">ldap path </Permission> 
    </Permissions>

The mode attribute must be set to either "update" or "set." When set to "update", this allows you to change the Access Control Entry (ACE). The Permissions parameter doesn't cause a merging with existing ACEs, but replaces them instead. The "set" mode replaces the entire ACL on the folder and configures it to the values specified in the <permissions> node.

The mapi role attribute can have any of the following values:

  • "owner"

  • "publishing editor"

  • "author"

  • "editor"

  • "publishing author"

  • "non editing author"

  • "contributor"

  • "none"

These values correspond to the MAPI roles that are exposed in the MAPI ACL editor. Please refer to this editor to view the specific rights that are granted with each role.

The ldap path in each <permission> node must refer to an entity that is mail/mailbox- enabled. This is required because without an Exchange legacy DN, MAPI will not properly manipulate the ACLs and users without causing a failure.

Output Parameters

The CreateFolder method of the Exchange Provider implements error handling in the following manner:

  • If the <MdbDN> parameter does not point to an Exchange public store, this method generates a unique error message.

  • If the <MdbDN> parameter does not refer to a MAPI mdb, this method returns a unique error message.

  • Creating top level folders also requires the setting of the folder's ACL and generates a unique error message if the ACL is not set.

  • If the ProhibitPostLimit parameter is too large, the method generates a special error listing the limits.

  • In the <permissions> node, the method checks and returns special errors that indicate when the role and mode attributes are not within a specified range.

  • On the <permissions> node, the method verifies that the referenced entity has an Exchange legacy DN and generates a special error if it does not.

  • If a mandatory parameter is not set, a special error message is generated.

  • If the role attribute on a <permission> node is not set, a unique error message is generated.

  • If the mode attribute on a <permission> node is not set, a unique error message is generated.

  • Folder names can not be called "." or ".." and can not include "/" or "\" characters, otherwise, unique error messages are generated.

Remarks

Permissions

In general, this method only requires three mandatory input parameters. However, the exception to this is if the folder being created is a top-level folder. If this is the case, then permissions must be set on the folder. The reason for setting permissions is that otherwise, the folder can inherit permissions from the Active Directory service which can make the folder visible outside the hosted organization.

The ModifyFolder method explains how to set folder permissions on a top-level folder. When performing this operation, permissions for the Everyone and Authenticated Users groups are removed from the folder.

DAV Requirements

The CreateFolder method uses DAV to perform operations and therefore requires the w3svc and related services to be operating. To help ensure a secure environment, the CreateFolder method works with Secure Sockets Layer (SSL) configured. Port 80 is used for non-SSL requests and port 443 is used for SSL connections. The Exchange Provider does not support the use of non-standard ports. Also, with SSL certificates, the server name is expected to be the fully-qualified domain name (FQDN) of the server and not the NetBIOS name. This is the same as ESM.

Mail-Enabling

Exchange should be in native mode to prevent the store from mail-enabling folders by default. Public folders will not be mail-enabled due to issues with creating public folder proxies.

Rollback Calls

The CreateFolder method calls the DeleteFolder method on transaction rollback.

Sample Code

Example XML Request

None.

Example XML Response

None.

Applies To

Exchange Provider API for:

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

See also

Tasks

Exchange Provider::DeleteFolder
Exchange Provider::ModifyFolder