Registering an Event Sink

You may design your application to be notified when certain events occur. To receive event notifications, your application must implement a COM sink of a class descended from the IMSAdminBaseSink interface. You may implement a sink for the following events.

• The metabase shuts down.
• A key or its associated data changes.

Shutdown Notify Sink

This sink method will be called when IISADMIN stops. The metabase will be open during this call, however, there is no guarantee that handles will not be open that prevent you from reading from or writing to portions of the metabase. In addition, your sink must not release its interface during this call. The recommended implementation is, when notified, set a flag and return, then release the interface. The metabase will wait for five seconds or until all interfaces have been released before actually shutting down.

Your callback method must implement the following prototype as a minimum:

HRESULT STDMETHODCALLTYPE ShutdownNotify( void) 
{ 
  return HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED); 
} 
 

Change Notify Sink

If your application needs to be notified whenever a key or its associated data changes, it must implement the SinkNotify method. This method will receive a notification whenever one of the following events occurs.

• A key that has been changed is closed by the CloseKey method.
• Permissions on a handle to a key are changed from write or read/write to read-only by the ChangePermissions method.

The SinkNotify method is not called if the handle is closed by the instance of the IMSMetadata interface that registered the sink. In other words, a client only receives notifications of changes made by other clients.

Note  Do not open any write handles within your SinkNotify processing or recursive notifications between clients may cause a system lockup. You may open read handles to the metabase within your SinkNotify method.

Your callback method must implement the following prototype as a minimum:

HRESULT SinkNotify( 
DWORD dwMDNumElements 
MD_CHANGE_OBJECT pcoChangeList[]
); 
 

The parameter dwMDNumElements receives the number of elements that have changed. The maximum number of change entries that are sent on a single call to the callback method is specified by the constant MD_MAX_CHANGE_ENTRIES. If more notifications are required, the method is called multiple times.

Remarks

IIS does not make secure calls to remote machines. If your program implements a sink and is executing on a machine other than the machine on which IIS is running, you must remove security by calling the COM CoInitializeSecurity function with the dwImpLevel parameter set to RPC_C_AUTHN_LEVEL_NONE, as shown in this example:

hRes = CoInitializeSecurity(NULL, 
            -1, 
            NULL, 
            NULL, 
            RPC_C_AUTHN_LEVEL_NONE, 
            0, 
            NULL, 
            EOAC_NONE, 
            0) 
 

For more information on this function, see the Reference topic in COM and ActiveX Object Services in the Platform SDK, which is also available in the MSDN Library.