NcDetectIdentify returns information about the NICs supported by the DLL being addressed. The calling function furnishes a numeric index value and the function responds with the appropriate zero-terminated string. The return value is zero if no error occurs; otherwise, the appropriate winerror.h value appears. The function prototype is:
LONG NcDetectIdentify(
LONG lIndex,
WCHAR *pwchBuffer,
LONG cwchBuffSize
);
Parameters
lIndex
Specifies an index number indicating the information to be retrieved. The information applies either to the DLL as a whole or to a specific NIC. The following index numbers are defined for this parameter:
·Index zero causes the function to output the manufacturer's identification for the DLL.
·Index one causes the function to output a date and version string.
·Indexes numbered from 1000, in blocks of 100 values (modulo 100), indicate NICs. For example:
1000
Causes the function to output the internal short alphabetic token string representing the first supported NIC.
1001
Causes the function to output the displayable name of the NIC (language-sensitive).
1002
Causes the function to output the name of the manufacturer.
1100
Causes the function to output the alphabetic token for the second NIC type supported.
The values of lIndex are referred to in function prototypes as lNetcardId in the following sections.
pwchBuffer
Points to the buffer in which the retrieved information is returned.
cwchBuffSize
Indicates the size in bytes of the buffer.
Comments
To determine all NICs supported by a given DLL, the calling function can repeatedly call NcDetectIdentify, starting at an lIndex of 1000 and incrementing by 100 with each call. When ERROR_NO_MORE_ITEMS is returned, the enumeration is at an end. If the buffer is too small, the function returns ERROR_INSUFFICIENT_BUFFER. This error code is consistent throughout all NIC detection functions that return wide-character data into a buffer.
When the calling function has the list of possible NICs, it can retrieve information about a particular adapter. To accomplish this, it supplies the particular NIC-information index value to NcDetectIdentify and reads the information retrieved by the function.
If the calling function wants to examine the hardware, it performs a NIC-detection search. This search must be ordered to prevent unavoidable hardware interlocks that can occur if tests are made in the wrong order. Depending on the algorithm used by the calling function, the search can be made in a variety of ways.
The calling function can elect to make calls to NcDetectIdentify for all recognized NICs to determine search order. In this case, each call specifies nn03, where nn = 00 specifies the base network information index value of the NIC. In response to each call, NcDetectIdentify outputs a numeric search order value for the specific NIC, ranging from 0 to 1000. This value can then be used by the user interface to sort its attempts to detect network adapters. The lower the number, the faster the user interface logic attempts to detect the card. Any NIC for which a search order is not specified has a default search order value of 500.