SMTP Service Design

 

The core SMTP protocol engine is implemented in SMTPSvc.dll, which resides in the \WINDOWS\system32\inetsrv directory. This protocol engine runs as unmanaged code in the IIS Inetinfo process and handles incoming and outgoing SMTP connections at the session layer. The following figure illustrates that the SMTP service is located in the Session, Presentation, and Application layers according to the Open Systems Interconnection (OSI) model of the International Organization for Standardization (ISO).

Inetinfo process and SMTP service in the OSI model

Internet Information Services (IIS) Integration

The fact that the SMTP service runs in the Inetinfo process indicates that the Exchange Server 2003 transport subsystem shares IIS resources with other services that also run in IIS, such as the Post Office Protocol version 3 (POP3) service, Internet Mail Access Protocol version 4 (IMAP4) service, and Exchange Routing Engine service (RESvc). Inetinfo.exe is the core IIS process, and the IIS Admin service controls Inetinfo.exe. This is explained in Exchange Server 2003 Services Dependencies.

Asynchronous Thread Execution

One of the most important resources that the SMTP service shares with all other services in the Inetinfo process is Asynchronous Thread Queue (ATQ). This is a pool of threads that IIS uses to handle all incoming network connection requests. A thread is an instance of code execution within a process. A process consists of a virtual address space, processor context, and at least one thread. Threads are created by using the CreateThread() method of the operating system and run within the virtual address space of the calling process (that is, the IIS Inetinfo process).

In asynchronous processing, each thread runs in the Inetinfo process without waiting for other threads to finish their processing. In synchronous processing, threads run after each other in a synchronized way (code execution is blocked at a function call until the function is complete). To synchronize asynchronous threads (for example, to avoid conflicts because of concurrent access to a particular resource), the operating system provides synchronization objects. An example of a synchronization object for a particular resource is an event object for a Windows socket. The SMTP service uses event objects to receive notifications of incoming SMTP connections. A Windows socket is an IP address combined with a port number. The default port to reach the SMTP protocol engine is TCP port 25. Combined with the IP address of the Exchange server that is running the SMTP service, this port number forms the socket of the default SMTP virtual server, for example: 192.168.1.100:25.

Handling Incoming SMTP Connections

The Inetinfo process handles incoming SMTP connections as follows:

1. When you start the SMTP service, the Inetinfo process initializes the SMTP virtual server's socket in TCP/IP to listen for incoming connection requests. To support multiple concurrent connections through the same virtual server, the socket is initialized in non-blocking mode for overlapped I/O operations. By default, an SMTP virtual server can accept almost an unlimited number of incoming network connections (although the actual physical limit is about 5000).

   Note

   In Microsoft Windows Server 2003, the server can handle only about 2,000 concurrent connections. In Windows Server 2003 Service Pack 1, the default is increased from 2,000 to 5,000 and can be increased even more through a setting in the metabase.

2. The Inetinfo process creates a synchronization object to inform the operating system that it is interested in receiving a network event notification for incoming connections over the socket. ATQ is associated with this synchronization object so that a thread from this thread pool can be notified when the synchronization object signals an incoming network connection.

3. The TCP/IP transport stack receives an incoming SMTP connection and signals this event to the Inetinfo process. Now a thread from ATQ can run to read data from the SMTP socket.

   Note

   The Inetinfo process can create additional threads in ATQ to ensure a sufficient number of threads available to listen for incoming connection requests. To tune IIS performance, you can specify the maximum number of threads that can be created in the system through the following registry parameter.

   Location	HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\InetInfo\Parameters
   Value	PoolThreadLimit
   Type	REG_DWORD
   Value Data	0 - 4,294,967,295 (unlimited)
   Description	PoolThreadLimit is a hard limit that includes all IIS pool threads.

4. The IIS thread runs the code in SMTPSvc.dll and responds to the incoming client request with a server greeting, named an SMTP banner, such as: 220 server01.TailspinToys.com Microsoft ESMTP MAIL Service, Version: 6.0.3790.0 ready at Sun, 21 Mar 2004 23:48:47 +0100.

5. The SMTP conversation progresses as the remote SMTP host transfers the message. Each time an SMTP command is received, a thread from ATQ runs the SMTP protocol code in SMTPSvc.dll and triggers events in the SMTP service that cause code in other DLLs to run. For example, the NTFS store driver writes the message in the form of a file into the virtual SMTP server's \Queue folder on the file system.

6. After the current SMTP command is processed, the Inetinfo process places the thread that was used to perform the SMTP processing back into ATQ to listen for new incoming commands or new connection requests. IIS reuses existing threads to avoid the overhead of creating a new thread each time a new command or connection request is received.

7. The remote host issues a Quit command, and the SMTP service releases the connection.

   Note

   The time to live (TTL) of inactive threads in ATQ is 24 hours. The Inetinfo process has at least two threads in ATQ at any one time to respond to incoming connection requests.

Limiting the Number of SMTP Threads

By default, the SMTP service can use up to 90 percent of the available threads in ATQ. Because this thread pool is shared with other IIS services that might also run on the same server, such as File Transfer Protocol (FTP), POP3, RESvc, and IMAP4 services, a high SMTP load can lead to a performance bottleneck in the Inetinfo process. This can cause the FTP, POP3, RESvc, or IMAP4 service to fail.

To avoid this situation, you can reserve an adequate number of threads for other IIS services by limiting the percentage of threads that the SMTP service can use. This is accomplished using the following registry parameter.

Location	HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\SMTPSVC\Queuing
Value	MaxPercentPoolThreads
Type	REG_DWORD
Value Data	The default is 0x5A (90%)
Description	Limits the percentage of ATQ threads that the SMTP service can use. The recommended setting is: MaxPercentPoolThreads = 90/(2*Number of SMTP virtual server instances)

You can also increase the overall number of threads in the Inetinfo process using the following registry parameter, if sufficient memory is available for the additional threads.

Location	HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\SMTPSVC\Queuing
Value	AdditionalPoolThreadsPerProc
Type	REG_DWORD
Value Data	The default is 0x5A (90%)
Description	Determines additional pool threads per processor that the Inetinfo process creates when the SMTP service is started. The recommended setting is: AdditionalPoolThreadsPerProc = ((9/(MaxPercentPoolThreads/100))-4)/2 Note If the AdditionalPoolThreadsPerProcvalue is greater than 200, you must increase the value of the PoolThreadLimit parameter under HKEY_LOCAL_MACHINE\ System\CurrentControlSet\Services\InetInfo\Parameters</STRONG>. Set the PoolThreadLimit to at least the same value as AdditionalPoolThreadsPerProc.

Component Object Model-Based SMTP Extensions

The SMTP protocol supports sending multiple messages during a single session. Delivery or relay for one message can proceed while the next message is transmitted. The SMTP "end of mail data" indicator (that is, a carriage return line feed followed by a period, followed by another carriage return line feed) or the final BDAT chunk of each individual message informs the receiving SMTP service to process the recipients and data of that particular message. This processing is referred to as transport processing, because it delivers the message to the local Exchange store or forwards it to the recipient's home server if the recipient's mailbox does not reside on the local server. The SMTP service can also relay messages to external recipients. For example, message relaying is performed when Exchange users who are working with Internet clients send messages to external recipients.

After a message is received through SMTP, it is passed to the advanced queuing engine (Phatq.dll). The thread that the SMTP service uses to pass the message to the advanced queuing engine is then returned to ATQ. The advanced queuing engine uses its own thread pool to process queued messages. This thread pool is separate from the thread pool used to handle SMTP protocol operations. You can read more about the advanced queuing engine in The Advanced Queuing Engine.

Events in the SMTP Transport Subsystem

When threads run the protocol code in Smtpsvc.dll or transport code in Phatq.dll, they trigger events that cause code in other DLLs to run. This event architecture is based entirely on COM. SMTP uses the Microsoft Server Extension Object COM Library (Seo.dll) to trigger SMTP events and uses COM activation to instantiate the event sinks that are registered for each particular event. SMTP events can indicate the transmission or arrival of an SMTP protocol command or the submission of a message into the SMTP transport subsystem, among other things. Event sinks, such as SMTP protocol extensions, categorizer, and routing engine, register for specific events in the SMTP service.

The following types of events can occur in the SMTP transport subsystem of Exchange 2003:

• SMTP protocol events   These events are specific to SMTP and allow event sinks to modify the behavior of the SMTP protocol engine by modifying, disabling, or adding inbound and outbound commands, as well as responses to those commands. For example, the X-LSA Sink protocol event sink of Exchange Server 2003 implements an additional SMTP command, X-LINK2STATE, to transmit link state information across routing groups, as explained in Message Routing Architecture. Protocol event sinks can also be used to modify standard SMTP and ESMTP commands, such as EHLO, to broaden the capabilities of the SMTP protocol. Protocol event sinks are covered in SMTP Protocol Extensions.

• SMTP store events   These events allow store event sinks (that is, store driver implementations) to persist the content of messages in file system directories or in the Exchange store. For example, in the transport subsystem of Exchange Server 2003, store events are used to perform local delivery to Exchange recipients. Store drivers are covered in SMTP Service Store Drivers.

• SMTP transport events   These events occur when messages arrive at the server, flow through the core transport subsystem, and are delivered to Exchange recipients or relayed to other SMTP hosts. In Exchange Server 2003, transport events are used to perform message categorization and message routing. The routing engine is covered in Message Routing Architecture. The categorizer event sinks are covered in SMTP Transport Components.

• SMTP system events   These events translate into calls to a sink acting as a system component. For example, the SMTP Eventlog sink is a system component that registers for system events to write internal processing information into the application event log.

Event sinks in the SMTP service

Event Dispatcher and Event Notifications

When an event occurs, a thread in the SMTP service, acting as the event dispatcher, checks the event registrations (stored as event bindings in the IIS metabase) to determine if any sinks are associated with the event. The event dispatcher determines all the event sinks that are registered to run and when to run them. The order depends on the sink's priority, as specified in the event binding information. Sinks are notified of an event in sequence. Sinks with the lowest priority run first.

For each sink, the following process occurs:

1. The event dispatcher compares the sink's event registration with the event conditions. If the conditions are met, the sink is executed.

   Note

   Some SMTP events, such as store events, do not have event conditions.

2. If necessary, the event dispatcher creates an instance of the sink using the class ID (CLSID) of the event sink COM class.

   Note

   Sinks can be cached to avoid this step on subsequent events.

3. The event dispatcher calls the IUnknown::QueryInterface method of COM to get the appropriate event notification interface of the event sink. Most sinks use the Active Template Library (ATL) to implement the sink interface.

4. The event dispatcher runs the sink by calling the appropriate event method on the sink interface. For transport events, the event dispatcher passes the message in the form of a MailMsg object to the event sink. This object contains the whole message, together with the transport envelope fields. The message and the envelope fields can be modified by the sink.

5. When the sink finishes processing, it returns an event status flag to the event dispatcher. The event dispatcher checks this flag to determine whether to notify subsequent sinks. For example, an event sink might instruct the event dispatcher to skip all remaining sinks to stop all further message processing.

   Event sinks use the following return codes to indicate whether to notify subsequent sinks:

   • S_OK   Other sinks at the same or lower priority are called.

   • S_FALSE   Other sinks at the same or lower priority are not called.

     Note

     SMTP protocol event sinks might also return the value MAILTRANSPORT_S_PENDING to indicate that the processing will complete asynchronously by calling the NotifyAsyncCompletion method. A protocol event sink can call the NotifyAsyncCompletion method to notify the inbound protocol event dispatcher that asynchronous processing is complete and to pass the processing result.

6. For transport events, after each sink is notified, or after one sink indicates to skip the remaining sinks, the status envelope field is examined for the message to determine the next action. A message might be delivered to the appropriate location, discarded, or placed in the SMTP virtual server's \Badmail folder on the file system.

Administrative Interfaces

The primary tool for managing SMTP protocol settings and SMTP virtual servers on a server running Exchange Server 2003 is Exchange System Manager, specifically the Exchange SMTP snap-in (\Programme\Exchsrvr\bin\SMTPMgr.dll). You can find this snap-in in Exchange System Manager, under each server object, under Protocols in the SMTP container. You can control most of the SMTP settings that apply to inbound message transfer and, to a lesser degree, outbound mail settings. Using Exchange System Manager, you can also create additional SMTP virtual servers on your Exchange server. Each SMTP virtual server represents an instance of the SMTP service and is defined by a unique combination of an IP address and a TCP port number. Each SMTP virtual server triggers its own events and manages its own set of event sinks. For more information about the configuration of virtual SMTP servers, see the Exchange Server 2003 Transport and Routing Guide.

