Background for the Four Sample CDO Applications

The easiest way to learn any new object library is to look at the objects in action, so the rest of this chapter shows you two sample applications that demonstrate different technologies in the CDO library: a Helpdesk application and a Calendar of Events application. Chapter 12 shows you two advanced samples: an Intranet News application and a CDO Visual Basic application. From these four samples, you will learn how to use the CDO library in your applications and become aware of the technical considerations that arise when you build CDO applications. All of these applications are written using Visual Basic and use either ASP or Windows Forms. You will need a version of Visual Studio 6.0 if you want the best experience in modifying the applications. Before we dive into the details of the sample applications, we'll first look at the necessary Exchange Server logon step.

Using the CDO Session Object

Whether you build CDO applications by using ASP or some other development tool, the most important point to remember is that you cannot create any other objects in the CDO library if you do not first successfully create a Session object. Furthermore, you cannot access any data in Exchange Server unless you successfully log on to the server using the Session object. Before we can look at the code in the CDO applications, you must understand how to log on to an Exchange server by using the Session object.

The Session object is the top-level object in the CDO hierarchy. It contains sessionwide settings and properties that return top-level objects. When you use the CreateObject method in your applications, you use the ProgID of the Session object ” MAPI.Session ”to create a CDO object. With one exception, CDO does not allow you to access any other objects in the library until you have successfully logged on using the Logon method of the Session object. The exception is the SetLocaleIDs method, which sets the Locale and CodePage IDs for the user .

Using the Logon Method

The Logon method takes a number of parameters, as shown in the following code; the parameter you use depends on the needs of your application:

 objSession.Logon( [ProfileName] [, ProfilePassword] [, ShowDialog] [, NewSession] [, ParentWindow] [, NoMail] [, ProfileInfo] ) 

The two common ways to log on to a CDO session are by passing in a MAPI profile name and by passing in the specific information CDO needs to dynamically generate a profile. Dynamically generated profiles are the preferred method when you build ASP applications with CDO. Because ASP pages cannot remotely access the profiles on a client's machine, CDO has no way to pull information from one of those profiles.

Authenticated Logon Using a Profile

To log on using a profile, you pass the profile name as the first parameter, ProfileName , to the Logon method. If you don't know which profile name to use, set the ShowDialog parameter to True , and CDO will prompt the user to pick a profile. The second parameter, ProfilePassword , specifies the profile password. You can leave this parameter blank and set the ShowDialog parameter to True , and CDO will prompt the user for a password. By setting the NewSession parameter to False , you can have CDO take advantage of an existing MAPI session, eliminating the overhead of creating a new MAPI session on the user's machine. The following code snippet shows how to use the Logon method with a profile named MS Outlook Settings :

 oSession.Logon ProfileName:="MS Outlook Settings", _    showDialog:=True, NewSession:=True 

Authenticated Logon Using a Dynamically Generated Profile

If your application is running in an environment in which profiles or the ability to prompt a user for a profile are not available, CDO allows you to dynamically generate a profile for the user by passing the user's server name and mailbox name to the Logon method. To get this information, you can have your application prompt the user for his server name and mailbox name. Alternatively, CDO can pull the default Exchange Server name from the registry by using the ConfigParameter properties in the CDO Rendering library, which you will learn about later in this chapter. For now, the code sample assumes that you know the name of at least one Exchange server in your organization. The following code shows how to log on to CDO using a dynamically generated profile:

 strServer = "Exchange Server Name" strMailbox = "User Alias Name (Not Display Name)" strProfileInfo = strServer + vbLf + strMailbox oSession.Logon "", "", False, True, 0, True, strProfileInfo 'Check for a valid logon set oInbox = oSession.GetInbox      If Err.number <> 0 Then  'Not Successful     oSession.Logoff     Response.Write "Logon Unsuccessful!" End If 

Note  

For the user's mailbox name, don't use the display name, such as Thomas Rizzo . Instead, use the alias of the user, such as thomriz . Also, when you use the ProfileInfo parameter, try to access an item in a CDO message store, such as the first message in the Inbox, because the Logon method will return success even if the parameters in ProfileInfo are incorrect. If an attempt to access items returns an error, the user was not successfully logged on. If you find that the alias has multiple overlaps, such as Rizzo and Rizzoti , and you must log on Rizzo , you can instead use the SMTP address of the user to log on to CDO.

Anonymous Access

CDO also allows users to anonymously access the Exchange Server public folder store as well as the Exchange Server directory. Anonymous access must be enabled by the administrator of the Exchange Server system. Also, the administrator or developer can control which folders and which directory entries the anonymous user can see by setting some options in the Exchange Administrator program. These options are discussed in more detail throughout this chapter.

To use anonymous access, you must pass the distinguished name of the Exchange server and the Anon account in the ProfileInfo parameter. You do this by using the following format:

 server distinguished name & vbLf & vbLf & "anon" 

The server's distinguished name takes this form:

 /o=enterprise/ou=site/cn=Configuration/cn=Servers/cn=server 

The enterprise parameter corresponds to the Exchange Server organization, and the site parameter corresponds to the Exchange Server site you want to access. The following code shows you how to log on using anonymous access:

 strProfileInfo = "/o=" & "Your Exchange Org" & "/ou=" & _     "Your Site" & "/cn=Configuration/cn=Servers/cn=" & _     "Your Server" & vbLF & vbLF & "anon" oSession.Logon "", "", False, True, 0, True, strProfileInfo If Err.number <> 0 Then     oSession.Logoff     response.Write "Logon Unsuccessful!" End If 

Note  

Anonymous access does not work with Exchange 2000 or 2003. For the sample applications to work, you must add some entries to the registry that a clean install of Exchange 2000 or 2003 does not include. The entries to add under the HKLM\SYSTEM\CurrentControlSet\Services \MSExchangeWEB\Parameters key are:

Server
The name of your Exchange Server
Enterprise
The name of your enterprise, such as First Organization
Site
The name of your site, such as First Administrative Group

You should avoid Anonymous Access with CDO 1.21 unless you have upgraded from Exchange 5.5 or have a mixed-mode environment with Exchange 5.5. A clean installation of Exchange will not include the necessary registry settings.