Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

MMCFreeNotifyHandle callback function

The MMCFreeNotifyHandle function is called by a snap-in to free the handle to an MMCN_PROPERTY_CHANGE notification message sent to the snap-in by MMC in response to an MMCPropertyChangeNotify call made by a property sheet.

Syntax


HRESULT STDAPICALLTYPE MMCFreeNotifyHandle(
  _In_ LONG_PTR lNotifyHandle
);

Parameters

lNotifyHandle [in]

A value that specifies a handle provided by the console during an IExtendPropertySheet2::CreatePropertyPages call.

Return value

This callback function can return one of these values.

S_OK

The handle was successfully freed.

Remarks

The handle to the notification is passed to the snap-in through a call to the IExtendPropertySheet2::CreatePropertyPages method. If the snap-in returns a success code (S_OK, S_FALSE) from this method, then the snap-in must call MMCFreeNotifyHandle. If the snap-in returns an error code, then MMC immediately frees the handle.

The snap-in can free the handle at any time, because MMC does not use the handle after it is given to the snap-in. The snap-in must only call MMCFreeNotifyHandle once and it must not use the handle in an MMCPropertyChangeNotify call after it is freed.

Be aware that the snap-in only must call MMCFreeNotifyHandle if its IExtendPropertySheet2::CreatePropertyPages method is called. MMC will not call IExtendPropertySheet2::CreatePropertyPages if the snap-in uses IPropertySheetCallback to add property pages and then calls IPropertySheetProvider::AddPrimaryPages with a NULL first parameter. Calling AddPrimaryPages in this way informs MMC that the pages have already been added, so it is not required to call the snap-in's IExtendPropertySheet2::CreatePropertyPages method. For more information, see Adding Wizard Pages: Implementation Details.

The following list contains scenarios that illustrate situations in which the snap-in can call MMCFreeNotifyHandle:

  • In IExtendPropertySheet2::CreatePropertyPages, the snap-in does not add any property pages. If CreatePropertyPages does not return an error result, the snap-in can call MMCFreeNotifyHandle before returning. Otherwise, MMC will free the handle.
  • In IExtendPropertySheet2::CreatePropertyPages, the snap-in adds property pages, but does not pass the handle to the pages. Again, if CreatePropertyPages does not return an error result, the snap-in can call MMCFreeNotifyHandle before returning.
  • In IExtendPropertySheet2::CreatePropertyPages, the snap-in adds property pages and also passes the handle to the pages. However, the property pages do not call MMCPropertyChangeNotify. In this case, the snap-in can call MMCFreeNotifyHandle either in the destructor of the property pages or before returning (without an error result) from CreatePropertyPages.
  • In IExtendPropertySheet2::CreatePropertyPages, the snap-in adds property pages and also passes the handle to the pages. The property pages call MMCPropertyChangeNotify. In this case, the snap-in should call MMCFreeNotifyHandle in the destructor of the property pages. Be aware that calling MMCFreeNotifyHandle in the snap-in's MMCN_PROPERTY_CHANGE notification handler is not recommended, because multiple pages may send notifications, or the same page could send multiple notifications (one each time the user clicks the Apply button).

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008

Header

Mmc.h

See also

IComponent
IExtendPropertySheet2::CreatePropertyPages
MMCPropertyChangeNotify

 

 

Show: