CApaCommandLine Class Reference

#include <mw/apacmdln.h>

Link against: apparc.lib

class CApaCommandLine : public CBase, public CBase

Inherits from

CApaCommandLine
- CBase
- CBase

Public Member Enumerations
enum	anonymous { EIpcFirstFreeSlot }

Public Member Functions
	~CApaCommandLine()
IMPORT_C TInt	AppStartupInstrumentationEventIdBase()
IMPORT_C TApaCommand	Command()
IMPORT_C void	ConstructCmdLineFromMessageL(const RMessage2 &)
IMPORT_C TInt	DebugMemFail()
IMPORT_C TInt	DefaultScreen()
IMPORT_C TPtrC	DocumentName()
IMPORT_C TInt	EnvironmentSlotForPublicUse(TInt)
IMPORT_C TPtrC	ExecutableName()
IMPORT_C TInt	GetCommandLineFromProcessEnvironment(CApaCommandLine *&)
IMPORT_C void	GetFileByHandleL(RFile &)
IMPORT_C void	GetIpcArgsLC(TIpcArgs &)
IMPORT_C TBool	IsDefaultScreenSet()
IMPORT_C CApaCommandLine *	NewL()
IMPORT_C CApaCommandLine *	NewLC()
IMPORT_C TInt	NumberOfEnvironmentSlotsForPublicUse()
IMPORT_C TPtrC8	OpaqueData()
IMPORT_C TProcessId	ParentProcessId()
IMPORT_C TInt	ParentWindowGroupID()
IMPORT_C TUint	ServerRequired()
IMPORT_C void	SetAppStartupInstrumentationEventIdBaseL(TInt)
IMPORT_C void	SetCommandL(TApaCommand)
IMPORT_C void	SetDebugMemFailL(TInt)
IMPORT_C void	SetDefaultScreenL(TInt)
IMPORT_C void	SetDocumentNameL(const TDesC &)
IMPORT_C void	SetExecutableNameL(const TDesC &)
IMPORT_C void	SetFileByHandleL(const RFile &)
IMPORT_C void	SetOpaqueDataL(const TDesC8 &)
IMPORT_C void	SetParentProcessId(TProcessId)
IMPORT_C void	SetParentWindowGroupID(TInt)
IMPORT_C void	SetProcessEnvironmentL(RProcess &)
IMPORT_C void	SetServerNotRequiredL()
IMPORT_C void	SetServerRequiredL(TUint)
IMPORT_C void	SetTailEndL(const TDesC8 &)
IMPORT_C TPtrC8	TailEnd()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Information for launching an application.

To start an application, passed a CApaCommandLine object to the RApaLsSession::StartApp() method.

This class is often referred to as a command line and contains: the name of an application EXE to be launched, a document name, a command code that defines the way the application is launched trailing data; the structure of this depends on the application to be launched.

To start an application, startup parameters are set on the CApaCommandLine object that is then externalized into a stream and attached to a new RProcess object. These parameters are then used to re-populate a new CApaCommandLine object inside the process by EikStart::RunApplication() and used to bootstrap the launching application.

Member Enumeration Documentation

Enum anonymous

Enumerator	Value	Description
EIpcFirstFreeSlot	3

Constructor & Destructor Documentation

~CApaCommandLine ( )

IMPORT_C

~CApaCommandLine

(

)

Destructor. Frees resources owned by the object prior to deletion.

Member Function Documentation

AppStartupInstrumentationEventIdBase ( )

IMPORT_C TInt

AppStartupInstrumentationEventIdBase

(

)

const

Command ( )

IMPORT_C TApaCommand

Command

(

)

const

Gets the command code from the launch information.

See the description of SetCommandL.

ConstructCmdLineFromMessageL ( const RMessage2 & )

IMPORT_C void

ConstructCmdLineFromMessageL

(

const RMessage2 &

aMessage

)

Acts as a second constructor and completes a commandline object from the aMessage object.

DebugMemFail ( )

IMPORT_C TInt

DebugMemFail

(

)

const

DefaultScreen ( )

IMPORT_C TInt

DefaultScreen

(

)

const

Extracts and returns the default (startup) screen that was specified in the command line.

Return Value: A number representing the default (startup) screen. 0 (Zero) if nothing present.

DocumentName ( )

IMPORT_C TPtrC

DocumentName

(

)

const

Gets the document name from the launch information.

Return Value: A pointer descriptor representing the document name. The document name is returned without any enclosing quotation marks. If the launch information contains no document name, then the pointer descriptor has zero length.

EnvironmentSlotForPublicUse ( TInt )

