C Function Reference

C Function Reference

NI VMS provides a C application programming interface (C API) comprised of two sets of high-level functions: one set for main functions used for off-line operations; and one set for all hardware-related operations. This API allows users to integrate NI VMS functionality into their own C applications.

The hardware API will only operate in conjunction with an on-line license.

Main API

The main part of the API is available for demonstration and off-line purposes. It has no hardware requirements, and can therefore be used on systems without hardware available. The main C API Lib and header files are located in the C directory for NI VMS. All functions are stored in the nivms.dll file. Refer to the NI Video Measurement Suite Readme for the locations of nivms.dll and the C directory for NI VMS. The following high-level C functions are available in the main API:

• Active Picture
• Analyse CAV
• Analyse CVBS
• Analyse S-Video
• Analyse Camera
• Analyse VBI
• Analyse Digital
• Software Filter
• Binary File I/O
• Configure
• Initialise
• Locations Editor
• Video Buffer
• View Line
• Version
• Vectorscope
• Get Waveform

Hardware API

The hardware part of the API has support for all hardware devices required for video acquisition. Refer to the NI Video Measurement Suite Readme for required NI driver software that you must install separately.

The following high-level C functions are available in the hardware API:

• Acquire
• Close
• Configure Devices
• Configure DevicesEx
• Handles
• Hardware Configurator
• Initialise
• Select Channels

Installation

The NI VMS C API is installed as part of the standard NI VMS installation and no special handling is needed during installation. However, in order to develop using the API the following packages must be present on the development system:

• Visual C++ 6 or later
• LabVIEW 2009 or later development system

Header files needed

When compiling code that uses the API the API header file must be included:

#include <VideoMASTER.h>

This header file normally resides in

<ProgramFilesFolder>\National Instruments\NI VMS\API\C

This file in turn needs the “extcode.h” file containing definitions of LabVIEW exported entities. This header file resides in

<ProgramFilesFolder>\National Instruments\<LabVIEW>\CINTOOLS

Where <LabVIEW> is an alias for the installed version(s) of LabVIEW.

When using Visual C++ these header locations may be set from the Project»Settings dialog as shown below:

Linking the API into code

When linking code that uses the API the API VideoMASTER.LIB file must be linked into the application.

This LIB file normally resides in

<ProgramFilesFolder>\National Instruments\NI VMS\API\C

In some cases it may be needed to LabVIEW’s C memory allocation functions to set-up data for an API function. These functions are located in the labviewv.lib file, located in

<ProgramFilesFolder>\National Instruments\<LabVIEW>\CINTOOLS

When using Visual C++ these header locations may be set from the Project»Settings dialog as shown below:

Running the generated code

The generated code needs access to the nivms.dll library and some support libraries at run time.

These libraries normally reside in

<ProgramFilesFolder>\National Instruments\NI VMS\Bin

It is therefore necessary that the above directory is made part of the systems DLL search path. If this is not feasible, the nivms.dll and support ’s must be placed in the same directory as the application executable in order for the DLL’s to be found.

API examples

The source codes for some API examples are installed along with the API. The examples are normally located in subdirectories of the following directory:

<ProgramFilesFolder>\National Instruments\NI VMS\API\C\Examples

In each subdirectory a file with extension .dsw exists, containing Visual C++ build instructions for the example. Provided that the API has been installed in the default locations, the .dsw file can be loaded into Visual Studio to automate the example build.

The resulting example is an .exe file can be run from within Visual Studio, or from a command line prompt. The example uses the DLL’s described in the previous section. The DLL search path for the example must therefore be set up as described in that section in order to run the example.

Backward compatibility

Version 1.3.3 of the API introduces extra parameters for some of the existing functions. These parameters are added as optional parameters at the end of the parameter list to ensure backward compatibility. Programs using previous versions of the API should compile “as is”, and should continue to work as expected.

One exception is the Component multiburst measurement. Previous versions of the API used a fixed flag amplitude of 600 mV for Component measurements. This version of the API supports a measured and scaled flag, and a user defined flag level. The default flag is a measured and scaled flag with offset 1. For Component signals a user defined flag amplitude of 600 mV should be employed instead to preserve backward compatibility.

