
	Home \| Products \| Support \| SiteMap

Read Me NCH Unified API

This is the "readme.html" documentation supplied in the nchapi.zip archive. It is designed to be a supplement source of information additional to that available from our website: www.nchsoftware.com/api.

Included Files

There should have been several files included along with this documentation. The purpose of these files follows:

nchapi.dll - This is the Dynamic Linked Library (DLL), Component Object Model (COM), and Java Native Interface (JNI) version of the Unified API. To use the DLL you must first locate and load this file within your program and then retrieve the address of the "NCHAPISendCommand" exported function. For COM you must first register this file within your system before you are able to utilize it. For JNI please refer to the specific Java Documentation below. See the source code of the C++, VB&VBS, and Java examples for more information on how to utilize the functionality of this file.
nchapi.exe - This is the Command Line Interface (CLI) version. Simply call this application from your system's command line prompt/shell/window, or from any shortcut or task scheduler/management window. The output of this call will be the return value and result string separated by a colon (':'). See the source code of the CLI example for more information on how to utilize the functionality of this file.
NCHAPIClientLib.dll - This is the Microsoft .NET Framework version. Please be aware that this file is only a wrapper for nchapi.dll, and that to use this functionality you must first add NCHAPIClientLib.dll (.NET) as reference to your project and then put nchapi.dll (native) in your program's directory or in any directory from %PATH%. Both files must be present when distributing your program. See the source code of the C# and the VB.NET examples for more information on how to utilize the functionality of this file.
server.exe - This is a simple test server application which allows you to trial your (and the provided sample) code with the different communication methods available though the Unified API. The test server is identified by the API Key "APITestServer" and responds to the following two commands:
- -showmessagebox - Displays a message box and takes two arguments: the message box text, and the message box caption.
- -testapi - A generic command which takes one argument.

Note: All NCH software products respond to the common "-testapi" command, which if called correctly returns "API Test OK" followed by its first argument. If no argument is specified then it will return "API Test Fail". This allows you to configure and test your API system before worrying about the syntax for specific commands and arguments.

Included Directories

There should be several directories also included which contain all the Visual Studio, header and source files (where appropriate) required for the provided working examples. The directories/examples included are:

C# - Which uses NCHAPIClientLib.dll and nchapi.dll (Microsoft .NET Framework).
C++ - Which uses nchapi.dll (Dynamic Linked Library).
CLI - Which uses nchapi.exe (Command Line Interface).
Java - Which uses nchapi.dll (Java Native Interface).
VB&VBS - Which uses nchapi.dll (Component Object Model & ActiveX).
VB.NET - Which uses NCHAPIClientLib.dll and nchapi.dll (Microsoft .NET Framework).

These examples will not function correctly until the appropriate Unified API file (dependent on which API method) has been copied to the correct folder or correctly registered.

API Specification

All commands and arguments are passed to the Unified API as an array of strings, with the number of these also sent. Commands are all preceded by a dash ('-') and are in lowercase with no spaces. Arguments can contain any characters necessary. Please note that both commands and arguments are case sensitive! Once the command has been executed by the program the API will respond by returning a number and a result string. The number is the return value of the command just sent and follows this guideline:

0 = Success,
-1 = Error: No/Unknown Command Received,
-2 = Error: Program Not Running.

The result string contains any information the program wishes to return, and has a maximum length of 8192 characters.

Java Documentation

There are several methods for how to use the NCH Unified API's capability in your Java code. The options are:

Use the provided NCHAPIClient class as the interface through which the NCH Unified API is called.
Write your own class to interact with the Unified API.

Important note regarding class and package naming

As a result of the style in which Java code can interface with native DLL code, the package name and class name of the class that calls the DLL code is hard-coded into the DLL. Thus, the only class that can call the JNI method in nchapi.dll is "nch.api.NCHAPIClient". If you choose to go down the route specified in #2 above, be aware that you must name your own class this.

1) Using the provided NCHAPIClient class

The provided class is designed to make interaction with the Unified API DLL as painless as possible. You will need to compile the class on your own and include it in your JARs. There are two constructors provided in the class. You should use one or the other, depending on where you want to place the nchapi.dll.

1.1) NCHAPIClient() Constructor

