IDsAdminNotifyHandler::Begin method (dsadmin.h)

Article
10/13/2021

The IDsAdminNotifyHandler::Begin method is called when an event that the notification handler has requested is occurring. The notification handler specifies the events to receive notifications for when IDsAdminNotifyHandler::Initialize is called.

Syntax

HRESULT Begin(
  [in]  ULONG       uEvent,
  [in]  IDataObject *pArg1,
  [in]  IDataObject *pArg2,
  [out] ULONG       *puFlags,
  [out] BSTR        *pBstr
);

Parameters

[in] uEvent

Contains a value the specifies the type of event that is occurring. This can be one of the following values.

DSA_NOTIFY_DEL

An object is deleted.

DSA_NOTIFY_REN

An object is renamed.

DSA_NOTIFY_MOV

An object is moved to another container.

DSA_NOTIFY_PROP

One or more properties of an object is modified.

[in] pArg1

Pointer to an IDataObject interface that supports the CFSTR_DSOBJECTNAMES clipboard format. The contents of the data object will vary depending on the value of uEvent. For more information, see the Remarks section.

[in] pArg2

Pointer to an IDataObject interface that supports the CFSTR_DSOBJECTNAMES clipboard format. The value of this parameter and the contents of the data object will vary depending on the value of uEvent. For more information, see the Remarks section.

[out] puFlags

Pointer to a ULONG value that receives a set of flags that modify the behavior of the notification handler in the notification confirmation dialog box. This can be zero or a combination of one or more of the following values.

DSA_NOTIFY_FLAG_ADDITIONAL_DATA

If this flag is set, the entry for this notification handler in the confirmation dialog box is selected. If this flag is not set, the entry for this notification handler in the confirmation dialog box is not selected.

DSA_NOTIFY_FLAG_FORCE_ADDITIONAL_DATA

If this flag is set, the entry for this notification handler in the confirmation dialog box is disabled and the user cannot change the selection state.

[out] pBstr

Pointer to a BSTR that receives a string that contains the name and/or description of the notification handler. This string is displayed in the confirmation dialog box. This string must be allocated by calling the SysAllocString function. The caller must free this string when it is no longer required. If this parameter receives NULL or an empty string, the notification handler is not added to the confirmation dialog box and IDsAdminNotifyHandler::Notify is not called.

Return value

If the method succeeds, S_OK is returned. If the method fails, a standard HRESULT value is returned.

Remarks

The value and contents of pArg1 and pArg2 vary depending upon the event processed as indicated by uEvent. The following list explains what pArg1 and pArg2 will contain for each different event type.

uEvent	pArg1	pArg2
DSA_NOTIFY_DEL	Contains the object deleted.	Not used. This will be NULL.
DSA_NOTIFY_REN	Contains the previous name of the object.	Contains the new name of the object.
DSA_NOTIFY_MOV	Contains the container that the object is moved from.	Contains the container that the object is moved to.
DSA_NOTIFY_PROP	Contains the object for which the properties have changed.	Not used. This will be NULL.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	dsadmin.h
DLL	DSAdmin.dll