Application interface (OneNote)

The Application interface includes methods help retrieve, manipulate, and update OneNote information and content. The methods are in four general categories:

• Notebook structure – Methods for working with notebook structure, including those for discovering, opening, modifying, closing, and deleting notebooks, section groups, and sections.

• Page content – Methods for working with pages and page content, including those for discovering, modifying, saving, and deleting page content. Page content includes binary objects, such as ink and images, and text objects, such as outlines.

• Navigation – Methods for finding, linking to, and navigating to pages and objects.

• Functional – All other methods that perform certain actions or set parameters in OneNote.

In addition, the Application interface includes a number of properties and events.

Notebook Structure methods

The methods described in this section enable you to discover, open, modify, close, and delete OneNote notebooks, section groups, and sections.

GetHierarchy method

The GetHierarchy method returns a string in OneNote 2013 XML format by default or you can set the preferred XML schema version by using the optional xsSchema parameter.

Depending on the parameters you pass, the GetHierarchy method can return various lists (for example all notebooks, all sections in all notebooks, all pages within a given section, or all pages within a given notebook). For each node, the XML string returned provides properties (for example, the section or page title, ID, and last-modified time).

Not all combinations of start node and scope are valid. For example, if you specify a section start node and a notebook scope, GetHierarchy returns a null result because a notebook is higher in the node hierarchy than a section.

The following C# example shows how to use the GetHierarchy method to get the entire OneNote hierarchy, including all notebooks, down to the page level. It copies the output string to the Clipboard, from which you can paste the string into a text editor for review.

static void GetEntireHierarchy()
    {
        String strXML;
        OneNote.Application onApplication = new OneNote.Application();
        onApplication.GetHierarchy(null, 
            OneNote.HierarchyScope.hsPages, out strXML);
        Clipboard.SetText(strXML);
        MessageBox.Show("The XML has been copied to the clipboard");
    }

UpdateHierarchy method

If you pass only a partial OneNote XML string for the bstrChangesXmlIn parameter, OneNote attempts to infer the changes you want. For example, if you include a Notebook element that contains only one section, OneNote adds the section after any existing sections. However, if the operation you specify is ambiguous, the result can be hard to determine. For example, if an existing notebook contains four sections, and the XML string you pass includes the notebook and only the fourth and first sections (in that order), OneNote might place the second and third sections before the fourth section or after the first section.

You cannot use the UpdateHierarchy method to delete part of a notebook. That is, passing an XML string that includes only part of an existing hierarchy does not delete sections that are not included in the string. To delete part of a hierarchy, use the DeleteHierarchy method.

The following C# code shows one way to use the UpdateHierarchy method to change the OneNote hierarchy, by changing the name of an existing section. It reads XML code from a sample file named ChangeSectionName.xml at the root of drive C, loads it into an XML document, and then passes the XML structure of that document to the method.

static void UpdateExistingHierarchy()
    {
        OneNote.Application onApplication = new OneNote.Application();
        
        // Get the XML from the file.
        XmlTextReader reader = new XmlTextReader("C:\\ChangeSectionName.xml");
        reader.WhitespaceHandling = WhitespaceHandling.None;
        XmlDocument xmlDocIn = new XmlDocument();
        xmlDocIn.Load(reader);
        
        // Update the hierarchy.
        onApplication.UpdateHierarchy(xmlDocIn.OuterXml,
        OneNote.XMLSchema.xs2007);   
    }

The following XML code is an excerpt of the ChangeSectionName.xml file that the previous C# code passes to the method. When the XML is passed to the UpdateHierarchy method, it changes the name of one of the sections in the existing hierarchy (by changing the value of the name attribute to "My Renamed Section"). It then removes all the sections except the one whose name was changed. In addition, the code removes unnecessary attributes from the target Section element, including the lastModifiedTime, isCurrentlyViewed, and color attributes, leaving only the name, ID, and path attributes intact.

<?xml version="1.0" ?> 
    <one:Notebooks xmlns:one="http://schemas.microsoft.com/office/onenote/12/2004/onenote"> 
        <one:Notebook name="My Notebook" nickname="My Notebook" ID="{0B8E7305-AC2C-4BCB-8651-1CDA55AAE14C}{1}{B0}"> 
            <one:Section name="My Renamed Section" ID="{5F4E2908-44BA-4C02-91FE-49FC665E9A33}{1}{B0}" path="C:\My Section.one" /> 
        </one:Notebook> 
    </one:Notebooks>

The preceding XML code was obtained by using the code shown in the example for the GetHierarchy method, which is modified, as follows, to limit the scope to sections.

