WSASetService Function
The WSASetService function registers or removes from the registry a service instance within one or more namespaces. This function can be used to affect a specific namespace provider, all providers associated with a specific namespace, or all providers across all namespaces.
Syntax
INT WSASetService(
__in LPWSAQUERYSET lpqsRegInfo,
__in WSAESETSERVICEOP essOperation,
__in DWORD dwControlFlags
);
Parameter
lpqsRegInfo [in]
Pointer to the service information for registration or deregistration.essOperation [in]
Enumeration whose values include those shown in the following table.Wert Bedeutung RNRSERVICE_REGISTER Register the service. For SAP, this means sending out a periodic broadcast. This is an NOP for the DNS namespace. For persistent data stores, this means updating the address information.
RNRSERVICE_DEREGISTER Remove the service from the registry. For SAP, this means stop sending out the periodic broadcast. This is an NOP for the DNS namespace. 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 specified address will be deleted, and this must match exactly the corresponding CSADDR_INFO structure that was specified when the service was registered.
dwControlFlags [in]
Meaning of dwControlFlags is dependent on the following values.Flag Bedeutung SERVICE MULTIPLE Controls scope of operation. When clear, service addresses are managed as a group. A register or removal from the registry 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 removal from the registry only invalidates the given set of addresses.
Rückgabewert
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 code | Meaning |
|---|---|
| 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. |
Hinweise
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 | 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.
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 computer. 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 remove the aborted address from the registry 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 remove these old stale addresses from the registry before registering new addresses.
Hinweis If ANSI character strings are used, there is a chance that the WSAQUERYSET data in lpqsRegInfo 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 it back to ANSI. This primarily impacts transports that return a "service record handle" used to uniquely identify a record. To work around this issue, please 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. |
Anforderungen
Mindestens unterstützter Client |
Windows 2000 Professional |
Mindestens unterstützter Server |
Windows 2000 Server |
Header |
Winsock2.h |
Bibliothek |
Ws2_32.lib |
DLL |
Ws2_32.dll |
Unicode- und ANSI-Namen |
WSASetServiceW (Unicode) and WSASetServiceA (ANSI) |