NSPSetService

The NSPSetService function registers or deregisters a service instance within a name space.

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 that this service is being registered in.
lpServiceClasslnfo
[in] Contains service class schema information.
lpqsRegInfo
[in] Specifies property information to be updated upon registration.
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 must match exactly the corresponding CSADD_INFO structure that was supplied when the service was registered.
dwControlFlags
[in] A set of control flags whose values include:
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
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 The 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 ID 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 The number of elements in the array of CSADDRO_INFO structures referenced by lpcsaBuffer.
lpcsaBuffer A pointer to an array of CSADDRO_INFO structures which contain the address[es] that the service is listening on.
lpBlob (Optional) This is a pointer to a provider-specific entity.

Note It is legal for the iProtocol field 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 the address family and socket type.

Return Values

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 SetLastError.

Error Codes

WSAEACCES The calling routine does not have sufficient privileges to install the service.
WSAEINVAL One or more parameters were invalid or missing for this provider.
WSA_NOT_ENOUGH_MEMORY Not enough free memory available to perform this 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 ws2spi.h.