What's New for Developers in OneNote 2007 (Part 1 of 2)

Saul Candib, Microsoft Corporation

May 2006

Applies to: 2007 Microsoft Office Suites, Microsoft Office OneNote 2007

Summary: This article is part one of a two-part series introducing and explaining new features of interest to developers in Microsoft Office OneNote 2007. Developer-related features include a new COM API that offers new import, export, selection, and search functionality. (23 printed pages)

For information about the OneNote 2007 XML Schema, see What's New for Developers in OneNote 2007 (Part 2 of 2).

Contents

  • Introduction to OneNote 2007

  • OneNote 2007 COM API

  • Working with the OneNote 2007 COM API in Visual Studio 2005

  • Conclusion

  • Additional Resources

Introduction to OneNote 2007

Microsoft Office OneNote 2007 provides a new COM application programming interface (API) that offers you the ability to import, export, and modify OneNote 2007 content programmatically.

For a list and descriptions of the new methods and enumerated values, see New Enumerations in this article.

Nodes and Object IDs in OneNote 2007

As used in this article, the word node refers to a particular node in the OneNote 2007 notebook hierarchy. The root node contains all notebook nodes, notebook nodes contain section group nodes and section nodes, section group nodes contain section group nodes and section nodes, and section nodes can contain pages. Each of these nodes corresponds to a similarly named entity in OneNote 2007.

Note

Section groups were previously known as "folders" in OneNote.

OneNote 2007 assigns object IDs to provide references to OneNote 2007 objects. Objects that have OneNote 2007 object IDs include notebooks, section groups, sections, pages, objects on pages, outlines, and paragraphs. When you call methods to return hierarchy data or page content, OneNote 2007 includes these IDs in the XML code it exports. You must supply object IDs as input parameters for many method calls. The object IDs stay the same for the entire time that a notebook is open: IDs change only when you close and reopen the notebook and when the cache file is recreated.

The fact that object IDs are of type String is irrelevant. Simply regard them as unique identifiers for OneNote 2007 objects.

Notes on OneNote Structure

It is important to understand how OneNote stores its files and structure on disk. The highest level of organization in OneNote is the notebook. Notebooks are folders on a local disk, a remote share, or a SharePoint site. Notebooks contain either sections, which are individual OneNote (.one) files, or section groups. Section groups are folders that contain more sections. Note that, in most places in the OneNote API, section groups are still called folders for reasons of backward-compatibility; you can use the terms interchangeably.

OneNote sections contain individual pages, and pages contain all of the data that the user sees on the page. Each page contains a single title area and one or more outlines, and each outline can contain one or more paragraphs of text. A page can also contain embedded files, ink, and images. For more information about all of these elements, see the 2007 Office System: XML Schema Reference.

OneNote 2007 COM API

The OneNote 2007 COM API includes two objects:

  • Application   New object for OneNote 2007 with all new methods.

  • CSimpleImporter   Existing object originally available in Microsoft Office OneNote 2003 Service Pack (SP) 1. Although OneNote 2007 retains this object in the API for compatibility, we do not recommend that you use it. The new members of the Application object provide the same functionality and much more. For more information about the CSimpleImporter object and its methods, see Importing Content into OneNote 2003 SP1.

Working with the OneNote 2007 COM API in Visual Studio 2005

The code samples in this article are written in Microsoft Visual C#. You can run them in Microsoft Visual Studio 2005 or develop in any programming language that supports COM, for example C++.

To use the samples provided in this article to work with the OneNote 2007 COM API in Microsoft Visual Studio 2005, follow these general steps:

  1. Create a Visual C# project in Visual Studio .NET.

  2. In Solution Explorer, right-click References for your project, and then click Add Reference.

  3. On the COM tab of the Add Reference dialog box, add a reference to the Microsoft OneNote 12.0 Object Library, and then click OK. Alternatively, on the .NET tab of the Add Reference dialog box, add a reference to Microsoft.Office.Interop.OneNote. These references are equivalent—add one or the other, but not both.

  4. Add the following using directives to your code:

    using System.Runtime.InteropServices;
    using Microsoft.Office.Interop.OneNote;
    
  5. To create an instance of the OneNote 2007 Application object to work with, add the following lines of code to your project:

    Microsoft.Office.Interop.OneNote.Application onApplication;
    onApplication = new Microsoft.Office Interop.OneNote.ApplicationClass();
    

Application Class Members

The Application class includes new methods in three 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.

The following sections describe the methods in each of these categories in more detail.

Notebook Structure Methods

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

GetHierarchy Method

You can use the GetHierarchy method to get the notebook node hierarchy structure, starting from the node you specify (all notebooks or a single notebook, section group, or section), and extending downward to all descendants at the level you specify. The GetHierarchy method returns a string in OneNote 2007 XML format.

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.

The GetHierarchy method has the following signature:

HRESULT GetHierarchy(
      [in]BSTR bstrStartNodeID,
      [in]HierarchyScope hsScope,
      [out]BSTR * pbstrHierarchyXmlOut);

The GetHierarchy method takes the following parameters:

  • bstrStartNodeID   The node (notebook, section group, or section) whose descendants you want. If you pass a null string (""), the method gets all nodes below the root node, that is, all notebooks, section groups, and sections. If you specify a notebook, section group, or section node, the method gets only descendants of that node.

  • hsScope   The lowest descendant node level you want. For example, if you specify pages, the method gets all nodes as far down as the page level. If you specify sections, the method gets only section nodes below the notebook. For more information, see the HierarchyScope enumeration in Table 1.

  • pbstrHierarchyXmlOut   (Output parameter.) A pointer to the string in which you want OneNote 2007 to write the XML output.

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 Visual C# example shows how to use the GetHierarchy method to get the entire OneNote 2007 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.

[C#]

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

UpdateHierarchy Method

You can use the UpdateHierarchy method to modify or update the hierarchy of notebooks. For example, you can add sections or section groups to a notebook, add a new notebook, move sections within a notebook, change the name of a section, add pages to a section, or change the order of pages within sections.

The UpdateHierarchy method has the following signature:

HRESULT UpdateHierarchy(
      [in]BSTR bstrChangesXmlIn,
      [in,defaultvalue(0)]DATE dateExpectedLastModified);

The UpdateHierarchy method takes the following parameters:

  • bstrChangesXmlIn   A string, containing OneNote 2007 XML code, that specifies the hierarchy changes to make. For example, if you want to insert a new section, you can add a Section element in the XML string where you want the new section added. Alternatively, if you want to change the name of an existing section, you can keep the same section ID and change its name attribute in the XML code.

  • dateExpectedLastModified   (Optional.) The date and time that you think the root node specified in the bstrChangesXmlIn parameter was last modified. The root node can be a notebook, section group, or section. If you pass a non-zero value for this parameter, OneNote 2007 proceeds with the update only if the value you pass matches the actual date and time the object was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits users made since the last time the object was modified.

If you pass only a partial OneNote 2007 XML string for bstrChangesXmlIn, OneNote 2007 attempts to infer the changes you want. For example, if you include a Notebook element that contains only one section, OneNote 2007 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 2007 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 notdelete sections not included in the string. To delete part of a hierarchy, use the DeleteHierarchy method.

The following Visual C# code shows one way to use the UpdateHierarchy method to change the OneNote 2007 hierarchy, by changing the name of an existing section. It reads XML code from a 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.

[C#]

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

Following is a version of the text of the ChangeSectionName.xml file that the sample code passes to the method. When the text is passed to the UpdateHierarchy method, this XML text changes the name of one of the sections in the existing hierarchy.

The sample XML file was obtained by using the code shown in the example for the GetHierarchy method above, modified to limit the scope to sections:

[xml]

static void GetAllSections()
      {
         String strXML;
         OneNote.ApplicationClass onApplication = new OneNote.ApplicationClass();
         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 resulting XML output was saved to a file at the root of drive C, and the file was modified to remove all the sections except the one whose name we wanted to change. In addition, we removed unnecessary attributes from the target Section element, including the lastModifiedTime, isCurrentlyViewed, and color attributes, leaving only the name, ID, and path attributes intact. Finally, the value of the name attribute was changed to the new name desired, in this case "My Renamed Section".

<?xml version="1.0" ?> 
-  <one:Notebooks xmlns:one="https://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 following Visual C# sample 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, substitute the name of a section that exists in your OneNote hierarchy for Sample_Section.

[C#]

      static void Main(string[] args)
      {
         
         // OneNote 2007 Beta2 Schema namespace
         string strNamespace = "https://schemas.microsoft.com/office/onenote/12/2004/onenote";
         string outputXML;

         ApplicationClass onApplication = new ApplicationClass();
         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.DateTime.MinValue);
         System.Console.Write("Done!\n");

      }

OpenHierarchy Method

You can use the OpenHierarchy method to open a section group or section that you specify. 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 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 OpenHierarchy method has the following signature:

HRESULT OpenHierarchy(
      [in]BSTR bstrPath,
      [in]BSTR bstrRelativeToObjectID,
      [out]BSTR * pbstrObjectID,
      [in,defaultvalue(cftNone)]CreateFileType cftIfNotExist);

The OpenHierarchy method takes the following parameters:

  • bstrPath   The path you want to open. For a notebook, or for a section group in a notebook, bstrPath can be a folder path or the path to an .one section file. If you specify the path to an .one section file, you must include the .one extension on the file-path string.

  • bstrRelativeToObjectID   The OneNote 2007 ID of the parent object (notebook or section group) under which you want the new object to open. If the bstrPath parameter is an absolute path, you can pass an empty string ("") for bstrRelativeToObjectID. Alternatively, you can pass the object ID of the notebook or section group that should contain the object (section or section group) that you want to create, and then specify the file name (for example, section1.one) of the object that you want to create under that parent object.

  • pbstrObjectID   (Output parameter.) The object ID that OneNote 2007 returns for the notebook, section group, or section that the OpenHierarchy method opens. This parameter is a pointer to the string into which you want the method to write the ID.

  • cftlfNotExist   (Optional.) An enumerated value from the CreateFileType enumeration. If you pass a value for cftIfNotExist, the OpenHierarchy method creates the section group or section file at the specified path only when the file does not already exist.

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 you specify.

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

DeleteHierarchy Method

You can use the DeleteHierarchy method to delete any hierarchy object (a section group, section, or page) from the OneNote 2007 notebook hierarchy.

The DeleteHierarchy method has the following signature:

HRESULT DeleteHierarchy(
      [in]BSTR bstrObjectID,
      [in,defaultvalue(0)]DATE dateExpectedLastModified);

The DeleteHierarchy method takes the following parameters:

  • bstrObjectID   The OneNote 2007 ID of the object you want to delete. The object can be a section group, section, or page.

  • dateExpectedLastModified   (Optional.) The date and time that you think the object you want to delete was last modified. If you pass a non-zero value for this parameter, OneNote 2007 proceeds with the update only if the value you pass matches the actual date and time the object was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits users made since the last time the object was modified.

CreateNewPage Method

You can use the CreateNewPage method to add a new page to the section you specify. The new page is added as the last page of the section.

The CreateNewPage method has the following signature:

HRESULT CreateNewPage(
      [in]BSTR bstrSectionID,
      [out]BSTR * pbstrPageID);
      [in,defaultvalue(npsDefault)]NewPageStyle npsNewPageStyle);

The CreateNewPage method takes the following parameters:

  • bstrSectionID   A string containing the OneNote 2007 ID of the section in which you want to create the new page.

  • pbstrPageID   (Output parameter.) A pointer to the string into which the method writes the OneNote 2007 ID for the newly created page.

  • npsNewPageStyle   A value from the NewPageStyle enumeration specifying the style of the page to be created.

The OneNote 2007 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 2007 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 2007 user interface (UI).

The CloseNotebook method has the following signature:

HRESULT CloseNotebook([in]BSTR bstrNotebookID);

The CloseNotebook method takes the following parameter:

  • bstrNotebookID   The OneNote 2007 ID of the notebook you want to close.

GetSpecialLocation Method

You can use the GetSpecialLocation method to find the path to where OneNote 2007 stores certain special items, such as backups, unfiled notes, and the default notebook.

For example, you can use this method to determine the location on disk of the Unfiled Notes folder—the folder where 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 Office Outlook or Microsoft Internet Explorer.

The GetSpecialLocation method has the following signature:

HRESULT GetSpecialLocation(
      [in]SpecialLocation slToGet,
      [out]BSTR * pbstrSpecialLocationPath);

The GetSpecialLocation method takes the following parameters:

slToGet   The special folder location to get. A value from the SpecialLocation enumeration.

pbstrSpecialLocationPath   (Output parameter.) A pointer to the string into which you want OneNote to write the path of the special folder.

Page Content Methods

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

GetPageContent Method

You can use the GetPageContent method to get the content (everything on the page) of the page you specify, in OneNote 2007 XML format.

The GetPageContent method has the following signature:

HRESULT GetPageContent(
      [in]BSTR bstrPageID,
      [out]BSTR * pbstrPageXmlOut,
      [in,defaultvalue(piBasic)]PageInfo pageInfoToExport);

The GetPageContent method takes the following parameters:

  • bstrPageId   The OneNote 2007 ID of the page whose content you want to get.

  • pbstrPageXmlOut   (Output parameter.) A pointer to the string into which you want OneNote 2007 to write the XML output.

  • pageInfoToExport   (Optional.) Specifies whether the GetPageContent method returns binary content, embedded in the XML code and base 64 encoded. Binary content can include, for example, images and ink data. The pageInfoToExport parameter also specifies whether to mark up the selection in the XML code that the GetPageContent method returns. It takes an enumerated value from the PageInfo enumeration.

By default, to avoid excess length in the XML string it returns, OneNote 2007 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 2007 ID in their tags. To get a binary object, you call the GetBinaryPageContent method and pass it the OneNote 2007 ID you get from the GetPageContent method. You use the GetPageContent method when you do not need the binary data immediately.

UpdatePageContent Method

The UpdatePageContent method updates or modifies the content on the page. 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 UpdatePageContent method has the following signature:

HRESULT UpdatePageContent(
      [in]BSTR bstrPageChangesXmlIn,
      [in,defaultvalue(0)]DATE dateExpectedLastModified);

The UpdatePageContent method takes the following parameters:

  • bstrPageChangesXmlIn   A string containing OneNote 2007 XML code that includes the changes you want to make to the page.

  • dateExpectedLastModified   (Optional.) The date and time that you think the page you want to update was last modified. If you pass a non-zero value for this parameter, OneNote 2007 proceeds with the update only if the value you pass matches the actual date and time the page was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits users made since the last time the page was modified.

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 replaces entirely 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 sample 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.ApplicationClass onApplication = new OneNote.ApplicationClass();
            String strImportXML;

            strImportXML = "<?xml version=\"1.0\"?>" +
               "   <one:Page xmlns:one=\"https://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 page content
            onApplication.UpdatePageContent(strImportXML, System.DateTime.MinValue);
         }

GetBinaryPageContent Method

The GetBinaryPageContent method returns a binary object, such as ink or images, on a OneNote 2007 page as a base 64&#150;encoded string.

The GetBinaryPageContent method has the following signature:

HRESULT GetBinaryPageContent(
      [in]BSTR bstrPageID,
      [in]BSTR bstrCallbackID,
      [out]BSTR * pbstrBinaryObjectB64Out);

The GetBinaryPageContent method takes the following parameters:

  • bstrPageID   The OneNote 2007 ID for the page that contains the binary object to get.

  • bstrCallBackID   The OneNote 2007 ID of the binary object you want to get. This ID, known as a callbackID, is in the OneNote 2007 XML code for a page returned by the GetPageContent method.

  • pbstrBinaryObectB64Out   (Output parameter.) A pointer to a string into which OneNote 2007 writes the binary object as a base 64&#150;encoded string.

DeletePageContent Method

The DeletePageContent method deletes an object, such as an Outline object, an Ink object, or an Image object, from a page.

The DeletePageContent method has the following signature:

HRESULT DeletePageContent(
      [in]BSTR bstrPageID,
      [in]BSTR bstrObjectID,
      [in,defaultvalue(0)]DATE dateExpectedLastModified);

The DeletePageContent method takes the following parameters:

  • bstrPageID   The OneNote 2007 ID of the page that contains the object to delete.

  • bstrObjectID   The OneNote 2007 ID of the object you want to delete.

  • dateExpectedLastModified   (Optional.) The date and time that you think the page that contains content you want to delete was last modified. If you pass a non-zero value for this parameter, OneNote 2007 proceeds with the deletion only if the value you pass matches the actual date and time the page was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits made by users since the last time the page was modified.

Publish Method

The Publish method exports the page you specify to a file in any format that OneNote supports. Currently, the following file formats are supported:

  • MHTML files (.mht)

  • Adobe Acrobat PDF files (.pdf)

  • XML Paper Specification (XPS) files (.xps)

  • OneNote files (.one)

  • OneNote Archive files (.onea)

  • Microsoft Office Word documents (.doc or .docx)

  • Microsoft Windows Enhanced Metafiles (.emf)

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

The Publish method has the following signature:

HRESULT Publish(
      [in]BSTR bstrHierarchyID,
      [in]BSTR bstrTargetFilePath);

      [in,defaultvalue(pfOneNote)]PublishFormat pfPublishFormat,
      [in,defaultvalue(0)]BSTR bstrCLSIDofExporter);

The Publish method takes the following parameters:

  • bstrHierarchyID   The OneNote 2007 ID of the hierarchy you want to export.

  • bstrTargetFilePath   The absolute path to the location where you want to save the resulting output file. The file you specify must be one that does not already exist at that location.

  • pfPublishFormat   The format in which you want the published page to be (MTHML, PDF, and so on). A value from the PublishFormat enumeration.

  • bstrCLSIDofExporter   The class ID (CLSID) of a registered COM application that can export Microsoft Windows enhanced metafiles (.emf). The COM application must implement the IMsoDocExporter interface. This parameter is included to permit third-party developers to write their own code to publish OneNote content in a custom format. For more information about the IMsoDocExporter interface, see Extending the Office (2007) Fixed-Format Export Feature.

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

The NavigateTo method navigates to the object that you specify. For example, you can navigate to sections, pages, and Outline elements within pages.

The NavigateTo method has the following signature:

HRESULT NavigateTo(
      [in]BSTR bstrObjectID,
      [in,defaultvalue(0)]VARIANT_BOOL fNewWindow);

The NavigateTo method takes the following parameters:

  • bstrObjectID   The OneNote 2007 ID of the object you want to navigate to.

  • fNewWindow   (Optional.) If you pass true for this parameter, a new OneNote 2007 window opens, and the object to which you navigate appears in that new window. Passing true avoids changing the user's current position in the active window.

