9.2.1 Detection Wrapper Functions

Setup wrapper functions generally return a INF list of the form:

{ <error code>, arg, ... }

As in most other symbolic languages, the parameters can be numbers, strings, atoms, or other lists. If an error occurs, setup returns only the error code.

Examples of how to call these functions are given in the system ntlanman.inf and utility.inf files. Details of the implementation are not discussed in this section. Instead, emphasis is placed on access and usage.

Each of the wrapper functions is accessed through the NCPA.CPL export CPlSETUP. The standard form for calling this function from an .inf file is as follows:

LibraryProcedure <ResultVarName>

$(NcpaCplHandleVar) CPlSetup $(!STF_HWND)

<FuncToBeRun> [other args]

Any additional arguments follow immediately behind the name, which is not case-sensitive, of the function to be run.

The resulting list is stored in the ResultVarName parameter. The first element of the list is the error code associated with the call, or zero if no error has occurred. The remaining elements depend on the function called.

If an error occurs, the variable FLibraryErrCtl is checked. If its value is one, the error is returned to the calling .inf file. If its value is undefined or something other than one, setup displays a DLL export call error message. This situation should be avoided, because it can be cryptic to the casual user. It allows a user to retry an operation that continues to fail.

The following summarizes these wrapper functions:

DTSTART

The DTSTART function must be called by the setup.inf file to initiate detection operations. The primary purpose of this function is to bind all known NIC detection DLLs and to create the data structures necessary to properly access and iterate the DLLs. Only the function name is required for the call and any subsequent calls are ignored. The format is as follows:

DTSTART

DTEND

DTEND should be called by setup.inf to terminate detection operations. It is called automatically when setup unbinds from NCPA.CPL. The format is as follows:

DTEND

DTRESET

DTRESET causes all detected NIC information to be discarded, and the internal iteration control to be reset. In other words, the detection code status after DTRESET is the same as that after DTSTART. The format is as follows:

DTRESET

DTCARD

DTCARD attempts to detect the next NIC on the next bus during the iteration cycle. The format is as follows:

DTCARD

The result, if detection succeeds (error code == 0), is a list in the following form:

{ error code,

OPTIONNAME,

card index,

numeric card type code,

detection confidence level,

bus interface type,

bus number

}

The card index returned is an integer that the .inf script must use to refer to the specific NIC in all future operations.

DTPARAMS

DTPARAMS returns parameter information for a particular NIC option. The format is as follows:

DTPARAMS <NIC option name>

The result is a list describing the NIC parameters. The basic result has the form:

{ error code

parameter description list

}

The parameter description list has the form:

{ {parameter 1 name,setting control,confidence,{v1, v2, v3, ...} },

{parameter 2 name,setting control,confidence,{v1, v2, v3, ...} },

....

}

The setting control is an integer that determines whether the option can be set using software. The confidence is an integer from 0 to 100. Each of the vn values is a valid setting for the appropriate parameter.

DTQUERY

DTQUERY takes the index of a previously detected NIC and returns the currently detectable configuration parameters.

DTVERIFY

DTVERIFY takes a set of configuration parameters for a NIC and returns an indication of the validity of the parameters.

DTSTRING

DTSTRING takes an option name and an integer and returns the corresponding string from the owning DLL.

DTPNAME

DTPNAME takes an option name and a parameter name and returns the external (displayable) version of the name.