Configuration Settings and Event Bindings

The SMTP transport subsystem of Exchange Server 2003 relies on the following three repositories for configuration information:

• Active Directory   Exchange System Manager stores and retrieves configuration information mainly from Active Directory. For example, recipient properties and restrictions, as well as the routing topology of an Exchange organization, including all routing groups and messaging connectors, are defined in Active Directory. The components in the SMTP transport subsystem communicate with Active Directory to obtain this information, as explained in Exchange Server 2003 and Active Directory.

• IIS metabase   The core components of the SMTP service that ship with Windows Server 2003 are not Active Directory-aware. For example, any settings that you apply to an SMTP virtual server must be transferred from Active Directory to the IIS metabase. This is the task of the metabase update service. The metabase update service registers with the configuration domain controller that Exchange Server 2003 uses to receive notification of any changes to the Exchange configuration. This notification occurs within 15 seconds of the change. As soon as the change is replicated to the configuration domain controller, IIS metabase update service replicates the change to the IIS metabase.

• Registry   Most configuration settings that you can configure for the SMTP transport subsystem are stored in Active Directory or IIS metabase. However, several system parameters that affect the SMTP service, such as MaxPercentPoolThreads or AdditionalPoolThreadsPerProc, are stored in the registry database under the following key: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\SMTPSVC.

  Another important key is: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\InetInfo, which contains configuration parameters for the Inetinfo process that hosts the SMTP service. Several important registry parameters have been introduced earlier in this section.

  Because all SMTP event sinks are COM components, they must be registered in the registry under the HKEY_CLASSES_ROOT hive. You can use Regsvr32.exe to manually register and unregister COM components.

Configuration Information in Active Directory

Exchange System Manager stores the configuration settings for SMTP virtual servers in the configuration directory partition of Active Directory. Each virtual server is represented by a separate configuration object. The location of this object matches the hierarchy of configuration objects shown in Exchange System Manager, and the common name corresponds to the numeral of the virtual server in the IIS metabase. For example, the default SMTP virtual server is the first SMTP virtual server in IIS, and so the corresponding common name (CN) of the default SMTP virtual server's configuration object in Active Directory is 1 (as in CN=1,CN=SMTP,CN=Protocols,CN=SERVER01,CN=Servers,CN=First administrative Group,CN=Administrative Groups,CN=TailspinToys,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=TailspinToys,DC=com).

The following table lists important configuration information that Exchange Server 2003 stores for SMTP virtual servers in Active Directory. To learn how to manage SMTP virtual server settings in Active Directory programmatically, see Setting Message Restriction on an SMTP Virtual Server Using ADSI.

Important Active Directory attributes for SMTP virtual servers

