Best Practices for Delivering Rights-Managed Content
Rights-managed content, including rights-managed HTML and restricted permission messages, can only be opened with client software that is aware of the format and file name extension. For example, the Rights Management Add-on for Internet Explorer recognizes and can open .rmh and .rpmsg files. If a user tries to open rights-managed content without the corresponding client software, these files are unrecognized. As an alternative to the default unrecognized file dialog, you can encode content inside an MIME Encapsulation of Aggregate HTML Documents (MHTML) file to provide users with specific, user-friendly instructions about how to obtain client software.
Note Although the examples in this topic use Collaboration Data Objects (CDO) for Windows 2000 to generate MHTML files, CDO is not required. Any technology that produces MHTML can be used.
The following sections describe best practices for delivering the types of content described in this software development kit (SDK).
- Delivering Rights-Managed HTML
- Determining Whether the Rights Management Add-on is Installed
- Creating Required MHTML Body Parts
- Delivering Restricted Permission Messages
- Related topics
Delivering Rights-Managed HTML
Rights-managed HTML files with the .rmh extension can be opened with the Rights Management Add-on. The MHTML file format, however, is recognized by Windows Internet Explorer regardless of whether the Rights Management Add-on is installed. To deliver rights-managed HTML files that are always recognized, create an MHTML file with a content type of multipart/related and two body parts. The first body part is HTML which determines whether the Rights Management Add-on is installed, and then displays rights-managed HTML from the second body part. The following sections describe how to create this MHTML file.
Determining Whether the Rights Management Add-on is Installed
The HTML body part of the MHTML file can check to see if the Rights Management Add-on is installed using an OBJECT element with a CLASSID attribute set to F969FE8E-1937-45AD-AF42-8A4D11CBDC2A. This is the class identifier (CLSID) of a Component Object Model (COM) object used by the Rights Management Add-on. If the Rights Management Add-on has not been installed, then this object fails to instantiate, and the HTML inside the OBJECT element is rendered. The OBJECT element can contain HTML describing why the rights-managed HTML file cannot be viewed along with instructions for obtaining and installing the Rights Management Add-on.
When the HTML body part finishes loading and the readyState property is complete, Microsoft JScript determines if the object is instantiated and therefore whether the Rights Management Add-on is installed. If the Rights Management Add-on is installed, an IFRAME element is displayed, and the SRC attribute is set to the body part containing the encoded rights-managed HTML.
The following example shows HTML that determines whether the Rights Management Add-on is installed and displays either the rights-managed HTML content or a message explaining why the rights-managed HTML content cannot be viewed.
<html>
<body style='margin:0' scroll='no'>
<script language='text/javascript'>
document.onreadystatechange=Loading;
function Loading(){
if (document.readyState!='complete') return;
var p = document.all('Probe');
if (p != null){
document.all('Frame1').src = 'cid:rmhcontent';
document.all('Frame1').style.display = 'block';}}
</script>
<frame id='Frame1' width='100%' height='100%'
style='display: none'></frame>
<object id='Probe' classid='clsid:F969FE8E-1937-45AD-AF42-8A4D11CBDC2A'>
<span style='color:red'>This is a <tla rid="tla_rmh"/> file. To view the contents,
install the Rights-managed SDK for Internet Explorer.</span>
</object>
</body>
</html>
Creating Required MHTML Body Parts
The MHTML file containing both the rights-managed HTML content and the HTML described in the previous section can be created in script using CDO for Windows 2000. After instantiating a Message object, set the HTMLBody property equal to a string containing the HTML. Next, call AddRelatedBodyPart to encode the rights-managed HTML file. The GetStream method retrieves the contents of the composite MHTML which can then be saved to disk.
The following example shows how to create an MHTML file with Microsoft Visual Basic Scripting Edition (VBScript). HTMLContent is a string containing the HTML from the previous section; WScript.Arguments(0) is the absolute path of a rights-managed HTML file to encode, and WScript.Arguments(1) is the filename of the resulting MHTML file.
Set iMsg = CreateObject("CDO.Message")
Set fso = CreateObject("Scripting.FileSystemObject")
On Error Resume Next
iMsg.AutoGenerateTextBody = false
iMsg.HTMLBody = HTMLContent
iMsg.AddRelatedBodyPart WScript.Arguments(0), "rmhcontent", cdoRefTypeId
If Err.Number <> 0 Then
WScript.Echo "Error: " + Err.Description
Else
Set MyFile = fso.CreateTextFile(WScript.Arguments(1), True)
MyFile.Write iMsg.GetStream.ReadText
MyFile.Close
End If
Running this script generates an MHTML file with encoded rights-managed HTML content. When this file is opened on a computer with the Rights Management Add-on installed, the Rights Management Add-on displays the rights-managed HTML content if the user has the correct permissions. When this file is opened on a computer without the Rights Management Add-on installed, Internet Explorer displays instructions that explain why the rights-managed HTML content cannot be shown.
Delivering Restricted Permission Messages
A restricted permission message can be sent in e-mail by attaching it to another message in many e-mail clients. It can also be sent by manually creating an MHTML file and sending it to a Simple Mail Transport Protocol (SMTP) server. This section describes how to generate and send an MHTML file using CDO for Windows 2000.
To send a message using CDO for Windows 2000, first create the HTML and text body parts of the MHTML using the HTMLBody property of the Message object. This body part should indicate that this is a restricted permission message that can be viewed by opening the attachment. It is also helpful to describe what actions should be taken if the recipient does not have the Rights Management Add-on or a mail client that can read restricted permission messages. Add the restricted permission message to the MHTML file by calling AddAttachment. Set the content type of this attachment to application/x-microsoft-rpmsg-message with the ContentMediaType property. Configure the method of sending and target SMTP server before calling the Send method to send the MHTML file as e-mail.
The following example shows how to send a restricted permission message using VBScript. WScript.Arguments(0) is the absolute path of an .rpmsg file, WScript.Arguments(1) is the recipient's e-mail address, WScript.Arguments(2) is the sender's e-mail address, and WScript.Arguments(3) is the recipient's SMTP server.
Set iMsg = CreateObject("CDO.Message")
Set iConf = CreateObject("CDO.Configuration")
HTMLContent = "<html>"&_
" <body>"&_
" You have received a message with restricted permission."&_
" Open this item to read its content."&_
" </body>"&_
"</html>"
On Error Resume Next
iMsg.HTMLBody = HTMLContent
iMsg.AddAttachment WScript.Arguments(0)
iMsg.Attachments(1).ContentMediaType = "application/x-microsoft-rpmsg-message"
Set Flds = iConf.Fields
Flds.Item("https://schemas.microsoft.com/cdo/configuration/smtpserver") = WScript.Arguments(3)
Flds.Item("https://schemas.microsoft.com/cdo/configuration/smtpserverport") = 25
Flds.Item("https://schemas.microsoft.com/cdo/configuration/sendusing") = 2
Flds.Update
Set iMsg.Configuration = iConf
iMsg.To = WScript.Arguments(1)
iMsg.From = WScript.Arguments(2)
iMsg.Subject = "Protected Message"
iMsg.Send
If Err.Number <> 0 Then
WScript.Echo "Error: " + Err.Description
End If
When this script is run, a restricted permission message appears in the recipient's Inbox. The content with restricted permission can be viewed by opening the attached .rpmsg file if the recipient has the correct permission.