CDO Rendering Objects Supplement

[Previous] [Next]

The RenderingApplication object is the topmost object in the CDO Rendering library, which is shown in Figure B-1. To use the objects in this library, you must first create a RenderingApplication object. To create a RenderingApplication object, use the CreateObject function and pass it the ProgID of the library, which is AMHTML.Application.

Figure B-1 The CDO Rendering library hierarchy.

RenderingApplication Object Methods

The RenderingApplication object contains methods that allow you to get configuration information and create rendering objects that display information from Exchange Server. The next section describes these methods and provides examples.

CreateRenderer Method

The CreateRenderer method creates a new rendering object and returns it to your application. The CreateRenderer method takes only one parameter—the class of renderer you want to create. This parameter can have two values, either CdoClassObjectRenderer (2) or CdoClassContainerRenderer (3). You should use an object renderer to display information from a single object in Exchange Server, and the container renderer to display objects that are contained by other objects, such as the contents of a folder. The following example creates both types of objects:

     Set oRenderApp = Server.CreateObject("AMHTML.Application")     Set oObjRenderer = oRenderApp.CreateRenderer(2)     Set oContRenderer = oRenderApp.CreateRenderer(3)

Impersonate Method

The Impersonate method uses the security context you pass to it to impersonate an authenticated user. Passing 0 to this method reverts to unauthenticated access. The way to set the security context for the current user is to use the ImpID property on the RenderingApplication object. Then pass that property to the Impersonate method to log on to Microsoft Windows NT using the security credentials of that user.

Impersonation is important when building authenticated web applications using Exchange Server. Since your application is running in the context of Microsoft Internet Information Server (IIS), you need to have IIS impersonate the security context of the user whose mailbox you are trying to access. If you do not do this, either CDO will return an "access denied" message or ASP will return a run-time error. Furthermore, when you are logging off the session and destroying your objects, you should again impersonate the user so that CDO can correctly release references. Not putting in impersonation code in Exchange Server ASP applications is probably the main cause of bugs in applications. The following code reverts to unauthenticated access, then impersonates the current user and logs onto an Exchange Server with that user's credentials:

     oRenderApp.Impersonate(0)         lImpID = oRenderApp.ImpID         oRenderApp.Impersonate(lImpID)         set oSession = Server.CreateObject("MAPI.Session")         bstrProfileInfo = "MyExchangeServer" & vblf & "UserName"         oSession1.Logon "", "", False, True, 0, True, bstrProfileInfo

ListComposeForms Method

The ListComposeForms method returns the list of custom forms on the Outlook Web Access server. You pass to this method a parameter to this method that contains the link pattern for your custom forms. Use this link pattern to give users a way to launch the custom forms or get more information about the forms. The link patten supports the following tokens as well: %class% (the message class), %classpath% (partial URL path for the form), and %formname% (which is the form's name from its Form.INI file). The following code shows you how to use the ListComposeForms method by printing out the form names on your server:

     <% frmNames = oRenderApp.ListComposeForms("%formname%")          <% if isempty(frmnames) then %>          <P>          <% else %>          <P>All the form names are:         <table>         <table border=1 columns=3 width=100%>          <tr><td><b>Name</b></td></tr>          <%          for i = 1 to UBound(frmNames)              Response.Write "<tr>"              Response.Write "<td>" & frmNames(i) & "</td>"             Response.Write "</tr>"          next          %>          </table>

LoadConfiguration Method

The LoadConfiguration method retrieves information from the source you specify as a parameter. Use this method in conjunction with the ConfigParameter property. The ConfigParameter property is the way you actually retrieve the values that the LoadConfiguaration method loads.

The values of the parameter passed to this method can be CdoConfigRegistry (1), which is self-explanatory, or CdoConfigDS (2), which specifies that you want to pull the information from the Exchange Server directory. If you specify the Registry as the source for the information, you must also pass to this method the section of the Registry you want to pull information from.

If you specify the directory as the source, you can pass an optional parameter, a Session object, which specifies which Exchange Server user to logon as. By default, LoadConfiguration performs an anonymous logon to obtain directory information. If a session is already running, you might want to pass the Session object to improve performance.

The following code pulls information from the Registry by using the LoadConfiguration method. Note that you can use this method to retrieve Registry information that is unrelated to CDO.

     oRenderApp.LoadConfiguration 1, _             "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\" & _             "MSExchangeWeb\Parameters"         bstrExchOrg    = oRenderApp.ConfigParameter("Enterprise")         bstrExchSite   = oRenderApp.ConfigParameter("Site")         bstrExchServer = oRenderApp.ConfigParameter("Server")

RenderingApplication Object Properties

The following sections describe the properties of the RenderingApplication object.

CodePage Property

The CodePage property returns or sets the code page used by all the rendering objects that were created by using the CreateRenderer method. Examples of values for this property are USA and 1252. Use the CodePage property in conjunction with the LCID property.

ConfigParameter Property

The ConfigParameter property returns the value of a named configuration parameter from the data source you specified in the LoadConfiguration method. This property takes a string parameter that specifies the key you are interested in. See the description of the LoadConfiguration method for an example of how to use the ConfigParameter property.

Formats Property

The Formats property returns a Formats collection. By changing the returned Formats collection, any new rendering objects you create by using the CreateRenderer method will inherit the new RenderingApplication Formats collection. For more information on the Formats collection, see the Formats Collection section later in this document.

FormsRoot Property

The FormsRoot property returns or sets the absolute path to the forms directory tree for Outlook Web Access. Setting FormsRoot enables CDO to generate a special-purpose format named classpath. This format is used to process the output of any %classpath% substitution tokens. Note that the FormsRoot property contains an absolute disk directory path, whereas the VirtualRoot property contains the HTTP path. The following example retrieves the disk path to the /exchange virtual root by using the ASP MapPath function to set the FormsRoot property to be the Outlook Web Access forms directory. On most machines, after using this code, the FormsRoot property will have a value of c:\exchsrvr\webdata\usa\forms.

     bstrVirtRoot = "/exchange"     oRenderApp.FormsRoot = Server.MapPath(bstrVirtRoot) & _         "\usa\forms"

ImpID Property

This property returns the security context handle for the current user. In your authenticated Exchange Server ASP applications, you should store this property in a session variable. In your Session_OnEnd, you should use the Impersonate method with your stored variable in order to correctly destroy your CDO objects.

LCID Property

The LCID property returns the locale identifier of the current user. This property is read-only and is automatically set when you set the CodePage property.

VirtualRoot Property

The VirtualRoot property returns or sets the beginning of the URL for the virtual root to your application. Setting this property forces CDO to create a special-purpose format named virtroot. This property defaults to /exchange, so in your rendering applications, be careful that you change this property before you use the %virtroot% substitution token. All virtual roots must start with a slash. An example of setting this property is shown here:

     bstrVirtRoot = "/exchange"     oRenderApp.VirtualRoot = bstrVirtRoot