Active Directory Attribute	Description
msExchServerBindings	Specifies the Internet Protocol (IP) port binding for Secure Sockets Layer (SSL) connections.
msExchAuthenticationFlags	Indicates which type of authentication this SMTP virtual server accepts.
msExchMaxIncomingConnections	Specifies the maximum number of inbound connections allowed for this SMTP virtual server.
msExchLogType	Specifies the log formats that this SMTP virtual server uses for protocol logging.
msExchAccessSSLFlags	Identifies the type of encrypted channel that this SMTP virtual server supports.
msExchServerAutoStart	Specifies when to start the virtual server. If true, starts the virtual server when the operating system is booted.
msExchNTAuthenticationProviders	Specifies a list of Security Support Provider Interface (SSPI) packages that may be used to authenticate to this SMTP virtual server. Exchange Server 2003 supports Kerberos authentication through Generic Security Services Application Programming Interface (GSSAPI), as well as the legacy Microsoft Windows NT LAN Manager Authentication Protocol (NTLM).
msExchIncomingConnectionTimeout	Specifies the maximum time duration before idle incoming connections are cancelled.
msExchSmtpMaxOutgoingConnections	Specifies the maximum number of outbound connections from this SMTP virtual server.
msExchSmtpOutgoingConnectionTimeout	Specifies the maximum time duration before idle outbound connections are cancelled.
msExchSmtpMaxOutgoingConnectionsPerDomain	Specifies the maximum number of outbound connections from this SMTP virtual server to a particular domain.
msExchSmtpOutgoingPort	Specifies the outbound connection port number that the SMTP virtual server uses to contact a remote SMTP host.
msExchSmtpOutgoingSecurePort	Specifies the outbound connection port number that the SMTP virtual server uses to contact a remote SMTP host, if Transport Layer Security (TLS) is used to protect the transmission channel.
msExchSmtpMaxHopCount	Specifies the maximum number of hops that the message transported by this SMTP virtual server can take to reach the final destination.
msExchSmtpMaxMessageSize	Specifies the maximum size allowed for a message delivered by this SMTP virtual server.
msExchSmtpMaxSessionSize	Specifies the maximum amount of data in Kilobytes that can be transferred in one SMTP session.
msExchSmtpMaxRecipients	Specifies the maximum number of recipients allowed on a message transferred by this SMTP virtual server.
msExchSmtpLocalQueueExpirationTimeout	Specifies the time at which this SMTP virtual server must expire a local undelivered message.
msExchSmtpLocalQueueDelayNotification	Specifies the time at which this SMTP virtual server must generate a delivery status notification to inform the sender that a local message did not reach its destination.
msExchSmtpRemoteQueueExpirationTimeout	Specifies the time at which this SMTP virtual server must expire an undelivered outbound message.
msExchSmtpRemoteQueueDelayNotification	Specifies the time at which this SMTP virtual server must generate a delivery status notification to inform the sender that an outbound message did not transfer.
msExchSmtpSmartHost	Specifies a smart host route for outbound messages from this SMTP virtual server.
msExchSmtpSmartHostType	Specifies the smart host type.
msExchSmtpMaxOutboundMsgPerDomain	Specifies the maximum number of outbound messages that this SMTP virtual server can transfer per domain in one session.
msExchSmtpOutboundSecurityFlag	Specifies the authentication that is used when connecting outbound from this SMTP virtual server.
msExchSmtpInboundCommandSupportOptions	Controls which SMTP commands are supported on inbound connections. By changing this value, you can disable features like 8BITMIME, BDAT, CHUNKING, and PIPELINING.
msExchSmtpRelayForAuth	Determines whether the message relaying requires authentication.
msExchSmtpPerformReverseDnsLookup	Specifies whether to perform reverse Domain Name System (DNS) lookups for delivery.
msExchSmtpDoMasquerade	Specifies whether to use a masquerade domain for Non-delivery reports (NDRs). If set, use the masquerade domain. NDRs are then returned to the alternate domain specified, instead of to the domain from which the e-mail messages originated.
msExchSmtpBadMailDirectory	Specifies location where badmail (e-mail messages contained in the BadMail folder) is stored on the file system.
msExchSmtpSendBadmailTo	Specifies an address to which to send badmail.
msExchSmtpFullyQualifiedDomainName	Specifies fully qualified domain name (FQDN) for this SMTP virtual server.
msExchSmtpPickupDirectory	Specifies the directory from which mail messages are obtained.
msExchSmtpQueueDirectory	Specifies the directory from which mail messages are queued.
msExchSmtpRemoteQueueRetries	Specifies the first, second, third, and subsequent retries for remote mail delivery.
msExchSmtpRelayIpList	Specifies a list of IP addresses for relay restriction.
msExchBridgeheadedLocalConnectorsDNBL	Specifies a list of connectors in the SMTP virtual server's routing group for which this SMTP virtual server is the local bridgehead.
msExchBridgeheadedRemoteConnectorsDNBL	Specifies a list of connectors in remote routing groups for which this SMTP virtual server is a remote bridgehead.

SMTP Configuration Settings in the Metabase

The IIS metabase is a hierarchical store of configuration and schema information, which is used to configure IIS resources. The metabase configuration and schema for IIS 4.0 and IIS 5.0 are stored in a binary file (MetaBase.bin), which is not easy to read or edit. You must use the MetaEdit tool to view and edit the metabase of IIS 4.0 and IIS 5.0. MetaEdit 2.2 is available for download at https://go.microsoft.com/fwlink/?LinkId=47942.

In IIS 6.0, Extensible Markup Language (XML)-formatted files, named MetaBase.xml and MBSchema.xml, replace the earlier binary file. The IIS configuration information is stored in the MetaBase.xml file, while the metabase schema is stored in the MBSchema.xml file. When IIS is started, these files are read by the metabase storage layer and then written to the in-memory metabase through Admin Base Objects (ABO), as shown in the following figure.

The metabase architecture of IIS 6.0

SMTP Configuration Keys

Members of the local Administrators group can view and modify the MetaBase.xml file, which is a plain text file that is located in the \Windows\System32\Inetsrv folder. Metabase entries that apply to the SMTP service and its SMTP virtual servers start with IIsSmtp.

The Location property in the configuration entries defines the hierarchy of the configuration objects. For example, in Location ="/LM/SmtpSvc/1", LM means local machine, SmtpSvc represents the SMTP service in general, and the numeral (1) represents the default SMTP virtual server. The enumerator "1" corresponds to the CN attribute of the default SMTP virtual server object in Active Directory.

The following figure illustrates the hierarchy of configuration entries for SMTP virtual servers, according to the Location property of each IIsSmtp metabase entry.

Hierarchy of SMTP configuration entries in the IIS metabase

Parameters that apply to the SMTP service generally are registered in the metabase in the SmtpSvc node. You can find this node when you search for the Location ="/LM/SmtpSvc". The following section is a shortened listing of this key:

<IIsSmtpService Location ="/LM/SmtpSvc"

    ConnectionTimeout="600"

    DefaultDomain="server01.TailspinToys.com"

    DomainRouting=""

    EnableReverseDnsLookup="FALSE"

    FullyQualifiedDomainName="server01.TailspinToys.com"

    ...

    SmtpRemoteProgressiveRetry="15,30,60,240"

    SmtpRemoteRetryThreshold="3"

    >

    <Custom

        Name="AuthFlags"

        ID="6000"

        Value="AuthBasic | AuthAnonymous | AuthNTLM"

        Type="DWORD"

        UserType="IIS_MD_UT_SERVER"

        Attributes="INHERIT"

    />

    ...

    <Custom

        Name="UnknownName_61537"

        ID="61537"

        Value="0"

        Type="DWORD"

        UserType="IIS_MD_UT_SERVER"

        Attributes="NO_ATTRIBUTES"

    />

</IIsSmtpService>

Under the SmtpSvc node, you find the configuration settings for each SMTP virtual server that you created on the server that is running Exchange Server 2003. SMTP virtual servers inherit the general settings configured for the SMTP service and can overwrite these settings. The following is a schematic listing of the configuration section for the default SMTP virtual server. Note the Location information.

<IIsSmtpServer Location ="/LM/SmtpSvc/1"

    ... property definitions that apply only to the

      particular virtual server ...

    >

    <Custom

        ... custom property defintion...

    />

</IIsSmtpServer>

Direct Metabase Editing

Because MetaBase.xml is a text file, members of the Administrators group can edit the IIS 6.0 metabase directly using common text tools, such as Notepad. However, this file remains open and locked when IIS is running. To support direct editing, you must enable the Enable Direct Metabase Edit feature in IIS Manager. For detailed instructions about how to enable direct editing of the IIS metabase, see How to Enable the Enable Direct Metabase Edit Feature in IIS Manager.

Local Domain Registrations

Under each SMTP virtual server node in the metabase, you can find important child nodes, such as Domain (Location ="/LM/SmtpSvc/1/Domain") and EventManager (Location ="/LM/SmtpSvc/1/EventManager") nodes. The domain node contains domain definitions that determine the route actions that the SMTP virtual server should perform. For example, the SMTP service must accept messages for all local SMTP domains, as defined in recipient policies, but might be required to reject any attempts to relay messages to non-local domains. The metabase update service replicates the domain information from recipient policies to the IIS metabase for all SMTP virtual servers.

Event Sink Registrations

The entries under the EventManager node are event registrations. For the SMTP service to work with event sinks, event sinks must be registered in the IIS metabase, so that the SMTP service can create and run these sinks when relevant events occur. IIsConfigObjects define event bindings in the IIS metabase. For example:

<IIsConfigObject    Location ="/LM/SmtpSvc/1/EventManager/

EventTypes/{283430C9-1850-11D2-9E03-00C04FA322BA}/

Bindings/{A928AD15-1610-11D2-9E02-00C04FA322BA}/

SinkClass"

>

<Custom

Name="MD_0"

ID="0"

Value="Exchange.Router"

Type="STRING"

UserType="UNKNOWN_UserType"

Attributes="NO_ATTRIBUTES"

/>

</IIsConfigObject>

