Unified NCH Software API

Complete API Solution for NCH Software Products

Our software is able to be controlled by other programs using a variety of methods written in many different languages. The NCH Unified Application Program Interface (API) introduces a simple way of addressing the need within your system to control our programs. The API allows the exchange of requests and data to be made between programs through various means.



Different methods (with "code snippet" examples) for using the Unified API include:

This document is only designed to provide a brief overview of the possibilities and techniques for using the Unified API, for additional information please see "readme.html" included in the nchapi.zip archive. This zip also contains the actual Unified API files, along with all the header and source files for working examples in C++, C#, Java, CLI, VB & VBS, and VB.NET. These examples will work with the included API Test Server to assist you in configuring your system. To download the NCH Unified API along with these examples click here...

In the below examples the "NCHAPIKey" refers to a unique API Key code that identifies which of our software products you are attempting to control and communicate with. All commands and arguments are sent through the Unified API as strings, which then respond with a number (integer return value) and a result string. For more information regarding API Key codes along with the available commands and arguments for that particular program please visit the homepage of the product and refer to the application's specific API documentation. To find the full list of our software products click here...

  Back to top


Dynamic Linked Library (DLL)

The DLL is a self-contained file which provides the generic interface required for linking newly created or preexisting applications together on the code level. When distributing your program you need to ensure that you include and correctly address the path to the DLL. The following is a C++ example (and can easily be implemented in C) which loads the DLL and sends a command, which returns a result to a message box:

#define API_SERVER_KEY "NCHAPIKey"

const unsigned int nArgs = 3;
LPCTSTR szArgs[] = {_T("-testapi"), _T("More Info"), _T("etc...")};

typedef DWORD (WINAPI *pFn) (LPCTSTR szProgramKey, UINT nArgs, LPCTSTR  const * szArgs, LPTSTR szResultString);

void SendCommandDLL()
{
  HMODULE hModDll = LoadLibrary(_T("nchapi.dll"));
  pFn pfSendCommand = (pFn)GetProcAddress(hModDll, "NCHAPISendCommand");

  TCHAR szResultString[8096]; 
  if ((pfSendCommand)(_T(API_SERVER_KEY), nArgs, szArgs, szResultString) == 0) {
    MessageBox(NULL, szResultString, _T("Result"), MB_OK);
  }
  FreeLibrary(hModDll);
}

  Back to top


Component Object Model (COM) / ActiveX

COM enables language-neutral interprocess communication allowing other programs to easily reference and pass on information and requests through a well defined interface, no matter what machine environment employed. ActiveX is a version of Object Linking and Embedding (OLE) which is a subsidiary of COM and uses the same techniques for implementation. When using either method you will need to include and register the nchapi.dll file with your distribution.

On a Windows machine to register the nchapi.dll file you would type into the run window (Start -> Run) something along the lines of:

regsvr32 "nchapi.dll"

The following is a VB & VBS example which uses the COM to send a command, which returns a result to a popup:

Dim shell, client, result
set shell = CreateObject("WScript.Shell")
set client = CreateObject("NCHAPI.Client")

Dim ServerKey
ServerKey = "NCHAPIKey"
Dim nArgs
nArgs = 3
Dim szArgs
szArgs = Array("-testapi", "More Info", "etc...")
Dim szResultString

if client.SendCommand(ServerKey, CInt(nArgs), szArgs, szResultString) = 0 then
  result = shell.Popup(szResultString, 0, "Result")
end if

  Back to top


Command Line Interface (CLI)

The command line has always been an easy way to control applications without the prior knowledge of specific programming languages. You are able to use this simple method of communication through various means such as the Windows Command Prompt or the Windows Task Scheduler. Two way communication is possible as the Unified API is able to return values and information obtained. All commands are executed left to right, which means each command will be run as it is read by the program.

The general syntax is:

nchapi.exe NCHAPIKey -testapi "More Info" "etc..."

  Back to top


Java Native Interface (JNI)

