Symbian3/SDK/Source/GUID-80F2A7AC-6E86-54F2-96F0-4417A2AEA017.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     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>