Location Framework Registry Settings
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
All configuration settings for the Location Framework Service are stored in the Registry. To change the base configuration of the Location Framework, the Registry settings must be changed and subsequently the Location Framework application restarted. Data with privacy concerns, such as user names and passwords, should not be written to the Registry and should be handled through an IOCTL mechanism, see Location Framework IOCTLs. This mechanism can be used to send changes to a plugin at run time. An application can open a plugin and send it IOCTLs and data blobs programmatically.
The Location Framework Registry is also utilized to make global changes such as whether or not to load a plugin, the order to load plugins, etc. In order to change a global configuration option, the registry must be changed directly. The LF service can be refreshed to make the change take affect without a reboot. This refresh will cause all plugins to be unloaded, the registry to be reread, and then the plugins and the system to be restarted. The Location Framework can be refreshed via the IOCTL_SERVICE_REFRESH. The file handle to open during the CreateFile call for the Location Framework is “LOC0:”.
Location Framework is loaded at boot time by services.exe. The Location Framework will read the available plugin DLLs from the registry and load all plugins at boot time. This is not an indication to the plugins to begin retrieving location information. Plugins will retrieve information only after receiving an indication from the Location Framework.
Plugins are configured via the registry. Each Provider is specified as a registry subkey of HKEY_LOCAL_MACHINE\System\CurrentControlSet\Location Framework\ Providers. Each Resolver is specified as a registry subkey of HKEY_LOCAL_MACHINE\System\CurrentControlSet\Location Framework\Resolvers. In the tables below, if a required registry setting is not specified or is wrongly configured the Location Framework will not load the plugin DLL.
The following configuration options are the same for both Providers and Resolvers.
| Value: type | Description |
|---|---|
DLL: REG_SZ |
Name of the DLL that implements the plugin. This value must be specified. |
GUID: REG_SZ |
GUID that uniquely identifies the plugin. Applications use to access the plugin directly via LocationPluginOpen. This value must be specified. |
PREFERENCE: REG_DWORD |
Indicates the preference this plugin has versus other plugins on the system. A plugin with a lower number will be started before a plugin with a higher number that generates the same type of report. Note that this is order it is started, not loaded. The load order is nondeterministic. This value must be specified. |
FRIENDLYNAME: REG_SZ: |
Friendly name of the plugin DLL, for use only in UI applications. For instance, “Microsoft GPS Provider” would be a friendly name. This value is optional. There is no default setting. |
PLUGINFLAGS: REG_DWORD |
DWORD specifying flags that modify the behavior of this plugin. The default value is 0. This value is optional. The currently defined plugin values are: PLUGIN_FLAGS_DISABLED - 0x1 – Causes Location Framework to not load the plugin DLL. > [!NOTE] > Future plugin flags may be defined at a later time, so this field is not available for third parties to extend. |
RETRYONFAILURE: REG_DWORD |
Time, in milliseconds, that a plugin should wait between attempting to retry to determine the location if its last attempt failed. The specific implementation of this flag differs for Providers and Resolvers, but the underlying concept is identical. This value must be specified. |
GENERATEDREPORTS: REG_MULTI_SZ |
List of GUIDs which indicate which report types (LOCATION_LATLONG_GUID for instance) that this plugin generates. This MUST be a REG_MULTI_SZ, not a REG_SZ, even if there is only one report generated. There must be at least 1 entry and no greater than MAX_PLUGIN_REPORT_TYPES (8). |
MAXIMUMINITIALWAIT: REG_DWORD |
Time, in milliseconds, that a plugin should wait for its first request for location to be processed. If the initial request takes longer than this amount then the plugin should indicate a failure. Some location technologies, such as GPS, must be allowed longer times to perform their initial position determination than subsequent determinations. |
VERSION: REG_DWORD |
The version of this plugin DLL. This value is optional and the default value is 1. |
The following configuration options are Provider Specific.
| Value: type | Description |
|---|---|
PROVIDERFLAGS: REG_DWORD |
DWORD specifying flags that modify the behavior of this plugin. The default value is 0. This value is optional. No provider flags are currently defined. Provider flags may be defined at a later time, so this field is not available for third parties to extend. |
POLLINTERVAL: REG_DWORD |
Time, in milliseconds, that a Provider should wait between querying for new location information. Note that the Provider, not the Location Framework, is responsible for interpreting and enforcing this value. This value must be specified. |
The following configuration options are Resolver Specific.
| Value: type | Description |
|---|---|
RESOLVERFLAGS: REG_DWORD |
DWORD specifying flags that modify the behavior of this Resolver. The default value is 0. This value is optional. No Resolver flags are currently defined. Resolver flags may be defined at a later time, so this field is not available for third parties to extend. |
SUPPORTEDREPORTS: REG_MULTI_SZ |
Indicates which Provider reports that the Resolver can process (for instance LOCATION_LATLONG_GUID) and resolve into other report types. Note that this MUST be a REG_MULTI_SZ, not a REG_SZ. There must be at least 1 entry and no greater than MAX_PLUGIN_REPORT_TYPES (8). |
MINIMUMREQUERY: REG_DWORD |
Minimum time, in milliseconds, that the Location Framework will wait between calls to ResolverGetLocation for this Resolver. A Provider DLL may be generating data at an extremely fast rate, but the Resolver may not wish to perform a translation each time a new position arrives. Consider for instance a GPS receiver providing location updates once per second, whereas a Web Service may only wish to go out to the network once every ten minutes. The Location Framework only calls the Resolver at most once every MINIMUMREQUERY milliseconds. This value must be specified. |
See Also
Reference
Concepts
Location Framework OS Design Development
Location Framework Security
Other Resources
Location Framework
Location Framework Application Development
Location Framework Samples