GetHyperLinkToObject Method

The GetHyperlinkToObject method gets a hyperlink, in OneNote 2007 format, to the notebook, section group, section, page, or page object that you specify. When you click the resulting link, OneNote 2007 opens and displays the specified object.

The GetHyperlinkToObject method has the following signature:

HRESULT GetHyperlinkToObject(
      [in] BSTR bstrHierarchyID,
      [in] BSTR bstrPageContentObjectID,
      [out] BSTR * pbstrHyperlinkOut);

The GetHyperlinkToObject method takes the following parameters:

  • bstrHierarchyID   The OneNote 2007 ID for the notebook, section group, section, or page for which you want a hyperlink.

  • bstrPageContentObjectID    (Optional.) The OneNote 2007 ID for the object within the page for which you want a hyperlink. The object can be, for example, an outline or Outline element. If you pass an empty string (""), the link returned points to the notebook, section group, section, or page that you specified in the bstrHierarchyID parameter. If you pass a non-empty string for the bstrPageContentObjectID parameter, the bstrHierarchyID parameter must be a reference to the page containing the object you specify.

  • pbstrHyperlinkOut   (Output parameter.) A pointer to a string into which the GetHyperlinkToObject method writes the output hyperlink text.

FindPages Method

The FindPages method returns a list of pages that match the query term you specify. Note that FindPages works only if you have Microsoft Windows Desktop Search 3.0 (or a later version) installed on your computer. Microsoft Windows Vista includes this component, but if you are running an earlier version of Windows, you must install Windows Desktop Search in order for FindPages to work.

