Querying NLA

To obtain notification of invalidated logical networks, use the WSANSPIoctl function to register for network location change events. Two methods can be used to determine whether a previously valid network location has become invalid: polling methods, or notification using overlapped I/O or Windows messaging.

Queries are formed using the WSALookupServiceBegin, WSALookupServiceNext, and WSALookupServiceEnd functions to enumerate all available logical networks. The use of each of these functions is explained individually throughout the remainder of this section, beginning with the WSALookupServiceBegin function.

Note

NLA requires the Mswsock.h header file, which by default is not included in the Winsock2.h file.

 

Step 1: Initiate the Query

For quick reference, the WSALookupServiceBegin function has the following syntax:

INT WSALookupServiceBegin(
  LPWSAQUERYSET lpqsRestrictions,
  DWORD dwControlFlags,
  LPHANDLE lphLookup
);

NLA supports the following dwControlFlags lookup flags:

LUP\_RETURN\_NAME LUP\_RETURN\_COMMENT LUP\_RETURN\_BLOB LUP\_RETURN\_ALL LUP\_DEEP

These flags restrict the result sets returned in subsequent calls to the WSALookupServiceNext, function to networks that contain fields of the specified type. For example, specifying LUP_RETURN_BLOB in the dwControlFlags parameter of the WSALookupServiceBegin function call restricts result sets from subsequent calls to WSALookupServiceNext, to networks that contain BLOB information. Using the LUP_RETURN_ALL flag is equivalent to specifying LUP_RETURN_NAME, LUP_RETURN_COMMENT, and LUP_RETURN_BLOB, but not LUP_DEEP.

For an explanation of these lookup flags, consult the WSALookupServiceBegin function reference page.

The lookup handle returned by NLA in the lphLookup parameter is private to NLA, and should not be modified. Since the returned handle is private to NLA, functions such as WSAGetOverlappedResult are not available.

NLA returns zero upon successful completion, as defined in the WSALookupServiceBegin function reference page. Otherwise, NLA supports the following error codes.

Error	Meaning
WSANOTINITIALISED	A successful call to the WSAStartup function to initialize NLA was not performed.
WSAEINVAL	One or more parameters were invalid, or parameters specified in the function call apply to protocols other than IP.
WSASERVICE_NOT_FOUND	The lpServiceClassId parameter of the WSAQUERYSET structure passed in the lpqsRestrictions parameter contains an invalid GUID.
WSANO_DATA	The LUP_CONTAINERS flag was specified in dwControlFlags parameter.
WSAEFAULT	An access violation occurred when attempting to access user-supplied parameters.
WSASYSNOTREADY	The NLA service is unavailable to process the request.
WSA_NOT_ENOUGH_MEMORY	NLA or the NLA service was unable to allocate enough memory to process this request.

 

Step 2: Perform the Query

The next step in querying NLA requires use of the WSALookupServiceNext function. For quick reference, the WSALookupServiceNext, function has the following syntax:

INT WSALookupServiceNext(
  HANDLE hLookup,
  DWORD dwControlFlags,
  LPDWORD lpdwBufferLength,
  LPWSAQUERYSET lpqsResults
);

The lLookup parameter is the lookup handle returned from the previous call to the WSALookupServiceBegin function.

The dwControlFlags parameter supports the following flags:

LUP\_RETURN\_NAME LUP\_RETURN\_COMMENT LUP\_RETURN\_BLOB LUP\_RETURN\_ALL LUP\_FLUSHPREVIOUS

These flags are independent of the flags supported in the WSALookupServiceBegin function call. Note that any constraints specified in the previous call to the WSALookupServiceBegin function constrain the lookup; adding flags with the WSALookupServiceNext function in an attempt to broaden the query beyond the constraints specified in the WSALookupServiceBegin call are silently ignored. Specifying a more restrictive set of flags than that specified in the WSALookupServiceBegin call, however, is allowed.

If the network detailed in lpqsResults is an active network, a series of NLA_BLOB structures is appended as specified in the lpBlob member of the WSAQUERYSET structure returned in lpqsResults. These NLA_BLOB structures may be chained, and can be enumerated by traversing the list while NLA_BLOB.header.nextOffset is nonzero. To obtain results for all network location information, continue calling the WSALookupServiceNext, function until the WSA_E_NO_MORE error is returned, as explained in the WSALookupServiceNext, reference page.

The WSALookupServiceNext function is also used in conjunction with the WSANSPIoctl function to receive notification of network changes. See Notification from NLA for more information.

NLA returns zero upon successful completion. Clients of NLA should continue calling the WSALookupServiceNext, function until WSA_E_NO_MORE is returned, indicating that all of the information about available networks has been returned.

Otherwise, calling the WSALookupServiceNext, function for NLA supports the following error codes.

Error	Meaning
WSANOTINITIALISED	A successful call to the WSAStartup function that initialized NLA was not performed.
WSA_INVALID_HANDLE	The lookup handle provided in the hLookup parameter was not a valid NLA SP handle. Clients must first call the WSALookupServiceBegin function and receive a valid NLA SP handle to obtain query results.
WSAESYSNOTREADY	The NLA service is unavailable to process this request.
WSAEFAULT	The buffer size specified in the lpdwBufferLength parameter was insufficient to hold the results pointed to by lpqsResults. The required buffer is specified in lpdwBufferLength; if the client cannot supply a sufficiently large buffer, the client can call the WSALookupServiceNext function with dwControlFlags set to LUP_FLUSHPREVIOUS to skip the entry.
WSA_NOT_ENOUGH_MEMORY	NLA is unable to obtain network information from the NLA system service due to insufficient memory in the calling process.
WSA_E_NO_MORE	There are no additional networks to enumerate for the query.

 

Step 3: Terminate the Query

When all queries to NLA are complete and an application no longer requires use of NLA, a call to the WSALookupServiceEnd function should be made. Do not call WSALookupServiceEnd if the application will receive change notification based on the submitted query. See Notification from NLA for more information on receiving notification. Like most Windows Sockets service providers, NLA maintains a reference count for its clients. Calling the WSALookupServiceEnd function when queries to NLA are completed enables system resources no longer required by NLA to be freed.

NLA supports the following error codes for WSALookupServiceEnd function calls.

Error	Meaning
WSANOTINITIALISED	A successful call to the WSAStartup function to initialize NLA was not performed.
WSA_INVALID_HANDLE	The handle provided in the hLookup parameter was not a valid NLA SP handle.