Platform SDK: CDO for Windows 2000

Configuration CoClass

The Configuration Component Object Model (COM) class defines an object that is used to manage messaging configuration settings.

CLSID
CD000002-8B95-11D1-82DB-00C04FB1625D
ProgID
CDO.Configuration
Type Library
Microsoft CDO for Windows 2000 Library
Inproc Server
CDOSYS.DLL
Threading Model
Both

Implemented Interfaces

IConfiguration

Fields

The following fields are used with instances of the Configuration COM class:

Name Description
http://schemas.microsoft.com/cdo/configuration/ namespace All fields within this namespace are used for configuration.
urn:schemas:calendar:timezoneid Used to configure the local time zone for Date typed values.

Remarks

Configuration settings are used by the Message object to specify certain operations, such as whether messages are sent using a Simple Mail Transfer Protocol (SMTP) service pickup directory, or sent through an SMTP service directly over the network. Configuration settings are made up of a set of fields (properties) that consist of name/value pairs. Each field is represented as a Microsoft® ActiveX® Data Object (ADO) Field object that is contained in an ADO Fields collection. To make them unique, most field names reside in the http://schemas.microsoft.com/cdo/configuration/ namespace. Additionally, the urn:schemas:calendar:timezoneid field is used within the Configuration object to set the local time zone.

To configure Message objects, you modify fields in the associated Configuration object. You can either modify fields in the existing Configuration object or create new Configuration object and set the Message object's Configuration property to this object.

In many cases, the default configuration settings are sufficient to send and post messages successfully. The default configuration settings depend on the software installed on the computer on which you are using the CDO component. When you send messages without associating a Configuration object, these defaults are used; for example, if the computer has the SMTP service installed, the default configuration for sending messages is to write them into files in the SMTP pickup directory. Additionally, various settings can be loaded from Microsoft® Outlook® Express if it is installed. For more information about default settings, see the configuration fields section of the reference.

Depending on the software installed, the default operations are summarized in the following table.

CDO Default Configuration Hierarchy

Software installed Defaults loaded from
CDO for Windows 2000, Outlook Express Default mail account
CDO for Windows 2000, IIS SMTP and Network News Transfer Protocol (NNTP) sites
CDO for Windows 2000, IIS, Outlook Express Microsoft Internet Information Server (IIS) and Outlook Express (sends messages through IIS pickup directory)

Configuration objects are effective for optimizing performance and for setting values that conform to user preferences. Default configuration information may not be appropriate for certain applications. The Configuration object should be global.

Configuration objects are useful for Active Server Pages (ASP) applications on the Web, which are created when a Session_OnStart event occurs and stored in each user's ASP Session object.

Example

Assume that the computer on which this example will run has neither an SMTP service nor Outlook Express installed. In this case, you need to send the message through some SMTP service on the network and must completely configure the Message object. Also assume that the SMTP service through which you intend to send messages requires authentication using the basic (clear-text) authentication mechanism. An instance of the Configuration COM class is created and the configuration fields in the object are set with values, such as the required SMTP server name, port, authentication, and user name and password. Additional values are set, such as the e-mail address, account name, and reply e-mail address. The values used in the example are listed in the following table.

Namespace: http://schemas.microsoft.com/cdo/configuration

Field Value
smtpserver fakesmtp.microsoft.com
smtpserverport 25
sendingusing cdoSendUsingPort (2)
smtpaccountname My Name
sendemailaddress "My Self" <myself@microsoft.com>
smtpuserreplyemailaddress "Another" <another@microsoft.com>
smtpauthenticate cdoBasic (1)
sendusername domain\user name
sendpassword password

Once the Configuration object is populated with relevant configuration information, the object reference is set on a Message object. The Message object uses the configuration information to send the message. In the examples that follow, the fully qualified field names are used to illustrate the process; however, there are string constants (as type library modules) in the type library for each of these field names.