The JNI is a framework which allows the traditionally platform independent Java code to use native (platform dependent) applications written for a specific operating system. When implementing your program you need to ensure that you include the nchapi.dll file. The following are Java examples which use JNI to send a command, and returns a result to a message dialog:

This first example simply uses the provided NCHAPIClient class as the interface through which the NCH Unified API is called:

import nch.api.NCHAPIClient;

public void sendCommandJNI() {
  String serverKey = "NCHAPIKey";
  String[] szArgs = { "-testapi", "More Info", "etc..." };
  NCHAPIClient client = new NCHAPIClient();
  if (client.sendCommand(serverKey, szArgs) == client.NCHAPI_SUCCESS) {
     JOptionPane.showMessageDialog(null, client.getResultString(), "Result", JOptionPane.INFORMATION_MESSAGE);
  }
}
Or you could write your own version of the class, but in most cases this would simply be reproducing the class already provided. Note that due to requirements of how Java interfaces with native code, any class you write must be named nch.api.NCHAPIClient:

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

public class NCHAPIClient {

public NCHAPIClient() {
  System.loadLibrary("nchapi");

  private String serverKey = "NCHAPIKey;
  private int nArgs = 3;
  private String[] szArgs = { "-testapi", "More Info", "etc..." };
  private String[] szReturnString = null;
  
  if (NCHAPISendCommand(serverKey, nArgs, szArgs, szReturnString) == 0) {
    JOptionPane.showMessageDialog(null, szReturnString, "Result", JOptionPane.INFORMATION_MESSAGE);
  }
}
}

  Back to top


Microsoft .NET Framework

This is the latest initiative from Microsoft and provides another language independent framework designed to reduce the complexity of communication and development. .NET natively provides solutions to many common program requirements without the need to deal with specific architectures through the use of the Common Language Infrastructure (CLI). A wrapper is used so that .NET applications can access the Unified API functionality.

The following is a C# example using .NET which returns a result to a message box:

public partial class FormMainDialog : Form
{
  NCHApi.Client apiCOMClient;
  public FormMainDialog()
  {
    InitializeComponent();
    apiCOMClient = new NCHApi.Client();
  }
  private void buttonSendCommand_Click(object sender, EventArgs e)
  {
    string ServerKey = "NCHAPIKey";
    int nArgs = 3;
    string[] szArgs = {"-testapi", "More Info", "etc..."};
    string szResultString = "";

    if (NCHApi.NCHAPIResult.Success == apiCOMClient.SendCommand(ServerKey, nArgs, szArgs, ref szResultString))
    {
      MessageBox.Show(szResultString, "Result", MessageBoxButtons.OK, MessageBoxIcon.Information);
    }
  }
}
The following is a VB.NET example using .NET which returns a result to a message box:

Public Class MainForm
  Private Sub buttonSendCommand_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles buttonSendCommand.Click
    Dim comClient As New NCHApi.Client()

    Dim ServerKey As String = "NCHAPIKey"
    Dim nArgs As Integer = 3
    Dim szArgs As String() = New String() {"-testapi", "More Info", "etc..."}
    Dim szResultString As String = ""

    Dim res As NCHApi.NCHAPIResult
      res = comClient.SendCommand(ServerKey, nArgs, szArgs, szResultString)
    If (res = NCHApi.NCHAPIResult.Success) Then
      MsgBox(szResultString, MsgBoxStyle.OkOnly & MsgBoxStyle.Information, "Result")
    End If
  End Sub
End Class

  Back to top


Unlimited Possibilities

Using the Unified NCH Software API allows a vast range of control, with literally thousands of new flexible configuration systems possible.

Imagine you are away from home and you forgot to record your favorite radio stream, or set VRS to start recording phone calls? Simply dial into your IVM system and use the prompts to send commands through the Unified API to the respective programs telling them to start recording.

What if you want to setup an extension in Axon for a specific time? Simply using the Windows Scheduler and the Unified API to send a command to Axon informing it to setup the appropriate extension. Need to automatically dial a number but you're away from home? Again use the Windows Scheduler and the Unified API to instruct IVM or Express Talk to make the call for you.

  Back to top


Other Information

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

  Back to top