The name resolution functions can be grouped into three categories: Service installation, client queries, and helper functions (and macros). The sections that follow identify the functions in each category and briefly describe their intended use. Key data structures are also described.
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 ID, and a series of WSANSCLASSINFO structures. These structures are each specific to a particular name space, 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 ID.
Once a service class exists, specific instances of a service can be installed or removed via 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 ID, service name (for this instance), applicable name space identifier and protocol information, and a set of transport addresses at which the service listens. Services should invoke WSASetService when they initialize in order to advertise their presence in dynamic name spaces.
The WSAEnumNameSpaceProviders function allows an application to discover which name spaces are accessible via Windows Sockets's name resolution facilities. It also allows an application to determine whether a given name space is supported by more than one name space provider, and to discover the provider ID for any particular name space provider. Using a provider ID, the application can restrict a query operation to a specified name space provider.
Windows Sockets' name space query operations involves 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 in order 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 Socket 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 Socket 2, however, applications should check for both WSAENOMORE and WSA_E_NO_MORE for the widest possible compatibility with Name Space Providers that use either one.
The name resolution helper functions include a function to retrieve a service class name given a service class ID, a pair of functions used to translate a transport address between a sockaddr struct 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 pre-allocated GUIDs.
The following macros from winsock2.h aid in mapping between well known service classes and these name spaces.
| 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, return 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) |