IPrintCoreHelperPS::SetOptions method (prcomoem.h)

The IPrintCoreHelperPS::SetOptions method sets multiple feature-option pairs at the same time.

Syntax

HRESULT SetOptions(
  [in, optional] IN PDEVMODE                      pDevmode,
  [in]           IN DWORD                         cbSize,
  [in]           IN BOOL                          bResolveConflicts,
  [in]           IN const PRINT_FEATURE_OPTION [] pFOPairs,
  [in]           IN DWORD                         cPairs,
  [out]          OUT PDWORD                       pcPairsWritten,
  [out]          OUT PDWORD                       pdwResult
);

Parameters

[in, optional] pDevmode

A pointer to a DEVMODEW structure. If this pointer is provided, IPrintCoreHelperPS::SetOptions should use the DEVMODEW structure that is pointed to by pDevmode rather than the default or current DEVMODEW structure. If this method is called from the plug-in provider or from IPrintOemPS::DevMode, this parameter is required. In most other situations, the parameter should be NULL. When the core driver sets pDevmode to NULL, it modifies its internal state rather than that of the passed-in DEVMODEW structure. This is required during operations such as full UI replacement, where the DEVMODEW structure returned by a DDI, such as DrvDocumentPropertySheets, is being serviced by the core driver's UI module.

[in] cbSize

The size, in bytes, of the DEVMODEW structure that is pointed to by the pDevmode parameter.

[in] bResolveConflicts

A Boolean value that indicates whether IPrintCoreHelperPS::SetOptions should resolve conflicts that arise from one or more constraints in the PPD view of the configuration file, as well as constraints for functionality that are implemented by Pscript or the print processor. If TRUE, this method should attempt to resolve the conflict. If FALSE, this method should not attempt to resolve conflicts.

[in] pFOPairs

An array of PRINT_FEATURE_OPTION elements, where each element contains a feature-option pair. Each feature-option pair lists a feature and the option to select for that feature. All settings are applied sequentially. Duplicates are not disallowed, but settings that appear later in the array (that is, at a higher index) override those that appear earlier in the array.

[in] cPairs

The number of feature-option pairs that are pointed to by the pFOPairs parameter.

[out] pcPairsWritten

A pointer to a variable that receives the number of feature-option pairs that were successfully saved before IPrintCoreHelperPS::SetOptions returned or failed. If this method returns successfully, pcPairsWritten will have the same value as cPairs. If the method fails, pcPairsWritten can have any value from zero through the value of cPairs. This parameter is optional and can be NULL.

[out] pdwResult

A pointer to a variable that receives the status of the conflict resolution. The status can be one of the following values.

Return value

IPrintCoreHelperPS::SetOptions should return one of the following values.

For other failures, the method should return a standard COM error code.

Remarks

IPrintCoreHelperPS::SetOptions can be used to make multiple settings changes simultaneously and to resolve constraints after all of the selected options have been set. Changes to options are applied sequentially, starting from the beginning of the pFOPairs array, so if the same feature appears twice in this array, only the last option for the feature will be selected. Changes to options are not committed unless the bResolveConflicts parameter is TRUE.

For most scenarios the bResolveConflicts parameter should be set to TRUE. Set this parameter to FALSE if you want to prompt the user to resolve conflicts.

Requirements

See also

IPrintCoreHelperPS

IPrintCoreHelperPS::GetOptions