nctGetNamesLength

Purpose

Gets the required size for a specified list of channels to allocate an array for the ChannelList input of nctGetNames.

Format

Inputs

FilePath

FilePath is an optional path to a CAN database file from which to get channel names. The file must use either the .DBC or .NCD extension.

If you pass NULL or empty-string to FilePath, this function examines the channel names from MAX.

For more information on FilePath, refer to nctGetNames.

Mode

Specifies the type of names to examine.

nctGetNamesModeChannels

Examine the list of channel names.

nctGetNamesModeMessages

Examine the list of message names.

MessageName

MessageName is an optional input that filters the names for a specific message. If you pass NULL or empty-string to MessageName, this function returns all names in the database. If you pass a nonempty string, the SizeofChannelList output is limited to channels of the specified message.

This input applies to Mode of nctGetNamesModeChannels only. It is ignored for Mode of nctGetNamesModeMessages.

Outputs

SizeofChannelList

Number of bytes required for nctGetNames to return all names for the specified FilePath, Mode, and MessageName. After calling nctGetNamesLength, you can allocate an array of size SizeofChannelList, then pass that array to nctGetNames using the same input parameters. This ensures that nctGetNames will return all names without error.

Return Value

The return value indicates the status of the function call as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.

Use the ncStatusToString function of the Frame API to obtain a descriptive string for the return value. The ncStatusToString and ncGetHardwareInfo functions are the only Frame API functions that can be called within a Channel API application.