Class CApaCommandLine

class CApaCommandLine : public CBase;

Description

Information for launching an application.

This 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.

The information is held in a buffer implemented by a heap descriptor.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CApaCommandLine - Information for launching an application.

Members

Defined in CApaCommandLine:

• Command()constGets the command code from the launch information.
• DefaultScreen()constExtracts and returns the default (startup) screen that was specified in the comm...
• DocumentName()constGets the document name from the launch information.
• EIpcFirstFreeSlot
• EnvironmentSlotForPublicUse(TInt)Returns the index of a process environment-slot for public use (in other words, ...
• ExecutableName()constGets the executable name from the launch information.
• NewL()Creates an empty command line object.
• NewLC()Creates an empty command line object, and puts a pointer to it onto the cleanup ...
• OpaqueData()constGets the opaque-data from the launch information.
• ParentProcessId()constGets the Parent Process ID of the Child Process launched with this command line.
• ParentWindowGroupID()constReturns the ID of the parent window-group - the application should create its ow...
• ServerRequired()constGets the server differentiator.
• SetCommandL(TApaCommand)Sets the command code.
• SetDefaultScreenL(TInt)Provides support for devices with more than one screen. A number representing th...
• SetDocumentNameL(const TDesC &)Sets the document name from the specified descriptor.
• SetExecutableNameL(const TDesC &)Sets the executable name from the specified descriptor.
• SetOpaqueDataL(const TDesC8 &)Sets the opaque-data from the specified 8-bit descriptor.
• SetParentProcessId(TProcessId)Sets the Parent Process ID for the Child Process launched with this command line...
• SetParentWindowGroupID(TInt)Sets the ID of the parent window-group - the application should create its own w...
• SetProcessEnvironmentL(RProcess &)constAssigns a command line to a process (EKA2 only).
• SetServerNotRequiredL()Sets that no server is required.
• SetServerRequiredL(TUint)Sets the required server.
• SetTailEndL(const TDesC8 &)Sets the trailing data.
• TailEnd()constGets the trailing data from the launch information.
• anonymous
• ~CApaCommandLine()Destructor.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C static CApaCommandLine* NewL();

Description

Creates an empty command line object.

Return value

IMPORT_C static CApaCommandLine* NewLC();

Description

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

Return value

IMPORT_C ~CApaCommandLine();

Description

Destructor.

Frees resources owned by the object prior to deletion.

IMPORT_C void SetProcessEnvironmentL(RProcess &aProcess) const;

Description

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(const TDesC &,const TDesC &,TOwnerType)),

• create the command line object (CApaCommandLine::NewLC()), and set it up using the various setter functions, for instance CApaCommandLine::SetDocumentNameL(const TDesC &),

• call CApaCommandLine::SetProcessEnvironmentL(RProcess &)const 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(const CApaCommandLine &) is the recommended way to launch an application with a command line.

Parameters

Leave codes

See also:

• RApaLsSession::StartApp(const CApaCommandLine &)Starts an application defined by the specified command line information. This is...

IMPORT_C void SetDocumentNameL(const TDesC &aDocName);

Description

Sets the document name from the specified descriptor.

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

Parameters

IMPORT_C TPtrC DocumentName() const;

Description

Gets the document name from the launch information.

Return value

IMPORT_C void SetExecutableNameL(const TDesC &aAppName);

Description

Sets the executable name from the specified descriptor.

Parameters

IMPORT_C TPtrC ExecutableName() const;

Description

Gets the executable name from the launch information.

Return value

IMPORT_C void SetOpaqueDataL(const TDesC8 &aOpaqueData);

Description

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

IMPORT_C TPtrC8 OpaqueData() const;

Description

Gets the opaque-data from the launch information.

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

Return value

See also:

• CApaCommandLine::SetOpaqueDataL(const TDesC8 &)Sets the opaque-data from the specified 8-bit descriptor.

IMPORT_C void SetTailEndL(const TDesC8 &aTailEnd);

Description

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

IMPORT_C TPtrC8 TailEnd() const;

Description

Gets the trailing data from the launch information.

See the description of SetTailEndL.

Return value

See also:

• CApaCommandLine::SetTailEndL(const TDesC8 &)Sets the trailing data.

IMPORT_C void SetCommandL(TApaCommand aCommand);

Description

Sets the command code.

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

Parameters

See also:

• TApaCommandDefines the command codes used to indicate the way an application is to be launc...

IMPORT_C TApaCommand Command() const;

Description

Gets the command code from the launch information.

See the description of SetCommandL.

Return value

See also:

• CApaCommandLine::SetCommandL(TApaCommand)Sets the command code.
• TApaCommandDefines the command codes used to indicate the way an application is to be launc...

IMPORT_C void SetParentProcessId(TProcessId aProcessId);

Description

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

IMPORT_C TProcessId ParentProcessId() const;

Description

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

See the description of SetParentProcessId.

Return value

See also:

• CApaCommandLine::SetParentProcessId(TProcessId)Sets the Parent Process ID for the Child Process launched with this command line...

IMPORT_C void SetServerNotRequiredL();

Description

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.

See also:

• CApaCommandLine::SetServerRequiredL(TUint)Sets the required server.

IMPORT_C void SetServerRequiredL(TUint aServerDifferentiator);

Description

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.

Parameters

IMPORT_C TUint ServerRequired() const;

Description

Gets the server differentiator.

See the description of SetServerRequiredL.

Return value

See also:

• CApaCommandLine::SetServerRequiredL(TUint)Sets the required server.

IMPORT_C void SetDefaultScreenL(TInt aDefaultScreenNumber);

Description

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

IMPORT_C TInt DefaultScreen() const;

Description

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

Return value

IMPORT_C void SetParentWindowGroupID(TInt aParentWindowGroupID);

Description

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

Parameters

IMPORT_C TInt ParentWindowGroupID() const;

Description

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

Return value

IMPORT_C static TInt EnvironmentSlotForPublicUse(TInt aIndex);

Description

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 can be found in the (private) enum value CApaCommandLine::ENumberOfEnvironmentSlotsForPublicUse, (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(TInt,TInt &), User::GetDesParameter(TInt,TDes8 &), etc, depending on the type of the object in that environment slot.

Parameters

Return value

n/a

Description