How to: Work with Information Rights Management Settings

There are two types of Information Rights Management (IRM) settings available in Microsoft Office InfoPath 2007: one for protecting access to InfoPath form templates, and one for controlling access to and actions on form data contained in completed forms. To work with these settings when designing a form template, click Manage Credentials on the File menu. To work with these settings when filling out a form, click Permission on the File menu, and then click Manage Credentials. For more information about using the Permission dialog box in InfoPath, see the "Create a Form Template with Restricted Permission" topic in InfoPath help.

Note

Restricting permission is only available to form templates compatible with InfoPath. Browser-compatible form templates do not support IRM. If you do not see Manage Credentials on the File menu when designing a form template, check your compatibility settings.

The IRM Object Model

Use the Permission class to access the UserPermissionCollection and IRM permission settings that can be applied to a form. To access the Permission object associated with a form template, use the Permission property of the XmlForm class. The returned Permission object provides access to the collection of UserPermission objects associated with the form template and each form instance created with that template.

The Permission object and its properties and methods are available whether permissions are restricted on the active form template or not. Use the Enabled property to determine whether a form has restricted permissions.

Permissions on a form are enabled in one of the following ways by using properties and methods of the Permission class:

The Enabled property is set to true.

The DocumentAuthor property is set.

The RequestPermissionUrl property is set.

The StoreLicenses property is set to true or false.

The ApplyPolicy method is called.

Note

If the Windows Rights Management client is not installed on a user's computer, using the Permission class raises an exception.

To work programmatically with IRM settings of individual users in forms, use the UserPermissionCollection and UserPermission classes.

A UserPermission object associates a set of permissions for the current form with a single user and an optional expiration date. Use the Add method of the UserPermissionCollection class to add and grant a user a set of permissions on the current form. Use the Remove method of the UserPermissionCollection class to remove a user and the user's permissions. While some permissions granted through the user interface apply to all users, such as printing and expiration date, you can use the UserPermission and UserPermissionCollection classes to assign them on a per-user basis with per-user expiration dates. The object model allows developers to enumerate permission settings in a form and to provide functionality that allows form users to add permissions to the form without having to use the Form Permission task pane or the Permission dialog box.

Note

Permissions cannot be applied when a form is in preview mode. For this reason, all of the properties of the Permission class are read-only when a form is being previewed. In preview mode, the Enabled property will always return false, and if code attempts to change this setting, a System.Runtime.InteropServices.COMException is raised and the error "The property/method is not available in preview mode" is returned. Similarly, the methods associated with the UserPermission and UserPermissionCollection classes will also return this error message when used in preview mode.

Overview of the Permission Class

The UserPermissionCollection class provides the following properties and one method.

Name	Description
ApplyPolicy method	Applies a policy to the form using a policy template file.
DocumentAuthor property	Gets or sets the author of the current form as an e-mail address.
Enabled property	Gets or sets whether the permission settings represented by the Permission object are enabled for the current form.
PermissionFromPolicy property	Gets or sets whether a permission policy has been applied to the current form.
PolicyDescription property	Gets a description of the policy that was applied to the current form.
PolicyName property	Gets the name of the policy that was applied to the current form.
RequestPermissionUrl property	Gets or sets the file, URL, or e-mail address to contact for users who need additional permissions on the current form.
StoreLicenses property	Gets or sets whether the user's license to view the current form should be cached to allow offline viewing when the user cannot connect to a rights management server.
UserPermissions property	Gets a UserPermissionCollection object for the current form.

Overview of the UserPermissionCollection Class

The UserPermissionCollection class provides the following properties and methods.

Name	Description
Add method (+3 overloads)	Adds a new user to the current form, optionally specifying permissions and an expiration date.
Remove method	Removes the UserPermission object with the specified UserId from the collection.
RemoveAll method	Removes all UserPermission objects from the collection.
Count property	Gets the number of UserPermission objects in the collection.
Item property (+1 overload)	Gets a UserPermission object.

Overview of the UserPermission Class

The UserPermission class provides the following properties and one method.

Name	Description
Remove method	Removes the current UserPermission object from the form's permissions.
ExpirationDate property	Gets or sets the optional expiration date for the permissions on the current form assigned to the user associated with an instance of the UserPermission class.
Permission property	Gets or sets a value representing the permissions on the current form assigned to the user associated with an instance of the UserPermission class.
UserId property	Gets the e-mail address of the user whose permissions on the current form are determined by the specified UserPermission object.

The PermissionType Enumeration

A user's permissions are set or read using PermissionType enumeration values.

Name	Description
PermissionType.Change	Allows users to view, edit, copy, and save, but not print a form. Equivalent to the Read, Edit, Save, and Extract permissions combined.
PermissionType.Edit	Allows the user to edit the form.
PermissionType.Extract	Allows a user with the Read permission to copy content in the form.
PermissionType.FullControl	Allows the user to add, change, and remove permissions for other users of a form.
PermissionType.ObjectModel	Allows a user to access the form document programmatically through its object model. Users without the ObjectModel permission cannot use the object model to determine their own permissions.
PermissionType.Print	Allows the user to print the form.
PermissionType.Read	Allows the user to read (view) the form. (The Read and View permissions are equivalent.)
PermissionType.Save	Allows the user to save the form.
PermissionType.View	Allows the user to view (read) the form. (The Read and View permissions are equivalent.)

Example

In the following example, clicking the Button control gets the UserPermissionsCollection for the current form, adds and assigns a user to the Change access level, and sets an expiration date of two days from the current date.

public void CTRL1_Clicked(object sender, ClickedEventArgs e)
{
   string strExpirationDate = DateTime.Today.AddDays(2).ToString();
   DateTime dtExpirationDate = DateTime.Parse(strExpirationDate);

   this.Permission.UserPermissions.Add("someone@example.com", 
      PermissionType.Change, dtExpirationDate);
}

Public Sub CTRL1_Clicked(ByVal sender As Object, _
   ByVal e As ClickedEventArgs)
   Dim strExpirationDate As String = _
      DateTime.Today.AddDays(2).ToString()
   dtExpirationDate As DateTime = DateTime.Parse(strExpirationDate)

   Me.Permission.UserPermissions.Add("someone@example.com", _
      PermissionType.Change, dtExpirationDate)
End Sub