Asynchronous Operations

Since these data exchanges are done over the network, their completion time is variable, and in any case, longer than synchronous calls. Doing it asynchronously avoids freezing the application waiting for the operation completion.

An asynchronous operation is initiated from a call to a method having a suffix ***_Async. Unlike the notification handler which needs being registered, the application gives this method a pointer to a special type of notification handler (suffixed with ***_AsyncReturnHandler) in the argument set, and receives an CPNS::IAsync pointer in return. This pointer is helpful to cancel the operation or identify its instance when a single asynchronous return handler object is shared between multiple concurrent operations.

Additionally, an asynchronous call has a user pointer argument allowing the association of custom data to the operation.

An asynchronous operation can take a while up to the point it is not needed anymore. It is possible to cancel it using CPNS::ICHAI::CancelAsync method.

Note

An asynchronous operation is using an internal Task to maintain the context during the remote procedure call. By default a two-second timeout automatically cancels the operation in the absence of response. This timeout can be disabled for debugging purposes using CPNS::ICHAI::SetAsyncTimeouts.

An AsyncReturnHandler interface usually contains a single method declaration. Independently of the operation success or failure, this method will always be called and provide a pointer to the related CPNS::IAsync, together a flag indicating success or failure, and additional data depending on the nature of the async operation. The user pointer can be retrieved using CPNS::IAsync::GetUserPointer().

Warning

the CPNS::IAsync pointer becomes invalid as soon as the call to the async return handler is finished.

Similarly to notifications, a hooked object pointer received from an async return handler must be acquired if the application needs keeping if for a while, and then released when not needed anymore.

Example of asynchronous operation call:

//From interface IRemoteDevice:
CPNS::IAsync* GetInputInformation_Async(
            IN CPNS::uint16 const wInputID,
            IN CPNS::IRemoteDevice_XXXInputInfo_AsyncReturnHandler * const pHandler,
            IN void* const pUserPointer = NULL
            );

Example of asynchronous return handler:

//From interface IRemoteDevice_XXXInputInfo_AsyncReturnHandler :
void OnRemoteDevice_XXXInputInfo_Return(
            IN CPNS::IAsync * const pAsync,
            IN CPNS::boolean const fSuccess,
            IN CPNS::uint16 const wInputID,
            IN CPNS::UTF8String const & strName,
            IN CPNS::CombinedInOutCapabilities const inCaps
            );