Syntax

  public XmlDocument getSchema (
     XmlDocument   initParameters)
  

  #include "NativeInterface.h"
  
  XmlDocument * METHOD_CALL getSchema (
     XmlDocument   *initParameters);
  

Parameters

initParameters

(IN) Points to an XML document that contains the configuration parameters for the driver so that the driver can authenticate to the application to obtain the schema.

Remarks

The DirXML engine calls the getSchema method to obtain an XML document containing a representation of the application’s schema. The getSchema method is called on a driver instance constructed explicitly for the query schema operation. After the getSchema method returns, the instance used for the getSchema called is destroyed (C++) or made available for garbage collection (Java).

When a driver is run for the first time, the DirXML engine calls the getSchema method before starting the driver for normal synchronization. This is done because the engine requires a schema representation to properly perform merges between eDirectory and application objects that are associated through a matching rule. In addition, ConsoleOne requires the application schema for the Mapping Rule snapin to function correctly. When the schema has been obtained, it is stored in the DirXML-ApplicationSchema attribute on the DirXML-Driver object corresponding to the driver.

The "initParameters" argument contains a document that contains the same initialization parameters as are sent to the DriverShim init method, as well as the <subscriber-options> and <publisher-options> elements that are sent to SubscriptionShim init and PublicationShim init methods. The return document should contain either a status, in the case of an error, or the schema representation.

If the application has a modifiable schema the driver should query the application and build the XML schema representation from the results of the query. If the application has an invariant schema, a reasonable implementation is to place a serialized XML document representing the schema into a string in the driver and return that XML document.The following is an example of the response to a getSchema call from the VRTest driver.

  <nds dtdversion="1.0" ndsversion="8.5">
     <output>
        <schema-def hierarchical="true">
           <class-def class-name="O" container="true">
              <attr-def attr-name="Name" case-sensitive="false" multi-valued="false" naming="true" read-only="false" required="false" type="string"/>
              <attr-def attr-name="Object Path" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
              <attr-def attr-name="Unique Id" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
           </class-def>
           <class-def class-name="OU" container="true">
              <attr-def attr-name="Name" case-sensitive="false" multi-valued="false" naming="true" read-only="false" required="false" type="string"/>
              <attr-def attr-name="Object Path" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true"
                 type="string"/>
              <attr-def attr-name="Unique Id" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
           </class-def>
           <class-def class-name="User Object" container="false">
              <attr-def attr-name="name" case-sensitive="false" multi-valued="false" naming="true" read-only="false" required="true" type="string"/>
              <attr-def attr-name="Family Name" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="false" type="string"/>
              <attr-def attr-name="First Name" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="false" type="string"/>
              <attr-def attr-name="Telephone" case-sensitive="false" multi-valued="true" naming="false" read-only="false" required="false" type="string"/>
              <attr-def attr-name="Object Path" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
              <attr-def attr-name="Unique Id" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
           </class-def>
           <class-def class-name="Bogus" container="false">
              <attr-def attr-name="Whatever" case-sensitive="false" multi-valued="true" naming="true" read-only="false" required="false" type="string"/>
              <attr-def attr-name="Object Path" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
              <attr-def attr-name="Unique Id" case-sensitive="false" multi-valued="false" naming="false" read-only="false" required="true" type="string"/>
           </class-def>
        </schema-def>
     </output>
  </nds>
  

For information on the format of this schema document, see schema-def.

The following code examples show how the skeleton driver implements the getSchema method.However, since the skeleton driver doesn’t support an actual application, an error is returned rather than a schema representation.

Sample Code

  public XmlDocument getSchema(XmlDocument initParameters)
  {
     //setup the shared authentication information
     authParams = getAuthenticationParams(initParameters. getDocument());
     
     //However, since we are just a skeleton, this code
     //creates a return document that says we can’t do it. 
        return   createStatusDocument(STATUS_ERROR,"Skeleton driver doesn’t support the getSchema operation");
  }
  

  XmlDocument * METHOD_CALL  CSkeletonDriver::getSchema(
     XmlDocument * initParameters)
  {
     try
     {
        common.tracer->trace("getSchema");
  
        //setup the shared authentication information
        authParams = common.getAuthenticationParams(initParameters->getDocument());
  
  //However, since this driver is just a skeleton...
  //
  //Create a return document that says we can't do it. Note that this
  
  

  //causes DirXML to display a warning in DSTrace that it is unable to
  //read the application schema
        return common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_ERROR,MSG_NO_SCHEMA));
     } catch (ShimException e)
     {
        return   common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_FATAL,e.getMessage()));
     } catch (...)
     {
        //something bad happened...
        return   common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_FATAL,MSG_BAD));
     }
  }