PeerDistRegisterForStatusChangeNotification function (peerdist.h)

Article
10/13/2021

The PeerDistRegisterForStatusChangeNotification function requests the Peer Distribution service status change notification.

Syntax

DWORD PeerDistRegisterForStatusChangeNotification(
  [in]           PEERDIST_INSTANCE_HANDLE hPeerDist,
  [in, optional] HANDLE                   hCompletionPort,
  [in, optional] ULONG_PTR                ulCompletionKey,
  [in]           LPOVERLAPPED             lpOverlapped,
  [out]          PEERDIST_STATUS          *pPeerDistStatus
);

Parameters

[in] hPeerDist

A PEERDIST_INSTANCE_HANDLE returned by PeerDistStartup.

[in, optional] hCompletionPort

A handle to the completion port that can be used for retrieving the completion notification of the asynchronous function. To create a completion port, use the CreateIoCompletionPort function. This parameter can be NULL.

[in, optional] ulCompletionKey

Value to be returned through the lpCompletionKey parameter of the GetQueuedCompletionStatus function. This parameter is ignored when hCompletionPort is NULL.

[in] lpOverlapped

Pointer to an OVERLAPPED structure. If the hEvent member of the structure is not NULL, it will be signaled via SetEvent() used in order to signal the notification. This can occur even if the completion port is specified via the hCompletionPort argument.

[out] pPeerDistStatus

A pointer to a PEERDIST_STATUS enumeration that indicates the current status of the Peer Distribution service.

Return value

If the function succeeds, the return value is ERROR_IO_PENDING. Otherwise, the function may return one of the following values:

Return code	Description
ERROR_INVALID_PARAMETER	One or more parameters are invalid.
ERROR_INVALID_HANDLE	The hPeerDist handle is invalid.

Remarks

This function optionally registers a completion port and an OVERLAPPED structure for status change notification. Upon successful completion, the pPeerDistStatus parameter will contain a valid PEERDIST_STATUS value.

Only one active registration for each session is allowed. The caller must register for notification each time after it signals. The notification will be sent only if the current status is changed from the previous notification. After the first call of the PeerDistRegisterForStatusChangeNotification function for the Peer Distribution session, the first notification will trigger only if the status is no longer equal to PEERDIST_STATUS_DISABLED.

A Peer Distribution status change can result in the Peer Distribution service moving to an available, unavailable, or disabled state. If the new status is disabled or unavailable, the content, content information, or stream handles the caller has access to will no longer function. In this case, any API that uses these handles will fail with error PEERDIST_ ERROR_INVALIDATED. The caller must explicitly close the handles by calling the appropriate Peer Distribution API.

Requirements

Requirement	Value
Minimum supported client	Windows 7 Professional [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	peerdist.h
Library	PeerDist.lib
DLL	PeerDist.dll