1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-1BD987D8-B018-51B7-80B2-4E1988841BC2" xml:lang="en"><title>How

    13 to cancel requests</title><shortdesc>This document describes how to cancel a previously scheduled request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>The <codeph>CActive</codeph> class provides the <codeph>Cancel()</codeph> member

    15 function to cancel an active object’s request.</p>

    16 <p>If no request has been issued, <codeph>Cancel()</codeph> does nothing,

    17 otherwise it calls <codeph>DoCancel()</codeph>. This is a pure virtual function

    18 that must be provided by derived classes and which handles specific cancellation

    19 as required by the service provider. <codeph>Cancel()</codeph> then waits

    20 for the completion of that request and sets the active request flag to false.</p>

    21 <p>The service provider must guarantee that the cancellation operation completes

    22 in a very short period of time.</p>

    23 <p>For example, a specialized timer active object, derived from <codeph>CTimer</codeph> which

    24 is derived from <codeph>CActive</codeph>, might implement this as:</p>

    25 <codeblock id="GUID-2454885F-9410-5E9F-A72E-618E78D32500" xml:space="preserve">void CTimedMessenger::DoCancel()

    26     {

    27       // Base class

    28     CTimer::DoCancel(); 

    29       // Reset variable - needed if the object is later re-activated

    30     iTicksDone = 0;

    31     ...

    32     }</codeblock>

    33 <p>Note that an active object's destructor should ensure that any outstanding

    34 requests are cancelled. If the class implements a DoCancel() function, then

    35 the destructor must call the <codeph>Cancel()</codeph> member function. For

    36 example:</p>

    37 <codeblock id="GUID-1C265422-8C45-5ED2-A2F8-DFF68C08BF9C" xml:space="preserve">CTimedMessenger::~CTimedMessenger()

    38     {

    39     Cancel();

    40     }</codeblock>

    41 </conbody></concept>