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 task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-C01412C2-ED4E-501C-8E79-F0293936845A" xml:lang="en"><title>Running

    13 a Command Conditionally in a CommandList</title><shortdesc>A structure for <codeph>conditional_information</codeph> contains

    14 the reasons for conditional values. The software reason and hardware reason

    15 will be defined by an enum and will have a special value. This special value

    16 will mean that the command is unconditional on that ‘reason’. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

    17 <context><p>Each command struct in a resource file contains a value of <codeph>LLINK</codeph> that

    18 is called <codeph>conditional_information</codeph>. When loading a command

    19 list the resource file reader makes a decision based upon the value of the <codeph>conditional_information</codeph> which

    20 can either be '0' or a nonzero value. </p> <p> Follow the steps given below

    21 to run a command conditionally in a <codeph>comamandList</codeph>:</p></context>

    22 <steps id="GUID-71EB385B-F7AE-56EB-842E-5C6C299E476C">

    23 <step id="GUID-62F657FC-705B-5E23-9402-79D0148D2CB0"><cmd/>

    24 <info> <codeph>STRUCT SSM_START_PROCESS_INFO</codeph> struct in a resource

    25 file initiates the process as shown in the code snippet: </info>

    26 <stepxmp><codeblock id="GUID-F919AD8A-0385-5672-89C5-8531618B5139" xml:space="preserve">

    27 STRUCT SSM_START_PROCESS_INFO                     // For starting processes

    28 {

    29     WORD type = EStartupProcess;                  // Must not be changed

    30     LTEXT path = "";                              // Value required

    31     LTEXT args = "";                              // Passed to the command line of the started process

    32     WORD start_method = EFireAndForget;           // Can also be EWaitForStart or EDeferredWaitForStart

    33     LONG timeout = 0;                             // In milliseconds, only used for EWaitForStart

    34     WORD fail_on_error = EPanicOnCommandFailure;  // Can be EIgnoreCommandFailure

    35     WORD no_of_retries_on_failure = 0;            // Only used for EWaitForStart

    36     LLINK conditional_information = 0;            // By default, commands are unconditional

    37 }</codeblock> </stepxmp>

    38 </step>

    39 <step id="GUID-71942AD3-586F-5E85-99B9-B15D3BB29DC8"><cmd/>

    40 <info>Set the <codeph>LLINK conditional_information</codeph> parameter to

    41 any value. </info>

    42 <substeps id="GUID-0BF78CB6-BFC2-574E-9225-69D3F766E43E">

    43 <substep id="GUID-6F8640AD-F709-5B5E-80DC-636BC9278B74"><cmd/>

    44 <info>If <codeph>LLINK conditional_information</codeph> is <codeph>0</codeph>,

    45 then the resource file reader adds the command to the <codeph>CommandList</codeph>. </info>

    46 </substep>

    47 <substep id="GUID-6692900D-FE18-549D-BF47-E332156DEA20"><cmd/>

    48 <info>If <codeph>LLINK conditional_information</codeph> is <codeph>nonzero</codeph>,

    49 then the resource file reader reads the resource which points to a <codeph>HBufC</codeph>,

    50 and calls a callback function provided by the policy. </info>

    51 </substep>

    52 </substeps>

    53 </step>

    54 <step id="GUID-04B19575-CB50-5EA4-8821-93E0558036AA"><cmd/>

    55 <info>A callback function is passed to the resource file reader by the policy

    56 plug-in calls the resource-file reader. The function that is called has a

    57 prototype similar to: </info>

    58 <stepxmp><codeblock id="GUID-2BFBECDE-DC68-58EA-9DBB-304074143E3C" xml:space="preserve">TBool ConditionalCommandAllowedL( HBufC* information );</codeblock> </stepxmp>

    59 <info>If the return value of this function is <codeph>true</codeph> then the

    60 command is added to the command list by the resource file reader, else it

    61 is discarded. </info>

    62 </step>

    63 </steps>

    64 <result><p>The command is run conditionally in a <codeph>CommandList</codeph>. </p> </result>

    65 </taskbody><related-links>

    66 <link href="GUID-E9FAE433-BDBE-5ABD-B168-6562D29112B1.dita"><linktext>Creating

    67 a Static CommandList</linktext></link>

    68 </related-links></task>