Customizing OneNote 2003 SP 1 Using New Command Line Switches


Andrew May
Microsoft Corporation

June 2004

Applies to:
    Microsoft® Office OneNote™ 2003 SP1

Summary: Microsoft Office OneNote 2003 Service Pack 1 (SP 1) features several new command line switches, including switches that you can use to record video notes, import content, and collaborate with other users. (7 printed pages)


Running OneNote with Command Line Switches
Using Switches to Create Audio and Video Notes
Using Switches to Collaborate
Using the Import Switch to Place Content in OneNote
Using Other Command Line Switches


For Service Pack 1 (SP 1), Microsoft® Office OneNote™ 2003 adds six new command line switches that enable you to customize performance. The first three switches allow you to automatically start, pause, and stop recording a video note. Two others deal with collaborating with other users in a shared work session. The final switch duplicates the content-importing functionality of the new CSimpleImporter interface in OneNote.

You can employ these command line switches in scripts, application programming, or even include them in desktop shortcuts.

Note   These extensibility features are only available when you upgrade to OneNote 2003 Service Pack 1 (SP1).

Running OneNote with Command Line Switches

You can modify how OneNote starts by adding switches when you launch OneNote from the command line. Several of these switches were made available in the initial release of OneNote 2003. For example, you can open OneNote to a specific page, print a specific page, start audio recording, or open a side note. The new switches in OneNote 2003 SP1 extend this functionality.

To use a command line switch to customize the way that OneNote starts, pass a string to the command line that is composed of both the fully qualified path to the OneNote application and the switch you want to use, plus strings for any parameters it requires.

These switches work if OneNote is running or not. If you execute a command line switch and OneNote is already running, the switch action executes on the currently running instance of OneNote.

The path of the OneNote executable program is found in the following registry key:


Using Switches to Create Audio and Video Notes

You can use four of the new switches to create OneNote video notes automatically.

  • /videonote. Starts OneNote recording on the active page, allows you to choose the audio and video devices to use, and allows you to specify a custom profile.
  • /pauserecording. Pauses video or audio recording in the current instance of OneNote. You can resume recording by passing this command line switch again.
  • /stoprecording. Stops recording the video or audio note in the current instance of OneNote.
  • /recordingprofile. Allows you to use an external recording profile instead of built-in profiles from OneNote.

Note that the pauserecording and stoprecording switches also work with audio notes. You can use audionote, a command line switch present in OneNote, to automatically start recording audio on the active page.

Specifying Audio and Video Devices

The videonote switch consists of the switch name and three optional string parameters:

/videonote videodevice audiodevice recordingprofilepath

To find the device that you specified, OneNote compares each string argument to the strings that it gets from the system that enumerates the installed devices. You do not need to pass the entire string for a device; instead, the string should be any unique subsection of that string so OneNote can correctly determine the intended device. OneNote uses the first device it encounters that has a matching string. If the string is not unique to a single device, OneNote may select the wrong device. Note that the class ID by itself is not sufficient to distinguish between devices.

For example, suppose that you have the following two video capture devices installed on your system:


The class ID in each case is identical. However, each string contains information that is unique. So you could pass the following switches to designate the first and second video devices, respectively:

OneNote.exe /videonote vid_046d&pid_08b2
OneNote.exe /videonote vid_046d&pid_08f0

Similarly, suppose you have the following three audio capture devices installed:

@device:cm:{33D9A762-90C8-11D0-BD43-00A0C911CE86}\Intel(r) Integrated Audio
@device:cm:{33D9A762-90C8-11D0-BD43-00A0C911CE86}\USB Audio Device

Again, the class ID is the same in each case, but each string contains unique information to distinguish which device you want to specify.

Therefore, to start OneNote recording a video note using the first video and audio device in each list, you would pass the following command line switch:

OneNote.exe /videonote vid_046d&pid_08b2 "Intel(r) Integrated Audio"

Also be aware that because a space serves as the delimiter between parameters, you cannot pass an argument string that contains a space, unless you enclose the string in quotes. If you pass an argument string that contains a space without enclosing it, OneNote assumes the space signifies the end of that string, and the switch fails.

If you do not specify a video or audio device, OneNote uses the default device, if one is available.

Specifying a recording profile

There are two of the command line switches that you use to specify a custom recording profile:

  • The recordingprofile switch.
  • The optional recordingprofilepath parameter of the videonote switch.

The recordingprofile switch has the following signature:

/recordingprofile filepath

Filepath is a required parameter that takes a string representing the fully-qualified path to a recording profile file.

You can specify a custom recording profile when you use the videonote switch. That switch's optional recordingprofilepath parameter also takes a string representing the fully-qualified path to a recording profile file.

A recording profile is a text file contains configuration information about video and audio recording, such as bit rate, sampling, and decoding. You can generate recording profiles using WMGenProfile, which is included as a sample application in the Windows Media Format 9 Series SDK. For more information on recording profiles, see the SDK.

Using Switches to Collaborate

