Customizing OneNote 2003 SP1 Using New Command Line Switches

Article
05/04/2004

The last aspect of the OneNote SP1 developer story that we should talk about is the half-dozen or so command line switches that OneNote SP1 has added. Once again, here's a draft version of an article that we'll publish on MSDN once OneNote 2003 SP1 is available. The information has been reviewed by the OneNote team, but this is still draft documentation, and should be considered as such.

Here you go:

Applies To:

Microsoft Office OneNote 2003 SP1 Preview

Summary: OneNote 2003 SP1 Preview features several new command line switches, including switches you can use to record video notes, import content, and collaborate with others.

Introduction

For SP1 Preview, OneNote 2003 has added six new command line switches that enable you to customize OneNote’s performance. The first three new switches let you automatically start, pause, and stop recording a video note. Two others deal with collaborating with others in a shared work space. The final switch duplicates the content importing functionality of OneNote’s new CSimpleImporter interface.

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 the OneNote 2003 Service Pack 1 (SP1) Preview.

Running OneNote with Command Line Switches

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

To use a command line switch to customize how OneNote starts, pass the command line a string composed of:

· 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 whether or not OneNote is already open. 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 exe can be found in the registry key: HKEY_CLASSES_ROOT\CLSID\{22148139-F1FC-4EB0-B237-DFCD8A38EFFC\LocalServer32

Using Switches to Create Audio and Video Notes

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

· /videonote, which starts OneNote recording on the active page, and lets you choose the audio and video devices to use, as well as specify a custom profile.

· /pauserecording, which pauses video or audio recording in the current instance of OneNote. You can resume recording by passing this command line switch again.

· /stoprecording, which stops recording the video or audio note in the current instance of OneNote.

· /recordingprofile, which lets you 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 2003, 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 you’ve specified, OneNote takes each string argument and compares it to the strings it gets from the system enumerating the devices installed. 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 whose string matches. 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 you had the following two video capture devices installed on your system:

@device:pnp:\\?\usb#vid_046d&pid_08b2&mi_00#6&708a54b&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\global

@device:pnp:\\?\usb#vid_046d&pid_08f0&mi_00#6&313056d4&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\global

The class ID in each case is identical. However, each string does contain 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 had 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
@device:cm:{33D9A762-90C8-11D0-BD43-00A0C911CE86}\Camera

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

So, 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

Two of the command line switches enable you to specify a custom recording profile. You can either:

· Use the recordingprofile switch.

· Use 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.

Alternately, 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 concerning 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 Media Windows Media Format 9 Software Developer’s Kit (SDK). For more information on recording profiles, see the SDK.

Using Switches to Collaborate

The next two command line switches we’ll discuss involve the important collaboration functionality added to OneNote 2003 SP1. Now, you can share a notebook page with one or more users, with each user able to dynamically add, edit, and delete content in real time to the page, and each user retaining 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 was started, and the password if one has been 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 programmatically initiate or join a shared session, respectively.

The startsharing switch has the following signature:

/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 (that is, .one). The page shared is the page most recently selected in that section.

The password parameter is optional. If you specify a password, all other users are required to specify that password in order to join the session. 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 has been 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. In order to join a session, you must know the address of the computer that started the session, and the password, if one has been 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 has been set, and the section of the notebook that is being shared, respectively. You will need to receive this information from the session initiator in order 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, from the Tools menu select Shared Session, and then 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, 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, _

arguments:=NoteSwitch)

'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 automatically import images, ink, and HTML into OneNote. You can even create the folders, sections, or pages onto which you want to place your content.

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.

/ 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 new 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 folder filename

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.

Conclusion

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