LPNSPSETSERVICE callback function (ws2spi.h)

Article
10/13/2021

The NSPSetService function registers or deregisters a service instance within a namespace.

Syntax

LPNSPSETSERVICE Lpnspsetservice;

INT Lpnspsetservice(
  [in] LPGUID lpProviderId,
  [in] LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in] LPWSAQUERYSETW lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags
)
{...}

Parameters

[in] lpProviderId

A pointer to the GUID of the specific namespace provider in which the service is registered.

[in] lpServiceClassInfo

The service class schema information.

[in] lpqsRegInfo

The property information to be updated upon registration.

[in] essOperation

The type of operation requested.

This parameter can be one of the values from the WSAESETSERVICEOP enumeration type defined in the Winsock2.h header file.

Value	Meaning
RNRSERVICE_REGISTER 0	Register the service. For the Service Advertising Protocol (SAP) namespace used within a NetWare environment, this means sending a periodic broadcast. This is an NOP for the Domain Name System (DNS) namespace. For persistent data stores this means updating the address information.
RNRSERVICE_DEREGISTER 1	Deregister the service. For the SAP namespace, this means stop sending the periodic broadcast. This is a NOP for the DNS namespace. For persistent data stores this means deleting address information.
RNRSERVICE_DELETE 2	Delete the service from dynamic name and persistent spaces. For services represented by multiple CSADDR_INFO structures (using the SERVICE_MULTIPLE flag), only the supplied address will be deleted, and this must match exactly the corresponding CSADDR_INFO structure supplied when the service was registered.

[in] dwControlFlags

A set of flags that controls the service operation requested.

The possible values for this parameter are defined in the Winsock2.h header file.

Value	Meaning
SERVICE_MULTIPLE 0x00000001	Control the scope of the operation. When this value is set, the action is only performed on the given address set. A register operation does not invalidate existing addresses and a deregister operation only invalidates the given set of addresses. When this value is absent, service addresses are managed as a group. A register or deregister invalidates all existing addresses before adding the given address set.

Value

Meaning

SERVICE_MULTIPLE

0x00000001

Control the scope of the operation.

When this value is set, the action is only performed on the given address set. A register operation does not invalidate existing addresses and a deregister operation only invalidates the given set of addresses.

When this value is absent, service addresses are managed as a group. A register or deregister invalidates all existing addresses before adding the given address set.

Return value

The function should return NO_ERROR (zero) if the routine succeeds. It should return SOCKET_ERROR (–1) if the routine fails and it must set the appropriate error code using WSASetLastError.

Error code	Meaning
WSAEACCES	The calling routine does not have sufficient privileges to install the service.
WSA_NOT_ENOUGH_MEMORY	There is not enough memory available to perform this operation.
WSAEINVAL	One or more parameters were invalid, or missing, for this provider.
WSAEOPNOTSUPP	The operation is not supported. This error is returned if the namespace provider does not implement this function.
WSASERVICE_NOT_FOUND	Service is unknown. The service cannot be found in the specified namespace.

Remarks

The following table lists the available values for essOperation and dwControlFlags.

Operation	Flags	Service already exists	Service does not exist
RNRSERVICE_REGISTER	None	Overwrites the object. Uses only addresses specified. Object is REGISTERED.	Creates a new object. Uses only addresses specified. Object is REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Updates object. Adds new addresses to existing set. Object is REGISTERED.	Creates a new object. Uses all addresses specified. Object is REGISTERED.
RNRSERVICE_DEREGISTER	None	Removes all addresses, but does not remove object from namespace. Object is DEREGISTERED.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Updates object. Removes only addresses that are specified. Only mark object as DEREGISTERED if no addresses are present. Does not remove from the namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	None	Removes object from the namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Removes only addresses that are specified. Only removes object from the namespace if no addresses remain.	WSASERVICE_NOT_FOUND

When the dwControlFlags parameter is set to SERVICE_MULTIPLE, this enables an application to manage its addresses independently. This is useful when the application must manage its protocols individually or when the service resides on more than one computer. For example, when a service uses more than one protocol, one listening socket may abort, but the other sockets remain operational. In this example, the service could deregister the aborted address without affecting the other addresses.

When using SERVICE_MULTIPLE, an application must not let old addresses remain in the object. This can happen if the application aborts without issuing a RNRSERVICE_DEREGISTER request. When a service registers, it should store its addresses. On its next call, the service should explicitly deregister these old addresses before registering new addresses.

Service Properties

The following table lists WSAQUERYSET member names and describes how service property data is represented. Members labeled as (Optional) can be supplied with a null pointer.

WSAQUERYSET member name	Service property description
dwSize	Set to the sizeof(WSAQUERYSET). This is a versioning mechanism.
lpszServiceInstanceName	The referenced string contains the service instance name.
lpServiceClassId	The GUID that corresponds to this service class.
lpVersion	Optional. Supplies the service instance version number.
lpszComment	Optional. An optional comment string.
dwNameSpace	Ignored for this operation.
lpNSProviderId	Ignored for this operation. The provider identifier is contained in the lpProviderId parameter.
lpszContext	Optional. The starting point of the query in a hierarchical namespace.
dwNumberOfProtocols	Ignored for this operation.
lpafpProtocols	Ignored for this operation.
pszQueryString	Ignored for this operation.
dwNumberOfCsAddrs	The number of elements in the array of CSADDR_INFO structures referenced by lpcsaBuffer.
lpcsaBuffer	A pointer to an array of CSADDR_INFO structures that contain the address or addresses that the service is listening on.
dwOutputFlags	Ignored for this operation.
lpBlob	Optional. Pointer to a provider-specific entity.

**Note** It is acceptable for the **iProtocol** member of the CSADDR_INFO structure to contain the manifest constant **IPROTOCOL_ANY**, indicating a wildcard value. The namespace provider should substitute an acceptable value for the given address family and socket type.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ws2spi.h