CLbtStartupTrigger Class Reference

#include <mw/lbtstartuptrigger.h>

Link against: lbt.lib

class CLbtStartupTrigger : public CLbtTriggerEntry

Inherits from

CLbtStartupTrigger
- CLbtTriggerEntry

Public Member Functions
	~CLbtStartupTrigger()
IMPORT_C const TDesC &	CommandLine()
IMPORT_C void	GetProcessId(TDes &, TSecureId &)
IMPORT_C CLbtStartupTrigger *	NewL()
IMPORT_C CLbtStartupTrigger *	NewL(const TDesC &, TLbtTriggerState, CRequestor::TRequestorType, CRequestor::TRequestorFormat, const TDesC &, TUid, CLbtTriggerConditionBase *, const TDesC &, const TSecureId &, const TDesC &)
IMPORT_C CLbtStartupTrigger *	NewL(const TDesC &, TLbtTriggerState, const RRequestorStack &, TUid, CLbtTriggerConditionBase *, const TDesC &, const TSecureId &, const TDesC &)
IMPORT_C CLbtStartupTrigger *	NewLC()
IMPORT_C void	SetCommandLineL(const TDesC &)
IMPORT_C void	SetProcessId(const TDesC &, const TSecureId &)
virtual IMPORT_C TType	Type()

Protected Member Functions
virtual void	DoExternalizeL(RWriteStream &)
virtual void	DoInternalizeL(RReadStream &)

Inherited Enumerations
	CLbtTriggerEntry:TAttribute
	CLbtTriggerEntry:TLbtTriggerState
	CLbtTriggerEntry:TType

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()
	CLbtTriggerEntry::CLbtTriggerEntry()
	CLbtTriggerEntry::ExternalizeL(RWriteStream &)const
	CLbtTriggerEntry::GetCondition()
	CLbtTriggerEntry::GetCondition()const
	CLbtTriggerEntry::GetRequestorsL(RRequestorStack &)const
	CLbtTriggerEntry::Id()const
	CLbtTriggerEntry::InternalizeL(RReadStream &)
	CLbtTriggerEntry::ManagerUi()const
	CLbtTriggerEntry::Name()const
	CLbtTriggerEntry::SetCondition(CLbtTriggerConditionBase *)
	CLbtTriggerEntry::SetId(TLbtTriggerId)
	CLbtTriggerEntry::SetManagerUi(TUid)
	CLbtTriggerEntry::SetNameL(const TDesC &)
	CLbtTriggerEntry::SetRequestorL(CRequestor::TRequestorType,CRequestor::TRequestorFormat,const TDesC &)
	CLbtTriggerEntry::SetRequestorsL(const RRequestorStack &)
	CLbtTriggerEntry::SetState(TLbtTriggerState)
	CLbtTriggerEntry::SetTimeToRearm(TInt)
	CLbtTriggerEntry::State()const
	CLbtTriggerEntry::TimeToRearm()const
	CLbtTriggerEntry::~CLbtTriggerEntry()

Detailed Description

Concrete class representing start-up trigger entries.

When a start-up trigger is fired, Location Triggering Server tries to launch a new instance of the trigger handling process. Trigger handling process is specified by the client application when the trigger is created. The command line arguments, if specified, are passed to the thread function of the new process's main thread. If the specified process can't be launched when the trigger is fired, Location Triggering Server will try to launch the process next time when the trigger is fired again.

Start-up trigger has following additional attributes

Trigger handling process identity Trigger handling process identity consists of the executable name of the trigger handling process. The process is launched when the start-up trigger is fired. This attribute can't be modified after the start-up trigger is created.

SID of the trigger handling process When SID of the trigger handling process is specified when the trigger is created, the trigger handling process is able to access the trigger. If the SID is not specified, the trigger handling process can't access the trigger. This attribute cannot be modified after the start-up trigger is created.

Command-line argument string Command-line argument string is passed as an argument to the main thread of the launched process, when it's first scheduled. Command-line argument string is passed to the launched process as it is specified. Location Triggering Server doesn't interpret any special character. This attribute can be modified after the trigger is created.

Trigger handling process identity must be specified when the trigger is created in Location Triggering Server. SID of the trigger handling process and Command-line argument string is optional.

If the trigger handling process is not the owner process of the trigger and the SID of the trigger handling process is not specified when the trigger is created, it can't access the firing trigger information. In this case, if the trigger handling process needs to get information of the firing trigger, it can get it either from command-line argument string which is set when the trigger is created or request a service from the owner process.