static void GetAllSections()
    {
        String strXML;
        OneNote.Application onApplication = new OneNote.Application();
        onApplication.GetHierarchy(System.String.Empty, 
            OneNote.HierarchyScope.hsSections, out strXML);
        Clipboard.SetText(strXML.ToString());
        MessageBox.Show("The XML has been copied to the Clipboard");
    }

The following C# example shows a complete console application that searches for a section named "Sample_Section", prompts the user to input a new name for the section, and then uses the UpdateHierarchy method to change the section name to the name that the user typed. Before running the code, change "Sample_Section" to the name of a section that exists in your OneNote hierarchy.

    static void Main(string[] args)
    {
        
        // OneNote 2013 Schema namespace.
        string strNamespace = "http://schemas.microsoft.com/office/onenote/2013/onenote";
        string outputXML;
        Application onApplication = new Application();
        onApplication.GetHierarchy(null, HierarchyScope.hsSections, out outputXML);
        // Load a new XmlDocument.
        XmlDocument xmlDoc = new XmlDocument();
        xmlDoc.LoadXml(outputXML);
        XmlNamespaceManager nsmgr = new XmlNamespaceManager(xmlDoc.NameTable);
            nsmgr.AddNamespace("one", strNamespace);
        // Search for the section named "Sample_Section".
        XmlNode xmlNode = xmlDoc.SelectSingleNode("//one:Section[@name='Sample_Section']", nsmgr);
        // Prompt for a new section title.
        System.Console.Write("Please enter a new title for the section: ");
        string input = System.Console.ReadLine();
        xmlNode.Attributes["name"].Value = input; 
        // Update the section with the new title.
        onApp.UpdateHierarchy(xmlNode.OuterXml);
        System.Console.Write("Done!\n");
    }

OpenHierarchy method

If you specify a section group that is not in an open notebook, the OpenHierarchy method opens the section group as a notebook. If you specify a section that is not in an open notebook, the OpenHierarchy method opens the section in the Recent Opened Sections section group. If you specify a section group or section that is already in an open notebook, nothing happens because the section group or section is already open, as well. In any case, OpenHierarchy returns the object ID for the section group, notebook, or section that you specify, so that you can use it in other operations.

You can also use the OpenHierarchy method to create new sections, instead of doing so by importing XML.

The following code shows how to use the OpenHierarchy method to open the Meetings section in the Work notebook and get the ID for the section. If the section does not already exist, OneNote creates it in the location that you specify.

static void OpenSection()
    {
        String strID;
        OneNote.Application onApplication = new OneNote.Application();
        onApplication.OpenHierarchy("C:\\Documents and Settings\\user\\My Documents\\OneNote Notebooks\\Work\\Meetings.one", 
        System.String.Empty, out strID, OneNote.CreateFileType.cftSection);
    }

DeleteHierarchy method

CreateNewPage method

The OneNote API includes the CreateNewPage method as a convenience. You can achieve the same result, with greater control over how the new page is positioned in the hierarchy, by calling the UpdateHierarchy method. The UpdateHierarchy method also lets you create subpages at the same time as you create a new page.

CloseNotebook method

You can use the CloseNotebook method to close the notebook you specify. When you call this method, OneNote synchronizes any offline files with current notebook content, if necessary, and then closes the specified notebook. After the method returns, the notebook no longer appears in the list of open notebooks in the OneNote user interface (UI).

GetHierarchyParent method

If the OneNote object has no parent object (for example, when a user wants to get the parent of a Notebook), an exception is thrown.

GetSpecialLocation method

You can use this method to determine the location on disk of the Unfiled Notes folder. That is the folder in which OneNote stores notes that are created when you drag an item into OneNote, as well as notes that come directly from other applications (such as those that result when you click Send to OneNote in Microsoft Outlook or Microsoft Internet Explorer).

Page Content methods

The methods described in this section enable you to discover, update, and delete the content on pages in OneNote notebooks, as well as to publish OneNote content.

GetPageContent method

By default, to avoid excess length in the XML string it returns, OneNote does not embed binary content in the XML code. For the same reason, it does not mark up the current selection with selection attributes. Binary objects include a OneNote ID in their tags. To get a binary object, you call the GetBinaryPageContent method and pass it the OneNote ID you get from the GetPageContent method. You use the GetPageContent method when you do not need the binary data immediately.

UpdatePageContent method

You can use this method to modify the page in various ways. For example, you can use the UpdatePageContent method to add an outline to a page, change the content of an outline, add images, add ink, move content, or modify text in outlines.

As a more specific example, you might use the GetPageContent method to export an existing page, make some changes to the XML code for the page, and then use the UpdatePageContent method to import the entire page again. Or, you might use this method to add new page objects, such as images, to the bottom of an existing page.

