TSPI_lineSetDevConfig

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function restores the configuration of a device associated one-to-one with the line device from an "" data structure previously obtained using the TSPI_lineGetDevConfig function. The contents of this data structure are specific to the line [service provider] and device class.

Syntax

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD dwDeviceID, 
  LPVOID const lpDeviceConfig,  
  DWORD dwSize, 
  LPCWSTR lpszDeviceClass 
);

Parameters

• dwDeviceID
  Line device to be configured.

• lpDeviceConfig
  Pointer to the configuration data structure that is returned in the variable portion of the VARSTRING structure by TSPI_lineGetDevConfig.

• dwSize
  Number of bytes in the structure pointed to by lpDeviceConfig. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig.

• lpszDeviceClass
  Pointer to a null-terminated Unicode string that specifies the device class of the device whose configuration is to be restored. Valid device class strings are the same as those specified for the TSPI_lineGetID function when it is applied to a "line" device (that is, when dwSelect has the value LINECALLSELECT_LINE).

Return Value

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

Remarks

The call state is device specific.

The service provider returns LINEERR_INVALPARAM if the information contained in the structure pointed to by lpDeviceConfig is not valid for this device.

The service provider returns LINEERR_INVALLINESTATE if the device configuration cannot be changed in the current line state. The line may be in use by another application.

This function can be used to restore the configuration of a device associated one-to-one with the line device from a data structure previously retrieved from the service provider using the TSPI_lineGetDevConfig function. The lpszDeviceClass parameter selects which of among possibly several different classes of devices is to have its configuration restored. The set of supported classes is restricted to those whose devices correspond one-to-one with the line device.

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

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 is 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.

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. Application programs 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 has to 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 set or retrieved through TSPI_lineGetDevConfig can revert to default or undefined values. The caller can reliably retrieve any temporary configuration only by a sequence such as TSPI_lineOpen, or 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 passed to this function is specific to the line and device class API, is undocumented, and is undefined. The structure passed to this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used from a previous TSPI_lineGetDevConfig to obtain 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 check this data structure for consistency to guard against failures due to a client application passing incompatible information.

Requirements

See Also

Reference

TSPI_lineClose
TSPI_lineGetDevConfig
TSPI_lineGetID
TSPI_lineOpen