setReferenceData Method

[This feature was first implemented for MSXML 5.0.]

Assigns a new data source to a specified <ds:Reference> element within a signature object. You can use this method to sign or verify different data from the default data source.

[JScript]

Script Syntax

objXMLDigitalSignature.setReferenceData(uri, pSRC);

[Visual Basic]

Visual Basic Syntax

objXMLDigitalSignature.setReferenceData(uri, pSRC)

[C/C++]

C/C++ Syntax Using Smart Pointers

objXMLDigitalSignature->setReferenceData(uri, pSRC);

C/C++ Syntax

HRESULT setReferenceData(
    BSTR uri,
    IUnknown* pSRC);

Parameters

uri [in]: Identifies the <ds:Reference> element. The string value of this parameter is matched against the URI attribute value of a <ds:Reference> element within an XML digital signature object. To locate a <ds:Reference> element without the URI attribute, set this parameter to "##null".
pSRC [in]: The new data source for use with the specified <ds:Reference> element for future verification or signing. The new data can be represented as an IXMLDOMNode, an IStream object, or a SAX proxy object created by the createSAXProxy Method method. For a SAX proxy, the caller must start the SAX reader by calling its parse or parseURL methods or performing other equivalent operations before sign or verify can proceed.

Return Values

S_OK: The value returned if successful.
E_FAILURE: The value returned if the method call failed.

Remarks

This method does not resolve or check the content of the uri parameter. It uses uri only to locate appropriate <ds:Reference> elements in the signature or template. To specify the <ds:Reference> element with NULL URI attribute value (that is, the <ds:Reference> element without the URI attribute ), use "##null" in the uri parameter. This method does not modify the <ds:Signature> XML fragment.

You must set the signature property before calling this method.

The new data source (pSrc) object can be any of the following types:

An IXMLOMNode object, which must be either a document or an element node, is treated as an XML document.
An IStream object is treated as a binary stream containing either XML or non-XML data, unless the stream undergoes a transformation that outputs XML. In the latter case, the IStream object is treated as an XML document.
A SAX proxy object, which must be connected to a SAX Reader that accepts a SAX stream, is treated as an XML document.

Although <ds:Signature> can have multiple <ds:Reference> elements with the same URI attribute value, you cannot override their data source using the setReferenceData method. Calling setReferenceData on such a signature object to override the data source will result in an error.

The setReferenceData method initiates the computation of the digest value either immediately or some time later. Therefore, once set, the new data source should not be modified or destroyed before you call sign or verify. Otherwise, the result is undefined.

Example

This example uses a enveloping signature template that contains two <ds:Object> elements. Each contains a simple text string. One object (obj2) is referenced in the <ds:Reference> element and the other is not. By default, signing is performed on the referenced data only. However, you can use the setReferenceData method to specify different data to be signed and/or verified.

The example uses an enveloping signature template, and outputs a signed signature file.

We've provided source files for the sample in three languages: JScript, Visual Basic, and C++. The output is the same in each language.

Applies To

IXMLDigitalSignature | IXMLDigitalSignatureEx

Versioning

MSXML 5.0 and later

To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button in the upper-left corner of the page.