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.

See also

Asynchronous service provider's responsibilities.