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

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51" xml:lang="en"><title>Environment

Slots</title><shortdesc>Up to 16 separate pieces of information can be passed to a process

on creation using Environment Slots. These include handles and binary data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Handles and binary data can be passed to a process at process creation

time using environment slots. This topic describes this concept, and explains

how to use the process APIs for environment slots. </p>

<ul>

<li id="GUID-1D2A9BFD-FAE6-55F0-9A54-58BA4165B1F0"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-FCF8DC31-9D90-53C8-BE30-76D6CD0243BC">Overview</xref>  </p> </li>

<li id="GUID-E2F77CE5-E856-582C-BF4F-0EF13E6A40D1"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-D84521B5-4C3B-538C-946A-88EAA3713A8D">The APIs</xref>  </p> </li>

<li id="GUID-8C3631E9-D240-5C72-A6E0-EF255A3C8D17"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-7F6B118C-0911-5979-8420-475985DB884B">Passing a file handle and a subsession</xref>  </p> </li>

<li id="GUID-3DDB166F-E949-5B0A-B4B9-FC6EE580ECCE"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-19964DED-E6AD-59B4-BEDB-2A40864FBD29">Passing a general handle, derived from RHandleBase</xref>  </p> </li>

<li id="GUID-D6A9288F-5B22-56B8-8F8E-738F7B38BD1E"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-AAB81C64-A515-50E5-BF80-1D625AF1251C">Passing descriptor data</xref>  </p> </li>

<li id="GUID-502C284C-3B56-5B6E-AEB5-F1E9DB513CA6"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-D2F661C6-21EB-50A6-A475-2A4A775A9F4D">Passing an integer</xref>  </p> </li>

<li id="GUID-E5B29175-9647-5F88-961C-47CD20DF2238"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita#GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51/GUID-02AD23DF-7D54-5178-AA5B-050333CD2609">Error handling issues</xref>  </p> </li>

</ul>

<section id="GUID-FCF8DC31-9D90-53C8-BE30-76D6CD0243BC"><title>Overview</title> <p>Handles

and binary data, in the form of descriptors or integer values, can be passed

to a process at process creation time, using what are called environment slots. </p> <p>Up

to 16 separate pieces of information can be passed to a process on creation.

For this purpose, a process has 16 environment slots that can contain the

information passed to it by the launching process. </p> <p>Slot 0 is reserved

and is never available for general purpose information passing. </p> <p>The

parent (launching) process can only pass information to the child (created)

process after the child process has been created. However, it should be done

before the child process is resumed; it is an error to try and set environment

data in a child process that has been resumed. </p> <p>A child process can

only extract the information from its environment slots once. Extracting information

from a slot causes that information to be deleted from the slot. </p> <p>It

is a matter of convention between the parent and child process as to the meaning

to be applied to a slot, and the type of data that it is to contain. </p> </section>

<section id="GUID-D84521B5-4C3B-538C-946A-88EAA3713A8D"><title>The APIs</title> <p>To

pass, a handle, a client server subsession, or binary data to a child process,

the parent process calls <codeph>RProcess::SetParameter()</codeph>, where

the <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita"><apiname>RProcess</apiname></xref> object represents the newly created child

process. There are five overloaded variants of <codeph>SetParameter()</codeph> used

for passing: </p> <table id="GUID-5BEA9FCB-68E8-56DD-BA60-71372984AA38">

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

<tbody>

<row>

<entry><p>handle: </p> </entry>

<entry><codeblock id="GUID-EA9128DD-3694-5A2B-AB86-78BA81B43F5A" xml:space="preserve">TInt RProcess::SetParameter(TInt aSlot, RHandleBase aHandle);</codeblock> </entry>

</row>

<row>

<entry><p>client server subsession: </p> </entry>

<entry><codeblock id="GUID-D7FFAA04-44E4-5C4C-8B3B-4628AB965B58" xml:space="preserve">TInt RProcess::SetParameter(TInt aSlot, const RSubSessionBase&amp; aSession);</codeblock> </entry>