This binding associates the GUID of a particular event, such as 283430C9-1850-11D2-9E03-00C04FA322BA, with an event sink, such as the Exchange Router sink. The second GUID entry in the binding information {A928AD15-1610-11D2-9E02-00C04FA322BA} is the identifier (ID) of this particular event binding entry. Event binding IDs must be unique in the metabase, but a particular event can have more than one event sink associated with it, as indicated in Figure 6.4, earlier in this section.

Event binding parameters are defined under each event sink node in the metabase hierarchy. The current listing defines a SinkClass value that creates an association between the SMTP transport OnGetMessageRouter event and the Exchange.Router sink class. Additional binding entries exist to define the display name for the event sink as Exchange Router, and to define other parameters, such as the priority of the event sink. The following table lists the parameters that can be specified for an event binding.

Event binding information

Property Description	Property Description
ID	A GUID that uniquely identifies the binding. This information is required.
DisplayName	An optional user-friendly name for the binding.
SinkClass	The programmatic identifier (ProgID) of the event sink class.
Enabled	A flag that indicates whether the binding is currently enabled. If this flag is not specified, the event sink is enabled. This parameter is optional.
MaxFirings	The number of event notifications the sink can receive before the binding is disabled. This parameter is optional.
EventBindingProperties	A dictionary (or hash) of additional properties that are defined for the entire binding. This parameter is optional.
SinkProperties	Sink properties are reserved for a particular sink implementation. When the sink is notified of an event, the event dispatcher passes the collection of sink properties to the event sink. For example, an event sink that is used to add a disclaimer to a message might receive the disclaimer text through a sink property.
SourceProperties	Source properties are defined by a particular event dispatcher implementation. For example, the inbound and outbound protocol event dispatcher uses a Rule and Priority property to determine when a sink is notified of an event. Most transport event sinks do not use the Rule source properties, except the OnTransportSubmission event. All protocol and transport events support use of the Priority source property. The following source properties are used for event bindings for protocol and transport events: Rule   A string identifying a protocol filter for the sink binding. The dispatcher uses the rule as a condition or set of conditions that determine whether the sink is notified. The rules are SMTP protocol command rules, such as EHLO. Rules may include conditions, such as EHLO=*.contoso.com. Multiple rules are separated by semi-colons. Priority   The sink's notification priority, compared to other sinks registered to receive notifications of the event. The range of values is 0 (highest) to 32767 (lowest). This property is optional. The default priority is 24575. Sinks with the same priority run in an unspecified order.

Server Extension Objects

GUIDs in event bindings guarantee a unique association between an event type and an event sink, but these identifiers can be problematic because they are not logically apparent. For example, if you want to know what event maps to the event sink in the listing in the preceding table, you must search for the GUID 283430C9-1850-11D2-9E03-00C04FA322BA in the registry under HKEY_CLASSES_ROOT\Component Categories. You can then find out that this GUID identifies the SMTP Transport OnGetMessageRouter event type. The second GUID in this example of a binding definition, A928AD15-1610-11D2-9E02-00C04FA322BA, is the CLSID of the Exchange Router class, implemented in Reapi.dll. The registry key for this COM component is HKEY_CLASSES_ROOT\CLSID\{A928AD15-1610-11d2-9E02-00C04FA322BA}. However, this CLSID is only used to create a unique ID for the event binding in the metabase. What matters is the SinkClass value that defines the association between the event type and the event sink class.

Fortunately, you do not have to work with GUIDs to manage event sink bindings. You can use server extension objects implemented in Seo.dll instead. Microsoft has developed a script that demonstrates using server extension objects to manage event bindings for the SMTP service. This script is called SMTPReg.vbs, and you can find it at smtpreg.vbs Event Management Script. For example, you can use SMTPReg.vbs with the following command to write all SMTP event bindings from the IIS metabase into a file called Event_Bindings.txt: cscript smtpreg.vbs /enum > Event_Bindings.txt. The following listing shows the output for the Exchange Router binding entry:

    ---------

    | Binding |

    ---------

        Event: SMTP Transport OnGetMessageRouter

        ID: {A928AD15-1610-11D2-9E02-00C04FA322BA}

        Name: Exchange Router

        SinkClass: Exchange.Router

        Enabled: True

        SourceProperties: {

            priority = 8192

        }