What +asynchronous service providers do

Request functions and the request status

An asynchronous +service provider offers one or more request functions.

Only +one request on a service provider can be outstanding at any one time. A request +function is one that takes a TRequestStatus& parameter +or, in rare cases, a TRequestStatus* parameter.

When +a request function is called (or when the asynchronous service provider is +constructed, opened or initialized), the handle of the client thread is noted +by the asynchronous service provider, so it knows which thread made the request. +A panic results if any other thread tries to use the asynchronous service +provider — for instance, to call its cancel function, or to issue another +request — since the client of an asynchronous service provider is assumed +to be a single thread.

The asynchronous service provider's request +function:

first sets the value +of the passed TRequestStatus to KRequestPending
then initiates the request, +which may complete any time later.

There are several typical cases:

the request completes +normally some time after the request function has returned.
the request completes +during the request function call, either because the request completes immediately, +or because of an error such as bad parameters meaning that the request cannot +even be initiated.
some other type of abnormal +completion such as cancellation, which can occur either during the request +function call or later.

Thread request semaphore

When a request completes, +the client thread’s request semaphore is signalled to indicate completion.

Each +thread has a single request semaphore. A thread which uses asynchronous services +must have a program whose main loop waits on the thread’s request semaphore +for any outstanding request to complete.

When any request completes, +the thread program must identify which of the outstanding requests has completed. +It does this by checking the TRequestStatus object associated +with each outstanding request and, if its value is not KRequestPending, +the program knows that the request is complete and can handle the completion +of that request.

Cancel functions

All asynchronous service providers +provide one or more cancel functions, which cancel any outstanding +request.

Because of the asynchronous nature of requests, a cancel function +may be called after the request has actually completed. For this reason, a +cancel function should be viewed as a request for early completion. +If you issue a cancel, the asynchronous service provider may complete the +request abnormally by posting KErrCancel in the request status +object, or it may complete the request normally by posting an appropriate +completion code.