Establishing Interface Connections and Sessions

To acquire images using the high-level or low-level functions, you must first learn how to establish a connection to an interface and create a session. Refer to the following sections for information about managing interfaces and sessions. Then refer to the high-level or low-level samples for information about acquiring images.

Interface Functions

Use interface functions to query the number of available interfaces, establish a connection to, control access to, and initialize hardware. All parameters configured in MAX for an image acquisition device are associated with an interface name. You can have one device associated with more than one interface name, which allows you to have several different configurations for one device. Use the interface name to refer to the device in the programming environment.

Interface name information is stored in an interface (.iid) file and includes the device serial number and the camera file associated with each channel or port on the device. NI-IMAQ specifies all interfaces by a name. By default, the system creates default names for the number of devices in the system. These names observe the convention shown in the following table.

Interface Name	Device Installed
img0	Device 0
img1	Device 1
...	...
imgn	Device n

The interface name always identifies a single port of an image acquisition device. A port identifies a single independent data stream from a camera. All NI image acquisition devices support at least one port. Devices that support multiple ports can sustain independent and asynchronous acquisitions from the cameras on each port.

The port number may be explicitly identified by using the :: operator to append the port number suffix to the interface name. Port numbers are zero-based. For example, img0::1 opens port number 1 of the image acquisition device identified by img0. Interface names that do not have a port number suffix default to port 0. img0::0 and img0 are equivalent in meaning.

You can edit existing interfaces or create new interfaces by using MAX. You also can use MAX to configure the default state of a particular interface.

Before you can acquire image data successfully, you must open an interface by using the imgInterfaceOpen function. imgInterfaceOpen requires an interface name and returns a handle to this interface. NI-IMAQ uses this handle to reference this interface when using other NI-IMAQ functions.

To establish a connection to the first device in your system, use the following program example:

INTERFACE_IDinterfaceID;

if (imgInterfaceOpen("img0", &interfaceID) == IMG_ERR_GOOD)

{

// user code

imgClose(interfaceID, FALSE);

}

This example opens an interface named img0. When the program is finished with the interface, it closes the interface using the imgClose function.

Refer to the NI-IMAQ Function Reference Help for a complete list of the available interface functions.

Session Functions

Use session functions to configure the type of acquisition you want to perform using a particular interface. After you have established a connection to an interface, create a session and configure it to perform the type of acquisition you require.

To create a session, call the imgSessionOpen function. This function requires a valid interface handle and returns a handle to a session. NI-IMAQ then uses this session handle to reference this session when using other NI-IMAQ calls.

To create a session, use the following example program:

INTERFACE_ID interfaceID;

SESSION_ID sessionID;

if (imgInterfaceOpen("img0", &interfaceID) == IMG_ERR_GOOD)

{

if (imgSessionOpen(interfaceID, &sessionID) == IMG_ERR_GOOD)

{

// user code

imgClose(sessionID, FALSE);

}

imgClose(interfaceID, FALSE);

}

This example opens an interface named img0 and then creates a session to acquire images. When the program is finished with the interface and session, it then closes both handles using the imgClose function.

Refer to the NI-IMAQ Function Reference Help for a complete list of the available session functions.