If a UIKON based UI application is specified as trigger handling process, the UIKON framework will prevent starting a new instance of the application if it's already running. In this case, the trigger handling process (UI application) shall issue trigger firing event notification request to Location Triggering Server when it's started.

If the owner process, Manager UI or trigger handling process of a trigger is removed from the system, the trigger becomes invalid. The process can be removed for example when the process's executable resides in removable media (like MMC), and that media is removed from the terminal. An invalid trigger is not supervised by the system. If a trigger has been invalid longer than the predefined system clean up time, the trigger is removed from the system. System clean up time is defined by system and cant' be accessed by client application.

Constructor & Destructor Documentation

~CLbtStartupTrigger ( )

IMPORT_C

~CLbtStartupTrigger

(

)

Destructor

Member Function Documentation

CommandLine ( )

IMPORT_C const TDesC &

CommandLine

(

)

const

Gets the command-line argument string.

Returns: The command-line argument string. Empty string is returned if the command-line argument string has not been set

DoExternalizeL ( RWriteStream & )

void

DoExternalizeL

(

RWriteStream &

aStream

)

const [protected, virtual]

Reimplemented from CLbtTriggerEntry::DoExternalizeL(RWriteStream &)const

Externalize method that subclass must implement.

Parameter	Description
aStream	Stream to which the object should be externalized.

DoInternalizeL ( RReadStream & )

void

DoInternalizeL

(

RReadStream &

aStream

)

[protected, virtual]

Reimplemented from CLbtTriggerEntry::DoInternalizeL(RReadStream &)

Internalize method that subclass must implement.

Parameter	Description
aStream	Stream from which the object should be internalized.

GetProcessId ( TDes &, TSecureId & )

IMPORT_C void	GetProcessId	(	TDes &	aFileName,
			TSecureId &	aSecureId
		)	const

Gets identity of the trigger handling process.

Parameter	Description
aFileName	On return contains the full path name of the executable of trigger handling process. Maximum length of the resulting full path name is KMaxFileName. Client gets panic USER 11 if the length of executable full path name is greater than the maximum length of aFileName. Empty string is returned if the attribute has not been set.
aSecureId	On return contains the SID of the triggering handling process. KNullUid is returned if the SID has not been previously set.

NewL ( )

IMPORT_C CLbtStartupTrigger *

NewL

(

)

[static]

Allocates and constructs a new start-up trigger entry. Default values are assigned to the attributes. The default values are

Trigger Id is KLbtNullTriggerId.

Trigger Name is an empty string.

Trigger State CLbtTriggerEntry::EStateEnabled.

Requestors are not set.

Manager UI is not set(KNullUid).

Trigger condition is not set.

Trigger handling process file name is empty string.

SID of the trigger handling process is KNullUid.

Command-line argument string is an empty string

Returns: Pointer to the new start-up trigger entry.

NewL ( const TDesC &, TLbtTriggerState, CRequestor::TRequestorType, CRequestor::TRequestorFormat, const TDesC &, TUid, CLbtTriggerConditionBase *, const TDesC &, const TSecureId &, const TDesC & )

IMPORT_C CLbtStartupTrigger *	NewL	(	const TDesC &	aName,
			TLbtTriggerState	aState,
			CRequestor::TRequestorType	aRequestorType,
			CRequestor::TRequestorFormat	aRequestorFormat,
			const TDesC &	aRequestorData,
			TUid	aManagerUi,
			CLbtTriggerConditionBase *	aCondition,
			const TDesC &	aFileName,
			const TSecureId &	aSecureId = KNullUid,
			const TDesC &	aCommandLine = KNullDesC()
		)	[static]

Allocates and constructs a new start-up trigger entry.

leave: KErrArgument If the name of the trigger is longer than KLbtMaxNameLength.

leave: Other standard symbian error code, such as KErrNoMemory, KErrGeneral, etc.

panic: ELbtErrArgument The length of aFileName is longer than KMaxFileName.

Parameter	Description
aName	The name of the trigger entry.
aState	The state of trigger entry.
aRequestorType	Identifies the type of requestor, a service or a contact.
aRequestorFormat	Determines the type of data held in aRequestorData
aRequestorData	Requestor data. Can be a telephone number, a URL etc.
aManagerUi	The UID of manager UI.
aCondition	Pointer of the new trigger condition object. This object takes the ownership of aCondition.
aFileName	A descriptor containing the full path name of the executable to be loaded when the start-up trigger is fired. If this name has no file extension, an extension of .exe is appended. The length of the resulting full path name must not be greater than KMaxFileName. The length of the file name itself must not be greater than KMaxOsName. If no path is specified, the system will look in system executable directories on all local drives, in the same search order as specified in TFindFile::FindByPath().
aSecureId	The SID of the trigger handling process. If the specified value is KNullUid or a wrong value is specified, the trigger handling process would not be able to access the trigger.
aCommandLine	Command-line argument string.

