add Method (IXMLDOMSchemaCollection-XMLSchemaCache)
Adds a new schema to the schema collection and associates the given namespace URI with the specified schema.
JScript Syntax
objXMLDOMSchemaCol.add(namespaceURI, var);
Parameters
namespaceURI
The namespace to associate with the specified schema. The empty string, "", will associate the schema with the empty namespace, .
This may be any string that can be used in an xmlns attribute, but it cannot contain entity references. The same white space normalization that occurs on the xmlns attribute also occurs on namespaceURI (that is, leading and trailing white space is trimmed, new lines are converted to spaces, and multiple adjacent white space characters are collapsed into one space).
var
This specifies the schema to load. It will load it synchronously and with resolveExternals=false and validateOnParse=false. This parameter can also take any DOMDocument as an argument.
This argument can be Null, which results in the removal of any schema for the specified namespaces. If the schema is an IXMLDOMNode, the entire document the node belongs to will be preserved.
Example
The following script example attaches a schema to an XML document.
var xmldoc = new ActiveXObject("Msxml2.FreeThreadedDOMDocument.6.0");
var SchemaCache = new ActiveXObject("Msxml2.XMLSchemaCache.6.0");
xmldoc.async = false;
xmldoc.validateOnParse = false;
SchemaCache.add("x-schema:books", "collection.xdr");
xmldoc.schemas = SchemaCache;
// The document will load only if a valid schema is attached to the xml
// file.
xmldoc.load("collection.xml");
if (xmldoc.parseError.errorCode != 0) {
var myErr = xmldoc.parseError;
WScript.Echo("You have error " + myErr.reason);
} else {
WScript.Echo(xmldoc.xml) ;
}
C/C++ Syntax
HRESULT add(BSTR namespaceURI, VARIANT var);
Parameters
namespaceURI[in]
The namespace to associate with the specified schema.
The empty string, "", will associate the schema with the empty namespace, . This may be any string that can be used in an xmlns attribute, but it cannot contain entity references. The same white space normalization that occurs on the xmlns attribute also occurs on this parameter (that is, leading and trailing white space is trimmed, new lines are converted to spaces, and multiple adjacent white space characters are collapsed into one space).
var[in]
This specifies the schema. It can be a BSTR, in which case it points to the URL to load. It will load it synchronously and with resolveExternals=false and validateOnParse=false. The var parameter can also be any DOMDocument.
This argument can be Null, which results in the removal of any schema for the specified namespaces. If the schema is an IXMLDOMNode, the entire document the node belongs to will be preserved.
Return Values
If this call fails, the collection remains unchanged. E_FAIL is returned if:
The collection is read-only.
The document is not a recognized schema.
An error occurs when compiling the schema.
The ready state of the document is not 4.
If it was loading a schema and encountered a parse error, then the parse error reason is returned in the IErrorInfo. If the VARIANT argument contains an invalid value,E_INVALIDARG is returned.
Example
#include "stdafx.h"
#include "tchar.h"
#include "msxml6.h"
void AddCollectionSample();
int APIENTRY WinMain(HINSTANCE hInstance,
HINSTANCE hPrevInstance,
LPSTR lpCmdLine,
int nCmdShow)
{
::CoInitialize(NULL);
AddCollectionSample();
::CoUninitialize();
return 0;
}
void AddCollectionSample()
{
IXMLDOMDocument2Ptr pIXMLDOMDocument2;
IXMLDOMSchemaCollection2Ptr pIXMLDOMSchemaCollection2Ptr;
int nResult;
try
{
// Create the DOM
nResult = pIXMLDOMDocument2.CreateInstance(__uuidof(MSXML2::DOMDocument60));
(nResult == 0) ? 0: throw nResult;
// Create the Schema Collections
nResult = pIXMLDOMSchemaCollection2Ptr.CreateInstance(__uuidof(MSXML2::XMLSchemaCache60));
(nResult == 0) ? 0: throw nResult;
// Add the schema to the collection
nResult = pIXMLDOMSchemaCollection2Ptr->add(_T("x-schema:books"), _T("c:\\temp\\collection.xsd"));
(nResult == 0) ? 0: throw nResult;
// Attach schemas
pIXMLDOMDocument2->schemas = pIXMLDOMSchemaCollection2Ptr.GetInterfacePtr();
pIXMLDOMDocument2->async = false;
pIXMLDOMDocument2->validateOnParse = true;
// Load the document into the DOM
nResult = pIXMLDOMDocument2->load(_T("c:\\temp\\collection.xml"));
(nResult == -1) ? 0: throw nResult;
::MessageBox(NULL, pIXMLDOMDocument2->xml, _T("Loaded Document"), MB_OK);
} catch(...)
{
::MessageBox(NULL, _T("Sample Failed"), _T("Error"), MB_OK);
}
}
Resource Files
The examples in this topic use the following files.
collection.xml
<?xml version='1.0'?>
<Collection xmlns="x-schema:books">
<Book>
<Title>Lover Birds</Title>
<Author>Cynthia Randall</Author>
<Publisher>Lucerne Publishing</Publisher>
</Book>
</Collection>
collection.xsd (MSXML 4.0 and later)
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="Collection">
<xs:complexType>
<xs:sequence>
<xs:element name="OtherBook">
<xs:complexType>
<xs:sequence>
<xs:element name="Title" type="xs:string"/>
<xs:element name="Author" type="xs:string"/>
<xs:element name="Publisher" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
collection.xdr (MSXML 3.0 and later)
<?xml version="1.0"?>
<Schema xmlns="urn:schemas-microsoft-com:xml-data">
<!-- AttributeType name="xmlns" -->
<ElementType name="Title"/>
<ElementType name="Author"/>
<ElementType name="Publisher"/>
<ElementType name="Book" model="closed">
<element type="Title"/>
<element type="Author"/>
<element type="Publisher"/>
</ElementType>
<ElementType name="Collection" model="closed">
<element type="Book"/>
</ElementType>
</Schema>
Output
<?xml version='1.0'?>
<Collection xmlns="x-schema:books">
<Book>
<Title>Lover Birds</Title>
<Author>Cynthia Randall</Author>
<Publisher>Lucerne Publishing</Publisher>
</Book>
</Collection>
Remarks for MSXML 6.0
In previous versions of MSXML, a schema already in the cache for a given namespace was replaced by the schema from the new location. In MSXML 6.0, when you call this method the declarations are merged with an existing schema with the same namespace. Using this feature, MSXML 6.0 supports "partial schemas". You can load several schemas, all having the same target namespace, into one schema in the schema cache.
Calling this method will cause all the schemas imported by the added schema to also be added into the cache as "top-level" schemas.
Schema imports are validated "lax" - this means that any namespace or type already added to the schema cache can be referenced by another schema in the cache, even if there is no explicit import in the referencing schema. You need to set validateOnLoad Property to false to avoid issues around the order of calls to this method.
The add operation is atomic. All the schemas must be added successfully to the cache, or else none are.
MSXML 6.0 has removed support for XDR schemas, whereas XDR is supported in MSXML 3.0 AND MSXML 4.0. If this method is called with an XDR schema, the call will fail.
Versioning
Implemented in: MSXML 3.0 and MSXML 6.0