PNRP and WSALookupServiceBegin

PNRP uses the WSALookupServiceBegin function to start the process that allows an application to do the following:

• Resolving a name
• Enumerating network clouds

Clients that attempt to perform one of the functions use the WSALookupServiceBegin, WSALookupServiceNext, and WSALookupServiceEnd functions.

By using WSANSPIoctl, the lookup service can be used asynchronously. For information about using the lookup service functions asynchronously, see PNRP and WSANSPIoctl.

The process for working with peer names is different from working with clouds. Each process is described separately in this topic.

Resolving a Name

An application uses WSALookupServiceBegin to obtain the IP address, port, and protocol for a peer service that is registered on another computer. The WSALookupServiceBegin function is used to start the name resolution process, and set up the parameters and restrictions. A handle is returned, and must be used when calling WSALookupServiceNext and WSANSPIoctl.

lpqsRestrictions

When resolving a peer name, the LPWSAQUERYSET structure that the lpqsRestrictions parameter references must contain the following values:

dwSize

Specifies the size of this structure.

lpszServiceInstanceName

Specifies a peer name to resolve.

lpServiceClassID

Must be SVCID_PNRPNAME.

lpVersion

Reserved, must be NULL.

lpszComment

Reserved, must be 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

Reserved, must be zero (0).

lpszQueryString

Reserved, must be NULL.

dwNumberOfCsAddrs

Reserved, must be zero (0).

lpcsaBuffer

Reserved, must be NULL.

dwOutputFlags

Reserved, must be zero (0).

lpBlob

Must be either a pointer to a BLOB structure or NULL. If it is NULL, default values are used. If it is set, lpBlob points to a PNRPINFO structure, and specific parameters in the PNRPINFO structure must be set. For more information, see the following descriptions for the PNRPINFO Structure.

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

Reserved, must be NULL.

nMaxResolve

Specifies the requested number of resolutions.

dwTimeout

Specifies the requested timeout period to wait for responses. The default is 30 seconds. The maximum is 600 seconds (10 minutes).

dwLifetime

Reserved, must be zero (0).

enResolveCriteria

Must be one of the allowed values. The default is PNRP_RESOLVE_CRITERIA_NON_CURRENT_PROCESS_PEER_NAME. Valid values are specified by PNRP_RESOLVE_CRITERIA.

dwFlags

Must be either zero (0) or PNRPINFO_HINT. The default is zero (0).

saHint

Specifies the IP address for the hint. The hint is used when attempting to find the nearest peer name. The format of the hint is an IPv6 address. If saHint is not specified when finding the closest peer name, then an IPv6 address of the local computer is used instead. This member is ignored if dwFlags is not set.

enNameState

Reserved, must be zero (0).

dwControlFlags

The following LUP_RETURN_* flags are supported by PNRP:

Enumerating Network Clouds

lpqsRestrictions

When enumerating clouds, the LPWSAQUERYSET structure that the lpqsRestrictions parameter references must contain the following values:

dwSize

Specifies the size of this structure.

lpszServiceInstanceName

Must be NULL.

lpServiceClassID

Must be SVCID_PNRPCLOUD.

lpVersion

Reserved, must be NULL.

lpszComment

Reserved, must be NULL.

dwNameSpace

Must be NS_PNRPCLOUD.

lpNSProviderID

Must be either NS_PROVIDER_PNRPCLOUD or NULL.

lpszContext

Reserved, must be NULL.

dwNumberOfProtocols

Reserved, must be zero (0).

lpszQueryString

Reserved, must be NULL.

dwNumberOfCsAddrs

Reserved, must be zero (0).

lpcsaBuffer

Reserved, must be NULL.

dwOutputFlags

Reserved, must be zero (0).

lpBlob

Pointer to a BLOB structure that points to a PNRPCLOUDINFO structure. If lpBlob is NULL, all clouds are enumerated.

PNRPCLOUDINFO Structure

When enumerating clouds, the following members of the PNRPCLOUDINFO structure must be set:

dwSize

Specifies the size of this structure.

Cloud

Points to a structure that specifies criteria that you can use to filter search results. The Cloud.Scope member can be PNRP_SCOPE_ANY, PNRP_GLOBAL_SCOPE, PNRP_SITE_LOCAL_SCOPE, or PNRP_LINK_LOCAL_SCOPE. If PNRP_SCOPE_ANY is specified, all clouds are returned. Otherwise, only clouds that match the Cloud.Scope are returned.

enCloudState

Reserved, must be zero (0).

dwControlFlags

The following LUP_RETURN_* flags are supported by PNRP:

Related topics

PNRP and BLOB

PNRP and WSALookupServiceEnd

PNRP and WSALookupServiceNext

PNRP and WSANSPIoctl

PNRP and WSAQUERYSET

PNRPCLOUDINFO

PNRPINFO

PNRP NSP Error Codes