Summary of Name Resolution Functions
The name resolution functions can be grouped into three categories: Service installation, client queries, and helper (with macros). The sections that follow identify the functions in each category and briefly describe their intended use. Key data structures are also described.
Service Installation
When the required service class does not already exist, an application uses WSAInstallServiceClass to install a new service class by supplying a service class name, a GUID for the service class identifier, and a series of WSANSCLASSINFO structures. These structures are each specific to a particular namespace, and supply common values such as recommended TCP port numbers or NetWare SAP Identifiers. A service class can be removed by calling WSARemoveServiceClass and supplying the GUID corresponding to the class identifier.
Once a service class exists, specific instances of a service can be installed or removed through WSASetService. This function takes a WSAQUERYSET structure as an input parameter along with an operation code and operation flags. The operation code indicates whether the service is being installed or removed. The WSAQUERYSET structure provides all of the relevant information about the service including service class identifier, service name (for this instance), applicable namespace identifier and protocol information, and a set of transport addresses at which the service listens. Services should invoke WSASetService when they initialize to advertise their presence in dynamic namespaces.
Client Query
The WSAEnumNameSpaceProviders function allows an application to discover which namespaces are accessible through Winsock name resolution facilities. It also allows an application to determine whether a given namespace is supported by more than one namespace provider, and to discover the provider identifier for any particular namespace provider. Using a provider identifier, the application can restrict a query operation to a specified namespace provider.
Winsock namespace–query operations involve a series of calls: WSALookupServiceBegin, followed by one or more calls to WSALookupServiceNext and ending with a call to WSALookupServiceEnd. WSALookupServiceBegin takes a WSAQUERYSET structure as input to define the query parameters along with a set of flags to provide additional control over the search operation. It returns a query handle which is used in the subsequent calls to WSALookupServiceNext and WSALookupServiceEnd.
The application invokes WSALookupServiceNext to obtain query results, with results supplied in an application-supplied WSAQUERYSET buffer. The application continues to call WSALookupServiceNext until the error code WSA_E_NO_MORE is returned indicating that all results have been retrieved. The search is then terminated by a call to WSALookupServiceEnd. The WSALookupServiceEnd function can also be used to cancel a currently pending WSALookupServiceNext when called from another thread.
In Windows Sockets 2, conflicting error codes are defined for WSAENOMORE (10102) and WSA_E_NO_MORE (10110). The error code WSAENOMORE will be removed in a future version and only WSA_E_NO_MORE will remain. For Windows Sockets 2, however, applications should check for both WSAENOMORE and WSA_E_NO_MORE for the widest possible compatibility with namespace providers that use either one.
Helper Functions
The name resolution helper functions include a function to retrieve a service class name given a service class identifier, a pair of functions used to translate a transport address between a SOCKADDR structure and an ASCII string representation, a function to retrieve the service class schema information for a given service class, and a set of macros for mapping well known services to preallocated GUIDs.
The following macros from Winsock2.h aid in mapping between well known service classes and these namespaces:
| Macro | Description |
|---|---|
| SVCID_TCP(Port) SVCID_UDP(Port) SVCID_NETWARE(Object Type) |
Given a port for TCP/IP or UDP/IP or the object type in the case of NetWare, returns the GUID (port number in host order). |
| IS_SVCID_TCP(GUID)IS_SVCID_UDP(GUID) IS_SVCID_NETWARE(GUID) |
Returns TRUE if the GUID is within the allowable range. |
| SET_TCP_SVCID(GUID, port)SET_UDP_SVCID(GUID, port) |
Initializes a GUID structure with the GUID equivalent for a TCP or UDP port number (port number must be in host order). |
| PORT_FROM_SVCID_TCP(GUID)PORT_FROM_SVCID_UDP(GUID) SAPID_FROM_SVCID_NETWARE(GUID) |
Returns the port or object type associated with the GUID (port number in host order). |
Related topics