Returns zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this function.

The call state is device-specific.

This function can be used to retrieve a data structure from the service provider that specifies the configuration of a device associated one-to-one with the line device. The lpszDeviceClassparameter selects which of among possibly several different classes of devices is to have its configuration retrieved. The set of supported classes is restricted to those whose devices correspond one-to-one with the line device.

A service provider should typically allow the tapi/line device class under this function. It would retrieve parameters that have "line" scope, such as the list of addresses in this line, the list of physical hardware devices such as COMM ports corresponding to the addresses, maximum number of concurrent calls (if configurable), and so on.

In general, this function does not allow media-related device classes such as mci waveaudio, low level wave, or datamodem device classes, because these usually apply to a particular call or a particular address. Because there can be more than one of these per line device, the identification of the particular call or address simply by the line device identifier parameter in this function would be ambiguous. An exception can be made for call-specific or address-specific device classes in cases where there is class configuration information that applies to the entire line device scope, such as initial defaults, and so on.

There are several reasons why exceptional support for call-specific and address-specific device classes is of only limited value under this function. First, because these classes can be ambiguous on multiple-address/multiple-call service providers, only a subset of service providers support them. Applications are not likely to add a device-specific dependency on the inclusion of these classes in this function. Second, as higher-level media "classes" emerge that implement high-level protocols such as dial-in file system access in terms of low-level transport APIs, configuration for these classes tends toward "instance" scope instead of "class" scope. The high-level media API must supply its own functions to configure call-specific or address-specific instances.

Whatever sort of devices and device classes this function supports, it can potentially affect two kinds of configuration information: permanent and temporary. Permanent information survives across different "opens" of the line, and even across different "inits" of the service provider itself. Temporary information survives only within a unique "open" of the line. When the line is closed, any such temporary information that has been retrieved or set through the TSPI_lineSetDevConfigfunction can revert to default or undefined values. The caller can reliably retrieve any temporary configuration only by a sequence such as TSPI_lineOpen, and TSPI_ lineGetDevConfig. The caller can reliably set temporary configuration information retrieved by such a sequence through a sequence such as TSPI_ lineOpen, TSPI_ lineSetDevConfig. The temporary part of configuration remains stable only until the next TSPI_ lineSetDevConfig, or TSPI_lineClose. The service provider must take care of storing any permanent part of the configuration, and reloading it whenever the service provider is initialized.

The exact format of the data contained within the structure returned by this function is specific to the line and device class API, is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in TSPI_lineSetDevConfigto restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this may work in some instances, it is not guaranteed). A service provider should put items in the data structure to allow it to be checked for consistency to guard against failures due to a client application passing incompatible information.