The FindPages method has the following signature:

HRESULT FindPages(
      [in]BSTR bstrStartNodeID,
      [in]BSTR bstrSearchString,
      [out]BSTR * pbstrHierarchyXmlOut,
      [in,defaultvalue(0)]VARIANT_BOOL fDisplay);

The FindPages method takes the following parameters:

  • bstrStartNodeID   The node (root, notebook, section group, or section) below which to search for content. This parameter sets the scope for the search.

  • bstrSearchString   The search string. Pass exactly the same string that you would type into the search box in the OneNote 2007 UI. You can use Boolean operators, such as AND and OR, which must be in all caps.

  • pbstrHierarchyXmlOut    (Output parameter.) A pointer to a string into which you want OneNote 2007 to write the output XML string. The resulting XML string contains the notebook hierarchy from the root downward to, and including, any pages that match the search string. For example, the FindPages method does not list sections that have no page matches in the hierarchy. Also, if only one page in a single section matches the string, the hierarchy returned includes the path to that section and page, but to no other parts of the notebook hierarchy.

  • fDisplay    (Optional.) Specifies whether to also run the search in the UI for the users, just as if users had typed it themselves. By default, OneNote 2007 sets fDisplay to false and performs the query with no change to the UI.

New Enumerations

OneNote 2007 adds several new enumerations to the OneNote 2007 object model.

Table 1. New enumerations

Enumeration

Member

Value

Description

CreateFileType

 

 

When passed to the OpenHierarchy method, specifies the type of object to create, if any, if the path passed to the method does not yet exist.

 

cftNone

0

Creates no new object.

 

cftNotebook

1

Creates a notebook with the specified name at the specified location.

 

cftFolder

2

Creates a section group with the specified name at the specified location.

 

cftSection

3

Creates a section with the specified name at the specified location.

HierarchyScope

 

 

When passed to the GetHierarchy method, specifies the lowest level in the notebook node hierarchy to get.

 

hsSelf

0

Gets just the start node specified and no descendants.

 

hsChildren

1

Gets the immediate child nodes of the start node, and no descendants in higher or lower subsection groups.

 

hsNotebooks

2

Gets all notebooks below the start node, or root.

 

hsSections

3

Gets all sections below the start node, including sections in section groups and subsection groups.

 

hsPages

4

Gets all pages below the start node, including all pages in section groups and subsection groups.

PageInfo

 

 

When passed to the GetPageContent method, specifies the type of information to return with the page content.

 

piBasic

0

Returns only basic page content, without selection markup and binary data objects. This is the standard value to pass.

 

piBinaryData

1

Returns page content with no selection markup, but with all binary data.

 