[Visual Basic]
  Dim iConf as new CDO.Configuration
  Dim Flds as ADODB.Fields
  Set Flds = iConf.Fields
  
    ' The full field name strings are used below to illustrate this process.
    ' The CDO for Windows 2000 type library contains string Modules
    ' that provide these values as named constants.  
    ' Use these module constants to avoid typos and so on.

  Flds("http://schemas.microsoft.com/cdo/configuration/smtpserver")               = "fakesmtp.microsoft.com"
  Flds("http://schemas.microsoft.com/cdo/configuration/smtpserverport")           = 25
  Flds("http://schemas.microsoft.com/cdo/configuration/sendusing")                = cdoSendUsingPort  ' CdoSendUsing enum value =  2
  Flds("http://schemas.microsoft.com/cdo/configuration/smtpaccountname")          = "My Name"
  Flds("http://schemas.microsoft.com/cdo/configuration/sendemailaddress")     = """MySelf"" <myself@microsoft.com>"
  Flds("http://schemas.microsoft.com/cdo/configuration/smtpuserreplyemailaddress")= """Another"" <another@microsoft.com>"
  Flds("http://schemas.microsoft.com/cdo/configuration/smtpauthenticate")         = cdoBasic
  Flds("http://schemas.microsoft.com/cdo/configuration/sendusername") = "domain\username"
  Flds("http://schemas.microsoft.com/cdo/configuration/sendpassword")    = "password"
  Flds.Update
   
  Dim iMsg as new CDO.Message
  Set iMsg.Configuration = iConf
  
  ' ... compose message; add attachments, and so on.
  
  iMsg.Send   ' Configuration settings in Config object are used to send the message.
 
[C++]
#import "c:\program files\common files\system\ado\msado15.dll" no_namespace
#import <cdosys.dll> no_namespace

main( ){  
  
  CoInitialize(NULL);
  {
    IMessagePtr IMsg(__uuidof(Message));
    IConfigurationPtr iConfig(__uuidof(Configuration));

    FieldsPtr Flds;
    FieldPtr Fld;   
    Flds = iConfig->Fields;

    // The full strings for field names are used to elucidate the process.
    // The cdosys.h header file contains BSTR constants that 
    // can be used to avoid typos, and so on.
   
    Flds->Item["http://schemas.microsoft.com/cdo/configuration/smtpserver"]->Value              
     = _variant_t("fakesmtp.microsoft.com") ;
    Flds->Item["http://schemas.microsoft.com/cdo/configuration/smtpserverport"]->Value         
      = _variant_t((long)25) ;
    Flds->Item["http://schemas.microsoft.com/cdo/configuration/sendusing"]->Value
    = _variant_t((long)cdoSendUsingPort) ;  // this value is 2
    Flds->Item["http://schemas.microsoft.com/cdo/configuration/smtpaccountname"]->Value          
    = _variant_t("My Name") ;
    Flds->Item["http://schemas.microsoft.com/cdo/configuration/sendemailaddress"]->Value     
    = _variant_t("\"MySelf\" <myself@microsoft.com>") ;
    Flds->Item["http://schemas.microsoft.com/cdo/configuration/smtpuserreplyemailaddress"]->Value  
    = _variant_t("\"Another\" <another@microsoft.com>") ;
    Flds->Item[_variant_t("http://schemas.microsoft.com/cdo/configuration/smtpauthenticate")]->Value     
     = _variant_t((long)cdoBasic) ;
    Flds->Item[_variant_t("http://schemas.microsoft.com/cdo/configuration/sendusername")]->Value 
    = _variant_t("domain\\username") ;
    Flds->Item[_variant_t("http://schemas.microsoft.com/cdo/configuration/sendpassword")]->Value   
    = _variant_t("password") ;
    Flds->Update();
       
    iMsg->Configuration = iConfig;

    // ... compose message; add attachments, and so on.

    iMsg->Send();
    
  }
  CoUninitialize();
}

See Also

IMessage.Configuration

IConfiguration Interface