Wednesday, August 30, 2006
Hierarchy Scope versus Node Type
I was just about to call this post A Look at GetHierarchy() III but I think two posts named the "same" is enough. The previous posts I demonstrated how you can get access to content from OneNote using GetHierarchy() using the startNodeID and the HierarchyScope enumeration. I hope you took a few minutes to play with and view the different outcomes based on the startNode and the HierarchyScope. In this post I am covering how the startNodeID type and the HierarchyScope parameters effect the Xml returned.
In this post the actual startNodeID is not as important as the type of node startNodeID refers to. The startNodeID does signifies the "starting node" or what the top-level element in the retuned hierarchy will be. It also determines what element nodes are returned to the caller when reviewed in conjunction with the HierachyScope element.
For example for any given node type and a scope of hsSelf the returned Xml will include a single node of that type with attributes defined for the specific node based on the object ID. Here are examples of resultant Xml based on the node type referenced by the startNodeID
Notebook / hsSelf:
<?xml version="1.0"?>
<one:Notebook xmlns:one="http://schemas.microsoft.com/office/onenote/12/2004/onenote" name="OneNote Guide Beta 2" nickname="OneNote Guide Beta 2" ID="{674B715E-9A47-4A2C-9D11-5B7325B27D4B}{1}{B0}" path="C:\Documents and Settings\OneNoteGuy\My Documents\OneNote Notebooks\OneNote Guide Beta 2" lastModifiedTime="2006-08-25T12:13:41.000Z" color="none"/>
Section Group / hsSelf:
<?xml version="1.0"?>
<one:Folder xmlns:one="http://schemas.microsoft.com/office/onenote/12/2004/onenote" name="Test" ID="{20476F31-4276-4DC7-ADBE-A50D4F54D711}{1}{B0}" path="C:\Documents and Settings\OneNoteGuy\My Documents\OneNote Notebooks\OneNote Guide Beta 2\Test" lastModifiedTime="2006-08-30T18:42:22.000Z"/>
Section / hsSelf:
<one:Section xmlns:one="http://schemas.microsoft.com/office/onenote/12/2004/onenote" name="More Cool Features" ID="{AD8C801C-F573-0C63-1AC6-624F5676F284}{1}{B0}" path="C:\Documents and Settings\OneNoteGuy\My Documents\OneNote Notebooks\OneNote Guide Beta 2\More Cool Features.one" lastModifiedTime="2006-06-19T18:15:48.000Z" color="#FFD869"/>
Page / hsSelf:
<?xml version="1.0" encoding="utf-16"?>
<one:Page xmlns:one="http://schemas.microsoft.com/office/onenote/12/2004/onenote" ID="{68B0DC18-EC17-0B54-1699-913646F56278}{1}{B0}" name="1. Get a Quick Feel for OneNote" dateTime="2006-06-19T18:15:41.000Z" lastModifiedTime="2006-06-19T18:15:45.000Z" />
The value hsSelf will always return a single element of that type with attributes for the specific instance of the node determined by the startNodeID.
The hsSelf value is self explanatory. hsChildren is just about as self explanatory as hsSelf. Depending on the node type you will see the major nodes below it. hsChildren generally does not recurse below the immediate child node. For example if you use a startNodeId that references a Notebook element and the hsChildren scope the returned Xml will contain the root Notebook element and the immediate children elements which based on the schema include Folder and Section elements. You will not see Page elements nested within the Section element. Apparently the singular exception to this "immediate child only" scope is when the startNodeID references a Page node. In this instance you will get all node contained within the Page node element. This includes nodes that nested within other nested nodes.
Below is a table that displays the resultant Xml for node type versus scope. Where the element is referred to in the singular form it means only one element. Elements referred to in the plural form means zero or more. Elements include all the elements attributes in the Xml result. Error indicates that the node type/scope is not applicable and you will receive a COM exception.
I should mention I am running OneNote 2007 Beta2 so things might change. Also note that a Section Group is defined in Xml as a Folder element.
As always if you find anything contrary to this info please post a comment. I just dont have the time to test every scenerio possible and appreciate a critical eye so we have the most accurate information available to the community.
