I_IrmProtector.HrProtect Method

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Generates a rights-managed version of the specified unprotected file.

HRESULT HrProtect(
    ILockBytes       *pilbInput,
    ILockBytes       *pilbOutput,
    I_IrmPolicyInfo    *piid,
    DWORD            *pdwStatus
) PURE;

Parameters

pilbInput

[in] The unprotected file.

pilbOutput

[out] The rights-managed stream that the Information Rights Management (IRM) protector generates from the specified unprotected file.

piid

[in] A link to data about the file to protect, and the user requesting it.

pdwStatus

[in] The status of the method call. Possible values are:

MSOIPI_STATUS_UNKNOWN

The result of the method cannot be determined.

MSOIPI_STATUS_PROTECT_SUCCESS

The protector has successfully generated the protected file stream.

MSOIPI_STATUS_ALREADY_PROTECTED

The file is already IRM protected.

MSOIPI_STATUS_CANT_PROTECT

A general failure of the protector.

MSOIPI_STATUS_NOT_MY_FILE

The specified file is not of a file type associated with this IRM protector.

MSOIPI_STATUS_FILE_CORRUPT

The specified file is corrupt.

MSOIPI_STATUS_WSS_IRM_FAILED

The protector is unable to access its rights management platform.

MSOIPI_STATUS_BAD_INSTALL

The protector is not installed properly.

Return Value

The protector methods return typical HRESULT values. In general, the protector should return a positive OK value for success or a negative FAIL value when unsuccessful.

Remarks

The I_IrmProtector Interface is implemented by both integrated and autonomous IRM protectors. For more information on integrated and autonomous protectors, see Custom IRM Protectors.

For integrated IRM protectors:

Integrated protectors do not need to implement this method. An integrated protector should return the HRESULT E_NOTIMPL if this method is called.

For autonomous IRM protectors:

This method takes a stream of data that represents an unprotected file of a type that the IRM protector can understand, and then generates a corresponding data stream that represents a protected version of that file. For autonomous protectors, you must implement the I_IrmProtector.HrProtect Method method so that it configures and executes the entire rights management process.

Using the I_IrmPolicyInfo Class object passed by Windows SharePoint Services as the piid argument, you can access the following information:

  • The GUID and URL of the document library that the requested file is from.

  • The email address of the user requesting the file, and a rights mask specifying the rights that user has to the file.

  • The title and description of the document library’s IRM policy.

  • The number of days that the user should have access to the file.

It is the responsibility of the autonomous protector to translate this data into something that an IRM-aware client application can consume.

In general, you should implement the I_IrmProtector.HrProtect Method method of an autonomous protector so that it accomplishes the following tasks:

  • Encrypt the sensitive parts of the requested file.

  • Grant correct permissions to the rights-managed file to the user requesting the file.

  • Give full control of the rights-managed file to the Windows SharePoint Services server, or to another user that the I_IrmProtector.HrUnprotect Method method of this autonomous protector has access to.

  • Add the document library GUID to the rights metadata of the file.

  • Add the other rights metadata, such as policy title and description, to the file as appropriate.

  • Return the appropriate status value in the pwdStatus argument.

The file type developer must decide where and how these data components are stored within the file. However, the IRM protector should be in agreement with the client application used to view and edit files of this file type.

The protected stream can also include a warning message that is backward-compatible with previous versions of client-side viewers of the protector’s file type.

See Also

Reference

I_IrmProtector Interface

I_IrmPolicyInfoRMS Class

I_IrmPolicyInfo Class

Concepts

Information Rights Management in Windows SharePoint Services Overview

Custom IRM Protectors