<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-C01412C2-ED4E-501C-8E79-F0293936845A" xml:lang="en"><title>Running
a Command Conditionally in a CommandList</title><shortdesc>A structure for <codeph>conditional_information</codeph> contains
the reasons for conditional values. The software reason and hardware reason
will be defined by an enum and will have a special value. This special value
will mean that the command is unconditional on that ‘reason’. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<context><p>Each command struct in a resource file contains a value of <codeph>LLINK</codeph> that
is called <codeph>conditional_information</codeph>. When loading a command
list the resource file reader makes a decision based upon the value of the <codeph>conditional_information</codeph> which
can either be '0' or a nonzero value. </p> <p> Follow the steps given below
to run a command conditionally in a <codeph>comamandList</codeph>:</p></context>
<steps id="GUID-71EB385B-F7AE-56EB-842E-5C6C299E476C">
<step id="GUID-62F657FC-705B-5E23-9402-79D0148D2CB0"><cmd/>
<info> <codeph>STRUCT SSM_START_PROCESS_INFO</codeph> struct in a resource
file initiates the process as shown in the code snippet: </info>
<stepxmp><codeblock id="GUID-F919AD8A-0385-5672-89C5-8531618B5139" xml:space="preserve">
STRUCT SSM_START_PROCESS_INFO                     // For starting processes
{
    WORD type = EStartupProcess;                  // Must not be changed
    LTEXT path = "";                              // Value required
    LTEXT args = "";                              // Passed to the command line of the started process
    WORD start_method = EFireAndForget;           // Can also be EWaitForStart or EDeferredWaitForStart
    LONG timeout = 0;                             // In milliseconds, only used for EWaitForStart
    WORD fail_on_error = EPanicOnCommandFailure;  // Can be EIgnoreCommandFailure
    WORD no_of_retries_on_failure = 0;            // Only used for EWaitForStart
    LLINK conditional_information = 0;            // By default, commands are unconditional
}</codeblock> </stepxmp>
</step>
<step id="GUID-71942AD3-586F-5E85-99B9-B15D3BB29DC8"><cmd/>
<info>Set the <codeph>LLINK conditional_information</codeph> parameter to
any value. </info>
<substeps id="GUID-0BF78CB6-BFC2-574E-9225-69D3F766E43E">
<substep id="GUID-6F8640AD-F709-5B5E-80DC-636BC9278B74"><cmd/>
<info>If <codeph>LLINK conditional_information</codeph> is <codeph>0</codeph>,
then the resource file reader adds the command to the <codeph>CommandList</codeph>. </info>
</substep>
<substep id="GUID-6692900D-FE18-549D-BF47-E332156DEA20"><cmd/>
<info>If <codeph>LLINK conditional_information</codeph> is <codeph>nonzero</codeph>,
then the resource file reader reads the resource which points to a <codeph>HBufC</codeph>,
and calls a callback function provided by the policy. </info>
</substep>
</substeps>
</step>
<step id="GUID-04B19575-CB50-5EA4-8821-93E0558036AA"><cmd/>
<info>A callback function is passed to the resource file reader by the policy
plug-in calls the resource-file reader. The function that is called has a
prototype similar to: </info>
<stepxmp><codeblock id="GUID-2BFBECDE-DC68-58EA-9DBB-304074143E3C" xml:space="preserve">TBool ConditionalCommandAllowedL( HBufC* information );</codeblock> </stepxmp>
<info>If the return value of this function is <codeph>true</codeph> then the
command is added to the command list by the resource file reader, else it
is discarded. </info>
</step>
</steps>
<result><p>The command is run conditionally in a <codeph>CommandList</codeph>. </p> </result>
</taskbody><related-links>
<link href="GUID-E9FAE433-BDBE-5ABD-B168-6562D29112B1.dita"><linktext>Creating
a Static CommandList</linktext></link>
</related-links></task>