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-49FEF50C-98C8-5789-881E-553164EF5517" xml:lang="en"><title>How

    13 to use CapSearch</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>CapSearch is a tool that allows you to search a ROM log for binaries with

    15 specific capabilities and list them within a report in HTML format.</p>

    16 <p>When using the <codeph>CapSearch</codeph> tool, you need to define the

    17 name and location of the ROM log and the Symbian Capability List. You should

    18 also specify whether to search for <codeph>EXACT</codeph> or <codeph>ALL</codeph> capabilities,

    19 and whether to include all binaries or only the executables in your search.</p>

    20 <p>Along with the HTML report, a list of binaries and capabilities is printed

    21 to standard output, which can be stored as a <filepath>.txt</filepath> file.

    22 The standard output facility can also be used to generate the Expected Capability

    23 List, which is used as input for <codeph>CapCheck</codeph>. </p>

    24 <p>The Expected Capability List is created by specifying no capabilities when

    25 running <codeph>CapSearch</codeph>, and by setting the <codeph>-match</codeph> option

    26 to <codeph>LEAST</codeph>.</p>

    27 <p>The Symbian Capability List is the header file named <filepath>e32capability.h</filepath>,

    28 and can be found in the <filepath>&lt;EPOCROOT&gt;\epoc32\include</filepath> directory.

    29 It lists all the permissible capabilities by name and corresponding number

    30 in hexadecimal format. Either name or number can be used when defining the

    31 capability to be searched.</p>

    32 <section><title>Command line syntax</title> <p>The command line syntax to

    33 be used for <codeph>CapSearch</codeph> is shown below.</p> <p><codeph>&gt;CapSearch.pl

    34 -r <rom_log_file> -s <symbian_capability_list> [-c <capability>]

    35 [-scope &lt;ALL|EXE&gt;] [-match &lt;EXACT|LEAST&gt;] [-R &lt;HTML_report&gt;]</codeph> </p> <p>The

    36 order of the arguments can be modified, as long as the mandatory ones are

    37 used, which are <codeph>-r</codeph> and <codeph>-s</codeph>.</p> <p><b>Arguments</b> </p> <p>The

    38 following arguments are used.</p> <table id="GUID-FCFC1EDF-C185-5B74-A3FC-411A088EA8D6">

    39 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

    40 <tbody>

    41 <row>

    42 <entry><p> <codeph>-r &lt;rom_log_file&gt;</codeph> </p> </entry>

    43 <entry><p> The name and location of the ROM log file, in relation to the directory

    44 where the tool is run from, for example <filepath>.\input\rom.log</filepath>.

    45 This flag is mandatory.</p> </entry>

    46 </row>

    47 <row>

    48 <entry><p> <codeph>-s &lt;Symbian_capability_list&gt;</codeph> </p> </entry>

    49 <entry><p>The name of the Symbian Capability List, listing all the capabilities

    50 available to search, and their corresponding values. This flag is mandatory

    51 and the list can be found in <filepath>&lt;EPOCROOT&gt;\epoc32\include\e32capability.h</filepath>.</p> </entry>

    52 </row>

    53 <row>

    54 <entry><p><codeph>-c &lt;capability&gt;</codeph> </p> </entry>

    55 <entry><p>Defines a text string or numerical value for the capability to be

    56 searched. This could be specified several times, i.e. <codeph>-c &lt;capability1&gt;

    57 -c &lt;capability2&gt; -c &lt;capability3&gt;</codeph>. The names and corresponding

    58 numbers are listed in the Symbian Capability List. </p> </entry>

    59 </row>

    60 <row>

    61 <entry><p><codeph>-scope &lt;ALL|EXE&gt;</codeph> </p> </entry>

    62 <entry><p>Defines the scope of the search - whether to only search the executables, <codeph>EXE</codeph>,

    63 within the ROM, or to include all the binaries, <codeph>ALL</codeph>. The

    64 default is <codeph>ALL</codeph>.</p> </entry>

    65 </row>

    66 <row>

    67 <entry><p><codeph>-match &lt;EXACT|LEAST&gt;</codeph> </p> </entry>

    68 <entry><p>Defines how the search should be carried out - whether to report

    69 binaries which contain the specified capability only, <codeph>EXACT</codeph>,

    70 or whether to report binaries which include the specified capability and more, <codeph>LEAST</codeph>.

    71 The default is <codeph>LEAST</codeph>.</p> </entry>

    72 </row>

    73 <row>

    74 <entry><p><codeph>-R &lt;HTML_report&gt;</codeph> </p> </entry>

    75 <entry><p>Defines the name of the HTML report to be generated in the working

    76 directory. If not specified, the default is <filepath>CapSearchReport.html</filepath>. </p> </entry>

    77 </row>

    78 <row>

    79 <entry><p><codeph>-h</codeph> </p> </entry>

    80 <entry><p>Displays help information (optional).</p> </entry>

    81 </row>

    82 </tbody>

    83 </tgroup>

    84 </table> <p><b>Example</b> </p> <p>A full example of how to use the <codeph>CapSearch</codeph> tool

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

    86 </conbody><related-links>

    87 <link href="GUID-9B7BF729-7982-5DFC-AD3C-10D327CA2909.dita"><linktext>CapSearch

    88  report - file format</linktext></link>

    89 <link href="GUID-54E05FE1-1A71-5293-9FB5-E27D7DF2392B.dita"><linktext>CapCheck

    90 Guide</linktext></link>

    91 <link href="GUID-C244E0D1-DF89-5C86-9C4C-419900BE0DDA.dita"><linktext>CapImportCheck

    92 Guide</linktext></link>

    93 </related-links></concept>