CHAPTER 14 Collaboration Data Objects for Windows NT Server

The ability for the server to send messages to clients and vice versa is an increasingly important aspect of many web sites. Using messaging back and forth between web server and client, you can alert the webmaster of issues with the site or send webmasters suggestions and comments. More important than either of those, however, is the ability to send notices and reminders to your users, making infrequent visitors into subscribers. “Subscribers” are the most important facets of any web site. With a list of people (or even a count of those people) who have subscribed to your web site (to be notified of updates or changes, for example), you have a concrete, quantifiable estimate of your site’s average users. In the past, such messaging required that the client machine activate a mail program and send the webmaster email. The webmaster would receive this email and, in turn, add the sender to her site’s mailing list. As technology for web sites evolved, you were able to send and receive mail from within server-only applications (through web forms, for example), and separate email functionality was not required. The web applications used mail behind the scenes. Such web applications were usually CGI applications and were written in lower-level languages. These applications are simple and work well. However, for the work that goes into writing them, they sometimes lack flexibility. With the advent of Collaboration Data Objects for NTS (formerly known as Active Messaging), you now have a COM interface to a powerful set of objects that makes adding messaging functionality to your ASP application simple. Collaboration Data Objects for Windows NT Server (CDONTS) is a collection of COM objects that work with Windows NT, IIS, and SMTP (or Microsoft Exchange) to enable your applications to easily send and receive electronic mail. It does not require Microsoft Exchange (or another mail server) but can use it if it exists on the same server on which the application is running. Without a mail server, CDONTS works with SMTP to route all messaging to a mail server on the network or Internet. Instantiating Collaboration Data Objects 257 Collaboration Data Objects Instantiating Collaboration Data Objects ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Like most messaging subsystems, CDONTS receives messages from an Inbox and writes messages to an Outbox. These mail bins exist in different places, depending on the server component with which CDONTS is working. If SMTP is being used, the Inbox and Outbox are actually mapped directly to file system files on the web server. In this instance, CDONTS sends all messages immediately through SMTP, and the Outbox is empty. Likewise, any incoming messages are removed from the Inbox and placed into the file system directly. You may have heard of CDO before IIS. It is called CDO for Exchange, and its object library is almost exactly the same as that of CDO for NTS. The only difference in functionality is that CDONTS uses the Session object’s LogonSMTP method to log on, whereas CDO for Exchange uses the Logon method. The only other difference is the presence of the NewMail object in the CDO for NTS library. This object has no counterpart in CDO for Exchange. A full explanation of Collaboration Data Objects for NTS, like one for ActiveX Data Objects, would require an entire book to itself. In the interest of space in this book, I will provide only a brief overview of the majority of features of CDONTS, since most ASP applications will not use the bulk of the functionality supported by CDONTS. Instead, I will cover in depth all the properties and methods of the NewMail object. This addition to the CDO library makes it possible to send mail— including attachments—from any ASP application script to any email address using just a few lines of code. Accessory Files/Required DLL Files Cdonts.DLL The dynamic link library and type library for the CDO for NTS COM objects. You must install this on the web server (using the latest executable setup file from Microsoft) before you can instantiate or use any of the CDO objects. It is installed by default when you install IIS 4.0. Microsoft Exchange does not have to be installed before installing CDO. However, SMTP (or Exchange) must be installed before you can successfully send and receive messages. Instantiating Collaboration Data Objects To create an instance of a Collaboration Data Object, use the Server.CreateObject method. Its syntax is as follows: Set objMyObject = Server.CreateObject(strProgId) where: • objMyObject represents the name of the collaboration data object variable you are instantiating. • strProgId represents the programmatic ID (ProgID) for the specific Collaboration Data Object you are instantiating. The possible values for this parameter can be found in Table 14-1. 258 Chapter 14 – Collaboration Data Objects for Windows NT Server Comments/Troubleshooting ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example <% ' The following code uses the CreateObject method to ' instantiate a NewMail object on the server. Dim objNewMail Set objNewMail = Server.CreateObject("CDONTS.NewMail") %> For more details on the use of the CreateObject method, see its entry in Chapter 8, Server Object. To use the CDO constants listed in this chapter, you must declare the CDO type library. The following code demonstrates this: [Excerpt from GLOBAL.ASA] <!-- METADATA TYPE="TypeLibrary" FILE="CDONTS.DLL" VERSION="1.2" --> All examples in this chapter assume you have declared the type library beforehand. In this chapter, any CDO constant is followed by the constant’s value in parentheses. Comments/Troubleshooting The only aspect of the properties and methods of the CDO that I might suggest you pay particular attention to is the use of the various Delete methods. The Delete method for nearly every object that has one allows you to delete the current object. This is intuitive for objects. However, you might expect that the Table 14-1: Values for Collaboration Data Objects Collaboration Data Object ProgID AddressEntry CDONTS.AddressEntry Attachment CDONTS.Attachment Folder CDONTS.Folder Message CDONTS.Message NewMail CDONTS.NewMail Recipient CDONTS.Recipients Session CDONTS.Session The CDO Object Model 259 Collaboration Data Objects The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Delete method of a collection would allow you to remove a specific item from the collection, whereas in fact it removes all the members of the collection! Sending email messages from within your ASP application is simple, especially using the NewMail object. However, one thing that I’ve taken for granted is the architecture that exists between your web server, your mail server, and the Internet. Unfortunately, this can be quite complex and the source of almost all the errors you will experience trying to message-enable your ASP applications. If you have CDONTS set up properly on the server, the calls to any of its methods and properties will work flawlessly, in my experience. Place your web server on the other side of a firewall from your mail server or place a proxy server anywhere along the path and you will likely run into issues. The most important thing to remember when constructing the architecture for messaging from ASP applications on your web server is to ensure that you have the SMTP ports on the firewall set to allow traffic from the web server to reach your mail server. Proxy settings must be addressed on a case-by-case basis. These issues aren’t difficult to resolve, just time consuming, especially in larger companies where the web development group is totally different (physically and politically) from the architecture security group that handles the organization’s firewalls and proxy servers. The CDO Object Model Figure 14-1 shows the 10 objects and collections that make up the CDO object hierarchy. This section lists and very briefly describes all of the properties, collections, and methods (CDO objects do not respond to any events) of each object in the model. As stated before, this is meant only as an overview. For the properties and methods of the NewMail object in the object model, see the in-depth coverage that follows this overview. Common Properties All the objects in the CDONTS object model—except the NewMail object—share four common properties: Application, Class, Parent, and Session. These properties are all read-only. If you ascertain the value of the Application or Session properties from one CDO object, their values will be the same for any other object in the object model. As you can see from the object model in Figure 14-1, the Session object is the highest object in the hierarchy. As such, it has no Parent or Session property values. These properties always have a value of Nothing for any Session object. 260 Chapter 14 – Collaboration Data Objects for Windows NT Server The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. The NewMail object has none of these common properties. Any attempt to retrieve the value of any of the properties listed in Table 14-2 for a NewMail object results in a runtime error. Figure 14-1: The CDO object model Table 14-2: Common Properties of CDO Objects Property Description Application Always contains the string value “Collaboration Data Objects for NTS Version 1.2.” It represents the name of the application using the current session. Class An integer value representing the type of CDO object: cdoAddressEntry (8) = AddressEntry cdoAttachment (5) = Attachment cdoAttachments (18) =Attachments Collection cdoFolder (2) = Folder cdoMsg (3) = Message cdoMessages (16) = Messages Collection cdoRecipient (4) = Recipient cdoRecipients (17) = Recipients Collection cdoSession (0) = Session Session Object Folder (Inbox or Outbox) Messages Collection Message AddressEntry Attachments Collections Attachment Recipients Collection Recipient NewMail The CDO Object Model 261 Collaboration Data Objects The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. AddressEntry Object Parent object: Message object. An object reference is obtained through the Sender Property of a Message object. Represents information about the sender of a specific Message object, including the sender’s email address, name, and email address type. You can obtain a reference to the AddressEntry object only from the Message object’s Sender property. The properties of the AddressEntry object are shown in Table 14-3; the properties are all read-only. Parent The immediate parent object of the current object in the CDO object model. This is the parent according to the object model, not the logical parent. For example, the Parent property of an Attachment object is the Attachments collection, not a Message object, even though you add email attachments to an email message. The value for this property for the Session object is Nothing. This property holds an object pointer and is not simply a string containing the name of the parent object. The following lists the objects in the CDO object library and their immediate parents according to the hierarchy. Note that the parent of the Session object is Nothing: — AddressEntry: Message — Attachment: Attachments Collection — Attachments Collection: Message — Folder: Session — Message: Messages Collection — Messages Collection: Folder — Recipient: Recipients Collection — Recipients Collection: Message — Session: Nothing Session The Session property represents the session within which the current CDO object has been instantiated. If you attempt to retrieve the value of the Session property of a Session object, you will retrieve the Session object itself. Table 14-3: AddressEntry Object Properties Property Description Address A string value representing the information required to send email to the person or process represented by the current AddressEntry object. Name A string value representing the alias or display name for the person represented by the current AddressEntry object. Type A string value that identifies the sender’s messaging service. For the current version of CDO for NTS, the Type property always holds the string “SMTP.” Table 14-2: Common Properties of CDO Objects (continued) Property Description 262 Chapter 14 – Collaboration Data Objects for Windows NT Server The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Attachment Object Parent object: Attachments collection. A new object reference is returned from the Add method of the Attachments Collection. A file or message that is attached to the current Message object. If the current Message object is still in the Inbox, the properties of the Attachment object are all read-only. If, however, the Message object is being prepared for delivery, these properties are all read/write. Remember that CDO for NTS does not control how (or if) the Attachment is displayed in the final Message object. This is controlled by the mail client being used. Tables 14-4 and 14-5 list the properties and methods of the Attachment object, respectively. Table 14-4: Attachment Object Properties Property Description ContentBase The Content-Base header of a MIME message attachment. For example, if all the relative URLs in your MIME message are valid only for http://www.mycorp.com, then the Content- Base value should be http://www.mycorp.com/. Once the ContentBase is set, the relative URLs in the message have meaning. For example, suppose you have a MIME email message containing an image with the SRC property set to /images/myimg.jpg. The ContentBase lets the mail client know that this means http://www.mycorp.com/images/ myimg.jpg. ContentID The Content-ID header of a MIME message attachment. This is read-only for messages coming in. CDO does not generate Content-ID headers for outgoing messages and attachments. For more information on Content-ID headers, see RFC 2111. ContentLocation The Content-Location header of a MIME message attachment. Name The name of the Attachment in the current Message object. This is the default property for Attachment objects. Source A string value that represents the physical location on the sender’s machine of the contents of the attachment. The attachment contents will be added to the Message object from the location listed here. Type The type of attachment. The possible values of the Type property are cdoFileData (1) (the attachment is the contents of a file) or cdoEmbeddedMessage (4) (the attachment is an embedded message). Table 14-5: Attachment Object Methods Method Description Delete Removes the current Attachment object from the Attachments collection ReadFromFile Reads the contents of a file into an Attachment object WriteToFile Writes the contents of an Attachment object to the file system The CDO Object Model 263 Collaboration Data Objects The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Attachments Collection Parent object: Message object. An object reference to an Attachments collection is returned from a call to the Attachments property of a Message object. The Attachments collection is a child of a Message object and contains zero or more Attachment objects. Use the Attachments collection to add new Attachment objects to a message or to access the attachments that are already part of the current message. Tables 14-6 and 14-7 list the properties and methods of the Attachments collection, respectively. Folder Object Parent object: Session object. An object reference to a Folder object can be returned from a call to the GetDefaultFolder method or from the InBox or OutBox properties of a Session object. The Folder object represents the Inbox or Outbox for the current session. Use the Folder object to access, add, or delete Message objects in the default Inbox or Outbox for the current messaging system and session. Tables 14-8 and 14-9 list the properties and the single collection, respectively, of the Folder object. Table 14-6: Attachments Collection Properties Property Description Count An integer value that represents the number of Attachment objects in the Attachments collection. This property is read-only. Item Returns a reference to a single Attachment object in the collection. This property is read-only. Table 14-7: Attachments Collection Methods Method Description Add Adds an Attachment object to the Attachments collection. You can add Attachment objects to an Attachments collection only for a message you are sending. Delete Removes all the Attachment objects from the current Attachments collection. Be cautious when using the Delete method of the Attachments collection, since it deletes every Attachment object in the collection. To remove a single Attachment object from a collection, use the Delete method of the Attachment object. Table 14-8: Folder Object Properties Property Description Messages Returns a pointer to the current Folder object’s Messages collection Name A read-only string that represents the name of the folder 264 Chapter 14 – Collaboration Data Objects for Windows NT Server The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Message Object Parent object: Messages collection. An object reference to a Message object is returned from a call to the Add method of a Messages collection. Each Message object in the Messages collection contains a single email message or document. Each Message object is the child of a Messages collection. A Message object can contain embedded Attachment objects. Tables 14-10, 14-11, and 14-12 list the properties, collections, and methods, respectively, of the Message object. Table 14-9: Folder Object Collection Collection Description Messages Each Folder object has a child Messages collection. The Messages collection contains zero or more Message objects Table 14-10: Message Object Properties Property Description Attachments Points to either a single Attachment object or to the Message object’s Attachments collection. ContentBase The Content-Base header of a MIME message content body. ContentID The Content-ID header of a MIME message content body. ContentLocation The Content-Location header of a MIME message content body. HTMLText A string value that represents the HTML version of the content body of the Message object. Importance An integer value that represents the priority of a Message object. This priority is used by the messaging system to schedule sending messages. MessageFormat An integer value that indicates whether the message is MIME encoded or simple text. Recipients An object pointer either to a single Recipient object for the current Message object or to the Recipients collection of the Message object. Sender The email address of the sender of the current Message object. This is an AddressEntry object. Size An integer value that represents the size in bytes of the Message object. Subject A string value representing the subject line that will be sent with the current Message object. Text A string value that contains the plain text of the message content body. TimeReceived A date/time value that represents the time and date when the current Message object was received into the Inbox. TimeSent A date/time value that represents the time and date when the current Message object was sent from the Outbox. The CDO Object Model 265 Collaboration Data Objects The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Messages Collection Parent object: Folder object. An object reference to a Messages collection is returned from the Messages property of a Folder object. The Messages collection contains all the Message objects in the current Folder object. Through the Messages collection, you can add Message objects to the current folder (Inbox only). Tables 14-13 and 14-14 list the properties and methods, respectively, of the Messages collection. NewMail Object Parent object: None. The NewMail object is an addition to the original CDO library specifically for adding messaging functionality to an application. It makes sending a mail message as simple as writing a few lines of code. The NewMail object was built solely to Table 14-11: Message Object Collections Collection Description Attachments Contains all the Attachment objects for the current message Recipients Contains all the Recipient objects for the current message Table 14-12: Message Object Methods Method Description Delete Removes the current Message object from the Messages collection Send Sends the current Message object to all recipients represented in the current Message object’s Recipients collection Table 14-13: Messages Collection Properties Property Description Count An integer value that represents the number of Message objects currently contained in the Messages collection Item An object pointer that allows you to retrieve a specific Message object from the Messages collection Table 14-14: Messages Collection Methods Method Description Add Adds a Message object to the Messages collection Delete Removes all the Message objects currently in the Messages collection GetFirst Retrieves the first Message object in the Messages collection GetLast Retrieves the last Message object in the Messages collection GetNext Retrieves the next Message object in the Messages collection in relation to a specific Message object GetPrevious Retrieves the previous Message object in the Messages collection in relation to a specific Message object 266 Chapter 14 – Collaboration Data Objects for Windows NT Server The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. quickly generate messages from within an application. There is no user interaction allowed for the NewMail object, and there is no support for an interface for logging into a mail server. None of the properties common to the other CDO library items are supported by the NewMail object. The properties of the NewMail object are write-only. If you add Recipient objects or Attachment objects to a NewMail object, those items cannot be removed. You cannot access the properties of any of the other CDO objects from within a NewMail object. The NewMail object is not part of the CDO hierarchy but is instantiated by itself. You cannot remove the NewMail object from memory until you explicitly set the NewMail object variable to Nothing. All of the properties and methods of the NewMail object listed in Tables 14-15 and 14-16 are detailed in the “NewMail Object Properties Reference” and “Methods Reference” sections of this chapter. Table 14-15: NewMail Object Properties Property Description Bcc A string value that represents the recipients that will receive a blind copy of the current message. Body A string value that represents the NewMail’s content body text. BodyFormat An integer value that represents the text format for the message content body text. Cc A string value that represents the recipients who will receive a copy of the current message. ContentBase A string value that represents the base root URL for all URLs relating to the NewMail object’s content. ContentLocation An absolute or relative path for all URLs relating to the NewMail object’s content. From A string value containing the email address of the NewMail message sender. Importance An integer value that represents the priority of the NewMail message. It is used by the messaging subsystem in scheduling the delivery of the current message. MailFormat An integer value that represents the encoding method for the NewMail object message’s content. Subject A string value containing the subject string for the current message. To A string value that represents the email address of the recipients of the NewMail object’s message. Value A string property that allows you to add headers, such as File, Keywords, or Reference, to the current message. The messaging subsystem must recognize these headers or they will be ignored. Version A string value that represents the version of the CDO library. The CDO Object Model 267 Collaboration Data Objects The CDO Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Recipient Object Parent object: Recipients collection Allows you to set and retrieve the properties for a specific recipient of your message. The properties and the single method of the Recipient object are shown in Tables 14-17 and 14-18, respectively. Recipients Collection Parent object: Message object The Recipients collection contains all the Recipient objects, representing the receivers of the current message. Its properties and methods are listed in Tables 14-19 and 14-20, respectively. Table 14-16: NewMail Object Methods Method Description AttachFile Attaches a file to the current message AttachURL Attaches a file to the current message and associates a URL with that attachment Send Sends the current message to all the recipients listed in the To, Cc, and Bcc properties SetLocaleIDs Identifies the messaging user’s locale Table 14-17: Recipient Object Properties Property Description Address A string value that represents the email address of the current message recipient Name A string value that represents the common name or alias for a specific recipient of the current message Type An integer value that represents the type of a specific recipient (To, Cc, or Bcc): cdoTo (1) = To cdoCc (2) = Cc cdoBcc (3) = Bcc Table 14-18: Recipient Object Method Method Description Delete Deletes the current Recipient object from the Recipients collection. Table 14-19: Recipients Collection Properties Property Description Count An integer value that indicates the number of Recipient objects currently contained in the collection Item An object property that returns a specific Recipient object in the collection 268 Chapter 14 – Collaboration Data Objects for Windows NT Server NewMail Object Properties Reference ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Session Object Parent object: None. The Session object is the top-level object in the CDONTS hierarchical object model. Unless you use the NewMail object, you must have an active Session object to send messages using the CDONTS library. The Session object’s properties and methods are shown in Tables 14-21 and 14-22, respectively. NewMail Object Properties Reference Bcc objNewMail.Bcc = strBCCRecipListString A string value containing a list of recipients who will receive a blind copy of the current message. Table 14-20: Recipients Collection Methods Method Description Add Adds a Recipient object to the collection Delete Removes all the current Recipient objects from the collection Table 14-21: Session Object Properties Property Description InBox A Folder object that represents the current Inbox of the current session MessageFormat An integer value that represents the default message encoding for any Message object instantiated within the current session Name A string value that represents the display name used to log into the mail system for this session OutBox A Folder object that represents the current Outbox of the current session Version A string value that represents the version of the CDO library Table 14-22: Session Object Methods Method Description GetDefaultFolder Retrieves the default Folder object for the current session Logoff Closes the current session with the mail system and logs off from the system LogonSMTP Initializes the current session SetLocaleIDs Sets the default locale ID for messages sent or received during this session Body 269 Collaboration Data Objects Body ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters strBCCRecipListString A string containing one or more recipient email addresses separated by semicolons (;) Example The following example demonstrates how to add a recipient to the Bcc list for the current message. <% ' Dimension local variables. Dim objNewMail Dim strBCCRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the Bcc property of the NewMail object to the following ' email addresses: (1) tom@execucom.com, (2) billw@firebird.com ' and (3) helen@zoologyzine.com. strBCCRecipList = _ "tom@execucom.com;billw@firebird.com;helen@zoologyzine.com" objNewMail.Bcc = strBCCRecipList ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send(,,"This is the subject",,cdoHigh) %> Notes As demonstrated in the example, the string you use to set the Bcc property of the NewMail object can contain a single email address or multiple email addresses separated by semicolons. Body objNewMail.Body = strBody A string value that represents the body content text of the current mail message. Parameters strBody A string value that contains the text you want sent as the body of your message 270 Chapter 14 – Collaboration Data Objects for Windows NT Server BodyFormat ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example The following example demonstrates how to set the Body property for the current message. <% ' Dimension local variables. Dim objNewMail ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes The string you use to set the value of the Body property can contain either text or HTML. If you wish to use HTML in the Body property, you must set the Body- Format property to reflect this content type. The possible values for BodyFormat are as follows: BodyFormat objNewMail.BodyFormat = intFormatType An integer value that you can use to set whether the content of the current message is plain text or HTML. Parameters intFormatType An integer that can be set to either of the following constants: CdoBodyFormatHTML(0) The Body property represents HTML. CdoBodyFormatText (1) The Body property represents plain text. Value Description 0 The value in the Body property includes some HTML. 1 The value in the Body property includes only text. Cc 271 Collaboration Data Objects Cc ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example The following example demonstrates how to set the BodyFormat property for the current message. <% ' Dimension local variables. Dim objNewMail Dim strBodyContent ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. strBodyContent = _ "<HTML><HEAD><TITLE>My HTML Content</TITLE></HEAD><BODY>" strBodyContent = strBodyContent & _ "Wow, this message takes just a few lines of code.</BODY>" ' Set the BodyFormat so that the NewMail object ' treats the body contents as HTML. objNewMail.BodyFormat = cdoBodyFormatHTML ' Set the body content string for the NewMail object. objNewMail.Body = strBodyContent ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes If you do not set the BodyFormat property, the default is cdoBodyFormatText. Cc objNewMail.Cc = strBCCRecipListString A string value that contains a list of recipients who will receive a copy of the current message. Parameters strCCRecipListString A string containing one or more recipient email addresses separated by semicolons (;) Example The following example demonstrates how to add a recipient to the Cc list for the current message. 272 Chapter 14 – Collaboration Data Objects for Windows NT Server ContentBase ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. <% ' Dimension local variables. Dim objNewMail Dim strCCRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the Bcc property of the NewMail object to the following ' email addresses: (1) billw@firebird.com and ' (2) helen@zoologyzine.com. strCCRecipList = _ "billw@firebird.com;helen@zoologyzine.com" objNewMail.Cc = strCCRecipList ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send(,,"This is the subject",,cdoHigh) %> Notes As demonstrated in the example, the string you use to set the Cc property can contain a single email address or multiple email addresses separated by semicolons. ContentBase objNewMail.ContentBase = strContentBase A string representing the base for all URLs referenced within the body of the message content. This property is used only for MIME HTML (for more information on MHTML, see RFC 2110). The ContentBase property represents the URL on which all relative URLs in the HTML section of the body are based. Parameters strContentBase A string containing a base URL for all URLs in the content HTML for the current message Example The following example demonstrates the use of the ContentBase property in conjunction with the ContentLocation property (see its entry later in the following section). ContentBase 273 Collaboration Data Objects ContentBase ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. <% ' Dimension local variables. Dim objNewMail Dim strBodyContent ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. strBodyContent = "<HTML><HEAD><TITLE>" strBodyContent = strBodyContent & "My HTML Content" strBodyContent = strbodyContent & "</TITLE></HEAD><BODY>" strBodyContent = strBodyContent & "Here is an excellent image:" strBodyContent = strBodyContent & "<BR>" strBodyContent = strBodyContent & "<IMG SRC = "TodaysPic.jpg">" strBodyContent = strBodyContent & _ "<BR>I hope you like today's picture.</BODY>" ' Set the ContentBase and ContentLocation so the messaging ' system knows how to resolve the simple URL in the preceding ' image tag. objNewMail.ContentBase = "http://www.MyPrimarySvr.com/" objNewMail.ContentLocation = "graphics/dailypics/" ' Now the preceding img tag can be resolved to: ' www.MyPrimarySvr.com/graphics/dailypics/TodaysPic.jpg ' when it is displayed on the recipient's mail client. ' Set the BodyFormat so that the NewMail object ' treats the body contents as HTML. objNewMail.BodyFormat = cdoBodyFormatHTML ' Set the body content string for the NewMail object. objNewMail.Body = strBodyContent ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes The ContentBase and ContentLocation properties are useful only for message body content containing HTML. The ContentBase property is to the URLs in the body HMTL content what the ContentBase argument of the AttachURL method is to URLs in attached HTML files. 274 Chapter 14 – Collaboration Data Objects for Windows NT Server ContentLocation ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ContentLocation objNewMail.ContentLocation = strContentLocation A string property representing the absolute or relative path for all URLs referenced within the body of the message content. Parameters strContentLocation A string containing a relative or absolute path for all URLs in the content HTML for the current message Example See the example for the ContentBase property in the preceding section. Notes The ContentBase and ContentLocation properties are useful only for message body content containing HTML. The ContentLocation property of the NewMail object is to the URLs in the body HMTL content what the ContentLocation argument of the AttachURL method is to URLs in attached HTML files. From objNewMail.From = strSenderAddr A string value that represents the full messaging address of the sender of the current message. Parameters strSenderAddr A string value containing the messaging address of the person or process that is sending the current NewMail object. This address is not resolved (checked) before it is placed in the mail header sent with the NewMail object. Example This example demonstrates the use of the From property. It also shows that if you set the From property and also include a From string in the Send method call, the setting you used for the From property is ignored and only the string sent to the Send method is actually used. <% ' Dimension local variables. Dim objNewMail ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. Importance 275 Collaboration Data Objects Importance ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Set the From property to the sender's email address. objNewMail.From = "sender@usacom.com" ' Send the message. For details about the Send method, ' see that section in this chapter. ' NOTE: Because we are including a value for the From ' parameter to the Send method call, the value here ' is actually sent to the message's recipient. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes If you set the value of the From property and then also include a From parameter in your call to the NewMail object’s Send method, the argument sent as a parameter to the Send method is the value actually placed in the message’s mail header. You cannot include more than one address in setting the From property, nor can you include a semicolon in the single address. Importance objNewMail.Importance = intPriority An integer value that allows you to set the mail message’s priority, which is used by the mail messaging system to schedule delivery of mail. Parameters intPriority An integer that can contain any of the following CDO constants: CdoLow (0) Low. Schedule delivery during off-hours or times of low system use. CdoNormal (1) Normal. Schedule delivery during regular delivery schedules for normal messages. CdoHigh (2) High. Attempt to deliver immediately. Example <% ' Dimension local variables. Dim objNewMail ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") 276 Chapter 14 – Collaboration Data Objects for Windows NT Server MailFormat ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Set the importance for the message to high. objNewMail.Importance = cdoHigh ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes If you do not set the Importance property, normal priority is assumed. If you set the Importance property explicitly, then later use the Importance argument in your call to the Send method, the second value (the argument to Send) is used and the earlier setting is ignored. The underlying mail messaging system must support this feature or it is ignored. Finally, you have no way of ascertaining how the recipient’s mail messaging system will handle your priority settings. MailFormat objNewMail.MailFormat = intFormatSetting An integer value that allows you to set whether the current message body is MIME encoded or simple text. Parameters intFormatSetting An integer value that can contain either of the following constants: CdoMailFormatMIME (0) The contents of the current message will be in the MIME format. CdoMailFormatText (1) The contents of the current message will be plain text. This is the default. Example This example demonstrates the use of the MailFormat property of the NewMail object. <% ' Dimension local variables. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") Subject 277 Collaboration Data Objects Subject ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ' Set the MailFormat property to plain text (although ' this isn't strictly necessary since it's the default). objNewMail.MailFormat = cdoMailFormatText ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details about the Send method, ' that section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes The value of the MailFormat property becomes the default setting for the EncodingMethod parameter of the NewMail object’s AttachURL and AttachFile methods. Subject objNewMail.Subject = strSubjectString The string that will be sent as the subject line for the current mail message. Parameters strSubjectString A string that holds the subject line to be sent with the message. This can be set to an empty string, but doing so defeats the purpose of the subject line. Example <% ' Dimension local variables. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the Subject property. objNewMail.Subject = "RE: An important note for you" ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details about the Send method, ' see that section in this chapter. Note that the ' subject parameter is not sent. 278 Chapter 14 – Collaboration Data Objects for Windows NT Server To ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes You should always set the Subject property of a NewMail object (or include a subject parameter in the call to the Send method for the current message). If you set the Subject property of the NewMail property and also supply a subject parameter when calling the Send method, the parameter value is used and the Subject property setting is ignored. To objNewMail.To = strRecipListString A string value that contains a list of recipients who will receive the current message. Parameters strRecipListString A string containing one or more recipient email addresses separated by semicolons (;) Example The following example demonstrates how to add a recipient to the To list for the current message. <% ' Dimension local variables. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the Newail object's To property to the following ' email addresses: (1) tom@execucom.com, ' (2) billw@firebird.com, and (3) helen@zoologyzine.com. strRecipList = _ "tom@execucom.com;billw@firebird.com;helen@zoologyzine.com" objNewMail.To = strRecipList ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details about the Send method, ' see the section on this chapter. objNewMail.Send(,,"This is the subject",,cdoHigh) %> Value 279 Collaboration Data Objects Value ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Notes As the example shows, the string assigned to the To property can contain a single email address or multiple email addresses separated by semicolons. Value objNewMail.Value(strHeaderName) = strHeaderValue A string value that represents an additional header to be added to the mail message. The Value property allows you to set the value of this header. Parameters strHeaderName A string containing the name of the header you wish to add to your mail message strHeaderValue A string containing the value of the header represented by strHeaderName Example The following example demonstrates how to use the Value property to add a new header to your current message. <% ' Dimension local variables. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the Value property to add a ReplyTo header to ' the current message before it is sent. objNewMail.Value("ReplyTo") = "Keyton<me@here.com>" ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. For details on the Send method, ' see that ssection in this chapter objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes The Value property of the NewMail object should be used sparingly and only when you know with certainty that the receiving mail messaging system will process the added header(s) correctly. 280 Chapter 14 – Collaboration Data Objects for Windows NT Server Version ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. You can set the value of a header more than once. However, this does not overwrite the first value, but rather adds a second header with the second value. The header name you include must match exactly what the receiving mail messaging system expects, or your header will be ignored or misinterpreted. For example, the ReplyTo header added in the example is not the same as the popular Reply-To header, and would thus be misinterpreted. Version objNewMail.Version A read-only string value holding the current version of CDONTS being used. Parameters None Example <% ' Dimension local variables. Dim objNewMail Dim strCDOVersion ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' The Version property for this version of CDONTS will ' always return the string "1.2". strCDOVersion = objNewMail.Version %> Notes The Version property is read-only. This property has limited functionality in typical applications. Methods Reference AttachFile objNewMail.AttachFile (strSource [, strFileName] [, lngEncodingSetting] ) Embeds an attachment from a file into a mail message. Parameters strSource A string containing the pathname and filename of the file to embed AttachURL 281 Collaboration Data Objects AttachURL ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. strFileName A string containing the name that will be displayed in the mail message to represent the embedded attachment lngEncodingSetting A Long that can contain either of the following CDO constants: CdoEncodingUUEncode (0) The attachment you embed in your message will be encoded in the UUEncode format. This is the default value. cdoEncodingBase64 (1) The attachment you embed in your message will be encoded in the base 64 format. Example <% ' Dimension local variables. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Attach a file in the current message. objNewMail.AttachFile "c:\Data\Proposal.doc", _ "Proposal.Doc", cdoEncodingBase64 ' Send the message. For details about the Send method, ' see that section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes If you set the MailFormat property of the NewMail object, you do not have to include a lngEncodingSetting parameter in your call to the AttachFile method. AttachURL objNewMail.AttachURL(strSource [, strContentLocation] _ [, strContentBase] [, lngEncodingSetting] ) Associates a URL with the attachment embedded in your message. 282 Chapter 14 – Collaboration Data Objects for Windows NT Server AttachURL ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters strSource A string containing the pathname and filename for the file that you want to embed in your message strContentLocation A string containing a relative or absolute path for all URLs in the content HTML for the current message strContentBase A string containing a base URL for all URLs in the content HTML for the current message lngEncodingSetting A Long parameter that can contain either of the following CDO constants: CdoEncodingUUEncode (0) The attachment you embed in your message will be encoded in the UUEncode format. This is the default value. cdoEncodingBase64 (1) The attachment you embed in your message will be encoded in the base 64 format. Example <% ' Dimension local variables. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Attach an attachment to your file and associate a URL ' with it. objNewMail.AttachURL "Proposal.htm", "htmdocs/april/", _ http://www.mysvr.com/graphics/, cdoEncodingBase64 ' Send the message. For details about the Send method, ' see tha section in this chapter. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",,cdoHigh) %> Notes The AttachURL method allows you to add an attachment and an associated URL. This is particularly important when the attachment internally references various Send (NewMail Object) 283 Collaboration Data Objects Send (NewMail Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. images or hyperlinks containing only relative links. For example, an attached HTML document might contain the following hyperlink: <A HREF = "Help.htm">Help Document</A> When this attached document is opened by the message recipient, he will see the following hyperlink, assuming the sender used the syntax in the preceding example: <A HREF = "http://www.mysvr.com/graphics/htmdocs/april/Help.htm”> Help Document </A> Send (NewMail Object) objNewMail.Send (strFrom [, strTo] [, strSubject] [,strBody] _ [,intImportance] ) Sends the current message to its recipients. Parameters strFrom A string value containing the full messaging address of the message’s sender. You cannot have semicolons in this string, nor can you specify multiple senders. strTo A string value containing the message’s primary recipients. You can have multiple recipient addresses in this string, but each must be separated from the last using a semicolon. strSubject A string value containing the subject line for the message. strBody A string value containing the body content for the message. intImportance An integer value corresponding to the priority of the message. The possible values for this parameter are as follows: CdoLow (0) The importance is low. Schedule delivery during off-hours or times of low system use. CdoNormal (1) The importance is normal. Schedule delivery during regular delivery schedules for normal messages. CdoHigh (2) The importance is high. Attempt to deliver immediately. Example <% ' Dimension local variables. 284 Chapter 14 – Collaboration Data Objects for Windows NT Server SetLocaleIDs (NewMail Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Dim objNewMail Dim strRecipList ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." ' Send the message. objNewMail.Send("me@here.com","you@there.com", _ "This is the subject",_ "This is the body of the message",cdoHigh) %> Notes The Send method does not require any arguments. However, if you include arguments, the values you include in your call override the values set using the corresponding property. For example, if you set the Importance property for your NewMail object to cdoHigh and then include an intImportance parameter of cdoLow in your call to the Send method, the message will be sent with low priority. SetLocaleIDs (NewMail Object) objNewMail.SetLocaleIDs (lngCodePageID ) Sets the message sender’s locale. This locale setting controls how certain internal features of the message, such as dates, will be evaluated. Parameters lngCodePageID A required Long value that represents the code page identifier for the message Example <% ' Dimension local variables. Dim objNewMail Dim strRecipList Dim lngChineseCodePage 950 ' Instantiate a NewMail object. Set objNewMail = Server.CreateObject("CDONTS.NewMail") ' Set the body string for the message. objNewMail.Body = _ "Wow, this message takes just a few lines of code." SetLocaleIDs (NewMail Object) 285 Collaboration Data Objects SetLocaleIDs (NewMail Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ' Set the LocaleID to that of Chinese for this message. lngChineseCodePage = 950 objNewMail.SetLocaleID = lngChineseCodePage ...[additional code] %> Notes The LocaleID setting for a sender’s message indicates how the sender’s machine formats dates and times. It also dictates the character selection for the page. You can obtain the current CodePage for a WinNT system by calling the GetCPInfo API function. If you do not use this method to set a LocaleID, your messaging system assumes that your message should use the value stored for this property in your system’s registry database. The SetLocaleIDs method will check the validity of your argument before setting the Locale ID for the current message. 286 ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.