IDsObjectPicker::InvokeDialog

The InvokeDialog method displays a modal object picker dialog box and returns the user's selections.

HRESULT InvokeDialog(
  HWND hwndParent,
  IDataObject **ppdoSelections
);

Parameters

hwndParent

Handle to the owner window of the dialog box. If this parameter is NULL, the dialog box has no owner window.

ppdoSelections

Pointer to a variable that receives a pointer to an IDataObject instance containing information about the user's selections.

Return Values

If the user clicks the OK button of the dialog box, the return value is S_OK. The OK button is enabled only if the user has made a selection.

If the user cancels or closes the dialog box, the return value is S_FALSE.

If an error occurs, the return value is a COM error code. For more information, see Error Handling.

Remarks

Before calling the InvokeDialog method, you must call the IDsObjectPicker::Initialize method to initialize the interface instance. After calling the Initialize method, you can make multiple InvokeDialog calls to display the dialog box multiple times without reinitializing it.

If the user selects one or more objects and clicks the OK button, you can use the IDataObject::GetData method to retrieve the user's selections. The data object uses the CFSTR_DSOP_DS_SELECTION_LIST clipboard format to store the selection information. The GetData method returns an HGLOBAL handle to a global memory block that contains a variable-length DS_SELECTION_LIST structure. The DS_SELECTION_LIST structure contains an array of DS_SELECTION structures, one for each object selected by the user.

Call the RegisterClipboardFormat function to register the CFSTR_DSOP_DS_SELECTION_LIST clipboard format. RegisterClipboardFormat returns a value you can use to identify the format when you call the IDataObject::GetData method.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Objsel.h.
  Library: Included as a resource in Objsel.dll.

See Also

Active Directory Display Interfaces, DS_SELECTION, DS_SELECTION_LIST, IDataObject, IDataObject::GetData, IDsObjectPicker::Initialize, Object Picker Dialog Box Interfaces, Object Picker Dialog Box Overview, RegisterClipboardFormat