IOpcSignatureRelationshipReferenceSet::Create method (msopc.h)

Creates an IOpcSignatureRelationshipReference interface pointer that represents a reference to a Relationships part, and adds the new interface pointer to the set. All or a subset of the relationships stored in the Relationships part to be referenced are selected for signing.

Syntax

HRESULT Create(
  [in]          IOpcUri                            *sourceUri,
  [in]          LPCWSTR                            digestMethod,
  [in]          OPC_RELATIONSHIPS_SIGNING_OPTION   relationshipSigningOption,
  [in]          IOpcRelationshipSelectorSet        *selectorSet,
  [in]          OPC_CANONICALIZATION_METHOD        transformMethod,
  [out, retval] IOpcSignatureRelationshipReference **relationshipReference
);

Parameters

[in] sourceUri

An IOpcUri interface pointer that represents the source URI of the relationships to be selected for signing.

[in] digestMethod

The digest method to be used for the relationships to be selected. To use the default digest method, pass NULL in this parameter.

Important  The default digest method must be set by calling the IOpcSigningOptions::SetDefaultDigestMethod method before IOpcDigitalSignatureManager::Sign is called.
 

[in] relationshipSigningOption

A value that indicates whether the relationships selected for signing include all or a subset of the relationships in the Relationships part to be referenced.

For information about the effect of relationshipSigningOption values on other parameters, see Remarks.

[in] selectorSet

An IOpcRelationshipSelectorSet interface pointer that can be used to identify a subset of relationships in the Relationships part to be selected for signing.

If relationshipSigningOption is set to OPC_RELATIONSHIP_SIGN_PART, selectorSet is NULL.

For information about selectorSet values, see Remarks.

[in] transformMethod

A value that describes the canonicalization method to be applied to the relationship markup of the selected relationships.

If relationshipSigningOption is set OPC_RELATIONSHIP_SIGN_USING_SELECTORS, the value of transformMethod is ignored.

For more information about the transform methods to be applied when relationshipSigningOption is set to OPC_RELATIONSHIP_SIGN_USING_SELECTORS, see Remarks.

[out, retval] relationshipReference

A new IOpcSignatureRelationshipReference interface pointer that represents the referenced Relationships part.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code Description
S_OK
The method succeeded.
E_INVALIDARG
The value passed in the relationshipSigningOption parameter is not a valid OPC_RELATIONSHIPS_SIGNING_OPTION enumeration value.
E_INVALIDARG
The value passed in the transformMethod parameter is not a valid OPC_CANONICALIZATION_METHOD enumeration value.
E_POINTER
The sourceUri parameter is NULL.
E_UNEXPECTED
The selectorSet parameter is not being passed NULL while the relationshipSigningOption parameter is passed a value of OPC_RELATIONSHIP_SIGN_PART.

Remarks

This method creates a reference to a Relationships part. All or a subset of the relationships that are stored in a referenced Relationships part can be signed when the signature is generated.

To sign all of the relationships in a Relationships part, call this method with the relationshipSigningOption parameter value set to OPC_RELATIONSHIP_SIGN_PART and the selectorSet parameter value set to NULL.

To sign a subset of the relationships in a Relationships part, call this method with the relationshipSigningOption parameter value set to OPC_RELATIONSHIP_SIGN_USING_SELECTORS and the selectorSet parameter value set to an IOpcRelationshipSelectorSet interface pointer. To create an IOpcRelationshipSelectorSet interface pointer, call the CreateRelationshipSelectorSet method.

The following table summarizes the parameter values required by this method to create a reference that indicates whether all of the relationships or a subset of the relationships (which are stored in the Relationships part to be referenced) are to be signed.

Description relationshipSigningOption Value selectorSet Value
Sign all of the relationships in the Relationships part OPC_RELATIONSHIP_SIGN_PART NULL
Sign a subset of the relationships in the Relationships part OPC_RELATIONSHIP_SIGN_USING_SELECTORS An IOpcRelationshipSelectorSet interface pointer
 

If a subset of relationships are to be signed, the specified transform method is ignored. Instead, when the signature is generated, the first transform applied is the Relationships Transform, and the second is the OPC_CANONICALIZATION_C14N canonicalization method.

When an IOpcSignatureRelationshipReference interface pointer is created and added to the set, the reference it represents is saved when the package is saved.

Relationships that will not be signed can be removed, modified or added to the package without invalidating the signature. If a subset of relationships has been selected for signing and the subset is altered, the signature will be invalidated.

Important  A selected subset could be altered if the relationship type of a relationship that is added to or modified in a referenced Relationships part matches a relationship type that was used to select one or more relationships in the subset.
 

Thread Safety

Packaging objects are not thread-safe.

For more information, see the Getting Started with the Packaging API.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header msopc.h

See also

Core Packaging Interfaces

Getting Started with the Packaging API

IOpcDigitalSignatureManager

IOpcSignatureRelationshipReferenceSet

IOpcSigningOptions

OPC_CANONICALIZATION_METHOD

OPC_RELATIONSHIPS_SIGNING_OPTION

Overviews

Packaging API Programming Guide

Packaging API Reference

Packaging API Samples

Packaging Digital Signature Interfaces

Packaging Interfaces

Reference