IPrintCorePS2::GetOptions method (prcomoem.h)

The IPrintCorePS2::GetOptions method retrieves the driver's current feature settings in the format of a list of feature/option keyword pairs.

Syntax

HRESULT GetOptions(
  [in]  PDEVOBJ pdevobj,
  [in]  DWORD   dwFlags,
  [in]  PCZZSTR pmszFeaturesRequested,
  [in]  DWORD   cbIn,
  [out] PZZSTR  pmszFeatureOptionBuf,
  [in]  DWORD   cbSize,
  [out] PDWORD  pcbNeeded
);

Parameters

[in] pdevobj

Pointer to a DEVOBJ structure.

[in] dwFlags

Is reserved and must be set to zero.

[in] pmszFeaturesRequested

Pointer to caller-supplied buffer containing a list of feature keywords (in MULTI_SZ format) whose settings are requested. Set this parameter to NULL to obtain settings for all features.

[in] cbIn

Specifies the size, in bytes, of the buffer pointed to by pmszFeaturesRequested. The size includes the last MULTI_SZ null character.

[out] pmszFeatureOptionBuf

Pointer to a caller-supplied buffer that receives a list of feature/option keyword pairs (in MULTI_SZ format) obtained from the driver settings. Each feature/option keyword pair contains the feature keyword name, a null character, the option keyword name, and another null character. The list is terminated by two NULL characters.

[in] cbSize

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

[out] pcbNeeded

Pointer to a memory location that receives the actual size, in bytes, of the requested data.

Return value

The method must return one of the following values.

Remarks

This method supports both document-sticky and printer-sticky features. It is supported only after the core driver finishes its DrvEnablePDEV processing, which sets up all option settings. A call to IPrintCorePS2::GetOptions when it is not supported should cause it to return E_NOTIMPL. For example, when the core driver calls a render plug-in's IPrintOemPS::EnablePDEV method, the driver is still occupied with its DrvEnablePDEV processing, so if the plug-in calls IPrintCorePS2::GetOptions within the plug-in's IPrintOemPS::DevMode method, the plug-in receives the E_NOTIMPL return value. However, because the plug-in's IPrintOemPS::EnablePDEV method is called after the core driver finishes its DrvEnablePDEV processing, the plug-in is able to call IPrintCorePS2::GetOptions successfully within its IPrintOemPS::EnablePDEV method.

If a requested feature keyword is not recognized, or the feature is recognized but there is currently no option selection for it, the feature is ignored and the feature/option keyword pair is not placed in the output buffer.

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.

This method is supported for any Pscript5 render plug-in.

For more information, see Using GetOptions and SetOptions.

Requirements

See also

DEVOBJ

DrvEnablePDEV

IPrintCorePS2

IPrintOemPS::DevMode

IPrintOemPS::EnablePDEV