WSASetServiceA

The WSASetService function registers or removes from the registry a service instance within one or more namespaces.

Syntax

INT WSASetServiceA(
         LPWSAQUERYSETA lpqsRegInfo,
         WSAESETSERVICEOP essoperation,
         DWORD dwControlFlags
)

Parameters

lpqsRegInfo
Type: LPWSAQUERYSETA

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

essoperation
Type: WSAESETSERVICEOP

[in]

dwControlFlags
Type: DWORD

[in]

Service install flags value that further controls the operation performed of the WSASetServicefunction. The possible values for this parameter are defined in the Winsock2.h header file.

Return value

Type: INT

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.

Return codes

Return code	Description
WSAEACCES	The calling routine does not have sufficient privileges to install the Service.
WSAEINVAL	One or more required parameters were invalid or missing.
WSANOTINITIALISED	The Ws2_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.

Remarks

The WSASetService function can be used to affect a specific namespace provider, all providers associated with a specific namespace, or all providers across all namespaces.

The available values for essOperation and dwControlFlags combine to control operation of the WSASetService function as shown in the following table.

Operation	Flags	Service already exists	Service does not exist
RNRSERVICE_REGISTER	None	Overwrites the object. Uses only addresses specified. The object is REGISTERED.	Creates a new object. Uses only addresses specified. Object is REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Updates the object. Adds new addresses to the existing set. The object is REGISTERED.	Creates a new object. Uses all addresses specified. Object is REGISTERED.
RNRSERVICE_DEREGISTER	None	Removes all addresses, but does not remove the object from the namespace. The object is removed from the registry.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Updates the object. Removes only addresses that are specified. Only marks the object as DEREGISTERED if no addresses are present. Does not remove the object from the namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	None	Removes the 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

Publishing services to directories, such as Active Directory Services, is restricted based on access control lists (ACLs). For more information, see Security Issues for Service Publication.

When the dwControlFlags parameter is set to SERVICE_MULTIPLE, an application can 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 computer. For instance, when a service uses more than one protocol, it may find that one listening socket aborts but the other sockets remain operational. In this case, the service could remove the aborted address from the registry without affecting the other addresses.

When the dwControlFlags parameter is set to 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 remove these old stale addresses from the registry before registering new addresses.

Note

If ANSI character strings are used, there is a chance that the WSAQUERYSET data in lpqsRegInfo may not contain any results after this function returns. This is because the ANSI version of this method, WSASetServiceA, converts the ANSI data in WSAQUERYSET to Unicode internally, but does not convert the results back to ANSI. This primarily impacts transports that return a “service record handle” used to uniquely identify a record. To work around this issue, applications should use Unicode string data in WSAQUERYSET when calling this function.

Service Properties

The following table describes how service property data is represented in a WSAQUERYSET structure. Fields labeled as (Optional) can contain a null pointer.

WSAQUERYSET member	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 that follows.
lpNSProviderId	See table that follows.
lpszContext	(Optional) Specifies the starting point of the query in a hierarchical namespace.
dwNumberOfProtocols	Ignored.
lpafpProtocols	Ignored.
lpszQueryString	Ignored.
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(es) that the service is listening on.
lpBlob	(Optional) This is a pointer to a provider-specific entity.

As illustrated in the following, the combination of the dwNameSpace and lpNSProviderId members determine that namespace providers are affected by this function.

dwNameSpace	lpNSProviderId	Scope of impact
Ignored	Non-null	The specified name-space provider.
A valid name- space identifier	Null	All name-space providers that support the indicated namespace.
NS_ALL	Null	All name-space providers.

Windows Phone 8: This API is supported.

Requirements

Header: Declared in winsock2.h.

Library: Use ws2_32.lib.