IPrintCoreHelper::SetOptions method

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

Syntax

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

Parameters

pDevmode

A pointer to a DEVMODEW structure. If this pointer is provided, IPrintCoreHelper::SetOptions should use the DEVMODEW structure that is pointed to by pDevmode instead of the default or current DEVMODEW structure. If this method is called from the plug-in provider or from either IPrintOemPS::DevMode or IPrintOemUni::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.

cbSize

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

bResolveConflicts

A Boolean value that indicates whether IPrintCoreHelper::SetOptions should resolve conflicts that arise from one or more constraints specified in the GPD or PPD view of the configuration file, as well as constraints for functionality implemented by Unidrv or 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. For more information, see the Remarks section.

pFOPairs

cPairs

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

pcPairsWritten

A pointer to a variable that receives the number of feature-option pairs that were successfully saved before IPrintCoreHelper::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.

pdwResult

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

Value Meaning
SETOPTIONS_RESULT_NO_CONFLICT No constraint that was specified in the GPD or PPD view of the configuration file was violated, relative to the new setting.
SETOPTIONS_RESULT_CONFLICT_RESOLVED At least one constraint that was specified in the GPD or PPD view of the configuration file was violated, and the caller requested that the method should resolve conflicts. This value results in changed settings with conflicts resolved.
SETOPTIONS_RESULT_CONFLICT_NOT_RESOLVED At least one constraint that was specified in the GPD or PPD view of the configuration file was violated, and the caller requested that the method should not resolve conflicts. The settings do not change, and conflicts remain.

Return Value

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

Return code Description
S_OK
The operation succeeded.
E_INVALIDARG
One or more of the arguments is invalid, or the feature was not supported.
E_OUTOFMEMORY
Memory for the result array could not be allocated.
 

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

Remarks

IPrintCoreHelper::SetOptions can be used to change multiple settings 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 (that is, saved to the registry) 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

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

See Also

IPrintCoreHelper

IPrintCoreHelper::GetOption