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