</row>

<row>

<entry><p>8-bit descriptor: </p> </entry>

<entry><codeblock id="GUID-32499AC5-3C9F-5927-A797-24A0367E22A7" xml:space="preserve">TInt RProcess::SetParameter(TInt aSlot, const TDesC8&amp; aDes);</codeblock> </entry>

</row>

<row>

<entry><p>16-bit descriptor: </p> </entry>

<entry><codeblock id="GUID-1997FC14-79C7-5DEC-9647-9FA14CB8EE84" xml:space="preserve">TInt RProcess::SetParameter(TInt aSlot, const TDesC16&amp; aDes);</codeblock> </entry>

</row>

<row>

<entry><p>integer: </p> </entry>

<entry><codeblock id="GUID-0F865FC0-C2D7-55A5-B90A-17F88958F6D9" xml:space="preserve">TInt RProcess::SetParameter(TInt aSlot, TInt aData);</codeblock> </entry>

</row>

</tbody>

</tgroup>

</table> <p>To extract, a handle, or a client server subsession, a child process

can use the <codeph>Open()</codeph> function called on the relevant <xref href="GUID-727D2B62-09A9-3CBC-AB6F-591E52EC68EB.dita"><apiname>RHandleBase</apiname></xref> derived

type: </p> <codeblock id="GUID-244AB92B-34FD-5B45-B0AA-1679D3DD9761" xml:space="preserve">TInt RSemaphore ::Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

TInt RBusLogicalChannel::Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

TInt RMsgQueueBase::Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

TInt RMutex::Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

TInt RChunk::Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

TInt RSessionBase::Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

    </codeblock> <p>To extract descriptor data, or integer data, a child process

can use the <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita"><apiname>User</apiname></xref> class functions: </p> <codeblock id="GUID-CC129A19-0FF6-58C6-B11C-564D816BF845" xml:space="preserve">static TInt User::ParameterLength(TInt aSlot);

static TInt User::GetTIntParameter(TInt aSlot, TInt& aData);

static TInt User::GetDesParameter(TInt aSlot, TDes8& aDes);

static TInt User::GetDesParameter(TInt aSlot, TDes16& aDes);

    </codeblock> <fig id="GUID-D9CD78E1-6813-5F68-9883-F1F6DC04C92A">

<title>Environment slots</title>

<image href="GUID-ABE7BC1A-C51B-5ADD-8568-87A81423B648_d0e307282_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-7F6B118C-0911-5979-8420-475985DB884B"><title> Passing a

file handle and a subsession</title> <p>File server session handles and file

handles can both be passed to a child process. </p> <p>The child process adopts

the file handle, and must not be closed by the parent. To use a file handle,

the session handle must also be passed. </p> <p>For <i>security reasons</i>,

when sharing a file handle, the parent process should create a separate file

server session for the specific purpose of sharing the file handle. If the

parent process has other files open with this file server session, the child

process can gain access to those files by iterating through all the possible

values for the file handle and attempting to <codeph>Adopt()</codeph> each

one. For the same reason, the child process should only use this session for

sharing the file; it should not access other files through this session. </p> <p>The

following two code fragments show code in the parent process and corresponding

code in the child process. </p> <codeblock id="GUID-202421E4-5ADA-50A8-AE75-32F1071C64B0" xml:space="preserve">//Code in the parent (launching) process

    RProcess p;

    p.Create(KProcName, KNullDesC);    //create “child” process

    RFile file;

    RFs session;

    session.Connect();                //connect to file server

    session.ShareProtected();

    file.Create(iSession, KFileName, EFileStreamText|EFileWrite|EFileShareAny);

    file.Write(0, KTestData);

    p.SetParameter(5, session);        //session handle passed in slot 5

    p.SetParameter(6, file);        //file handle passed in slot 6

    Session.Close();

    p.Resume();

  </codeblock> <p> <codeph>KProcName</codeph> is the full path name of the

