XJAPI_GetXJLinkName

Retrieve the name of an attached XJLink.

XJAPI_ERROR XJAPI_GetXJLinkName(
    unsigned int serialNumber,
    char *buffer,
    unsigned int length
);

Version

This function was added in XJTAG version 3.2.9 and so requires that XJAPI_VERSION be defined to be greater than or equal to 0x030209.

Arguments

serialNumber

The serial number of the XJLink whose name should be returned.

buffer

A pointer to a buffer to write the NULL-terminated string into.

length

The size of buffer, including the space for the NULL terminator.

Return value

An XJAPI_ERROR value indicating whether the function call was successful or not:

XJAPI_ERROR_PARAMETER2

buffer was null.

XJAPI_ERROR_PARAMETER3

The name of the XJLink exceeds the supplied length.

XJAPI_ERROR_NOTFOUND

An XJLink with serial number serialNumber was not found.

Notes

Currently, the maximum length of an XJLink's name is 32 characters. The string returned is in UTF-8, so it is best to allow for a maximum of 4 bytes per character in the name plus a byte for the null terminator, i.e. 257 bytes.

Example

unsigned int serialNumber = 10032;
char name[257];

XJAPI_ERROR ec = XJAPI_GetXJLinkName(serialNumber, name, sizeof(name));
if (ec == XJAPI_SUCCESS) {
    printf("XJLink with serial number %d has the name '%s'", serialNumber, name);
}
else if (ec == XJAPI_ERROR_NOTFOUND) {
    printf("XJLink with serial number %d was not found\n", serialNumber);
}
else {
    char text[256];
    XJAPI_GetLastError(text, sizeof(text));
    printf("Failed to get XJLink name: %s\n", text);
}