Unified NCH Software APIComplete API Solution for NCH Software ProductsOur 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.
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... 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); } Component Object Model (COM) / ActiveXCOM 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 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..." 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); } } } Microsoft .NET FrameworkThis 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 Unlimited PossibilitiesUsing 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. Other InformationIf you have problems writing your application, please see www.nch.com.au/support. |