Returns: Pointer to the new start-up trigger entry.

NewL ( const TDesC &, TLbtTriggerState, const RRequestorStack &, TUid, CLbtTriggerConditionBase *, const TDesC &, const TSecureId &, const TDesC & )

IMPORT_C CLbtStartupTrigger *	NewL	(	const TDesC &	aName,
			TLbtTriggerState	aState,
			const RRequestorStack &	aRequestors,
			TUid	aManagerUi,
			CLbtTriggerConditionBase *	aCondition,
			const TDesC &	aFileName,
			const TSecureId &	aSecureId = KNullUid,
			const TDesC &	aCommandLine = KNullDesC()
		)	[static]

Allocates and construct a new start-up trigger entry.

panic: ELbtErrArgument The length of aFileName is greater than KMaxFileName.

leave: KErrArgument If the name of the trigger is longer than KLbtMaxNameLength.

leave: Other standard symbian error code, such as KErrNoMemory, KErrGeneral, etc.

Parameter	Description
aName	The name of the trigger entry.
aState	The state of trigger entry.
aRequestors	The requestor for the service. This object does not take the ownership of aRequestor.
aManagerUi	The UID of manager UI.
aCondition	Pointer of the new trigger condition object. This object takes the ownership of aCondition.
aFileName	A descriptor containing the full path name of the executable to be loaded when the start-up trigger is fired. If this name has no file extension, an extension of .exe is appended. The length of the resulting full path name must not be greater than KMaxFileName. The length of the file name itself must not be greater than KMaxOsName. If no path is specified, the system will look in system executable directories on all local drives, in the same search order as specified in TFindFile::FindByPath().
aSecureId	The SID of the trigger handling process. If the specified value is KNullUid or a wrong value is specified, the trigger handling process would not be able to access the trigger.
aCommandLine	Command-line argument string.

Returns: Pointer to the new start-up trigger entry.

NewLC ( )

IMPORT_C CLbtStartupTrigger *

NewLC

(

)

[static]

Allocates and constructs a new start-up trigger entry. The constructed object is pushed onto cleanup stack. Default values are assigned to the attributes. The default values are

Trigger Id is KLbtNullTriggerId.

Trigger Name is an empty string.

Trigger State CLbtTriggerEntry::EStateEnabled.

Requestors are not set.

Manager UI is not set(KNullUid).

Trigger condition is not set.

Trigger handling process file name is empty string.

SID of the trigger handling process is KNullUid.

Command-line argument string is an empty string

Returns: Pointer to the new start-up trigger entry.

SetCommandLineL ( const TDesC & )

IMPORT_C void

SetCommandLineL

(

const TDesC &

aCommandLine

)

Sets the command-line argument string.

Parameter	Description
aCommandLine	The command-line argument string. It can be an empty string.

SetProcessId ( const TDesC &, const TSecureId & )

IMPORT_C void	SetProcessId	(	const TDesC &	aFileName,
			const TSecureId &	aSecureId
		)

Sets the identity of the trigger handling process.

panic: ELbtErrArgument The length of aFileName is greater than KMaxFileName.

Parameter	Description
aFileName	A descriptor containing the full path name of the executable to be loaded when the start-up trigger is fired. If this name has no file extension, an extension of .exe is appended. The length of the resulting full path name must not be greater than KMaxFileName. The length of the file name itself must not be greater than KMaxOsName. If no path is specified, the system will look in system executable directories on all local drives, in the same search order as specified in TFindFile::FindByPath().
aSecureId	The SID of the trigger handling process. If the specified value is KNullUid or a wrong value is specified, the trigger handling process would not be able to access the trigger.

Parameter

Description

aFileName

A descriptor containing the full path name of the executable to be loaded when the start-up trigger is fired. If this name has no file extension, an extension of .exe is appended. The length of the resulting full path name must not be greater than KMaxFileName. The length of the file name itself must not be greater than KMaxOsName. If no path is specified, the system will look in system executable directories on all local drives, in the same search order as specified in TFindFile::FindByPath().

aSecureId

The SID of the trigger handling process. If the specified value is KNullUid or a wrong value is specified, the trigger handling process would not be able to access the trigger.

Type ( )

IMPORT_C TType

Type

(

)

const [virtual]

Reimplemented from CLbtTriggerEntry::Type()const

Gets the type of trigger entry, CLbtTriggerEntry::EStartup.

Returns: CLbtTriggerEntry::EStartup.