IXpsSignatureManager::Sign method

Article
06/01/2017

Signs the contents of an XPS package as specified by the signing options and returns the resulting digital signature.

Syntax

HRESULT Sign(
  [in]                IXpsSigningOptions *signOptions,
  [in]          const CERT_CONTEXT       *x509Certificate,
  [out, retval]       IXpsSignature      **signature
);

Parameters

signOptions [in]
A pointer to the IXpsSigningOptions interface that contains the signing options.

Note

The SignatureMethod and the DigestMethod properties of the IXpsSigningOptions interface must be initialized before the pointer to that interface can be used in the signOptions parameter.
x509Certificate [in]
A pointer to the CERT_CONTEXT structure that contains the X.509 certificate to be used for signing.
signature [out, retval]
A pointer to the IXpsSignature interface that contains the new digital signature.

If successful, this method creates the signature part, adds it to the package, and in signature returns a pointer to the interface of that signature part.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the table that follows. For return values that are not listed in this table, see XPS Digital Signature API Errors and XPS Document Errors.

Return code	Description
S_OK	The method succeeded.
XPS_E_MARKUP_COMPATIBILITY_ELEMENTS	The XPS_SIGN_FLAGS value specified that no markup compatibility elements were expected; however, markup compatibility elements were found.
XPS_E_NO_CUSTOM_OBJECTS	signOptions does not point to a recognized interface implementation. Custom implementation of XPS Document API interfaces is not supported.
XPS_E_PACKAGE_NOT_OPENED	An XPS package has not yet been opened in the signature manager.

Remarks

Adding a new signature does not overwrite the original file or stream that was read by calling the LoadPackageFile or LoadPackageStream method. The signature will be added to the in-memory copy of the XPS package until the package is saved (by calling the SavePackageToFile or SavePackageToStream method).

If the new signature includes parts that contain markup compatibility elements, the default is for this method to fail with an error of XPS_E_MARKUP_COMPATIBILITY_ELEMENTS. To override this behavior, call IXpsSigningOptions::SetFlags; this will set the XPS_SIGN_FLAGS_IGNORE_MARKUP_COMPATIBILITY flag in the IXpsSigningOptions interface referenced by the signOptions parameter.

If this method returns an HRESULT value that is not in the list of its return values, the signature manager should be released and recreated.

This method will succeed even if the new signature breaks existing signatures.

Requirements

Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Header	Xpsdigitalsignature.h
IDL	XpsDigitalSignature.idl

Share via