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-80F2A7AC-6E86-54F2-96F0-4417A2AEA017" xml:lang="en"><title>Handle-numbers</title><shortdesc>This document describes the use of handle-numbers to identify handles.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    13 <p>A handle is a way in which a thread or process can identify an object that

    14 is owned or managed by another thread or process. Such objects are Kernel

    15 side objects.</p>

    16 <p>A handle uses a number, the handle-number, to identify the associated Kernel

    17 side object. The handle, an instance of a <codeph>RHandleBase</codeph> derived

    18 class, encapsulates the handle-number.</p>

    19 <p>The objects referred to by handles are always instances of <codeph>CObject</codeph> derived

    20 classes, i.e. they are reference counting objects. The handle-number is created

    21 when the object is created (or opened, if the object already exists) and added

    22 to an object index.</p>

    23 <p>Typically, calling <codeph>Open()</codeph> or <codeph>Create()</codeph> or

    24 a similarly named function on an <codeph>RHandleBase</codeph>  <i>derived</i> class

    25 causes the associated object to be created or opened and added to an object

    26 index, owned either by the thread or the process. Adding the object to the

    27 object index creates a handle-number and this is returned to, and encapsulated

    28 by, the handle.</p>

    29 <p>For example, <codeph>RMutex</codeph> is the handle for a mutex; all user

    30 side interaction with a specific mutex is directed through an instance of <codeph>RMutex</codeph>.

    31 The <codeph>RMutex</codeph> object exists on the user side; the corresponding

    32 mutex (a DMutex object) exists on the Kernel side.</p>

    33 <fig id="GUID-86253ED0-C374-52C5-BF3E-463D09A3ECD3">

    34 <image href="GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e205603_href.png" placement="inline"/>

    35 </fig>

    36 <p>Here, code running on the user side constructs an <codeph>RMutex</codeph> and

    37 calls its <codeph>Create()</codeph> member function. This causes the Kernel

    38 to:</p>

    39 <ul>

    40 <li id="GUID-69E652C5-BC3E-5C2C-95DE-8F0BC5DF6C13"><p>construct the corresponding

    41 Kernel object, a <codeph>DMutex</codeph> </p> </li>

    42 <li id="GUID-CA86B942-A4CA-5E9E-BA36-2E581C01C646"><p>add the <codeph>DMutex</codeph> to

    43 the current thread's object index (a <codeph>CObjectIx</codeph>)</p> </li>

    44 <li id="GUID-6BD33635-074D-59CB-BB7E-1AF6F0290481"><p>return the handle-number

    45 to the RMutex.</p> </li>

    46 </ul>

    47 <codeblock id="GUID-96432516-6FC7-584C-843D-17D0E07956CB" xml:space="preserve">...

    48 RMutex m;

    49 m.Create();

    50 ...</codeblock>

    51 <p>See also:</p>

    52 <ul>

    53 <li id="GUID-B218DFCC-054D-53ED-9C36-9947C1BC2895"><p><xref href="GUID-A95CDFDE-285F-5DE2-AADE-29B2B9663757.dita">The

    54 object index</xref> </p> <p><xref href="GUID-8C4EB8E0-78F0-553D-91AE-EC070A47B0EE.dita">The

    55 handle-number and the object index</xref> </p> <p><xref href="GUID-A52E8853-9A8A-5B66-A2B0-F943B32AA5C6.dita">Reference

    56 counting objects</xref> </p> </li>

    57 </ul>

    58 </conbody></concept>