Version 1.4.0 of the API introduces an extra parameter measureBlackCB within the additionalConfiguration structures for CVBS and S-Video analysis, specifying whether the black bar should be measured or not in a color bar measurement. Furthermore, some API functions have extra parameters. These parameters are added as optional parameters at the end of the parameter list to ensure backward compatibility. Programs using previous versions of the API should compile “as is”, and should continue to work as expected, with the exception of the CVBS and S-Video color bar tests, where the user need to define whether the black color bar should be measured or not.

Version 2 of the API introduced new functions for filtering and digital signals. In addition, a number of existing functions have been enhanced with respect to the number of parameters accepted. Furthermore, existing parameters have been expanded to contain more subtypes. The API is still compatible at the source code level, due to the definitions provided by the videomaster.h file.

Parameter conventions

NI VMS is a LabVIEW application which is composed of a collection of Virtual Instruments (VI’s). Each VI consists of a set of input terminals, a set of output terminals, a computational node, and a (possibly unused) user interface window. VI’s may call out to each other exchanging data via the input and output terminals. A VI that is called passes the data provided on the input terminals on to the computational node, executes the computational node, and provides the results of the computation on its output terminals. One VI in the application is designated the main VI. This VI gets control when the application executes.

The C Application Programming Interface provides a C functional interface to the NI VMS LabVIEW API. The main rules followed in the C API are, that for each VI in the LabVIEW API there is a corresponding function in the C API, and the VI input and output terminals are mapped to C function parameters. A few VI terminals cannot be mapped to C function parameters, and in these cases an alternative C function is provided.

The LabVIEW API is extensively documented in the online manual, which is the main API reference. This manual documents the mapping between LabVIEW API and C API and provides application hints and examples.

LabVIEW provides the notion of an “error cluster”, which is a compound element consisting of a Boolean error indicator, an integer error code, and an error message string.

Most VI’s take an error cluster as input and provides a resulting error cluster as output.

A VI reports errors by setting the error flag, error code and error string of an error cluster provided as an output terminal. Furthermore it is a common LabVIEW idiom that VI’s that take an error cluster as input, tests for errors on this input. If an error is detected, the VI does nothing, but passes the content of the error cluster unmodified on to the output terminal containing the resulting error cluster. This allows connecting and executing VI’s in sequence providing a form of functional programming.

In the C API error clusters are mapped to an ErrorCluster struct that must be set to all zeros to indicate “no error”.

For each VI in the LabVIEW API, a corresponding C API function exists.

1. The LabVIEW generated C prototype function contains a parameter for the waveforms output terminal of the VI of type HWAVES. Accessing this parameter from C is not supported and will result in a crash. National Instruments recommends modifying the VI to return the individual components of the waveform instead. We have therefore provided modified versions of the Analyse functions that does not return the waveforms parameter, but instead buffers the waveforms for access using the CVideoMASTER_GetWaveform function

Most API functions that return data allocates space for the data to be returned. This is done using an internal LabVIEW allocator, which is different from the standard C/C++ memory allocators. This means that data returned from the API functions must not be deallocated by the standard allocators, and that API functions that return data in locations specified by the API parameters needs to be called with parameters that has been initialized to all-zeros.

#define zeroIt(what) memset(&what, 0, sizeof(what))

ErrorCluster errorIn;
ErrorCluster errorOut;
zeroIt(errorIn);
zeroIt(errorOut);

Overall DLL status

All DLLs built from LabVIEW contain an exported function called LVDLLStatus, with the following prototype:

MgErr LVDLLStatus(CStr errStr, int32 errStrLen, NULL);

The calling program uses this routine to verify that the LabVIEW DLL loaded correctly. If an error occurs while loading the DLL, the function returns that error, otherwise 0 is returned. Pass a string buffer to the errStr input to receive additional information about the error. Set the errStrLen input to the number of bytes in the string buffer passed as errStr.

MgErr errReturn;
char errStatus[1024];

if ((errReturn = LVDLLStatus(errStatus, 1024, NULL)) != 0) {
    printf("LVDLLStatus returned %d:%s\n", errReturn,
        errStatus);
    return(1);
} else {
    printf("API DLL loaded OK\n");
}