The next two command line switches we discuss involve the important collaboration functionality added to OneNote 2003 SP1. With these switches, you can share a notebook page with one or more users and each user can dynamically add, edit, and delete content in real time to the page, and each user can retain a copy of the notebook page at the end of the session.

One user starts the session by setting up a shared session. The user selects the notebook page they want to share, then specifies a password for the session if desired. He can then invite other users to join the session. Users who want to join the session must specify the address (either IP or network domain) of the computer on which the session started, and the password if one is set. The user who started the session also determines whether other users have the ability to edit the shared notebook page.

The command line switches, startsharing and joinsharing, enable you to initiate or join a shared session programmatically.

The startsharing switch has the following syntax:

/startsharing password filename

As its name implies, this switch initiates a shared session from the computer on which it's executed. The filename string parameter refers to the notebook section to share. The filename string must be a fully-qualified path to the section, including section name and file extension (.one). The page that is shared is the page most recently selected in that section.

The password parameter is optional. If you specify a password, in order to join the session, all other users are required to specify that password . The password can contain any characters; however, strings that contain spaces must be enclosed in quotes. You will need to communicate the computer address and session password to participants in order for them to join the session.

Once the shared session is started, other users can join and collaborate. The joinsharing switch has the following signature:

/joinsharing sessionaddress password filename

Executing this command line switch adds the computer to the shared session. To join a session, you must know the address of the computer that started the session, and the password, if one is specified. The sessionaddress parameter takes a string that represents the address of the computer that started the session; this address may be the computer's IP address, or full network domain name. The password and filename parameters represent the password for the session, if one is set, and the section of the notebook that is being shared, respectively. You need to receive this information from the session initiator to join the session. The filename parameter is optional; if you omit it, OneNote opens to the last section opened. You can only share one notebook section at a time.

To start or join a session using the user interface

  1. On the Tools menu, point to SharedSession.
  2. Click Start Shared Session or Join Shared Session.

The following function programmatically initiates a shared session in OneNote. The calling application passes string representing the location of the OneNote application and the notebook section to share. The example function generates a random numeric string to use as a password, and then starts a new process that initiates a shared session in OneNote. The function then returns the password to the calling application. Note that the auto-generated password offers no extra security, and is only done for convenience.

Public Function ShareOneNote(ByVal appLocation As String, _
    ByVal section As String) As String
    Dim NoteSwitch As String
    Dim OneNoteProcess As Process
    Dim Ran As New Random
    Dim Password As String

    'Generate a random numeric password
    'NOT for security, just for convenience
    Password = Ran.Next(100000001).ToString
    'Compose command line switch
    NoteSwitch = " /startsharing " & Password & " " & section
    'Pass command line to OneNote application
    OneNoteProcess = Process.Start(fileName:=appLocation, _
    'Return generated session password to calling application
    Return Password

End Function

Using the Import Switch to Place Content in OneNote

You can also use a command line switch to import images, ink, and HTML automatically into OneNote. You can even create the folders, sections, or pages to place your content on.

The import switch consists of the switch name and a single required parameter:

/import filename

The filename parameter takes an XML file that specifies:

  • The folders, sections, and pages on which you want to place content. If a folder, section, or page does not exist, OneNote creates them.
  • Details of the images, ink, and outlines (in HTML form) that you want to place on each specified page.

The file must adhere to the requirements of the OneNote 1.1 SimpleImport XML Schema.

This switch duplicates some of the functionality of OneNote's CSimpleImporter interface. For more information about this interface, including a discussion of the OneNote SimpleImport schema, see Importing Content into OneNote 2003 SP1 Preview.

Using Other Command Line Switches

Below is a list of the command line switches previously available in OneNote 2003. All parameters take strings as arguments.

Switches Description
/ filename Opens a file, where filename is a fully qualified file name, including the disk, folder path, and .one file extension.
/new filename Creates a section, called New Section 1, in the default folder (such as My Notebook), although filename is a required parameter that includes the disk and folder path and any unique file name with the .one file extension.
Note   If a section called New Section 1 already exists in the folder, the number in the section name is increased incrementally, such as New Section 2.
/newfromexisting folderfilename Copies the file that is specified by filename to the folder that is specified by folder and opens the file.
/openro filename Opens a file as read-only, where filename is a fully qualified file name, including the disk and folder path and .one file extension.
/print filename Prints a file, where filename is a fully qualified file name, including the disk and folder path and .one file extension.
/forcerepair filename Runs the file repair feature for a file, where filename is a fully qualified file name, including the disk and folder path. This is the same file repair feature that OneNote automatically runs if it detects file corruption while opening a file.
/sidenote Starts OneNote in a miniature window, open to the Side Notes section by default.
/audionote Starts recording on the active page.
/newtaskpane Opens the New task pane.
/paste Pastes the contents of the Clipboard.


Command line switches offer an easy-to-implement approach to customizing OneNote—not just from the command line—but through scripts, code, or even desktop shortcuts.