Notification from NLA

NLA is capable of providing its clients with notification of network location changes. The mechanism used to request notification of change events is a combination of the WSALookupServiceBegin, WSANSPIoctl, and WSALookupServiceNext functions.

In order to receive change notification from NLA, a client must first call the WSALookupServiceBegin to obtain a valid NLA SP lookup handle. Next, the client can call WSALookupServiceNext or WSANSPIoctl in any order; to register for notification, call the WSANSPIoctl function with the SIO_NSP_NOTIFY_CHANGE control code set in the dwControlCode parameter.

The WSALookupServiceNext function returns WSA_E_NO_MORE as a set delimiter. When a client has registered for notification using the WSANSPIoctl function and WSALookupServiceNext returns WSA_E_NO_MORE, calling WSALookupServiceNext again reveals whether a change has occurred:

• If no changes have occurred since the previous WSA_E_NO_MORE, WSA_E_NO_MORE is returned.

• If a change has occurred, or if a change has occurred and a polling call is made, the WSALookupServiceNext function call returns networks as WSAQUERYSET structures, with one of the following flags set in its dwOutputFlags member:

  RESULT\_IS\_ADDED RESULT\_IS\_CHANGED RESULT\_IS\_DELETED

Change notification is provided for any fields that changed since the NLA lookup handle was obtained with the WSALookupServiceBegin function call, or since the last enumeration that resulted in the WSA_E_NO_MORE error. When all changed network location information is provided, WSA_E_NO_MORE is returned. Clients can reissue a WSANSPIoctl function call on the same query handle at any time, one at a time, with the SIO_NSP_NOTIFY_CHANGE flag set. This capability enables a client to recycle the query handle on an ongoing basis, thereby relieving the client from having to maintain change-state information on its own. Once a client no longer needs change notifications, it should close the query handle using the WSALookupServiceEnd function.