<?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 <rom_log_file> -s <symbian_capability_list> [-c <capability>]

[-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>