Registering a Service Instance with NLA

NLA clients can record network configuration information on a system-wide basis, enabling future queries to return the specified configuration information regardless of whether the network is active. This capability allows NLA clients to affect a consistent network information user experience across multiple applications.

Parameters

To register a service instance with the Network Location Awareness service provider, use the WSASetService function. In order to properly register a service instance certain parameters of the WSASetService function must be set with the appropriate information, as explained in this section. For quick reference, the WSASetService function has the following syntax:

INT WSASetService(
  LPWSAQUERYSET lpqsRegInfo,
  WSAESETSERVICEOP essOperation,
  DWORD dwControlFlags
);

For the lpqsRegInfo parameter, provide a WSAQUERYSET structure from either an NLA SP query result, or constructed adhering to the requirements of an NLA SP query, as specified in Querying NLA.

Operations supported for the essOperation parameter are the following:

RNRSERVICE_REGISTER

The network defined in the WSAQUERYSET structure provided in lpqsRegInfo is made persistent for the active user by storing the network instance in the registry hive for the current user, which allows impersonation.

RNRSERVICE_DELETE

If the network defined in the WSAQUERYSET structure provided in lpqsRegInfo is persistent, it will be removed.

The operation specified in the essOperation parameter can be modified by the following options, which can be specified with binary OR logic:

NLA_FRIENDLY_NAME

When used with RNRSERVICE_REGISTER, the lpszComment field of the network defined in lpqsRegInfo is checked for validity and stored persistently. When used with RNRSERVICE_DELETE and the defined network has a friendly name, the friendly name is removed but the network entry is left intact.

NLA_ALLUSERS_NETWORK

When used with RNRSERVICE_REGISTER, the entry is stored persistently under HKEY_LOCAL_MACHINE, making it available during queries to all users on the local computer. When used with RNRSERVICE_DELETE, the specified network is removed from HKEY_LOCAL_MACHINE. An error is returned if the specified network is not present. In order to delete a network from the registry hive of the current user, this flag must not be specified. This flag is only valid in the security context of a local system administrator.

NLA supports the following error codes for WSASetService function calls: