NSPSetService
A version of this page is also available for
4/8/2010
This function registers or deregisters a service instance within a name space.
Syntax
int NSPSetService(
LPGUID lpProviderId,
LPWSASERVICECLASSINFOW lpServiceClassInfo,
LPWSAQUERYSETW lpqsRegInfo,
WSAESETSERVICEOP essOperation,
DWORD dwControlFlags
);
Parameters
- lpProviderId
[in] Pointer to the GUID of the specific name-space provider in which the service is being registered.
- lpServiceClassInfo
[in] Contains service class schema information.
- lpqsRegInfo
[in] Specifies property information to be updated on registration.
essOperation
[in] Enumeration. The following table shows the possible values.Value Description RNRSERVICE_REGISTER
Register the service. For SAP, this means sending out a periodic broadcast. This is an 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 an 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 must match exactly the corresponding CSADD_INFO structure that was supplied when the service was registered.
dwControlFlags
[in] Set of control flags. The following table shows the possible values.Value Description SERVICE_MULTIPLE
Controls scope of operation. 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 specific meanings. The following table shows these meanings.
| 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 name space. 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 name space. |
WSASERVICE_ NOT_FOUND. |
RNRSERVICE_ DELETE |
None |
Removes object from the name space. |
WSASERVICE_ NOT_FOUND. |
RNRSERVICE_ DELETE |
SERVICE _MULTIPLE |
Removes only addresses that are specified. Only removes object from the name space if no addresses remain. |
WSASERVICE_ NOT_FOUND. |
Return Value
If no error occurs, NSPSetService returns NO_ERROR (zero). Otherwise, the function returns SOCKET_ERROR (–1) and it must set the appropriate error code using the SetLastError function.
Note
The default Name Service Provider (for DNS/WINS) in Windows Embedded CE does not support this function and will always return SOCKET_ERROR and set the error code to WSAEOPNOTSUPP.
Remarks
The SERVICE_MULTIPLE parameter 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. Members labeled as (Optional) can be supplied with a NULL pointer.
| WSAQUERYSET member name | Service property description |
|---|---|
dwSize |
Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism. |
DwOuputFlags |
Not applicable and ignored. |
LpszServiceInstanceName |
Referenced string contains the service instance name. |
LpServiceClassId |
GUID corresponding to this service class. |
LpVersion |
(Optional) Supplies service instance version number. |
LpszComment |
(Optional) An optional comment string. |
DwNameSpace |
Ignored for this operation. |
LpNSProviderId |
Ignored for this operation, provider identifier is contained in the lpProviderId parameter. |
LpszContext |
(Optional) Specifies the starting point of the query in a hierarchical name space. |
DwNumberOfProtocols |
Ignored. |
LpafpProtocols |
Ignored. |
LpszQueryString |
Ignored. |
DwNumberOfCsAddrs |
Number of elements in the array of CSADDRO_INFO structures referenced by lpcsaBuffer. |
LpcsaBuffer |
Pointer to an array of CSADDRO_INFO structures that contain the address or addresses that the service is listening on. |
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, signifying a wildcard value. The name-space provider should substitute a value that is reasonable for the given address family and socket type.
Requirements
| Header | ws2spi.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |