IPrintCoreUI2::WhyConstrained method (prcomoem.h)

Article
03/13/2023

The IPrintCoreUI2::WhyConstrained method determines why the specified feature/option selection is constrained.

Syntax

HRESULT WhyConstrained(
  [in]  POEMUIOBJ poemuiobj,
  [in]  DWORD     dwFlags,
  [in]  PCSTR     pszFeatureKeyword,
  [in]  PCSTR     pszOptionKeyword,
  [out] PZZSTR    pmszReasonList,
  [in]  DWORD     cbSize,
  [out] PDWORD    pcbNeeded
);

Parameters

[in] poemuiobj

Pointer to the current context, an OEMUIOBJ structure.

[in] dwFlags

Is reserved and must be set to zero.

[in] pszFeatureKeyword

Pointer to a caller-supplied buffer containing the single feature keyword of interest to the caller.

[in] pszOptionKeyword

Pointer to a caller-supplied buffer containing the option keyword.

[out] pmszReasonList

Pointer to a caller-supplied buffer that receives a list of the feature/option keyword pairs that place constraints on the specified feature/option. This list is in MULTI_SZ format with each item in the list separated from the next by a null character. The list is terminated with two null characters.

Set this parameter to NULL to simply query for the size (*pcbNeeded) of the reason list without having the list filled in.

[in] cbSize

Specifies the size, in bytes, of the buffer pointed to by pmszReasonList.

[out] pcbNeeded

Pointer to a memory location that receives the actual size, in bytes, of the reason list.

Return value

The method must return one of the following values.

Return code	Description
S_OK	The method succeeded.
E_OUTOFMEMORY	The value in cbSize was smaller than the number of bytes to be written to the output buffer (the buffer pointed to by pmszReasonList). The method was called with pmszReasonList set to NULL.
E_NOTIMPL	The method is not supported.
E_INVALIDARG	The poemuiobj parameter pointed to an invalid context object. The feature keyword or option keyword was not recognized. The feature stickiness (see Replacing Driver-Supplied Property Sheet Pages) did not match that specified in the current context.
E_FAIL	The method failed

Remarks

This method is supported only for Windows XP Pscript5 UI plug-ins that fully replace the core driver's standard UI pages, and is supported only during the UI plug-in's IPrintOemUI::DocumentPropertySheets and IPrintOemUI::DevicePropertySheets functions, and their property sheet callback routines. See Replacing Driver-Supplied Property Sheet Pages for more information.

When a user of the OEM UI attempts to select an item that is constrained, the caller can use this method to display a message explaining why the item is constrained. When this method returns, pmszReasonList points to a list of one or more feature/option pairs that appear in the current driver settings, but conflict with the selected feature/option keywords. If there were no conflicts, the method should return S_OK, pmszReasonList should be filled in with an empty ASCII string containing only a null character, and *pcbNeeded should be set to 1.

To reduce the need to make two calls per data access, pass the method an output buffer of a fixed size (1 KB, for example), and then check the function return value. If the method returns S_OK, the buffer already contains the data of interest. If the method returns E_OUTOFMEMORY, the value in *pcbNeeded is the buffer size needed to hold the data of interest. The caller should then allocate a buffer of that larger size and proceed with a second call to the method.

Requirements

Requirement	Value
Target Platform	Desktop
Header	prcomoem.h (include Prcomoem.h)