<?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-F14A2C1F-7803-5D93-B871-6AAC30F50115" xml:lang="en"><title>Calling

a Custom Command</title><shortdesc>This section describes the how to call the custom command with

the parameters. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<context><p> <codeph>STRUCT SSM_START_CUSTOM_COMMAND</codeph> is an API to

start synchronous or asynchronous custom command. Custom commands are implemented

using the <xref href="GUID-DEDD8780-C422-3239-ACDC-A66D209992E6.dita"><apiname>MSsmCustomCommand</apiname></xref> interface. It can be called

with parameters. This functionality is provided by the <codeph>dll_info</codeph> part

of the custom command struct. </p> <p><b>Required background</b></p><p>Before

you start, you must know:</p><ul>

<li><p>File name for the DLL containing this custom command.</p></li>

<li><p>Ordinal of the position of the custom command creation function in

the specified DLL.</p></li>

<li><p>A link to a resource containing data to be passed as a parameter to

the custom command (optional).</p></li>

</ul><p><b>Procedure</b></p><p>Follow the steps given below to call a custom

command:</p></context>

<steps id="GUID-38AF9DBD-A973-5319-8D0C-309CBD56A672">

<step id="GUID-8FB256A0-F9A8-5EAA-A6B1-D4BB5326B86F"><cmd/>

<info>Create a custom command as shown in the code snippet. </info>

<stepxmp><codeblock id="GUID-9AF71EED-DE52-5459-8EF7-50179547F2CC" xml:space="preserve">CreateCustomCommand::CreateCustomCommand()</codeblock> </stepxmp>

</step>

<step id="GUID-122D2B5C-15DA-5AAD-BE30-E16C917C0EB0"><cmd/>

<info>Initialize the custom command as shown in the code snippet. </info>

<stepxmp><codeblock id="GUID-CB9868B4-1EDC-5C21-B429-E3E2B201CF40" xml:space="preserve">TInt CreateCustomCommand::Initialize( CSsmCustomCommandEnv* aCmdEnv )</codeblock> </stepxmp>

</step>

<step id="GUID-E52563F4-D40D-5F57-8F4E-E9461CEF1E2C"><cmd/>

<info>Call the custom command using <codeph>SSM_START_CUSTOM_COMMAND</codeph> as

shown in the code snippet. </info>

<stepxmp><codeblock id="GUID-0D3E1107-2EAC-5F8A-A01A-B53BDE25B596" xml:space="preserve">

// Valid ESsmWaitForStart struct with data

RESOURCE SSM_START_CUSTOM_COMMAND r_command_custom_cmd1

{

    severity = ECmdCriticalSeverity;

    execution_behaviour = ESsmWaitForStart;

    dllname = "tcust_cmd.dll";

    ordinal = 1;

    unload_on_finish = EUnloadImmediately;

    retries = 3;

    dll_data = r_command_custom_cmd_good_data;

}

// Custom command data

RESOURCE SSM_COMMAND_CUSTOM_CMD_DATA r_command_custom_cmd_good_data

{

    val1 = '1';

    val2 = '2';

    val3 = '3';

    val4 = '4';

    val5 = '5';

}

</codeblock> </stepxmp>

</step>

</steps>

<result><p>The custom command is called. </p> </result>

</taskbody><related-links>

<link href="GUID-EFBBB53F-8402-5010-8B8D-96D0FC46F784.dita"><linktext>Creating

a Custom Command</linktext></link>

<link href="GUID-63F2124B-9B41-58D8-9439-CE4D8C3503D8.dita"><linktext>Running a

Custom Command</linktext></link>