This constructor will look for the nchapi.dll in a series of directories. If you have not defined a java.library.path environment variable on the command-line to java.exe (e.g., "-Djava.library.path=c:\dlls\"), then it will look through the directories in the computer's %PATH%. Java will use the first copy of nchapi.dll it finds.

1.1.1) Relying on %PATH%

If you allow Java to search through the %PATH% to find the nchapi.dll, it is recommended that you place the dll in c:\[Windows Directory]\System32, as this directory is included in the %PATH% environment variable by default.

1.1.2) Relying on java.library.path

If you specify a directory in which nchapi.dll is placed and use the -Djava.library.path= statement, you can put the nchapi.dll in any directory on the system, even one which is not included in the %PATH% environment variable, and change the location easily at program start-up time.

1.2) NCHAPIClient(String pathToDLL) Constructor

Like in 1.1.2, this constructor will allow you to place the dll in any location on the computer. Pass into this constructor the directory where your software can find nchapi.dll. Use this constructor if you want to place the dll in a directory that is not in the %PATH% but you do not want to specify it on the command-line. For instance, you might use this constructor if you want to save the DLL location in a configuration file and read it at runtime.

1.3) Calling the Unified API

Calling the API is done via the sendCommand() method. You should consult the documentation for the NCH software application you wish to communicate with for the exact parameters you need to use. The first argument to sendCommand() is the name of the application you wish to call. The second argument is a String array, each element of which is a parameter to the API call. This method will return an integer value that can be used to determine the success or failure of the API call. See the NCHAPI_* constants in the class -- these are the possible return values. In a nutshell, the constant values mean:

NCHAPI_SUCCESS -- the API call worked.
NCHAPI_ERROR -- the API call failed.
NCHAPI_CODE_NOTFOUND -- the program to which the API call was to be sent was not running.

1.4) The Verbose Result String

In addition to the integer result returned by sendCommand(), the API returns a more verbose string that can be used for enhanced debugging. The exact format of this code depends on the API call that you made. This result string is basically a human-readable result that tells exactly what happened (for example, a call may get an integer result of NCHAPI_ERROR and a result string of "Recording could not be started because the software is currently playing another MP3."). This result string can be returned from the NCHAPIClient class after sendCommand() is called via a call to getResultString().

2) Writing your own NCHAPIClient Class

Are you REALLY sure you want to write your own version of the class? In 99% of cases, you will be simply reproducing the class we provide you. If you choose to not use the NCHAPIClient class, there are several steps you will need to account for and things to know that are handled by the client class. Please read the following and be sure you understand ALL OF IT COMPLETELY before continuing.

2.1) Package Name and Location

As mentioned above, due to limitations in JNI, you **MUST** name the class that calls the code in nchapi.dll "NCHAPIClient" and it **MUST** be located in a package named "nch.api". There is no way around this.

2.2) Loading the DLL

There are two ways to load a DLL with Java:

System.load(...);
System.loadLibrary(...);

2.2.1) System.load(...);

This load is used when you want to specify the path to the DLL to load. For example:

   System.load("c:\dlls\nchapi.dll");

2.2.2) System.loadLibrary(...);

This load is used when you want the JVM to search %PATH% and java.library.path (see 1.1) for the DLL to load. If you use this style, you must use the following line of code to load the nchapi.dll:

   System.loadLibrary("nchapi");

Note that there is no ".dll" in the above. This is the proper convention.

2.3) Declaring the Native Method

You must also prepare the JVM to know that it needs to call a native method. Do this by declaring the method that you will be connecting to in the .dll. Use this piece of code:

   private static native int NCHAPISendCommand(String szServerKey, int nArgs, String[] szArgs, String[] szResultString);

2.4) Calling the Native Method

To call the native method, you need to pass in more arguments than you do in using our NCHAPIClient class. Here are the arguments to pass in and what they mean:

szServerKey - This is the name of the program that you are calling (the same as argument #1 in NCHAPIClient.sendCommand().
nArgs - This is the number of arguments in the argument array.
szArgs - This is a String array containing the arguments to the DLL code. This is the same as argument #2 in NCHAPIClient.sendCommand().
szResultString - This is how the DLL will return the verbose result String to your calling code. This argument MUST be a *1-element, EMPTY* String array. It will be filled with a value in the DLL.

Other Information

If you have problems writing your application, please see www.nch.com.au/support.


© NCH Software	Top \| Home