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-5872329F-2B52-5F52-83C1-205F2F933877" xml:lang="en"><title>OR_LEAVE

    13 macro Tutorial</title><shortdesc>Macro is a rule or pattern that specifies how a certain input sequence

    14 should be mapped to an output sequence according to a defined procedure. This

    15 tutorial describes the OR_LEAVE macro and provides details on how the OR_LEAVE

    16 macro should be used. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    17 <section><title>Required background</title> <p>Before beginning you must know

    18 the following: </p> <ul>

    19 <li id="GUID-13B9C89C-BFF4-553F-B647-034322ADFAE2"><p> <xref href="GUID-611F17E3-DC06-33B7-AE5E-E69B5AEC5969.dita"><apiname>UserLeaveIfError()</apiname></xref> <b> :</b> Error

    20 handling code. This function is called when a client is passing a file for

    21 a server to handle. </p> </li>

    22 </ul> </section>

    23 <section><title>Introduction</title> <p>The OR_LEAVE macro is a convenience

    24 macro that allows the developer to deemphasize auxiliary error checking code

    25 in most cases. It is a postfix macro which implements <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-96AFAC46-F3AD-392B-8A97-AFCBF2978CFB"><apiname>User::LeaveIfError()</apiname></xref> on

    26 an integer return type. This means that there is less focus on the error handling

    27 code and makes the code easier to read. </p> <title>Defining a OR_LEAVE macro </title> <p>The

    28 OR_LEAVE macro is defined as a postfix operator. An example code snippet is

    29 shown below: </p> <codeblock id="GUID-031AA312-AB5E-5B0F-940C-33DD71A82BCC" xml:space="preserve">

    30 #define OR_LEAVE || Eleave

    31 inline void operator||(Tint aStatus, Tleave /*aTag*/)

    32     {

    33     User::LeaveIfError(aStatus);

    34     }

    35 </codeblock> <p>It is a postfix macro which implements <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-96AFAC46-F3AD-392B-8A97-AFCBF2978CFB"><apiname>User::LeaveIfError()</apiname></xref> function

    36 on an integer return type. This means that there is less focus on the error

    37 handling code and makes the code easier to read. </p> </section>

    38 <section><title>Using OR_LEAVE macro</title><p>The <codeph>OR_LEAVE</codeph> 

    39 is used to replace a call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-96AFAC46-F3AD-392B-8A97-AFCBF2978CFB"><apiname>User::LeaveIfError()</apiname></xref> function.

    40 An example code snippet is shown below:  </p><codeblock xml:space="preserve">User::LeaveIfError(iTimer-&gt;CreateLocal());</codeblock><p>The

    41 call to <codeph>iTimer-&gt;CreateLocal()</codeph> is included within the error

    42 handling code <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-96AFAC46-F3AD-392B-8A97-AFCBF2978CFB"><apiname>User::LeaveIfError()</apiname></xref> function and is difficult

    43 to read. The following fragment uses the <codeph>OR_LEAVE</codeph> macro. </p><codeblock xml:space="preserve">iTimer-&gt;CreateLocal() OR_LEAVE;

    44 </codeblock></section>

    45 </conbody><related-links>

    46 <link href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita"><linktext>EUser High

    47 Level Library  Overview</linktext></link>

    48 </related-links></concept>