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.
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 );
Operations supported for the essOperation parameter are the following:
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.
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:
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.
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:
|WSANOTINITIALISED||A successful call to the WSAStartup function to initialize NLA was not performed.|
|WSAEACCESS||NLA_ALLUSERS_NETWORK was specified in dwControlFlags while not in the security context of a local system administrator.|
|WSAEALREADY||The specified network is already persistently stored in the requested manner, and no flags were specified in dwControlFlags to indicate an update to the existing entry.|
|WSAEAFNOSUPPORT||A protocol family was specified for which there is no support. Only IP protocol families are supported in NLA.|
|WSAEPFNOSUPPORT||A protocol was specified for which there is no support. Only IP protocol is supported in NLA.|