<?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-49FEF50C-98C8-5789-881E-553164EF5517" xml:lang="en"><title>How
to use CapSearch</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>CapSearch is a tool that allows you to search a ROM log for binaries with
specific capabilities and list them within a report in HTML format.</p>
<p>When using the <codeph>CapSearch</codeph> tool, you need to define the
name and location of the ROM log and the Symbian Capability List. You should
also specify whether to search for <codeph>EXACT</codeph> or <codeph>ALL</codeph> capabilities,
and whether to include all binaries or only the executables in your search.</p>
<p>Along with the HTML report, a list of binaries and capabilities is printed
to standard output, which can be stored as a <filepath>.txt</filepath> file.
The standard output facility can also be used to generate the Expected Capability
List, which is used as input for <codeph>CapCheck</codeph>. </p>
<p>The Expected Capability List is created by specifying no capabilities when
running <codeph>CapSearch</codeph>, and by setting the <codeph>-match</codeph> option
to <codeph>LEAST</codeph>.</p>
<p>The Symbian Capability List is the header file named <filepath>e32capability.h</filepath>,
and can be found in the <filepath>&lt;EPOCROOT&gt;\epoc32\include</filepath> directory.
It lists all the permissible capabilities by name and corresponding number
in hexadecimal format. Either name or number can be used when defining the
capability to be searched.</p>
<section><title>Command line syntax</title> <p>The command line syntax to
be used for <codeph>CapSearch</codeph> is shown below.</p> <p><codeph>&gt;CapSearch.pl
-r &lt;rom_log_file&gt; -s &lt;symbian_capability_list&gt; [-c &lt;capability&gt;]
[-scope &lt;ALL|EXE&gt;] [-match &lt;EXACT|LEAST&gt;] [-R &lt;HTML_report&gt;]</codeph> </p> <p>The
order of the arguments can be modified, as long as the mandatory ones are
used, which are <codeph>-r</codeph> and <codeph>-s</codeph>.</p> <p><b>Arguments</b> </p> <p>The
following arguments are used.</p> <table id="GUID-FCFC1EDF-C185-5B74-A3FC-411A088EA8D6">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>-r &lt;rom_log_file&gt;</codeph> </p> </entry>
<entry><p> The name and location of the ROM log file, in relation to the directory
where the tool is run from, for example <filepath>.\input\rom.log</filepath>.
This flag is mandatory.</p> </entry>
</row>
<row>
<entry><p> <codeph>-s &lt;Symbian_capability_list&gt;</codeph> </p> </entry>
<entry><p>The name of the Symbian Capability List, listing all the capabilities
available to search, and their corresponding values. This flag is mandatory
and the list can be found in <filepath>&lt;EPOCROOT&gt;\epoc32\include\e32capability.h</filepath>.</p> </entry>
</row>
<row>
<entry><p><codeph>-c &lt;capability&gt;</codeph> </p> </entry>
<entry><p>Defines a text string or numerical value for the capability to be
searched. This could be specified several times, i.e. <codeph>-c &lt;capability1&gt;
-c &lt;capability2&gt; -c &lt;capability3&gt;</codeph>. The names and corresponding
numbers are listed in the Symbian Capability List. </p> </entry>
</row>
<row>
<entry><p><codeph>-scope &lt;ALL|EXE&gt;</codeph> </p> </entry>
<entry><p>Defines the scope of the search - whether to only search the executables, <codeph>EXE</codeph>,
within the ROM, or to include all the binaries, <codeph>ALL</codeph>. The
default is <codeph>ALL</codeph>.</p> </entry>
</row>
<row>
<entry><p><codeph>-match &lt;EXACT|LEAST&gt;</codeph> </p> </entry>
<entry><p>Defines how the search should be carried out - whether to report
binaries which contain the specified capability only, <codeph>EXACT</codeph>,
or whether to report binaries which include the specified capability and more, <codeph>LEAST</codeph>.
The default is <codeph>LEAST</codeph>.</p> </entry>
</row>
<row>
<entry><p><codeph>-R &lt;HTML_report&gt;</codeph> </p> </entry>
<entry><p>Defines the name of the HTML report to be generated in the working
directory. If not specified, the default is <filepath>CapSearchReport.html</filepath>. </p> </entry>
</row>
<row>
<entry><p><codeph>-h</codeph> </p> </entry>
<entry><p>Displays help information (optional).</p> </entry>
</row>
</tbody>
</tgroup>
</table> <p><b>Example</b> </p> <p>A full example of how to use the <codeph>CapSearch</codeph> tool
is shown below:</p> <codeblock id="GUID-BD61AFE0-2240-57DD-98C6-0C3DE50A05E8" xml:space="preserve">&gt;CapSearch.pl -r .\input\rom.log -s e32capability.h -c NetworkControl -c ReadUserData -c WriteUserData -scope ALL -match -least -R results.html</codeblock> </section>
</conbody><related-links>
<link href="GUID-9B7BF729-7982-5DFC-AD3C-10D327CA2909.dita"><linktext>CapSearch
 report - file format</linktext></link>
<link href="GUID-54E05FE1-1A71-5293-9FB5-E27D7DF2392B.dita"><linktext>CapCheck
Guide</linktext></link>
<link href="GUID-C244E0D1-DF89-5C86-9C4C-419900BE0DDA.dita"><linktext>CapImportCheck
Guide</linktext></link>
</related-links></concept>