IMPORT_C TInt

EnvironmentSlotForPublicUse

(

TInt

aIndex

)

[static]

Returns the index of a process environment-slot for public use (in other words, one that is not used internally by CApaCommandLine). The number of slots available for public use is returned from NumberOfEnvironmentSlotsForPublicUse(), (this value may be increased over time). The returned value can then be passed into any of the Open(TInt,...) functions on RSessionBase, RMutex, RChunk, RCondVar, etc, or into User::GetTIntParameter(), User::GetDesParameter(), etc, depending on the type of the object in that environment slot.

Parameters
aIndex	The logical index of the public environment-slot. This must be greater than or equal to zero, and less than the value returned from NumberOfEnvironmentSlotsForPublicUse().

Return Value: The physical index of an environment-slot in the local process.

ExecutableName ( )

IMPORT_C TPtrC

ExecutableName

(

)

const

Gets the executable name from the launch information.

Return Value: A pointer descriptor representing the executable name.

GetCommandLineFromProcessEnvironment ( CApaCommandLine *& )

IMPORT_C TInt

GetCommandLineFromProcessEnvironment

(

CApaCommandLine *&

aCommandLine

)

[static]

Constructs a command line object.

If command line information is provided in the environment-slots it creates command line object from process environment-slots, else creates it from the information returned by User::CommandLine().

It can be called from a context where there is no CTrapCleanup.

Calling this function more than once in a process is not supported and will result in an empty command line being returned. If an application wants to inspect any part of its command line, it should override CEikAppUi::ProcessCommandParametersL(CApaCommandLine& aCommandLine) and call the base class implementation if required.

See also: CEikAppUi::ProcessCommandParametersL(CApaCommandLine& aCommandLine).

Parameters
aCommandLine	On return, a pointer to a newly constructed command line object.

Return Value: KErrNone, if successful; otherwise one of the other system-wide error codes.

GetFileByHandleL ( RFile & )

IMPORT_C void

GetFileByHandleL

(

RFile &

aFile

)

const

Opens (by handle) the file that was passed into SetFileByHandleL by the process launching the local application.

On entering this function, aFile must be non-open. It is recommended that aFile is pushed onto the cleanup-stack (via CleanupClosePushL()) before this function is called.

Parameters
aFile	The file object to be set up from the handle passed into the application. The caller has the responsibility to Close() this object, even if this function leaves.

GetIpcArgsLC ( TIpcArgs & )

IMPORT_C void

GetIpcArgsLC

(

TIpcArgs &

aIpcArgs

)

const

IsDefaultScreenSet ( )

IMPORT_C TBool

IsDefaultScreenSet

(

)

const

NewL ( )

IMPORT_C CApaCommandLine *

NewL

(

)

[static]

Creates an empty command line object.

Return Value: A pointer to the new command line object.

NewLC ( )

IMPORT_C CApaCommandLine *

NewLC

(

)

[static]

Creates an empty command line object, and puts a pointer to it onto the cleanup stack.

Return Value: A pointer to the new command line object.

NumberOfEnvironmentSlotsForPublicUse ( )

IMPORT_C TInt

NumberOfEnvironmentSlotsForPublicUse

(

)

[static]

The number of process environment-slot available for public use.

OpaqueData ( )

IMPORT_C TPtrC8

OpaqueData

(

)

const

Gets the opaque-data from the launch information.

See the description of SetOpaqueDataL. By default, this attribute is an empty descriptor.

ParentProcessId ( )

IMPORT_C TProcessId

ParentProcessId

(

)

const

Gets the Parent Process ID of the Child Process launched with this command line.

See the description of SetParentProcessId.

ParentWindowGroupID ( )

IMPORT_C TInt

ParentWindowGroupID

(

)

const

Returns the ID of the parent window-group - the application should create its own window-group as a child of this parent.

Return Value: The ID of the parent window-group - the application should create its window-group as a child off this .

ServerRequired ( )

IMPORT_C TUint

ServerRequired

(

)

const

Gets the server differentiator.

See the description of SetServerRequiredL.

SetAppStartupInstrumentationEventIdBaseL ( TInt )

IMPORT_C void

SetAppStartupInstrumentationEventIdBaseL

(

TInt

aEventIdBase

)

SetCommandL ( TApaCommand )

IMPORT_C void

SetCommandL

(

TApaCommand

aCommand

)

Sets the command code.

The command code is used to indicate how an application is to be launched.

Parameters
aCommand	The command code.

SetDebugMemFailL ( TInt )

IMPORT_C void

SetDebugMemFailL