The only objects that you must include in the XML code that you pass to the UpdatePageContent method are page-level objects (such as outlines, images on the page, or ink on the page) that have changed. This method does not modify or remove page-level objects that you do not specify in the bstrPageChangesXmlIn parameter. The method entirely replaces page-level objects, such as outlines, whose IDs match those of the objects you pass. Consequently, you must fully specify all page-level objects in your code, including their existing content and changes you want to make to them.

For example, if your page contains an outline and a background page image, you can replace the outline and leave the image unchanged by completely specifying the outline in the XML code, using the ID of the existing outline, and not including the image in the code. Because the revised outline you include in the code completely replaces the existing outline, you must include the entire contents of the outline.

Also, the UpdatePageContent method modifies only element properties that you specify in the bstrPageChangesXmlIn parameter. For example, if you specify some, but not all, properties of the PageSettings element, the properties that you do not specify remain unchanged.

The following example shows how to use the UpdatePageContent method to change the title of a page and add some sample text to the page. Before running the code, substitute a valid page ID for the page ID shown in the code, so that the code works on your computer. You can get the page ID for a page by using the GetHierarchy method and examining the output.

static void UpdatePageContent()
    {
        OneNote.Application onApplication = new OneNote.Application();
        String strImportXML;
        strImportXML = "<?xml version=\"1.0\"?>" +
            "<one:Page xmlns:one=\"http://schemas.microsoft.com/office/onenote/12/2004/onenote\" 
            ID=\"{3428B7BB-EF39-4B9C-A167-3FAE20630C37}{1}{B0}\">" +
            "    <one:PageSettings RTL=\"false\" color=\"automatic\">" +
            "        <one:PageSize>" +
            "            <one:Automatic/>" +
            "        </one:PageSize>" +
            "        <one:RuleLines visible=\"false\"/>" +
            "    </one:PageSettings>" +
            "    <one:Title style=\"font-family:Calibri;
                 font-size:17.0pt\" lang=\"en-US\">" +
            "        <one:OE alignment=\"left\">" +
            "            <one:T>" +
            "                <![CDATA[My Sample Page]]>" +
            "            </one:T>" +
            "        </one:OE>" +
            "    </one:Title>" +
            "    <one:Outline >" +
            "        <one:Position x=\"120\" y=\"160\"/>" +
            "        <one:Size width=\"120\" height=\"15\"/>" +
            "        <one:OEChildren>" +
            "            <one:OE alignment=\"left\">" +
            "                <one:T>" +
            "                    <![CDATA[Sample Text]]>" +
            "                </one:T>" +
            "            </one:OE>" +
            "        </one:OEChildren>" +
            "    </one:Outline>" +
            "</one:Page>";
        // Update the page content.
        onApplication.UpdatePageContent(strImportXML, System.DateTime.MinValue);
    }

GetBinaryPageContent method

DeletePageContent method

Publish method

Currently, OneNote supports the following file formats:

• MHTML files (.mht)
• Adobe Acrobat PDF files (.pdf)
• XML Paper Specification (XPS) files (.xps)
• OneNote 2013, 2010 or 2007 files (.one)
• OneNote Package files (.onepkg)
• Microsoft Word documents (.doc or .docx)
• Microsoft Windows Enhanced Metafiles (.emf)
• HTML files (.html)

This method produces exactly the same results you would get by clicking Publish in the UI and specifying the format.

Navigation methods

The methods described in this section enable you to find, navigate to, and link to OneNote notebooks, section groups, sections, pages, and page objects.

NavigateTo method

NavigateToUrl method

GetHyperLinkToObject method

When you attempt to navigate to the resulting link, OneNote opens and displays the specified object in the browser.

GetWebHyperlinktoObject method

FindPages method

FindPages works only if you have Microsoft Search 3.0 or 4.0 installed on your computer. Windows Vista and Windows 7 include this component. However, if you are running an earlier version of Windows, you must install Windows Search for FindPages to work.

FindMeta method

FindMeta works only if you have Microsoft Windows Search 3.0 or 4.0 installed on your computer. Windows Vista and Windows 7 include this component. However, if you are running an earlier version of Windows, you must install Windows Search for FindMeta to work.

Functional methods

The methods described in this section enable you to perform certain actions or set parameters within the OneNote application.

MergeFiles method

The MergeFiles method was intended for mobile scenarios in which multiple versions of an OneNote file may exist.

MergeSections method

This method performs the same operation as the Merge into Another Section feature that is visible when you right-click a section.

QuickFiling method

SyncHierarchy method

SetFilingLocation method

The types of content that can be filed include Outlook items and Web Notes from Internet Explorer that are imported to OneNote through the Send to OneNote command in each application. The filing location of items that are printed into OneNote can also be set with this method.

Properties

This section describes the properties of the Application interface.

Events

This section describes the events of the Application interface.

OnNavigate event

OnHierarchyChange method

See also

• OneNote developer reference