How to handle a single asynchronous request

This document describes how to handle a single asynchronous request.

A thread that requests an asynchronous service from another thread can continue processing but eventually reaches a point where it must wait until the asynchronous request is complete before it can resume processing.

Typically, the requester performs the following sequence:

creates an object of type TRequestStatus to monitor the state of the request.
calls the asynchronous provider's request function, passing the TRequestStatus object; all asynchronous functions are prototyped to take a TRequestStatus parameter.
uses the operating system function User::WaitForRequest() to allow the thread to wait for completion of the request.

TRequestStatus status;                        // Request status object
someProvider.IssueRequest(parameters,status); // Issue the request
...
User::WaitForRequest(status);                 // Wait for completion
if (status==KErrNone)
    {
    /* success */
    }
else if (status==KErrXxx)
    {
    /* check for some error */
    }
else // check for other error conditions etc.
...

Notes

there is no special name for a request function; the request performed depends on the class, the function name and the parameters passed.
when the request is complete, an integer is stored in the request status object to convey additional information about the completion of the function. The meaning of the completion code varies from function to function. Additionally, information returned by the request may be returned to reference parameters passed to the request function.
The integer completion code must not be KErrPending. By convention, KErrNone indicates no error and KErrCancel indicates a cancelled request. Other values may be used for specific types of error.