CommonPropertySheetUI

LONG CommonPropertySheetUI(

HWND hWndOwner,

PFNPROPSHEETUI pfnPropSheetUI,

LPARAM lParam,

LPDWORD pResult

);

CommonPropertySheetUI manages and displays a property sheet.

Parameters

hWndOwner: Window handle for the owner of the property sheet. This parameter can be null.
pfnPropSheetUI: Pointer to a callback function of type PFNPROPSHEETUI.
lParam: Specifies the parameter that is passed to the function to which pfnPropSheetUI points when it is called by the CPSUI.
pResult: Pointer to a DWORD that receives the final result of the function to which pfnPropSheetUI points when it is called. Specifically, the Result field of the PROPSHEETUI_INFO structure is copied into pResult if an error is not returned; otherwise, pResult is set to null.

Return Value

CommonPropertySheetUI returns one of the following values:

Return Value

Description

CPSUI_CANCEL

The property sheet was not displayed because there were no pages.

CPSUI_OK

The function succeeded.

CPSUI_RESTARTWINDOWS

The function succeeded. The property sheet was displayed, and the end-user changed a selection that requires the login session to be restarted in order for the change to take effect.

CPSUI_REBOOTSYSTEM

The function succeeded. The property sheet was displayed, and the end-user changed a selection that requires the system to be rebooted in order for the change to take effect.

ERR_CPSUI_Xxx

The property sheet was not displayed due to the error specified by the return error code. These error code values are always less than zero.

Comments

CommonPropertySheetUI is the main entry point for the CPSUI. An application calls this function to have the CPSUI manage and display a property sheet.

The function to which pfnPropSheetUI points is a caller-defined function in which the caller requests the CPSUI to add pages to the property sheet. The CPSUI calls this function as follows:

PROPSHEETUI_INFO   PSUIInfo;
pfnPropSheetUI(&PSUIInfo, lParam);

When an end-user closes the property sheet by selecting OK or Cancel, CommonPropertySheetUI returns the appropriate CPSUI_Xxx value to the original caller.

If the function to which pfnPropSheetUI points returns a LONG value greater than zero, the CPSUI displays the property sheet dialog boxes. When an end-user closes the property sheet by selecting OK or Cancel, CommonPropertySheetUI returns one of CPSUI_OK, CPSUI_RESTARTWINDOWS, or CPSUI_REBOOTSYSTEM. If the callback returns a LONG value that is equal to or less than zero, there were no pages on the property sheet or an error was encountered. In this situation, the CPSUI did not display the property sheet and CommonPropertySheetUI returns CPSUI_CANCEL or ERR_CPSUI_Xxx.

When the last call to pfnPropSheetUI() returns, the value in the Result field of PROPSHEETUI_INFO is copied into the DWORD to which pResult points. The pResult parameter is set only when CommonPropertySheetUI does not return ERR_CPSUI_Xxx. CommonPropertySheetUI does not return the last DWORD result of pfnPropSheet() if pResult is null.

HWND hWndOwner,
PFNPROPSHEETUI pfnPropSheetUI,
LPARAM lParam,
LPDWORD pResult
);

Return Value	Description
CPSUI_CANCEL	The property sheet was not displayed because there were no pages.
CPSUI_OK	The function succeeded.
CPSUI_RESTARTWINDOWS	The function succeeded. The property sheet was displayed, and the end-user changed a selection that requires the login session to be restarted in order for the change to take effect.
CPSUI_REBOOTSYSTEM	The function succeeded. The property sheet was displayed, and the end-user changed a selection that requires the system to be rebooted in order for the change to take effect.
ERR_CPSUI_Xxx	The property sheet was not displayed due to the error specified by the return error code. These error code values are always less than zero.