<?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-D8837969-74D0-5E17-AD42-3F10DD1FD5BF" xml:lang="en"><title>Loader+
−
Search Rules</title><shortdesc>This topic provides a summary of the rules that the loader follows+
−
to search for EXEs and DLLs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>+
−
<ul>+
−
<li id="GUID-D6BAD23C-005E-58E4-8418-16FFBE8AC052"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-D9984B1D-8C7E-55B5-86AC-E90E244BDFB3">Search rules for an EXE</xref>  </p> </li>+
−
<li id="GUID-373C451E-17C1-576C-8D00-6F15174CCD9D"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL in the import table of an EXE or another DLL</xref>  </p> </li>+
−
<li id="GUID-5FD789FB-95A3-51DF-9AD4-FD7474ED9088"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-FA4768B2-A741-5601-990C-46B51DA77803">Search rules for a DLL loaded from a program</xref>  </p> </li>+
−
</ul>+
−
<section id="GUID-D9984B1D-8C7E-55B5-86AC-E90E244BDFB3"><title>Search rules+
−
for an EXE</title> <p>To start a new process, call <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>. </p> <p> <codeph>RProcess::Create()</codeph> loads+
−
the EXE specified in the input parameters. The function then looks through+
−
the import table of the EXE to get a list of DLLs that the EXE references.+
−
The loader uses the list of DLLs in the import table to load the DLLs. If+
−
DLLs reference other DLLS, the loader uses the same method to load those DLLs.+
−
See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search+
−
rules for a DLL listed in the import table of an EXE</xref>. </p> <p>The result+
−
of a search for an EXE depends on: </p> <ul>+
−
<li id="GUID-DC1D5577-2D85-5B9F-B4F4-B10F4208CA46"><p>the name of the EXE.+
−
You provide this information. </p> </li>+
−
<li id="GUID-7BBF1688-8013-5C4D-8C60-09CA0E22D6B5"><p>the UID type : you provide.+
−
This is optional </p> </li>+
−
<li id="GUID-351742AD-AAE3-5050-AF93-DA990309FF37"><p>the version of the EXEs+
−
on the device </p> </li>+
−
</ul> <p>You pass the name of the EXE in the first parameter of <codeph>RProcess::Create()</codeph>.+
−
You have a number of choices: </p> <ul>+
−
<li id="GUID-30C6FEB3-DED9-5BAF-AF3F-700FA8EE58D0"><p>you can specify the+
−
file name only. The loader will assume a <filepath>.exe</filepath> file extension.+
−
For example: </p> <p> <filepath>efile</filepath>  </p> </li>+
−
<li id="GUID-94CD2AC1-5FC5-52D8-893B-E6232522F494"><p>you can specify a filename+
−
and an extension. For example: </p> <p> <filepath>efile.exe</filepath>  </p> </li>+
−
<li id="GUID-06F6A1CF-FD26-5402-983F-E32D2D1F8B90"><p>you can put a path in+
−
front of the file name. A path has limited use, because the loader can load+
−
EXEs only from the directory <filepath>\sys\bin</filepath>, or from subdirectories+
−
of <filepath>\sys\bin</filepath>. </p> </li>+
−
</ul> <p><b>The+
−
search procedure</b> </p> <p>The loader searches for EXEs with the given name+
−
and extension. More than one EXE with the given name and extension can exist+
−
on a device. </p> <ol id="GUID-16CF313D-BAB9-58BB-AB38-ED59BDF572D4">+
−
<li id="GUID-DE4AD994-9C84-5113-B2C7-9030DC08C22E"><p>If you do not provide+
−
a path, the loader searches the <filepath>\sys\bin</filepath> directory on+
−
all drives. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are+
−
not searched. </p> <p>If you provide a path, there are only three useful cases: </p> <ul>+
−
<li id="GUID-3D83CC05-0B68-5CA7-AB52-01A7858E2383"><p>to limit the search+
−
to a specific drive. For example: </p> <p> <filepath>X:\sys\bin</filepath>  </p> <p>where <filepath>X:</filepath> can+
−
be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li>+
−
<li id="GUID-821A186F-9DA4-51E6-9CAD-E833D9DEDF3F"><p>to limit the search+
−
to a subdirectory of <filepath>\sys\bin</filepath> on a specific drive. For+
−
example: </p> <p> <filepath>X:\sys\bin\aaa\bbb</filepath>  </p> <p>The use+
−
of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> <p>where <filepath>X</filepath>:+
−
can be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li>+
−
<li id="GUID-63815160-C411-5BEB-AC8F-7224F33883BE"><p>to limit the search+
−
to a subdirectory of <filepath>\sys\bin</filepath> on all drives. For example: </p> <p> <filepath>\sys\bin\aaa\bbb</filepath>  </p> <p>The+
−
loader searches all drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>.+
−
The <filepath>Z:</filepath> drive is searched last. </p> <p>The use of subdirectories+
−
in <filepath>\sys\bin</filepath> is not common. </p> </li>+
−
</ul> <p>The loader cannot load EXEs from other directories, because system+
−
security prevents it. </p> </li>+
−
<li id="GUID-1AFA13C7-24B4-5598-94CA-448D05449BBA"><p>The loader compares+
−
the UID type (<xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref>) of each EXE in the list with the+
−
UID type you specify in <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>. The UID type+
−
is a set of three UIDs. Each UID in the UID type that you specify must match+
−
the same UID in the UID type of the EXE. If you specify <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref> for+
−
any of the three UIDs in your UID type, a match is automatic. </p> </li>+
−
<li id="GUID-7F8E3D49-F2CB-5445-ACCC-F7967B4C745F"><p>If the search has found+
−
no EXEs, the load fails. </p> </li>+
−
<li id="GUID-1469E256-98FF-51B8-9936-78ED389EDCBE"><p>If the search has found+
−
one EXE only, the loader loads that EXE. </p> </li>+
−
<li id="GUID-90B5C4A5-A0E9-5ADD-B76A-3491C322C4B1"><p>If more than one EXE+
−
has been found, the loader loads the EXE with the highest version. A version <codeph>N.n</codeph> is+
−
higher than version <codeph>M.m</codeph> if <codeph>(N&gt;M or (N==M and n&gt;m))</codeph>. </p> </li>+
−
<li id="GUID-A4761946-0490-5887-9686-184B6BED556C"><p>If all EXEs have the+
−
same version, the loader loads the version found first. </p> </li>+
−
</ol> </section>+
−
<section id="GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5"><title>Search rules+
−
for a DLL in the import table of an EXE or another DLL</title> <p>After the+
−
loader has selected the EXE, the loader loads all DLLs in the import table.+
−
This is also called static linkage. </p> <p>The import table contains the+
−
name and extension of each DLL. The import table also contains the version+
−
of each DLL and the 3rd UID that identifies each DLL. The version information+
−
is stored in the import table when the executable file is built. All DLLs+
−
have an ordered set of three UIDs. The third UID gives a unique identity to+
−
the DLL. See <xref href="GUID-C135B8D8-DA5A-5852-9C2D-18622404FE99.dita">UID protection</xref>. </p> <p><b>The search procedure</b> </p> <p>The search uses the following procedure+
−
for each DLL: </p> <ol id="GUID-FF01C553-8546-5A2C-B34B-8F85014631D6">+
−
<li id="GUID-42FD9744-4B2C-55D6-A7B0-73DE248861DE"><p>The loader searches+
−
the <filepath>\sys\bin</filepath> directory on all drives for all DLLs that+
−
have the filename and extension. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched+
−
last. Subdirectories of <filepath>\sys\bin</filepath> are not searched. The+
−
loader searches for all versions of the DLL. If the loader finds the same+
−
version of a DLL on more than one drive, the loader only adds the first one+
−
to the set of possible DLLs. For example, if version 2.1 of a DLL is on drive <filepath>D:</filepath> and+
−
on drive <filepath>Z:</filepath>, only the version on drive <filepath>D:</filepath> is+
−
added to the set of possible DLLs. </p> <p>The loader cannot load DLLs from+
−
other directories, because system security prevents it. </p> <p>[Before December+
−
2007, the loader had different behaviour. The loader searched the drive from+
−
which the EXE was loaded before the loader checked the other drives. For example,+
−
if the EXE was loaded from drive <filepath>Z:</filepath>, and version 2.1+
−
of a DLL was on drive <filepath>D:</filepath> and drive <filepath>Z:</filepath>,+
−
the loader selected the version of the DLL that was on drive <filepath>Z:</filepath>.] </p> </li>+
−
<li id="GUID-BC036626-7461-5C4E-A710-09D693CE5A1E"><p>The loader then selects+
−
those DLLs that have the same 3rd UID from the set of possible DLLs. This+
−
operation can decrease the set of possible DLLs. If there are no DLLs in the+
−
set, the load fails. </p> </li>+
−
<li id="GUID-9AE6A749-4C72-557F-AB3A-5E33E246A8AE"><p>The loader then selects+
−
those DLLs that have platform security capabilities that match or exceed those+
−
of the EXE. This selection operation can decrease the set of possible DLLs.+
−
If there are no DLLs in the set the load fails. </p> <p>See also : <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">Platform+
−
security</xref>. </p> </li>+
−
<li id="GUID-7F083400-E8FB-52E0-A8CD-D96DDB093F39"><p>Each DLL in the import+
−
table of the EXE has a version number. This number is the version of the DLL+
−
to which the EXE is linked. The loader uses the version number in the import+
−
table to select the correct version of the DLL. The following flowchart shows+
−
how the loader selects the DLL from the set of possible DLLs. </p> <fig id="GUID-1F388A1E-BBB8-5481-8197-1F3C87BB2948">+
−
<image href="GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e269418_href.png" placement="inline"/>+
−
</fig> </li>+
−
<li id="GUID-56B0AF9F-4D39-517B-A3A5-779B7D892CEF"><p>If there are no DLLs+
−
that meet the requirements, the load fails. </p> </li>+
−
</ol> </section>+
−
<section id="GUID-FA4768B2-A741-5601-990C-46B51DA77803"><title>Search rules+
−
for a DLL loaded from a program</title> <p>To load a DLL from a program, call <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>.+
−
This is known as dynamic linking. </p> <p> <codeph>RLibrary::Load()</codeph> loads+
−
the DLL specified in the input parameters. The function then uses the import+
−
table to get a list of referred DLLs. The loader loads the DLLs in the list+
−
and uses the same search method that the loader uses for EXEs. See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL in the import table of an EXE</xref>. </p> <p>The+
−
result of a search for an DLL depends on: </p> <ul>+
−
<li id="GUID-CBC9178F-D0CD-5558-9AA0-338F7CB52479"><p>the name of the DLL.+
−
You provide this information. </p> </li>+
−
<li id="GUID-E735C0C9-CFCE-5A37-8E41-313039AAD44B"><p>the UID type : you provide.+
−
This is optional. </p> </li>+
−
<li id="GUID-14168E41-7825-5546-BD2C-02BB107D2D3C"><p>the required version+
−
: you provide. This is optional. </p> </li>+
−
<li id="GUID-03ED4A5A-813A-5332-BCA5-8735793A4370"><p>the version of the DLLs+
−
on the device. </p> </li>+
−
</ul> <p>You pass the name of the DLL in the first parameter of <codeph>RLibrary::Load()</codeph>.+
−
You have a number of choices: </p> <ul>+
−
<li id="GUID-D5C6F45B-0BCF-58E5-993A-999F96F24354"><p>you can specify the+
−
file name only. The loader will assume a <filepath>.dll</filepath> file extension.+
−
For example: </p> <p> <filepath>efsrv</filepath>  </p> </li>+
−
<li id="GUID-63E96237-0DA1-502E-9C39-4562A31BF616"><p>you can specify a filename+
−
and an extension. For example: </p> <p> <filepath>efsrv.dll</filepath>  </p> </li>+
−
<li id="GUID-B1FC4B22-267B-5B6B-8ADC-62C7012C7925"><p>you can put a path in+
−
front of the file name. A path has limited use, because the loader can load+
−
DLLs only from the directory <filepath>\sys\bin</filepath>, or from subdirectories+
−
of <filepath>\sys\bin</filepath>. </p> </li>+
−
</ul> <p>See <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">Dynamically+
−
loading link libraries</xref> and <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">Using+
−
ECom</xref>. </p> <p><b>The+
−
search procedure</b> </p> <p>The loader searches for DLLs with the given name+
−
and extension. More than one DLL with the given name and extension can exist+
−
on a device. </p> <ol id="GUID-5AA22DFB-F4D1-5358-96DE-D6B43BCB905E">+
−
<li id="GUID-60421212-8123-54A2-9A77-71C39E7EB4B6"><p>If you do not provide+
−
a path, the loader searches the <filepath>\sys\bin</filepath> directory on+
−
all drives. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are+
−
not searched. </p> <p>If you provide a path, there are only three useful cases: </p> <ul>+
−
<li id="GUID-693CCFBB-E1A7-50BD-AC89-95F73E0A569D"><p>to limit the search+
−
to a specific drive. For example: </p> <p> <filepath>X:\sys\bin</filepath>  </p> <p>where <filepath>X:</filepath> can+
−
be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li>+
−
<li id="GUID-F1B66565-1FC3-571D-9CD2-84AE8013F48E"><p>to limit the search+
−
to a subdirectory of <filepath>\sys\bin</filepath> on a specific drive. For+
−
example: </p> <p> <filepath>X:\sys\bin\aaa\bb</filepath>  </p> <p>The use+
−
of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> <p>where <filepath>X:</filepath> can+
−
be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li>+
−
<li id="GUID-AADB293F-8945-5875-B3C2-9B77F938EDEF"><p>to limit the search+
−
to a subdirectory of <filepath>\sys\bin</filepath> on all drives. For example: </p> <p> <filepath>\sys\bin\aaa\bbb</filepath>  </p> <p>The+
−
loader searches all drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>.+
−
The <filepath>Z:</filepath> drive is searched last. </p> <p>The use of subdirectories+
−
in <filepath>\sys\bin</filepath> is not common. </p> </li>+
−
</ul> <p>System security prevents the loader from loading DLLs from any other+
−
directories. </p> </li>+
−
<li id="GUID-F0DD2783-C346-5F30-8691-7BC3F13D8F76"><p>The loader compares+
−
the UID type (<xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref>) of each DLL in the list with the+
−
UID type you specify in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>. The UID type+
−
is a set of three UIDs. Each UID in the UID type that you specify must match+
−
the same UID in the UID type of the DLL. If you specify <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref> for+
−
any of the three UIDs in your UID type, there is a match. </p> </li>+
−
<li id="GUID-F86E7050-500E-5C21-AA70-98DC95E8BB73"><p>If the search has found+
−
no DLLs, the load fails. </p> </li>+
−
<li id="GUID-27848CFE-3B37-5350-83B1-48A2B1E83705"><p>The loader then selects+
−
those DLLs that have platform security capabilities that match or exceed those+
−
of the process . This selection operation can decrease the set of possible+
−
DLLs. If there are no DLLs in the set the load fails. </p> </li>+
−
<li id="GUID-0A421D77-7BE4-5C9F-AB93-F6F0E06342A3"><p>If the search has found+
−
no DLLs, the load fails. </p> </li>+
−
<li id="GUID-A34E59F9-FAD4-54DB-86A6-C2A428710FB8"><p>If you specify a version+
−
number in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>, the loader selects a version+
−
of the DLL from the set. The following flowchart shows how the loader selects+
−
the DLL from the set of possible DLLs. </p> <fig id="GUID-9412E498-19E5-5D58-B913-DD55BBB79D4D">+
−
<image href="GUID-91224821-8094-59ED-A100-4174193A25EE_d0e269709_href.png" placement="inline"/>+
−
</fig> </li>+
−
<li id="GUID-61AE1C0C-A698-5BEC-A5DA-E28CB5D807A3"><p>If there are no DLLs+
−
that meet the requirements, the load fails. </p> </li>+
−
<li id="GUID-D8791217-B11C-548A-9756-10476E843A51"><p>If you do not specify+
−
a version number in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>, the loader loads+
−
the DLL with the highest version. A version <codeph>N.n</codeph> is higher+
−
than version <codeph>M.m</codeph>, if <codeph>(N&gt;M or (N==M and n&gt;m))</codeph>. </p> </li>+
−
<li id="GUID-D43C380A-C315-5C7B-8508-0720EB1E1EEE"><p>If all DLLs have the+
−
same version, the loader loads the DLL found first. </p> </li>+
−
</ol> </section>+
−
</conbody></concept>+
−