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.
[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 |
---|---|
|
The method succeeded. |
|
The value passed in the relationshipSigningOption parameter is not a valid OPC_RELATIONSHIPS_SIGNING_OPTION enumeration value. |
|
The value passed in the transformMethod parameter is not a valid OPC_CANONICALIZATION_METHOD enumeration value. |
|
The sourceUri parameter is NULL. |
|
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.
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
Getting Started with the Packaging API
IOpcSignatureRelationshipReferenceSet
OPC_RELATIONSHIPS_SIGNING_OPTION
Overviews
Packaging API Programming Guide
Packaging Digital Signature Interfaces
Reference