PNRP and WSASetService
PNRP uses the WSASetService function to register or remove peer names.
Registering a Name
Registration includes a peer name and set of endpoints where a service can be contacted. A registration is specific to a PNRP cloud. After a peer is registered, there is a delay between the registration and the propagation of the registration information to other nodes. During this time, other nodes may not be able to resolve a newly registered peer.
Service registration is not persistent.
- If a client process that registers a peer name exits or calls WSACleanup, then the peer name is unregistered.
- If a specified peer name is already registered in the same cloud by the current process, it is replaced with new registration values.
When registering a peer name, the following parameter values must be indicated:
- essOperation parameter must have a value of RNRSERVICE_REGISTER.
- dwControlFlags parameter must be zero (0).
When registering a peer name, the LPWSAQUERYSET structure referenced by the lpqsRegInfo parameter must contain the following values:
-
dwSize
-
Specifies the size of this structure.
-
lpszServiceInstanceName
-
Specifies a peer name to register. If the peer name is unsecured, then the identity is optional. If the identity is specified as NULL, PNRP uses the machine local identity—by default.
-
lpServiceClassID
-
Must be SVCID_PNRPNAME.
-
lpVersion
-
Ignored. Set to NULL.
-
lpszComment
-
Ignored. However, the string is still required to be fewer than 40 characters, including the NULL terminator.
-
dwNameSpace
-
Must be either NS_PNRPNAME or NS_ALL.
-
lpNSProviderID
-
Must be either NS_PROVIDER_PNRPNAME or NULL.
-
lpszContext
-
Must be a cloud name, an empty string, or NULL. If this value is NULL or an empty string, the default cloud, "Global", is used. Otherwise, it must point to a valid cloud name.
-
dwNumberOfProtocols
-
Ignored. Set to zero (0).
-
lpszQueryString
-
Ignored. Set to NULL.
-
dwNumberOfCsAddrs
-
Specifies the number of addresses registered by a service. The maximum number of addresses that can be registered for a single name is 10.
-
lpcsaBuffer
-
Pointer to a list of addresses to register.
-
dwOutputFlags
-
Ignored. Set to zero (0).
-
lpBlob
-
Pointer to a BLOB structure that points to a PNRPINFO structure. Specific parameters in the PNRPINFO structure must be set. For more information, see the following PNRPINFO structure section.
PNRPINFO Structure
If the lpBlob member of the LPWSAQUERYSET structure is set, the following members of the PNRPINFO structure must be set:
-
dwSize
-
Specifies the size of this structure.
-
lpwszIdentity
-
Specifies the identity of the peer name that is created by using PeerIdentityCreate. If a peer name is unsecured, then the identity is optional. If the identity is specified as NULL, PNRP uses the computer local identity—by default.
-
nMaxResolve
-
Ignored. Set to zero (0).
-
dwTimeout
-
Ignored. Set to zero (0).
-
dwLifetime
-
Specifies the number of seconds between refresh operations.
-
enResolveCriteria
-
Ignored. Set to zero (0).
-
dwFlags
-
Must be either zero (0) or PNRPINFO_HINT. The default is zero (0). This means that the service location portion of the PNRP ID is built by using the IP address in saHint. Otherwise, the service location is built by using the first IP address in the first IPv6 entry of the lpcsaBuffer member.
-
saHint
-
Specifies the IPv6 address for the hint.
-
enNameState
-
Ignored. Set to zero (0).
Unregistering a Peer Name
The following list identifies the important information about unregistering a peer name.
- Only an application that registers a peer name can unregister it.
- A peer name is unregistered automatically if WSACleanup is called.
- PNRP always removes the entire service name registration. It does not allow removal of individual addresses.
- When unregistering a name, the essOperation parameter must have a value of RNRSERVICE_DELETE.
- PNRP does not support the value RNRSERVICE_DEREGISTER.
- The dwControlFlags parameter must be zero (0).
When unregistering a name, the LPWSAQUERYSET structure that the lpqsRegInfo parameter references must contain the following values:
-
dwSize
-
Specifies the size of this structure.
-
lpszServiceInstanceName
-
Specifies a peer name to unregister.
-
lpServiceClassID
-
Must be SVCID_PNRPNAME.
-
lpVersion
-
Ignored. Set to NULL.
-
lpszComment
-
Ignored. Set to NULL.
-
dwNameSpace
-
Must be either NS_PNRPNAME or NS_ALL.
-
lpNSProviderID
-
Must be either NS_PROVIDER_PNRPNAME or NULL.
-
lpszContext
-
Must be a cloud name, an empty string, or NULL. If this value is NULL or an empty string, the default cloud, "Global" is used. Otherwise, it must point to a valid cloud name.
-
dwNumberOfProtocols
-
Ignored. Set to zero (0).
-
lpszQueryString
-
Ignored. Set to NULL.
-
dwNumberOfCsAddrs
-
Ignored. Set to NULL.
-
lpcsaBuffer
-
Ignored. Set to NULL.
-
dwOutputFlags
-
Ignored. Set to zero (0).
-
lpBlob
-
Pointer to a BLOB structure that points to a PNRPINFO structure. The lpszIdentity member of the lpBlob structure identifies the name of the identity that is used to register a peer name. The remaining members must be set to the same values that are used when registering a name.
Related topics
-
WSASetService
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for