<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<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>
<p>A handle is a way in which a thread or process can identify an object that
is owned or managed by another thread or process. Such objects are Kernel
side objects.</p>
<p>A handle uses a number, the handle-number, to identify the associated Kernel
side object. The handle, an instance of a <codeph>RHandleBase</codeph> derived
class, encapsulates the handle-number.</p>
<p>The objects referred to by handles are always instances of <codeph>CObject</codeph> derived
classes, i.e. they are reference counting objects. The handle-number is created
when the object is created (or opened, if the object already exists) and added
to an object index.</p>
<p>Typically, calling <codeph>Open()</codeph> or <codeph>Create()</codeph> or
a similarly named function on an <codeph>RHandleBase</codeph>  <i>derived</i> class
causes the associated object to be created or opened and added to an object
index, owned either by the thread or the process. Adding the object to the
object index creates a handle-number and this is returned to, and encapsulated
by, the handle.</p>
<p>For example, <codeph>RMutex</codeph> is the handle for a mutex; all user
side interaction with a specific mutex is directed through an instance of <codeph>RMutex</codeph>.
The <codeph>RMutex</codeph> object exists on the user side; the corresponding
mutex (a DMutex object) exists on the Kernel side.</p>
<fig id="GUID-86253ED0-C374-52C5-BF3E-463D09A3ECD3">
<image href="GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e205603_href.png" placement="inline"/>
</fig>
<p>Here, code running on the user side constructs an <codeph>RMutex</codeph> and
calls its <codeph>Create()</codeph> member function. This causes the Kernel
to:</p>
<ul>
<li id="GUID-69E652C5-BC3E-5C2C-95DE-8F0BC5DF6C13"><p>construct the corresponding
Kernel object, a <codeph>DMutex</codeph> </p> </li>
<li id="GUID-CA86B942-A4CA-5E9E-BA36-2E581C01C646"><p>add the <codeph>DMutex</codeph> to
the current thread's object index (a <codeph>CObjectIx</codeph>)</p> </li>
<li id="GUID-6BD33635-074D-59CB-BB7E-1AF6F0290481"><p>return the handle-number
to the RMutex.</p> </li>
</ul>
<codeblock id="GUID-96432516-6FC7-584C-843D-17D0E07956CB" xml:space="preserve">...
RMutex m;
m.Create();
...</codeblock>
<p>See also:</p>
<ul>
<li id="GUID-B218DFCC-054D-53ED-9C36-9947C1BC2895"><p><xref href="GUID-A95CDFDE-285F-5DE2-AADE-29B2B9663757.dita">The
object index</xref> </p> <p><xref href="GUID-8C4EB8E0-78F0-553D-91AE-EC070A47B0EE.dita">The
handle-number and the object index</xref> </p> <p><xref href="GUID-A52E8853-9A8A-5B66-A2B0-F943B32AA5C6.dita">Reference
counting objects</xref> </p> </li>
</ul>
</conbody></concept>