Share via


IXpsSignatureManager::Sign method

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

See also

IXpsSignatureManager

CERT_CONTEXT

IXpsSignature

IXpsSigningOptions

XPS Digital Signature API Errors

XPS Document Errors

XML Paper Specification