(

TInt

aDebugMemFail

)

SetDefaultScreenL ( TInt )

IMPORT_C void

SetDefaultScreenL

(

TInt

aDefaultScreenNumber

)

Provides support for devices with more than one screen. A number representing the default or startup screen may be passed to an application. Screen numbers and characteristics are defined in the window server initialisation file (wsini.ini).

Parameters
aDefaultScreenNumber	The number of the default (startup) screen.

SetDocumentNameL ( const TDesC & )

IMPORT_C void

SetDocumentNameL

(

const TDesC &

aDocName

)

Sets the document name from the specified descriptor.

If the document name has embedded spaces, then it must be enclosed within quotation marks.

Parameters
aDocName	A descriptor containing the document name.

SetExecutableNameL ( const TDesC & )

IMPORT_C void

SetExecutableNameL

(

const TDesC &

aAppName

)

Sets the executable name from the specified descriptor.

Parameters
aAppName	A descriptor containing the executable name.

SetFileByHandleL ( const RFile & )

IMPORT_C void

SetFileByHandleL

(

const RFile &

aFile

)

Sets the file to be passed into the application (by handle). This will then be retrieved by that application-process calling GetFileByHandleL().

Parameters
aFile	The file object to be passed into the application. No transfer of this object's ownership takes place in this function.

SetOpaqueDataL ( const TDesC8 & )

IMPORT_C void

SetOpaqueDataL

(

const TDesC8 &

aOpaqueData

)

Sets the opaque-data from the specified 8-bit descriptor.

This is called internally and populated from the data in the application's registration resource file, i.e. from the resource indicated by the opaque_data field of the APP_REGISTRATION_INFO resource (if the opaque_data field was non-zero).

Parameters
aOpaqueData	An 8-bit descriptor containing the opaque-data.

SetParentProcessId ( TProcessId )

IMPORT_C void

SetParentProcessId

(

TProcessId

aProcessId

)

Sets the Parent Process ID for the Child Process launched with this command line.

This establishes a Parent-Child relationship which ensures that the child process is terminated when the parent terminates.

Parameters
aProcessId	The Process ID.

SetParentWindowGroupID ( TInt )

IMPORT_C void

SetParentWindowGroupID

(

TInt

aParentWindowGroupID

)

Sets the ID of the parent window-group - the application should create its own window-group as a child off this parent.

Parameters
aParentWindowGroupID	The ID of the parent window-group - the application should create its window-group as a child off this parent.

SetProcessEnvironmentL ( RProcess & )

IMPORT_C void

SetProcessEnvironmentL

(

RProcess &

aProcess

)

const

Assigns a command line to a process (EKA2 only).

This replaces the EKA1 method which involved retrieving the full command line (using CApaCommandLine::FullCommandLine()) and passing it to the process (or thread on the emulator).

This function is used as follows (the order of the first 2 steps is irrelevant):-

create the process and load the executable (RProcess::Create()),
create the command line object (CApaCommandLine::NewLC()), and set it up using the various setter functions, for instance SetDocumentNameL(),
call SetProcessEnvironmentL() to assign the command line to the process,
call Resume() on the process.

Note that this sequence of steps bypasses the application architecture, and is not recommended. RApaLsSession::StartApp() is the recommended way to launch an application with a command line.

Parameters
aProcess	The process to which the command line is assigned.

Leave Codes
KErrNotSupported	This indicates that the function was called on EKA1.

SetServerNotRequiredL ( )

IMPORT_C void

SetServerNotRequiredL

(

)

Sets that no server is required.

The value of server differentiator is set to zero, to indicate that no server is required.

See the description of SetServerRequiredL.

SetServerRequiredL ( TUint )

IMPORT_C void

SetServerRequiredL

(

TUint

aServerDifferentiator

)

Sets the required server.

The server differentiator is a number generated by the client that helps to uniquely identify the server. It is used by an application to indicate whether a server should be created and how it should be named.

See also: REikAppServiceBase::LaunchAppL()

Parameters
aServerDifferentiator	A differentiator for the required server.

SetTailEndL ( const TDesC8 & )

IMPORT_C void

SetTailEndL

(

const TDesC8 &

aTailEnd

)

Sets the trailing data.

The UI Framework provides a specific set of pre-defined command line options. Additional user defined or pre-defined command line options, may be passed to an application by setting the TailEnd.

Parameters
aTailEnd	An 8 bit descriptor containing the trailing data.

TailEnd ( )

IMPORT_C TPtrC8

TailEnd

(

)

const

Gets the trailing data from the launch information.

See the description of SetTailEndL.