As with any of the other components that can be accessed from Active Server Pages, one of the keys to getting the best out of CDO for NTS is to understand the object model that underlies it. As you can see from the diagram below, the CDO for NTS object model is actually fairly simple.
The CDO for NTS object model is chiefly comprised of a hierarchy of objects headed by the Session object. In addition to this, however, there is another discrete object, which is quite separate from the hierarchy. We'll start by looking at this object, the NewMail object, and then move on to the other, hierarchical objects.
As an aside, it is worth noting that the CDO for NTS library (CDONTS.DLL) includes declarations for constants which can be used in place of explicit values in certain expressions. The constants which are identifiable by the prefix cdo (such as cdoEncodingBase64 which has a value of 1) are available from Visual Basic, but are NOT available from within VBScript. If you want use these values, however, you can create a separate file containing these declarations and include it in your script with a set of statements at the head of the page like this:
<% @ LANGUAGE="VBSCRIPT" %>
<% Option Explicit %>
<!--#include file="cdovbs.inc"-->
The Option Explicit is particularly useful here as it will cause an error to be generated if a particular constant declaration cannot be found. Without the Option Explicit, if a constant such as cdoEncodingBase64 were used later in the code without having been previously declared, VBScript would interpret the undeclared constant a variable with a value of 0 and continue execution without raising an error. The problems that result from this type of error can be very, very hard to debug.
Unlike adovbs.inc which contains the type library declarations for ADO, Microsoft does not provide a cdovbs.inc file when CDO for NTS is installed.
You can download a sample cdovbs.inc which you can use, from the Wrox web site http://rapid.wrox.co.uk/books/1266.
The NewMail object provides the quickest method of mail-enabling a web page and allows us to send a message in just three or four lines of code. In its simplest format we can send a message using the NewMail object like this:
Set objMail = CreateObject("CDONTS.Newmail")
objMail.Send ("rob@here.com", "jdr@there.com", "Bad news", "I owe you £50")
Set objMail = Nothing
This would cause an SMTP message to be sent to jdr@there.com with a subject of "Bad News", a body text reading "I owe you £50". The message will appear to have been sent from rob@here.com.
The first line of code creates an instance of the NewMail object. The second causes the message to be sent and the last line clears up by reclaiming the resources that had been allocated to the NewMail object when it was instantiated. There is no need to deal with folder or message collections and, interestingly, there is no need to log on either.
As you can see, most of the key information about the message is provided in the form of parameters to the Send method. If we wanted to, however, we could explicitly set the properties of the NewMail object like this:
Set objMail = CreateObject("CDONTS.Newmail")
objMail.From = "rob@here.com"
objMail.To = "jdr@there.com"
objMail.Subject = "Bad News"
objMail.Body = "I owe you £50"
objMail.Send
Set objMail = NothingThis achieves exactly the same result as the three previous lines of code, but has the advantage of making the code easier to read (and therefore to debug if it doesn't produce the desired results).
Because there is no logon authentication and it is up to you to specify who the message is from, you can send anonymous mail from CDO for NTS by simply omitting to specify the From property!
You may have noticed from the example above that the intended recipient of the mail message was referenced using a full SMTP address (i.e. jdr@there.com). When specifying recipients in CDO for NTS you always have to use the full SMTP address as there is no concept of address books or address resolution.
Recipients are specified using the To, Cc and Bcc properties, like this:
objMail.To = "jdr@there.com"
objMail.Cc = "stephen@there.com"
objMail.Bcc ="margaret@here.com"
In this case, the message would be sent to jdr@there.com; a copy would be sent to stephen@there.com; and a blind copy would be sent to margaret@here.com.
When a person is specified as the BCC (Blind Carbon Copy) recipient of a mail message, it means that they are sent a copy of the mail message, but that neither the original recipient nor anyone who was specified as a copy recipient knows that the BCC recipient has been sent a copy.
In order to specify multiple recipients for a message, simply separate the recipients' names with a semicolon:
objMail.To = "jdr@there.com;stephen@there.com;margaret@here.com"
Multiple recipients can be specified for the To, Cc and Bcc properties. However, messages can only have one sender, so the From property of the NewMail object should always be a single SMTP address.
To specify the text that will appear as the body of the message, simply set the Body property of the NewMail object.
objMail.Body = "I owe you £50"
Although plain text is the default, the NewMail object also supports HTML as a format for the body of the mail message. To send a message which contains HTML in its body, we need to change the BodyFormat of the NewMail object to cdoBodyFormatHTML and then set the Body property to a string containing HTML.
Set objMail = CreateObject("CDONTS.Newmail")
sHTML = "<HTML>"
sHTML = sHTML & "<HEAD>"
sHTML = sHTML & "<TITLE>Bad News!</TITLE>"
sHTML = sHTML & "</HEAD>"
sHTML = sHTML & "<BODY>"
sHTML = sHTML & "<P>I owe you <FONT COLOR="#FF0000"><STRONG>"
sHTML = sHTML & "£50</STRONG></FONT>!</P>"
sHTML = sHTML & "</BODY></HTML>"
objMail.From = "rob@here.com"
objMail.To = "jdr@there.com"
objMail.BodyFormat = cdoBodyFormatHTML
objMail.Body = sHTML
objMail.Send
Set objMail = Nothing
If the body of our message is in HTML and it contains a number of URLs, we can streamline things somewhat by taking advantage of the ContentBase and ContentLocation properties of the NewMail object. If the ContentLocation property has been specified for a NewMail object, then any URLs in the message body are deemed to be relative to the path specified in the ContentLocation property. If the ContentBase property has also been set, then the path in the ContentLocation property is deemed to be relative to the path in the ContentBase property.
To make this a little clearer, have a look at the following code:
Set objMail = CreateObject("CDONTS.Newmail")
sHTML = "<HTML>"
sHTML = sHTML & "<HEAD>"
sHTML = sHTML & "<TITLE>Bad News!</TITLE>"
sHTML = sHTML & "</HEAD>"
sHTML = sHTML & "<BODY>"
sHTML = sHTML & "<P><IMG SRC="ouch.gif" WIDTH="28" HEIGHT="28"></P>"
sHTML = sHTML & "<P>I owe you <FONT COLOR="#FF0000"><STRONG>"
sHTML = sHTML & "£50</STRONG></FONT>!</P>"
sHTML = sHTML & "</BODY></HTML>"
objMail.From = "rob@here.com"
objMail.To = "margaret@here.com"
objMail.BodyFormat = cdoBodyFormatHTML
objMail.ContentBase = "http://www.here.com/"
objMail.ContentLocation = "miscellaneous/"
objMail.Body = sHTML
objMail.Send
Set objMail = Nothing
When this message is displayed, the browser will prefix the image source ouch.gif with the values read from the ContentBase and ContentLocation properties and attempt to retrieve the image file from http://www.here.com/miscellaneous/ouch.gif.
If you prefer, you can specify the ContentBase and ContentLocation in UNC format:
objMail.ContentBase = "\\our_server\"
objMail.ContentLocation = "miscellaneous\"
It is easy to attach files to mail messages using the AttachFile method of the NewMail object. So if we wanted to attach a bitmap to the mail message we could do so like this:
objMail.AttachFile ("c:\images\logo.bmp", "Our logo")
This would attach the file logo.bmp with the caption "Our logo". By default, the attachment is encoded using the UUENCODE format, but we can override this default and send the attachment using Base 64 format by supplying the optional encodingmethod parameter to the AttachFile method.
objMail.AttachFile ("c:\images\logo.bmp", "Our logo", cdoEncodingBase64)
To set the encoding method for this attachment back to UUENCODE we would use the constant cdoEncodingUUEncode instead. Bear in mind that changing the encoding method for a NewMail object only affects that object. It does not alter the default method used for encoding new NewMail objects.
By default, messages sent with the NewMail object are sent as plain text. If we want, however, we can send a message in MIME format by changing the NewMail object's MailFormat property like this.
objMail.MailFormat = cdoMailFormatMIME
If we wanted to explicitly set the format of the message back to plain text, we would use the constant cdoMailFormatText. Again, bear in mind that changing the MailFormat property affects only the current NewMail object. It has no effect on the default format used in NewMail objects that are created in the future.
Changing the MailFormat property of a message also affects the default method used for encoding any attachments that the message might have. If the message is to be sent as plain text, the default encoding method for any new attachments is to use the UUENCODE format. If the message is to be sent in MIME format, then the default for any new attachments is to use Base 64 encoding. Finally, it should be noted that if we explicitly specify that an attachment is to use the Base 64 encoding method, the MailFormat property of the message to which it is attached is automatically changed to cdoMailFormatMIME.
With the wide variety of encoding and formatting options available how do you select the best one to use? Well, that really depends on two things; what is the purpose of your message and who is it being sent to? Here are some suggestions for you to bear in mind.
If you are using CDO for NTS simply to provide you with notification you of some exceptional event which has occurred – a form of administrative alert – then you will probably not be too concerned about how pretty the message appears. You won't want to go through the hassle of formatting the message in HTML when plain text will do just as well.
However, if you are using CDO for NTS to allow you to dispatch promotional material such as an electronic marketing brochure to subscribers to your web site, then you might want to spend some time formatting the message in HTML to make it look as eye-catching and slick as possible. (In this situation, you could use a tool such as Microsoft FrontPage 98 to generate the HTML and then paste it into the ASP code).
Bear in mind, however, that the presence of all those tags means that HTML documents are larger than plain text documents. Larger documents, and especially ones which contain images, mean longer download times and bigger phone bills for recipients who are downloading your message over a dial-up connection.
You should also think about the capabilities of the mail clients that will be used by recipients of your messages. Most modern mail clients can cope with messages which use the MIME format, but there may be some who do not. So if you are not sure about the capabilities of your target audience, you might want to go for the safer option and send the message as plain text instead.
It is also possible to change the importance, or priority, of a mail message generated by using the NewMail object. This is done by setting the object's Importance property. By default, messages are assigned an importance of Normal, which is represented by the constant cdoNormal. To change the importance of the message to high, simply use the constant cdoHigh, and to make it a low importance message, use cdoLow.
objMail.Importance = cdoLow
You can also change the importance of the message by supplying a value for the optional Importance parameter of the Send method of the NewMail object, like this:
objMail.Send ("rob@here.com", "jdr@there.com", "Bad news", "I owe you £50", cdoHigh)You should be aware that changing the importance of a mail message will not necessarily have any effect on the speed with which the message is actually delivered to the recipient, as the implementation of this feature may vary among the various servers in the path from your server to the destination mail server. You should also note that although some mail clients visually differentiate high, normal and low importance messages through some type of icon, you might not be in a position to guarantee that this functionality is available to all of the message's recipients.
It was stated earlier in this chapter that the NewMail object was designed to allow for the quick and easy generation of mail messages from a web page and we looked at an example of sending a message in three lines of code.
Set objMail = CreateObject("CDONTS.Newmail")
objMail.Send ("rob@here.com", "jdr@there.com", "Bad news", "I owe you £50")
Set objMail = NothingThe screenshot below shows how such a message would appear to the recipient if viewed in Microsoft Outlook Express.
Now let's have a look at the source of the actual message that was sent. Different mail clients provide different methods for viewing the message source, but in Outlook Express you do this by opening the message and then selecting the Properties item from the File menu. On the Details tab of the dialog which then appears, click the Message Source… button. This will display the native source code for the message you are looking at and it will probably look something like this.
x-sender: rob@here.com
x-receiver: jdr@there.com
Received: from mail pickup service by asti.ivory.co.uk with Microsoft SMTPSVC;
Sun, 14 Dec 1997 12:01:31 +0000
From: <rob@here.com>
To: <jdr@there.com>
Subject: Bad News
Date: Sun, 14 Dec 1997 12:01:31 -0000
X-MimeOLE: Produced By Microsoft MimeOLE V4.71.1712.3
Message-ID: <002dd3101120ec7ASTI@asti.ivory.co.uk>
I owe you £50
You will notice that as well as the body text, there is a lot of extra information contained in the message source which is not displayed when the mail message is viewed. This header information is automatically generated based on the values that were specified either as explicit property settings for the NewMail object or as parameters to the Send method. It also includes details such as the time-stamp line below which are generated by the SMTP server itself.
Received: from mail pickup service by asti.ivory.co.uk with Microsoft SMTPSVC;
Sun, 14 Dec 1997 12:01:31 +0000
If we want, however, we can add our own headers to the message we are sending. The reason for doing this is that many messaging systems are able to interpret certain other headers which are not automatically added by the NewMail object. Details of these headers, such as the Keywords, References and Reply-To headers, can be found in the document entitled Standard for the Format of ARPA Internet Text Messages (STD011) located at http://ds1.internic.net/std/std11.txt.
To add a custom header to the message we use the Value property of the NewMail object. So if we want to add a Reply-To header, we would do so like this.
Set objMail = CreateObject("CDONTS.Newmail")
objMail.Value("Reply-To") = "stephen@ivory.co.uk"
objMail.Send ("rob@here.com", "jdr@there.com", "Bad news", "I owe you £50")
Set objMail = NothingIf we then look at the message source of the message that this creates, we can see that it now has an appropriate line added to the headers indicating the reply address:
x-sender: rob@here.com
x-receiver: jdr@there.com
Received: from mail pickup service by asti.ivory.co.uk with Microsoft SMTPSVC;
Sun, 14 Dec 1997 12:01:31 +0000
Reply-To: <stephen@ivory.co.uk>
From: <rob@here.com>
To: <jdr@there.com>
Subject: Bad News
Date: Sun, 14 Dec 1997 12:01:31 -0000
X-MimeOLE: Produced By Microsoft MimeOLE V4.71.1712.3
Message-ID: <002dd3101120ec7ASTI@asti.ivory.co.uk>
I owe you £50
And when we open the resulting message and attempt to reply to the sender, the reply is correctly addressed to the person specified in the Reply-To header.
The Value property is actually the default property of the NewMail object, which means that we could achieve the same effect by using this code instead:
Set objMail = CreateObject("CDONTS.Newmail")
objMail("Reply-To") = "stephen@ivory.co.uk"
objMail.Send ("rob@here.com", "jdr@there.com", "Bad news", "I owe you £50")
Set objMail = Nothing
You can set the Value property of a NewMail object as many times as you want. Every time you set the property it adds a new header to the message, so you can add a number of custom headers to the same message.
Set objMail = CreateObject("CDONTS.Newmail")
objMail("Reply-To") = "stephen@ivory.co.uk"
objMail("Keywords") = "Bet,England,Rugby,Lose"
objMail.Send ("rob@here.com", "jdr@there.com", "Bad news", "I owe you £50")
Set objMail = Nothing
We have spent a good deal of time looking at the NewMail object and how it can be used. Before we leave this and go on to investigate the hierarchy of other objects in the CDO for NTS hierarchy, there are a few other observations that are worth making.
The first point to make is that with the exception of the Version property (which returns the version of the CDO for NTS library), none of the properties of the NewMail object are readable. The reason for this is that the NewMail object is designed to be operated without user-intervention and there is therefore no need to provide either a user interface or a mechanism for reading properties. A further implication of this is that recipients, attachments and headers, once added, cannot be removed from a NewMail object.
Secondly, you should be aware that once the Send method has been invoked against the NewMail object, the NewMail object is invalidated and cannot be reused. Attempting to access the object after it has been invalidated will lead to a run-time error in the ASP script. To send another message you will need to create a new NewMail object.
Finally, it is worth reiterating that the NewMail object is completely distinct from the other objects that form the hierarchy of Collaboration Data Objects for NT Server. These other objects provide a greater granularity of control and are more suited when you want to do something a little more complex than can be achieved through the limited functionality of the NewMail object. We'll have a look at those other objects now.
We saw earlier that the majority of the objects within the CDO for NTS library form a hierarchy topped by the Session object.
Clearly, using the object hierarchy to send mail messages is going to be a more long-winded process than using the NewMail object, but the corollary is that the degree of control that the object hierarchy provides to the programmer is significantly increased.
The top-level object of the CDO for NTS hierarchy is the Session object, which is used to store settings and options that apply throughout a user's session. Once we have created a Session object, the first thing we should do is to invoke the object's LogonSMTP method to indicate the context for the Session object.
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP ("Rob Smith", "rob@ivory.co.uk")
This creates a Session for a user, sets the user's SMTP address to rob@ivory.co.uk and sets the user's friendly name to Rob Smith.
Note that the user's identity is not validated by the LogonSMTP method. In other words, any SMTP address and friendly name can be provided as parameters to the LogonSMTP method and CDO for NTS will use them without complaint. However, if the SMTP address is incorrect the message will not be deliverable.
Once a session has been established, we can then access the Inbox and Outbox folders for that particular session.
When we have finished with the Session object, we should log off by invoking the LogOff method and then set the Session object to Nothing.
objSession.Logoff
Set objSession = NothingA folder is any location in which messages can be stored. These include the Inbox, in which incoming messages are stored; the Outbox in which outgoing messages are held before they are sent; and any personal folders that might have been set up when using other servers such as Exchange Server.
In order to manipulate the messages in a folder, we must first set a reference to the folder itself. The easiest way to do this in CDO for NTS is to use the Inbox and Outbox properties of the Session object which each return a folder object.
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP ("Rob Smith", "rob@ivory.co.uk")
Set objInbox = objSession.Inbox
Once we have a folder object, we can then go on to inspect any messages that are stored within that folder, by using the Messages property of the folder. This returns a Messages collection which contains all of the messages in the folder.
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP ("Rob Smith", "rob@ivory.co.uk")
Set objInbox = objSession.Inbox
Set colMessages = objInbox.Messages
Response.Write objInbox.Name & " – " & colMessages.Count & " messages"
The actual folders returned by the Inbox and Outbox properties of a Session object depend on whether CDO for NTS is being run against the SMTP service of IIS 4.0 or against Exchange Server.
Inbox property will return the user's regular mailbox and the Outbox property will be the user's outbox.Inbox property will return the Drop directory. Although this contains all of the messages for recipients on the server, only those messages addressed to the user who was bound to the Session object by the LogonSMTP method will be available.
Once we have created a reference to a folder representing an Inbox we can view and delete the messages in that Inbox, through the Messages collection and the Message object. By contrast, the Outbox folder is where we will create any Message objects that we want to send out.
The GetDefaultFolder method of the Session object can also be used against an IIS 4.0 SMTP server to return the Inbox or Outbox folder. However, the GetDefaultFolder method is more useful against an Exchange Server where it can be used to retrieve other types of folders such as Outlook calendar or contacts folders.
You will have noticed by now that using the CDO for NTS object hierarchy is considerably more involved than simply using the NewMail object. But it is when we see what can be done with the Messages collection and Message object that we begin to realize how much more powerful the object hierarchy is. So far, we have looked at how to create a session and set a reference to an Inbox or Outbox folder. Now we will look at what we can do with the messages inside those folders.
The following code demonstrates how it is possible to display a summary of all messages received for a particular user, which contain a given string in their body text.
<%@ LANGUAGE="VBSCRIPT"%>
<%Option Explicit%>
<% Response.Buffer=True %>
<%
'Dim all the variables here
...
%>
<HTML>
<HEAD>
<TITLE>Search Results</TITLE>
</HEAD>
<BODY>
<H1>Search Results</H1>
<TABLE>
<TR>
<TD>User:</TD>
<TD><I><%=Request.QueryString("Name")%></I> </TD></TR>
<TR>
<TD>Address:</TD>
<TD><I><%=Request.QueryString("Address")%></I> </TD></TR>
<TR>
<TD>Search String:</TD>
<TD><I><%=Request.QueryString("Text")%></I> </TD></TR>
</TABLE>
<p>
<%
sName = Request.QueryString("Name")
sAddress = Request.QueryString("Address")
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP sName, sAddress
Set objInbox = objSession.Inbox
If objInbox.Messages.Count = 0 Then
Response.Write "There are no messages in the Inbox"
Set objInbox = Nothing
objSession.Logoff
Set objSession = Nothing
Response.End
Else
%>
<P>
<TABLE BORDER="0" BGCOLOR="#C0C0C0" CELLSPACING="2">
<TR>
<TD BGCOLOR="#E0E0E0" WIDTH="200"><B>Subject</B></TD>
<TD BGCOLOR="#E0E0E0" WIDTH="150"><B>Sent By</B></TD>
<TD BGCOLOR="#E0E0E0" WIDTH="200"><B>Time Sent</B></TD></TR>
<%
Set colMessages = objInbox.Messages
iHits = 0
For iLoop = 1 to colMessages.Count
Set objMessage = colMessages(iLoop)
If Instr(objMessage.Text, Request.QueryString("Text")) Then
iHits = iHits + 1
%>
<TR>
<TD BGCOLOR="#E0E0E0" WIDTH="200"><%=objMessage.Subject%></TD>
<TD BGCOLOR="#E0E0E0" WIDTH="100"><%=objMessage.Sender%></TD>
<TD BGCOLOR="#E0E0E0" WIDTH="200"><%=objMessage.TimeSent%></TD>
</TR>
<%
End If
Next
%>
</TABLE>
<%
If iHits = 0 Then
Response.Clear
Response.Write "No messages contained the specified text"
End If
End If
Set objMessage = Nothing
Set colMessages = Nothing
Set objInbox = Nothing
objSession.Logoff
Set objSession = Nothing
%>
</BODY>
</HTML>
When this script is run and the appropriate arguments are passed in as QueryString parameters, a page similar to this one will be displayed.
The first few lines of code are responsible for displaying the parameters which are passed in as QueryString parameters:
<TABLE>
<TR>
<TD>User:</TD>
<TD><I><%=Request.QueryString("Name")%></I> </TD></TR>
<TR>
<TD>Address:</TD>
<TD><I><%=Request.QueryString("Address")%></I> </TD></TR>
<TR>
<TD>Search String:</TD>
<TD><I><%=Request.QueryString("Text")%></I> </TD></TR>
</TABLE>
The Name argument (John.de.Robeck)is the friendly name of the recipient of the messages which we want to search through. The Address argument (jdr@here.com) corresponds to the person's SMTP address. And the Text argument supplies the text which we will be search for in the body of that person's messages. Note that we use the encoded value %20 to represent a space in the Text argument.
The next step is to create a Session object and log on using the name and SMTP address supplied as arguments.
sName = Request.QueryString("Name")
sAddress = Request.QueryString("Address")
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP sName, sAddress
Next, we create a reference to the Inbox by using the Inbox property of the Session object. Because we will be executing this code against an IIS 4.0 SMTP server, this will give us access to all of the messages in the Drop directory which were addressed to the person whose address we used when we performed the LogonSMTP method.
Set objInbox = objSession.Inbox
The Messages property of the Inbox object objInbox returns a collection containing all of the messages in the Inbox. We can then inspect the Count property of this collection to determine whether or not there are any messages addressed to this person.
If objInbox.Messages.Count = 0 Then
Response.Write "There are no messages in the Inbox"
Set objInbox = Nothing
objSession.Logoff
Set objSession = Nothing
Response.End
If the Count property returns 0, we display a message saying that there are no messages and after reclaiming the memory allocated to the various objects we have instantiated so far, we end our script.
However, if the Inbox does contain messages, we must inspect them each to determine whether they contain the text which was supplied in the Text argument to this page. We start by caching the Messages collection of the Inbox in an object variable for performance purposes and then initialize a counter.
Set colMessages = objInbox.Messages
iHits = 0
We then loop through each of the Message objects in the Messages collection and assign each one to a variable (objMessage) in turn. Note that the collection is not zero-based. In other words, the first item in the collection has an index of 1 rather than 0.
For iLoop = 1 to colMessages.Count
Set objMessage = colMessages(iLoop)
In order to determine whether the message we have cached contains the selected string, we use the Instr function. This searches one string for occurrences of a substring and, if it is found, returns the starting position of the substring. We are only concerned that the substring should be located and are not bothered about its position, so we simply need to check that the Instr function returns a non-zero value.
If Instr(objMessage.Text, Request.QueryString("Text")) ThenIf the text for which we are searching is found, we increment our hit counter and then add a row to the table displaying the results.
iHits = iHits + 1
%>
<TR>
<TD BGCOLOR="#E0E0E0" WIDTH="200"><%=objMessage.Subject%></TD>
<TD BGCOLOR="#E0E0E0" WIDTH="100"><%=objMessage.Sender%></TD>
<TD BGCOLOR="#E0E0E0" WIDTH="200"><%=objMessage.TimeSent%></TD>
</TR>
We then continue our loop until we have searched through all of the messages in the Inbox. If none of the messages were found to contain the selected text, the hit counter (iHits) will still be at zero. If this is the case, we clear the contents of the Response buffer (which would have contained the headings for the result table) and display a message indicating that the text could not be found in any of the messages.
If iHits = 0 Then
Response.Clear
Response.Write "No messages contained the specified text"
End IfAll that remains is to reclaim all the resources which was allocated to our object variables and end the script.
Set objMessage = Nothing
Set colMessages = Nothing
Set objInbox = Nothing
objSession.Logoff
Set objSession = Nothing
This is just one example of the way that you can manipulate messages in the Inbox. Most of the time you will only be able to inspect the messages and their properties in the Inbox. The key exception to this role is when you use the Delete method of the Messages collection to delete a message. By way of contrast, messages that you create in the Outbox can be modified and this is what we do when we want to send a message using the CDO for NTS object hierarchy.
The principle behind sending a message using CDO for NTS objects is straightforward, although clearly not as simple as if we were just to use the NewMail object. Here is an example of how it works.
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP "John", "jdr@there.com"
Set objOutbox = objSession.Outbox
Set objMessage = objOutbox.Messages.Add
objMessage.Subject = "Where are my books?"
objMessage.Text = "I can't find them anywhere and I need them now!"
objMessage.Importance = cdoHigh
objMessage.Attachments.Add "BookList.txt", cdoFileData, "c:\pressies.txt"
objMessage.Recipients.Add "Rob", "rob@ivory.co.uk", cdoTo
objMessage.Recipients.Add "Jim", "jim@ivory.co.uk", cdoCC
objMessage.Send
Set objMessage= Nothing
Set objOutbox = Nothing
objSession.Logoff
Set objSession = NothingExecuting this script should cause the following message to be sent. The message is displayed in Outlook Express. It may look different when viewed in other mail clients.
Note the image of a stamp in the upper right corner bearing an exclamation mark. This is how Outlook indicates that the message has a high priority.
If you have managed to follow this chapter so far, there shouldn't be anything in this code fragment that will throw you. We start of with the now familiar process of creating a Session object and logging on as John, with an SMTP address of jdr@there.com.
Set objSession = CreateObject("CDONTS.Session")
objSession.LogonSMTP "John", "jdr@there.com"This time, however, we are not going to be looking in John's Inbox. Rather, we want to send a message and for that we need access to his Outbox. So we set a reference to the Outbox and then create a new message in the Outbox.
Set objOutbox = objSession.Outbox
Set objMessage = objOutbox.Messages.AddNext, we need to set the properties of the message. We fill in the subject line and body text of the message and then set its importance as high.
objMessage.Subject = "Where are my books?"
objMessage.Text = "I can't find them anywhere and I need them now!"
objMessage.Importance = cdoHigh
Next, we add an attachment to the message. There are two types of attachment that we can add to messages. The first type, which is denoted by the constant cdoFileData, are operating system files, such as Word documents or Excel spreadsheets. To attach these we use the syntax we have used here:
objMessage.Attachments.Add "BookList.txt", cdoFileData, "c:\pressies.txt"
This line adds a new Attachment object to the collection of Attachments for the current message. When adding a file attachment, we pass three parameters to the Add method of the Message object:
"BookList.txt") specifies the caption which will appear against the attachment when viewed by a client.cdoFileData) signifies that the attachment is a file."c:\pressies.txt") indicates the location of the file which is to be attached.
The second type of attachment, denoted by the constant cdoEmbeddedMessage, is an embedded message. This would be used if you wanted to embed another mail message in the message you were sending. To embed a message we would have used this syntax:
objMessage.Attachments.Add "", cdoEmbeddedMessage, objOldMessage
When embedding a message, the three parameters to the Add method have the following meanings:
"") specifying the name of the attachment is always ignored when embedding a message.cdoEmbeddedMessage) signifies that the attachment is an embedded message.objOldMessage) is a Message object representing the message which is to be embedded.The penultimate step is to specify the two recipients of the message.
objMessage.Recipients.Add "Rob", "rob@ivory.co.uk", cdoTo
objMessage.Recipients.Add "Jim", "jim@ivory.co.uk", cdoCC
The first recipient has a display name of Rob, an SMTP address of rob@ivory.co.uk and is the primary recipient of the message. The second recipient has a display name of Jim, an SMTP address of jim@ivory.co.uk and will receive a copy of the message.
All that remains now is to send the message.
objMessage.Send
As with the NewMail object, the Send method causes the Message object to be sent and then invalidates it. This means that any subsequent reference to the Message object will generate an error. All that remains is to log off and free up the resources that had been allocated to the objects we used in this code.
There is one object in the CDO for NTS hierarchy at which we have not yet looked and that is the AddressEntry object. Although displayed in the hierarchy as if it were a child of the Message object, this is not strictly true. In fact, the AddressEntry object is accessed through the Sender property of the Message object, like this:
Dim objAddressEntry
Set objAddressEntry = objMessage.Sender
sAddressName = objAddressEntry.Name
sAddressType = objAddressEntry.Type
sAddress = objAddressEntry.Address
As you may have guessed from this, the purpose of the AddressEntry is to provide more information about the sender of a message. So far we have concerned ourselves solely with the use of CDO for NTS as a method for manipulating mail within a purely SMTP environment. However, as we noted earlier, CDO for NTS can be used against Exchange Server 5.5. In Exchange, with the appropriate connectors installed, one can receive messages from senders on a variety of other messaging systems, such as MS Mail or cc:Mail.
We saw earlier that the format of an SMTP address is always in the format username@domainname, as in rob.smith@ivory.co.uk. However, different messaging systems use different formats for their addresses. Consequently, in an environment such as Exchange 5.5, where messages may be received from heterogeneous messaging systems, we need a mechanism for determining both the messaging system and the address of the sender of a message if we are to reply to that message.
The AddressEntry object provides this mechanism and has three specific properties (Name, Type and Address) in addition to the properties which are common to all objects in the CDO for NTS hierarchy.
Name property returns the friendly name. This is the name that is typically displayed by the mail client in its From: box.Type property returns the messaging system used by the sender of the message.Address property returns the true messaging system-specific address of the sender of the message.
To see how this works, let's consider the message that we created in the previous example. In this example, the Name property of the AddressEntry object representing the sender of the message would be John. Why? Because that was the display name that we used when we logged on to the session from which we sent the message.
objSession.LogonSMTP "John", "jdr@there.com"
Similarly, the Address property would return jdr@there.com because that was the address we used to log on with.
And finally, the Type property would return SMTP. In fact, when using CDO for NTS with the SMTP server that comes with IIS 4.0, the Type property of all AddressEntry objects will be SMTP. When running CDO for NTS against Exchange Server 5.5, however, the Type might vary and the table below gives a few examples of the values that one might encounter in such a heterogeneous environment.
| Name | Type | Address |
| John | SMTP | jdr@there.com |
| John2 | CCMAIL | John de Robeck at There |
| John3 | MS | THERE/EDINBURGH/JOHND |
| John4 | X400 | c=UK;a= p=There; o=Edinburgh; s=deRobeck; g=John |
The primary use for the AddressEntry object is in constructing a valid Recipient object for use in replies to messages. By concatenating the Type property and the Address property of the AddressEntry object in the form type: address one can form a return address which is acceptable to Exchange Server as in the example below:
Set objAddressEntry = objOldMessage.Sender
sReturnAddress = objAddressEntry.Type & ": " & objAddressEntry.Address
objNewMessage.Recipients.Add objAddressEntry.Name, sReturnAddress, cdoTo
There are four properties common to all objects in the CDO for NTS object hierarchy. These are the Application, Class, Parent and Session properties. The following table details what each of these objects returns together with notes on their use.
| Property | Returns | Note |
| Application | String | The string indicates the version of CDO for NTS. For the version of CDO for NTS released with IIS 4.0 the application object returns: Collaboration Data Objects for NTS version 1.2 |
| Class | Long Integer | The integer indicates the type of object of which this is a property. The objects indicated by each of the return values are as follows:
0Session object |
| Parent | Object or Nothing | The object returned is the immediate parent of the specified object in the CDO for NTS hierarchy (see diagram above). Two cases worthy of note are:
the AddressEntry object, which returns as its parent the Message object from whose Sender property it is derived; |
| Session | Session object | This returns the Session object at the top of the CDO for NTS hierarchy. |