1. Overview

The Finder provides an integration technique for external applications allowing to instruct the Finder to show a specific Source.
The technique is based on the custom nxt:// application URL protocol.

2. Launching the Finder with Hyperlinks

During installation of the Finder the nxt:// protocol is registered in Windows. Hyperlinks allow showing a Source based on its Name, last known IP Address, or Id:

• nxt://Show-NxSource?SessionName=SESSION_NAME&Name=SOURCE_NAME

• nxt://Show-NxSource?SessionName=SESSION_NAME&IpAddress=SOURCE_LAST_IP_ADDRESS

• nxt://Show-NxSource?SessionName=SESSION_NAME&Id=SOURCE_ID

SessionName is an optional argument. If the value is not provided the user will be requested to manually connect to a session.

On top of that it is also possible to launch a new instance of the Finder, and optionally connect it to a session:

• nxt://New-NxFinder

• nxt://New-NxFinder?SessionName=SESSION_NAME

2.1. Encoding the Arguments

In case one, or more, of the arguments contains special characters which are not supported by URLs (such as "/", "%", "&", " ", etc.) then it is possible to encode them using Base64 or URL encoding. In this cases one of the additional parameter Encoding=Base64 or Encoding=Url must be added.

2.1.1. Base64 Encoding

When possible it is suggested to use Base64 encoding, as it is more robust. The following example will instruct the Finder to display a Source with id 12 using session Default/Session:

nxt://Show-NxSource?Encoding=Base64&SessionName=RGVmYXVsdC9TZXNzaW9u&Name=MTI=

2.1.2. URL Encoding

URL encoding is a simple alternative to Base64 encoding that ensures support for limited scenarios. URL encoding can be used for instance if one of the arguments might contain a space. Some browsers in fact automatically encode a space in a URL as "%20". The following hyperlink:

<a href="nxt://Show-NxSource?SessionName=Default session&Name=WorkPC1">My link</a>

when invoked from such browsers is translated as:

nxt://Show-NxSource?SessionName=Default%20session&Name=WorkPC1

with the consequence that, if no encoding is specified, the system will look for a session with name Default%20session instead of Default session. The following example shows how to correct such issues using URL encoding:

nxt://Show-NxSource?Encoding=Url&SessionName=Default session&Name=WorkPC1

2.2. Ensuring the Presence of a Finder

The command automatically ensures the presense of a Finder connected to the session specified in the arguments. This is done as follows:

1. Use the first Finder connected to the requested session, if one exists;

2. If the SessionName argument is not provided and there is already a Finder connected to a session, then use that finder;

3. Use the first Finder which is not connected to any sessions, if one exists;
4. Launch a new Finder instance.

2.3. Information Levels

Depending on the Information Level configured in the privileges of the Session being used, some of the variations for showing a Source might not be available:

3. Launching the Finder from the Command Line

Launching the Finder from the Command Line is analogous to using hyperlinks. The only difference is that the hyperlink must be passed as argument to explorer.exe. The following example can be run from Command Line to show a Source with name WorkPC1 on Session Default session:

explorer "nxt://Show-NxSource?SessionName=Default session&Name=WorkPC1"

4. Debugging Issues

In case of malformed commands (wrong arguments, malformed encoded strings, etc.) the nxt:// protocol handler does not display error messages. During development and integration however it is useful to have some feedback in case of errors. A possibility is to attach a trace listener to the protocol handler. Simply create a file named NEXThink.Finder.PowerShell.exe.config with the content below and copy it in the Finder install directory:

<?xml version="1.0"?>
<configuration>
  <system.diagnostics>
    <trace autoflush="true" indentsize="4">
      <listeners>
        <add name="FileListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="DESTINATION_FILE" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

where DESTINATION_FILE is the full path and name of the log file where trace information will be saved (for instance c:\log\Finder_Launcher.log)