piSelection

2

Returns page content with selection markup, but no binary data.

 

piBinaryDataSelection

3

Returns page content with selection markup and all binary data.

 

piAll

3

Returns all page content.

PublishFormat

 

 

When passed to the Publish method, specifies the format in which you want the published page to appear.

 

pfOneNote

0

Published page is in .one format.

 

pfOneNoteArchive

1

Published page is in .onea format.

 

pfMHTML

2

Published page is in .mht format.

 

pfPDF

3

Published page is in .pdf format.

 

pfXPS

4

Published page is in .xps format.

 

pfWord

5

Published page is in .doc or .docx format.

 

pfEMF

6

Published page is in enhanced metafile (.emf) format.

SpecialLocation

 

 

When passed to the GetSpecialLocation method, specifies the special location path to get.

 

slBackupFolder

0

Gets the path to the Backup Folders folder location.

 

slUnfiledNotesSection

1

Gets the path to the Unfiled Notes folder location.

 

slDefaultNotebookFolder

2

Gets the path to the Default Notebook folder location.

NewPageStyle

 

 

When passed to the CreateNewPage method, specifies the style of the new page.

 

npsDefault

0

Create a page that has the default page style.

 

npsBlankPageWithTitle

1

Create a blank page that has a title.

 

npsBlankPageNoTitle

2

Create a blank page that has no title.

Error Codes

OneNote methods return the error codes shown in Table 2.

Table 2. Error codes

HResult

Value

Description

hrMalformedXML

0x80042000

XML is not well-formed.

hrInvalidXML

0x80042001

XML is invalid.

hrCreatingSection

0x80042002

Error creating a section.

hrOpeningSection

0x80042003

Error opening a section.

hrSectionDoesNotExist

0x80042004

Section does not exist.

hrPageDoesNotExist

0x80042005

Page does not exist.

hrFileDoesNotExist

0x80042006

File does not exist.

hrInsertingImage

0x80042007

Error inserting an image.

hrInsertingInk

0x80042008

Error inserting ink.

hrInsertingHtml

0x80042009

Error inserting HTML.

hrNavigatingToPage

0x8004200a

Error navigating to page.

hrSectionReadOnly

0x8004200b

Section is read-only.

hrPageReadOnly

0x8004200c

Page is read-only.

hrInsertingOutlineText

0x8004200d

Error inserting outline text.

hrPageObjectDoesNotExist

0x8004200e

Page object does not exist.

hrBinaryObjectDoesNotExist

0x8004200f

Binary object does not exist.

hrLastModifiedDateDidNotMatch

0x80042010

Last modified date does not match.

hrGroupDoesNotExist

0x80042011

Section group does not exist.

hrPageDoesNotExistInGroup

0x80042012

Page does not exist in section group.

hrNoActiveSelection

0x80042013

No active selection.

hrObjectDoesNotExist

0x80042014

Object does not exist.

hrNotebookDoesNotExist

0x80042015

Notebook does not exist.

hrInsertingFile

0x80042016

Error inserting file.

hrInvalidName

0x80042017

Name is invalid.

hrFolderDoesNotExist

0x80042018

Folder (section group) does not exist.

hrInvalidQuery

0x80042019

Invalid query.

hrFileAlreadyExists

0x8004201a

File already exists.

hrSectionEncryptedAndLocked

0x8004201b

Section is encrypted and locked.

hrDisabledByPolicy

0x8004201c

Action disabled by a policy.

hrNotYetSynchronized

0x8004201d

OneNote has not yet synchronized content.

Conclusion

This article, which is part one of a two-part series, describes the new COM object model for OneNote 2007. It explains how you can use the new model to modify the OneNote 2007 notebook hierarchy and import and export content in the form of XML code. To learn the basics of the OneNote 2007 XML Schema, see What's New for Developers in OneNote 2007 (Part 2 of 2).

Additional Resources

For more information, see the following resources: