3.2.4.1.6 AsyncPoll (Opnum 5)

  • Article

The AsyncPoll method is used to register an asynchronous callback, associated with an outbound connection, which the server uses to provide version chain vectors and notifications of version chain vector changes to the client.

 DWORD AsyncPoll(
   [in] FRS_CONNECTION_ID connectionId,
   [out] FRS_ASYNC_RESPONSE_CONTEXT* response
 );

connectionId: The GUID of an outbound connection (see the objectGUID attribute specified in section 2.3.11) that the client established by a previous call to the EstablishConnection method.

response: The FRS_ASYNC_RESPONSE_CONTEXT structure that contains the context for the requested poll.

Return Values: This method MUST return 0 on success or a nonzero error code on failure. For protocol purposes all nonzero values MUST be treated as equivalent failures unless otherwise specified.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The method completed successfully.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Validating the asynchronous poll request: The server validates the asynchronous poll request by performing the following checks:

  • If an outbound connection for the specified connection is not established between the client and server (see the EstablishConnection method), then the server MUST fail the call with an implementation-defined failure value.

Actions Triggered: Upon successfully validating the asynchronous poll request, the server MUST register the callback with the specified outbound connection.

The server invokes the callback in response to a client call to the RequestVersionVector method. The conditions under which the callback is invoked are determined by the type of the version vector request issued by the client. See the RequestVersionVector method specified in section 3.2.4.1.5 for more information.

The client SHOULD NOT issue more than one call to the AsyncPoll method for a particular outbound connection without an intervening call to the RequestVersionVector method. The server MUST ensure that no more than one AsyncPoll callback is registered with an outbound connection at the same time. If an AsyncPoll request is already registered with the outbound connection, the server MUST replace the pre-existing AsyncPoll callback with the new AsyncPoll callback. The pre-existing callback MUST be completed with an implementation-defined failure value.