This TSPI_lineSetCurrentLocation function is called by TAPI whenever the address translation location is changed by the user (in the Dialing Propertiesdialog box) or an application (using the lineSetCurrentLocation function). Service providers that store parameters specific to a location (for example, touch-tone sequences to invoke particular PBX functions) use the location to select the set of parameters applicable to the new location.
LONG TSPIAPI TSPI_lineSetCurrentLocation(
DWORD dwLocation
);
Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:
LINEERR_NOMEM and LINEERR_OPERATIONFAILED.
Service providers that store sets of parameters based on the user's current location should identify those sets by the permanent location identifier of the location.
If the service provider does not implement specific parameters by location, this function can be omitted.
If the value passed in to the service provider by this function is not recognized by the service provider (for example, because no location-specific parameters have yet been set for the specified location), the service provider uses a default set of parameters.
TAPI ignores the value returned by the service provider for this function; it is returned for debugging purposes only.
The service provider can synchronize its stored location-specific parameters with the locations stored by TAPI whenever the TSPI_providerConfig or TSPI_lineConfigDialog function is called, by using the lineGetTranslateCaps function to obtain a table of current locations. Newly defined locations and removed locations can be detected at this time, and appropriate adjustments made to the service provider's stored location parameters (including prompting the user to make settings for new locations).
For backward compatibility, if the service provider does not export this function, TAPI does not call it, and no ill effects result.
TSPI_lineConfigDialog, TSPI_providerConfig