WSASetService

The Windows Sockets WSASetService function registers or deregisters a service instance within one or more name spaces. This function can be used to affect a specific name space provider, all providers associated with a specific name space, or all providers across all name spaces.

INT WSASetService(
  LPWSAQUERYSET lpqsRegInfo,  
  WSAESETSERVICEOP essOperation,  
  DWORD dwControlFlags        
);

Parameters

lpqsRegInfo

[in] A pointer to the service information for registration or deregistration.

essOperation

[in] An enumeration whose values include:

RNRSERVICE_REGISTER: Register the service. For SAP, this means sending out a periodic broadcast. This is a NOP for the DNS name space. For persistent data stores, this means updating the address information.
RNRSERVICE_DEREGISTER: Deregister the service. For SAP, this means stop sending out the periodic broadcast. This is a NOP for the DNS name space. For persistent data stores this means deleting address information.
RNRSERVICE_DELETE: 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 much match exactly the corresponding CSADD_INFO structure that was supplied when the service was registered.

dwControlFlags

[in] The meaning of dwControlFlags is dependent on the following values:

Flag	Meaning
SERVICE MULTIPLE	Controls scope of operation. When clear, service addresses are managed as a group. A register or deregister invalidates all existing addresses before adding the given address set. When set, the action is only performed on the given address set. A register does not invalidate existing addresses and a deregister only invalidates the given set of addresses.

The available values for essOperation and dwControlFlags combine to give meanings as shown in the following table:

Operation	Flags	Service already exists	Service does not exist
RNRSERVICE _REGISTER	none	Overwrite the object. Use only addresses specified. Object is REGISTERED.	Create a new object. Use only addresses specified. Object is REGISTERED.
RNRSERVICE _REGISTER	SERVICE _MULTIPLE	Update object. Add new addresses to existing set. Object is REGISTERED.	Create a new object. Use all addresses specified. Object is REGISTERED.
RNRSERVICE _DEREGISTER	none	Remove all addresses, but do not remove object from name space. Object is DEREGISTERED.	WSASERVICE _NOT_FOUND
RNRSERVICE _DEREGISTER	SERVICE _MULTIPLE	Update object. Remove only addresses that are specified. Only mark object as DEREGISTERED if no addresses present. Do not remove from the name space.	WSASERVICE _NOT_FOUND
RNRSERVICE _DELETE	none	Remove object from the name space.	WSASERVICE _NOT_FOUND
RNRSERVICE _DELETE	SERVICE _MULTIPLE	Remove only addresses that are specified. Only remove object from the name space if no addresses remain.	WSASERVICE _NOT_FOUND

Remarks

SERVICE_MULTIPLE lets an application manage its addresses independently. This is useful when the application wants to manage its protocols individually or when the service resides on more than one machine. For instance, when a service uses more than one protocol, it may find that one listening socket aborts but the others remain operational. In this case, the service could deregister the aborted address without affecting the other addresses.

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

Service Properties

The following table describes how service property data is represented in a WSAQUERYSET structure. Fields labeled as (Optional) can be supplied with a NULL pointer.

WSAQUERYSET Field Name	Service Property Description
Field Name	Service Property Description
dwSize	Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism.
DwOutputFlags	Not applicable and ignored.
LpszServiceInstanceName	Referenced string contains the service instance name.
LpServiceClassId	The GUID corresponding to this service class.
lpVersion	(Optional) Supplies service instance version number.
LpszComment	(Optional) An optional comment string.
DwNameSpace	See table below.
LpNSProviderId	See table below.
LpszContext	(Optional) Specifies the starting point of the query in a hierarchical name space.
DwNumberOfProtocols	Ignored.
LpafpProtocols	Ignored.
LpszQueryString	Ignored.
DwNumberOfCsAddrs	The number of elements in the array of CSADDRO_INFO structures referenced by lpcsaBuffer.
LpcsaBuffer	A pointer to an array of CSADDRO_INFO structures that contain the address(es) that the service is listening on.
lpBlob	(Optional) This is a pointer to a provider-specific entity.

As illustrated below, the combination of the dwNameSpace and lpNSProviderId parameters determine that name space providers are affected by this function.

dwNameSpace	lpNSProviderId	Scope of Impact
Ignored	Non-NULL	The specified name space provider
a valid name space ID	NULL	All name space providers that support the indicated name space
NS_ALL	NULL	All name space providers

Return Values

The return value for WSASetService is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSAEACCES	The calling routine does not have sufficient privileges to install the Service.
WSAEINVAL	One or more required parameters were invalid or missing.
WSANOTINITIALIZED	The WiS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions
WSA NOT ENOUGH MEMORY	There was insufficient memory to perform the operation.
WSASERVICE NOT FOUND	No such service is known. The service cannot be found in the specified name space.

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Unsupported.
  Header: Declared in winsock2.h.
  Import Library: Link with ws2_32.lib.