executable associated with the child process, and <codeph>KFilename</codeph> is

the file name. </p> <codeblock id="GUID-AE2354AA-D95A-5291-BFC4-1EDF470D65AE" xml:space="preserve">//Code in the child (launched) process

    RFs session;

    session.Open(5);            //obtain session handle from slot 5

    RFile file;

    TInt handle;

    ret = User::GetTIntParameter(8, handle);//get file handle from slot 8

    file.Adopt(session, handle);            //adopt the handle

    TBuf8<100> rbuf;                         //use the file

    ret = file.Read(0, rbuf);

    file.Close();

    session.Close();

  </codeblock> </section>

<section id="GUID-19964DED-E6AD-59B4-BEDB-2A40864FBD29"><title> Passing a

general handle, derived from RHandleBase</title> <p>General handles derived

from <xref href="GUID-727D2B62-09A9-3CBC-AB6F-591E52EC68EB.dita"><apiname>RHandleBase</apiname></xref> can be passed to a child process. </p> <p>The

handle is duplicated when it is stored in the child process’s environment.

The parent can close the handle immediately after calling <codeph>SetParameter()</codeph>,

or continue to use the handle and close it later. </p> <p>The following two

code fragments show code in the parent process and corresponding code in the

child process. </p> <codeblock id="GUID-591C111A-05B8-5247-84C1-411650AA1FB0" xml:space="preserve">//Code in the parent (launching) process,

//passing handles to a mutex and a semaphore.

    RMutex mutex;

    RSemaphore sem; 

    RProcess p;

    p.Create(KProcName, KNullDesC);

    mutex.CreateGlobal(KMutexName);    //create the mutex

    sem.CreateGlobal(KSemName,0);    //create the semaphore

    p.SetParameter(3, mutex);    //put mutex handle into child process env' slot 3

    p.SetParameter(4, sem);        //put semaphore handle into child process env' slot 4

    mutex.Close();

    Sem.Close();

    p.Resume();            //resume the child process

    </codeblock> <codeblock id="GUID-78E31AB6-4900-5AE8-9755-8ACDD8265235" xml:space="preserve">//Code in the child (launched) process retrieving the handles.

    RMutex mutex;

    mutex.Open(3, EOwnerThread);    //get mutex handle

    RSemaphore sem;

    sem.Open(4, EOwnerThread);        //get semaphore handle

    //use the semaphore and mutex

    mutex.Close();

    sem.Close();

    </codeblock> </section>

<section id="GUID-AAB81C64-A515-50E5-BF80-1D625AF1251C"><title> Passing descriptor

data</title> <p>Both 8-bit and 16-bit descriptor data can be passed from a

parent to a child process. </p> <p>Internally, an <xref href="GUID-5BEA9976-B969-3949-B855-E657FFF38EE2.dita"><apiname>HBuf</apiname></xref> descriptor

is created containing the passed descriptor data, and a pointer to this descriptor

is passed in the relevant slot. </p> <p>The child process retrieves the descriptor

data by calling <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-54C7406E-C498-3BE7-BB2C-1C5BA902A4D7"><apiname>User::GetDesParameter()</apiname></xref>. It can get the

length of the data by calling <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-ABD3F4AE-C226-3AF1-AD25-7A45B186385C"><apiname>User::ParameterLength()</apiname></xref>. </p> <p>The

following two code fragments show code in the parent process and corresponding

code in the child process. </p> <codeblock id="GUID-57FFCAC9-CA4E-50B7-843A-0523243F5B1E" xml:space="preserve">//Code in the parent (launching) process, passing 8 and sixteen bit data

    RProcess p;

    p.Create(KProcName, KNullDesC);

    p.SetParameter(2, KSixteenBitDes);

    p.SetParameter(3, KEightBitDes);

    p.Resume();

    </codeblock> <p>where <codeph>KSixteenBitDes</codeph> is a 16-descriptor,

and <codeph>KEightBitDes</codeph> is an 8-bit descriptor. </p> <codeblock id="GUID-8B442CA2-0A6A-546C-805B-99C306891B40" xml:space="preserve">//Code in the child (launched) process retrieving 8 and sixteen bit data

    TInt len;

    TInt ret;

    TBuf16<40> buf;

    len = User::ParameterLength(2);        //parameter length is the size in bytes

    ret = User::GetDesParameter(2, buf);

    //buf.Length() should have the value of len/2;

    TBuf8<40> buf8;

    len = User::ParameterLength(3);

    ret = User::GetDesParameter(3, buf8);

    //buf.Length() should be the same as len

    </codeblock> <p>Note that the descriptors, <codeph>buf</codeph>, and <codeph>buf8</codeph> used

in the child process must have sufficiently large maximum lengths to accomodate

the data. </p> </section>

<section id="GUID-D2F661C6-21EB-50A6-A475-2A4A775A9F4D"><title>Passing an

integer</title> <p>An integer can be passed from a parent to a child process. </p> <p>The

following two code fragments show code in the parent process and corresponding

code in the child process. </p> <codeblock id="GUID-AA845210-E551-50B3-9E1F-CD6F8C37D13B" xml:space="preserve">//Code in the parent (launching) process

    RProcess p;

    TInt ret;

    ret = p.Create(KProcName, KNullDesC);

    p.SetParameter(12, 1234);  // Using slot 12

    p.Resume();

    </codeblock> <codeblock id="GUID-D5E4CFA8-15DA-543F-9616-7F075FBBCDC1" xml:space="preserve">//Code in the child (launched) process, retrieving the integer.

    TInt val;

    TInt ret;

    ret = User::GetTIntParameter(12, val);

    </codeblock> </section>

<section id="GUID-02AD23DF-7D54-5178-AA5B-050333CD2609"><title>Error handling

issues</title> <p>The parent process is panicked when calling <codeph>SetParameter()</codeph> with

a handle if: </p> <ul>

<li id="GUID-1BDFA3C0-0E69-5B0C-A27F-D2DEFC0B2C0F"><p>the parent process is

not the creator of the child process </p> </li>

<li id="GUID-1DF3C097-73AC-54B8-9654-435C6F163E95"><p>the slot number is out

of range, i.e. is not in the range 0 to 15 </p> </li>

<li id="GUID-B02324A1-D241-5103-A2EC-297474EF65E1"><p>the slot is in use </p> </li>

<li id="GUID-6014D837-107F-536C-8947-74C5967D2264"><p>the handle is local. </p> </li>

</ul> <p>The parent process is panicked when calling <codeph>SetParameter()</codeph> with

a descriptor or integer if: </p> <ul>

<li id="GUID-2FAF76CC-2569-5E2E-ADBA-AFA124F11C84"><p>the parent process is

not the creator of the child process </p> </li>

<li id="GUID-C23722B2-4EEB-5050-B82E-F58F450F088F"><p>the slot number is out

of range, i.e. is not in the range 0 to 15 </p> </li>

<li id="GUID-9ADA7D18-B084-509C-8F4A-66E885F61D0A"><p>the slot is in use </p> </li>

<li id="GUID-32B64BAC-F13E-5029-93ED-642994E35886"><p>the length of the data

is negative. </p> </li>

</ul> <p>The child process is panicked if the slot number is out of range. </p> <p>The

API functions that extract data from the process environment return <xref href="GUID-0BEA3647-7888-3612-A2D3-7E27AC405E29.dita"><apiname>KErrArgument</apiname></xref> if

a slot contains the incorrect data type, or the length is incorrect. They

return <xref href="GUID-5E653C17-372C-32E1-A1B2-9E69A9991C40.dita"><apiname>KErrNotFound</apiname></xref> if a slot is empty. </p> </section>