Programmer's Guide

RaDeKL Radar API Programmer’s Guide 8

Part III: Radar Management Functions

RaDeKL_ListRadars

Get a list of all RaDeKL Radar devices connected to the system. Note: This function will only retrieve

RaDeKL Radar devices and will ignore other devices that may be based on the same FTDI USB Chip.

Each device has a serial number (up to 15 chars) and a device description (up to 63 chars). The serial

number can then be used in a call to RaDeKL_OpenRadar to open the device. The serial number is unique

to each unit sold, whereas the description string is unique to a particular version (or model) of RaDeKL

Radars and may change with future versions.

Format:

ULONG RaDeKL_ListRadars (DWORD *numdevs, char ***serial_numbers, char ***descriptions);

Parameters:

numdevs Pointer to a DWORD to receive the device count. This may be NULL, in which

case no device count is returned.

serial_numbers Pointer to a pointer to a (null-terminated) list of character strings to receive the

serial numbers of the connected devices. (*numdevs) should initially be NULL, as

the function allocates the list and the individual strings. See example for

clarification. If NULL is passed as numdev, no serial numbers are returned.

descriptions Pointer to a pointer to a (null-terminated) list of character strings to receive the

descriptions of the connected devices. (*descriptions) should initially be NULL, as

the function allocates the list and the individual strings. See example for

clarification. If NULL is passed as descriptions, no descriptions are returned.

Return Value:

RaDeKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes.

Remarks:

This function will automatically allocate the storage required for the serial number and description lists and

the associated character strings. If valid pointers are passed in, the existing storage (as allocated by a

previous call to RaDeKL_ListRadars) will first be de-allocated before the new lists are allocated. This way

the designer does not need to bother maintaining these lists (i.e. simplifying re-scanning of connected radar

units), as long as the pointers are initially set to NULL. See examples below for clarification. Any remaining

lists will be de-allocated when the program terminates. If the design requires an explicit de-allocation of the

lists, use RaDeKL_ListRadarsCleanup described below.