ISMTPStoreDriver::Init

[This is preliminary documentation and subject to change.]

The ISMTPStoreDriver::Init method is called by the SMTP service to initialize each instance of a store driver.

HRESULT Init(
   [in] DWORD dwInstance,
   [in,unique] IUnknown *pBinding,
   [in] IUnknown *pServer,
   [in] DWORD dwReason,
   [out] IUnknown **ppStoreDriver
);

dwInstance

The virtual service instance number for which to initialize.

pBinding

The binding for the store driver. This may be NULL.

pServer

A reference to the server object that exposes the ISMTPServer interface. This may be NULL. The store driver may call methods on this object to perform advanced initialization functions and should always call QueryInterface to retrieve the ISMTPServer interface and cache the reference for future use, such as a call to EnumerateAndSubmitMessages.

dwReason

Specifies the reason for the initialization, either SMTP_INIT_VSERVER_STARTUP, or SMTP_INIT_BINDING_CHANGE.

ppStoreDriver

On successful return, a reference to the store driver object to use. If this value is non-NULL, the caller should release the original interface reference and use this reference for all subsequent calls to the store driver. This mechanism allows the store driver to examine the parameters to the Init call, and redirect further operations by the virtual server to this store driver to be on a different object.

Return Values

Remarks

Through this call a store driver object receives initialization information from the SMTP virtual service. This information includes the instance number of the server, a pointer to the binding information for the store driver event binding, a reference to an object exposing the ISMTPServer interface, and a flag indicating the reason for the call. By examining the parameters, the store driver can determine if another instance of this store driver class is available, and whether the binding options are similar enough that that previous instance is still valid. If so, then the store driver can return a pointer to the previous instance, causing the virtual server to make all further calls on that previous instance. Caching instances of store drivers, however, is not required.

During the Init method, store drivers normally read configuration information used to persist message content and property streams. For example, the default SMTP (NTFS) store driver uses the ISMTPServer interface to read metabase properties identifying the Queue and Drop directory locations for the particular virtual server instance. Messages delivered locally are copied to the Drop directory location, and undelivered messages are temporarily stored in the Queue directory.

The Init function is called each time a new store driver is created. For performance reasons, it is best to expose an implementation of the IEventIsCacheable::IsCacheable method that returns S_OK, indicating to the event dispatcher that the object can be cached for subsequent use. The SMTP dispatcher makes repeated calls to the store driver object to allocate backing store for messages (IMailMsgStoreDriver::AllocMessage), close content handles (IMailMsgStoreDriver::CloseContentHandle), and delete backing store files (IMailMsgStoreDriver::Delete). If the object is not cached, each new instance will be re-initialized for each of the above calls.

See Also

ISMTPStoreDriver::PrepareForShutdown, ISMTPStoreDriver::Shutdown