ADsPropCreateNotifyObj function (adsprop.h)

Article
02/22/2024

The ADsPropCreateNotifyObj function is used to create, or obtain, a notification object for use by an Active Directory Domain Services property sheet extension.

Syntax

HRESULT ADsPropCreateNotifyObj(
  [in]  LPDATAOBJECT pAppThdDataObj,
  [in]  PWSTR        pwzADsObjName,
  [out] HWND         *phNotifyObj
);

Parameters

[in] pAppThdDataObj

A pointer to the IDataObject object that represents the directory object that the property page applies to. This is the IDataObject passed to the property page IShellExtInit::Initialize method.

[in] pwzADsObjName

The Active Directory Domain Services object name obtained by calling the IDataObject::GetData method for the CFSTR_DSOBJECTNAMES clipboard format on the IDataObject represented by pAppThdDataObj.

[out] phNotifyObj

Pointer to an HWND value that receives the handle of the notification object.

Return value

Returns S_OK if successful, or an OLE-defined error value otherwise.

Remarks

The ADsPropCreateNotifyObj function is used in the implementation of an Active Directory Domain Services property sheet extension. The extension must first request the CFSTR_DSOBJECTNAMES data from the IDataObject interface passed to IShellExtInit::Initialize by calling IDataObject::GetData. This provides the data object and object name required to call ADsPropCreateNotifyObj.

When the notification object is no longer required, a WM_ADSPROP_NOTIFY_EXIT message is sent to the notification object. This causes the notification object to destroy itself. When the WM_ADSPROP_NOTIFY_EXIT message is sent, the notification object handle should be considered invalid.

Examples

The following C++ example shows how to use the ADsPropCreateNotifyObj function.

HWND CreateADsNotificationObject(IDataObject *pDataObject)
{
    STGMEDIUM   stm;
    FORMATETC   fe;
    HRESULT     hr;
    HWND        hwndNotifyObject = NULL;

    if(NULL == pDataObject)
    {
        return NULL;
    }

    fe.cfFormat = RegisterClipboardFormat(CFSTR_DSOBJECTNAMES);
    if(0 == fe.cfFormat)
    {
        return NULL;
    }
    fe.ptd = NULL;
    fe.dwAspect = DVASPECT_CONTENT;
    fe.lindex = -1;
    fe.tymed = TYMED_HGLOBAL;
    hr = pDataObject->GetData(&fe, &stm);
    if(SUCCEEDED(hr))
    {
        LPDSOBJECTNAMES pdson = 
            (LPDSOBJECTNAMES)GlobalLock(stm.hGlobal);

        if(pdson)
        {
            LPWSTR  pwszName = (LPWSTR)((LPBYTE)pdson + 
                pdson->aObjects[0].offsetName);
            
            hr = ADsPropCreateNotifyObj(pDataObject, 
                pwszName, 
                &hwndNotifyObject);
    
            GlobalUnlock(stm.hGlobal);    
        }
        
        ReleaseStgMedium(&stm);
    }

    return hwndNotifyObject;
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	adsprop.h
Library	Dsprop.lib
DLL	Dsprop.dll