Registering an Event Sink

You can design your application so that it is 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 can 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, so it is possible that handles that prevent you from reading from or writing to portions of the metabase will be open. 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 receives only notifications of changes made by other clients.

Note   Do not open any write handles within your SinkNotify processing, because recursive notifications between clients may cause a system lockup. You can 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 set security by calling the COM CoInitializeSecurity function with the dwImpLevel parameter set to RPC_C_AUTHN_LEVEL_NONE, as shown in the following example:

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

The function CoInitializeSecurity registers and sets the default security values for the process. This function is called exactly once per process, either explicitly or implicitly. It can be called by the client or the server, or both.

The dwImpLevel parameter is the default impersonation level for proxies. The value of this parameter applies when the process is the client. Outgoing calls from the client always use the impersonation level as specified (it is not negotiated). Incoming calls to the client can be at any impersonation level. By default, all IUnknown calls are made with this impersonation level, so even security-aware applications should set this level carefully.

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