williamr@2: /*
williamr@2: * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Concrete class representing start-up trigger entries.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef LBTSTARTUPTRIGGER_H
williamr@2: #define LBTSTARTUPTRIGGER_H
williamr@2: 
williamr@2: #include <lbttriggerentry.h>
williamr@2: #include <lbs.h>
williamr@2: 
williamr@2: /**
williamr@2:  *  Concrete class representing start-up trigger entries.
williamr@2:  *
williamr@2:  *  When a start-up trigger is fired, Location Triggering Server tries to 
williamr@2:  *  launch a new instance of the trigger handling process. Trigger handling
williamr@2:  *  process is specified by the client application when the trigger is 
williamr@2:  *  created. The command line arguments, if specified, are passed to the 
williamr@2:  *  thread function of the new process's main thread. If the specified 
williamr@2:  *  process can't be launched when the trigger is fired, Location Triggering 
williamr@2:  *  Server will try to launch the process next time when the trigger is 
williamr@2:  *  fired again. 
williamr@2:  *
williamr@2:  *  Start-up trigger has following additional attributes
williamr@2:  *
williamr@2:  *  -  <B>Trigger handling process identity</B> Trigger handling process 
williamr@2:  *  identity consists of the executable name of the trigger handling process.
williamr@2:  *  The process is launched when the start-up trigger is fired. This attribute 
williamr@2:  *  can't be modified after the start-up trigger is created.
williamr@2:  *
williamr@2:  *  -  <B> SID of the trigger handling process</B> When SID of the trigger 
williamr@2:  *  handling process is specified when the trigger is created, the trigger 
williamr@2:  *  handling process is able to access the trigger. If the SID is not specified,
williamr@2:  *  the trigger handling process can't access the trigger. This attribute 
williamr@2:  *  cannot be modified after the start-up trigger is created.
williamr@2:  *
williamr@2:  *  -  <B>Command-line argument string</B> Command-line argument string is passed
williamr@2:  *  as an argument to the main thread of the launched process, when it's 
williamr@2:  *  first scheduled. Command-line argument string is passed to the launched 
williamr@2:  *  process as it is specified. Location Triggering Server doesn't interpret any
williamr@2:  *  special character. This attribute can be modified after the trigger is
williamr@2:  *  created.
williamr@2:  *
williamr@2:  *  Trigger handling process identity must be specified when the trigger 
williamr@2:  *  is created in Location Triggering Server. SID of the trigger handling 
williamr@2:  *  process and Command-line argument string is optional.
williamr@2:  *
williamr@2:  *  If the trigger handling process is not the owner process of the trigger and
williamr@2:  *  the SID of the trigger handling process is not specified when the trigger 
williamr@2:  *  is created, it can't access the firing trigger
williamr@2:  *  information. In this case, if the trigger handling process needs to 
williamr@2:  *  get information of the firing trigger, it can get it either from 
williamr@2:  *  command-line argument string which is set when the trigger is created 
williamr@2:  *  or request a service from the owner process.
williamr@2:  *
williamr@2:  *  If a UIKON based UI application is specified as trigger handling process,
williamr@2:  *  the UIKON framework will prevent starting a new instance of the application if
williamr@2:  *  it's already running. In this case, the trigger handling process (UI application)
williamr@2:  *  shall issue trigger firing event notification request to Location Triggering 
williamr@2:  *  Server when it's started.
williamr@2:  *
williamr@2:  *  If the owner process, Manager UI or trigger handling process 
williamr@2:  *  of a trigger is removed from the system, the trigger becomes 
williamr@2:  *  invalid. The process can be removed for example when the process's 
williamr@2:  *  executable resides in removable media (like MMC), and that media is 
williamr@2:  *  removed from the terminal. An invalid trigger is not supervised by 
williamr@2:  *  the system. If a trigger has been invalid longer than the predefined system 
williamr@2:  *  clean up time, the trigger is removed from the system. System clean up time 
williamr@2:  *  is defined by system and cant' be accessed by client application.
williamr@2:  * 
williamr@2:  *  @see RLbt
williamr@2:  *
williamr@2:  *  @lib lbt.lib
williamr@2:  *  @since S60 5.1
williamr@2:  */
williamr@2: class CLbtStartupTrigger : public CLbtTriggerEntry
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * Allocates and constructs a new start-up trigger entry.
williamr@2:      * Default values are assigned to the attributes. 
williamr@2:      * The default values are
williamr@2:      * 
williamr@2:      *  - Trigger Id is KLbtNullTriggerId.
williamr@2:      *
williamr@2:      *  - Trigger Name is an empty string.
williamr@2:      *
williamr@2:      *  - Trigger State CLbtTriggerEntry::EStateEnabled.
williamr@2:      *  
williamr@2:      *  - Requestors are not set. 
williamr@2:      *
williamr@2:      *  - Manager UI is not set(KNullUid). 
williamr@2:      *
williamr@2:      *  - Trigger condition is not set.
williamr@2:      *
williamr@2:      *  - Trigger handling process file name is empty string.
williamr@2:      * 
williamr@2:      *  - SID of the trigger handling process is KNullUid.
williamr@2:      *
williamr@2:      *  - Command-line argument string is an empty string
williamr@2:      *
williamr@2:      * @return Pointer to the new start-up trigger entry.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtStartupTrigger* NewL();
williamr@2: 
williamr@2:     /**
williamr@2:      * Allocates and constructs a new start-up trigger entry. The
williamr@2:      * constructed object is pushed onto cleanup stack.
williamr@2:      * Default values are assigned to the attributes. 
williamr@2:      * The default values are
williamr@2:      * 
williamr@2:      *  - Trigger Id is KLbtNullTriggerId.
williamr@2:      *
williamr@2:      *  - Trigger Name is an empty string.
williamr@2:      *
williamr@2:      *  - Trigger State CLbtTriggerEntry::EStateEnabled.
williamr@2:      *  
williamr@2:      *  - Requestors are not set. 
williamr@2:      *
williamr@2:      *  - Manager UI is not set(KNullUid). 
williamr@2:      *
williamr@2:      *  - Trigger condition is not set.
williamr@2:      *
williamr@2:      *  - Trigger handling process file name is empty string.
williamr@2:      * 
williamr@2:      *  - SID of the trigger handling process is KNullUid.
williamr@2:      *
williamr@2:      *  - Command-line argument string is an empty string
williamr@2:      *
williamr@2:      * @return Pointer to the new start-up trigger entry.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtStartupTrigger* NewLC();
williamr@2: 
williamr@2:     /**
williamr@2:      * Allocates and constructs a new start-up trigger entry.
williamr@2:      *
williamr@2:      * @param[in] aName The name of the trigger entry.
williamr@2:      * @param[in] aState The state of trigger entry.
williamr@2:      * @param[in] aRequestorType Identifies the type of requestor, a
williamr@2:      * service or a contact.
williamr@2:      * @param[in] aRequestorFormat Determines the type of data held 
williamr@2:      * in aRequestorData
williamr@2:      * @param[in] aRequestorData Requestor data. Can be a telephone 
williamr@2:      * number, a URL etc.
williamr@2:      * @param[in] aManagerUi The UID of manager UI. 
williamr@2:      * @param[in] aCondition Pointer of the new trigger condition object.
williamr@2:      * This object takes the ownership of aCondition.
williamr@2:      * @param[in] aFileName A descriptor containing the full path name of
williamr@2:      * the executable to be loaded when the start-up trigger is fired. If 
williamr@2:      * this name has no file extension, an extension of .exe is appended. 
williamr@2:      * The length of the resulting full path name must not be greater 
williamr@2:      * than KMaxFileName. The length of the file name itself must not be 
williamr@2:      * greater than KMaxOsName. If no path is specified, the system will 
williamr@2:      * look in system executable directories on all local drives, in the  
williamr@2:      * same search order as specified in TFindFile::FindByPath().
williamr@2:      * @param[in] aSecureId The SID of the trigger handling process.
williamr@2:      * If the specified value is KNullUid or a wrong value is specified,
williamr@2:      * the trigger handling process would not be able to access the 
williamr@2:      * trigger.
williamr@2:      * @param[in] aCommandLine Command-line argument string.
williamr@2:      * @return Pointer to the new start-up trigger entry.
williamr@2:      * @leave KErrArgument If the name of the trigger is longer than
williamr@2:      *   @p KLbtMaxNameLength.
williamr@2:      * @leave Other standard symbian error code, such as KErrNoMemory,
williamr@2:      * KErrGeneral, etc.
williamr@2:      * @panic ELbtErrArgument The length of aFileName is longer than
williamr@2:      * @p KMaxFileName.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtStartupTrigger* NewL( 
williamr@2:         const TDesC& aName,
williamr@2:         TLbtTriggerState aState,
williamr@2:         CRequestor::TRequestorType aRequestorType,
williamr@2:         CRequestor::TRequestorFormat aRequestorFormat,
williamr@2:         const TDesC& aRequestorData,
williamr@2:         TUid aManagerUi,
williamr@2:         CLbtTriggerConditionBase* aCondition,
williamr@2:         const TDesC& aFileName, 
williamr@2:         const TSecureId& aSecureId = KNullUid,
williamr@2:         const TDesC& aCommandLine = KNullDesC() );
williamr@2:     
williamr@2:     /**
williamr@2:      * Allocates and construct a new start-up trigger entry.
williamr@2:      *
williamr@2:      * @panic ELbtErrArgument The length of aFileName is greater than
williamr@2:      * @p KMaxFileName.
williamr@2:      *
williamr@2:      * @param[in] aName The name of the trigger entry.
williamr@2:      * @param[in] aState The state of trigger entry.
williamr@2:      * @param[in] aRequestors The requestor for the service. This object
williamr@2:      * does not take the ownership of aRequestor.
williamr@2:      * @param[in] aManagerUi The UID of manager UI.
williamr@2:      * @param[in] aCondition Pointer of the new trigger condition object.
williamr@2:      * This object takes the ownership of aCondition.
williamr@2:      * @param[in] aFileName A descriptor containing the full path name of
williamr@2:      * the executable to be loaded when the start-up trigger is fired. If 
williamr@2:      * this name has no file extension, an extension of .exe is appended. 
williamr@2:      * The length of the resulting full path name must not be greater 
williamr@2:      * than KMaxFileName. The length of the file name itself must not be 
williamr@2:      * greater than KMaxOsName. If no path is specified, the system will 
williamr@2:      * look in system executable directories on all local drives, in the  
williamr@2:      * same search order as specified in TFindFile::FindByPath().
williamr@2:      * @param[in] aSecureId The SID of the trigger handling process.
williamr@2:      * If the specified value is KNullUid or a wrong value is specified,
williamr@2:      * the trigger handling process would not be able to access the 
williamr@2:      * trigger.
williamr@2:      * @param[in] aCommandLine Command-line argument string.
williamr@2:      * @return Pointer to the new start-up trigger entry.
williamr@2:      * @leave KErrArgument If the name of the trigger is longer than
williamr@2:      * @p KLbtMaxNameLength.
williamr@2:      * @leave Other standard symbian error code, such as KErrNoMemory,
williamr@2:      * KErrGeneral, etc.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtStartupTrigger* NewL( 
williamr@2:         const TDesC& aName,
williamr@2:         TLbtTriggerState aState,
williamr@2:         const RRequestorStack& aRequestors,
williamr@2:         TUid aManagerUi,
williamr@2:         CLbtTriggerConditionBase* aCondition,
williamr@2:         const TDesC& aFileName, 
williamr@2:         const TSecureId& aSecureId = KNullUid,
williamr@2:         const TDesC& aCommandLine = KNullDesC() );
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor
williamr@2:      */
williamr@2:     IMPORT_C ~CLbtStartupTrigger();
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the type of trigger entry, CLbtTriggerEntry::EStartup.
williamr@2:      *
williamr@2:      * @return CLbtTriggerEntry::EStartup.
williamr@2:      */
williamr@2:     IMPORT_C TType Type() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets identity of the trigger handling process.
williamr@2:      * 
williamr@2:      * @param[out] aFileName On return contains the full path name
williamr@2:      * of the executable of trigger handling process. Maximum length 
williamr@2:      * of the resulting full path name is KMaxFileName. Client gets 
williamr@2:      * panic USER 11 if the length of executable full path name is 
williamr@2:      * greater than the maximum length of aFileName. Empty string 
williamr@2:      * is returned if the attribute has not been set.
williamr@2:      * @param[out] aSecureId On return contains the SID of
williamr@2:      * the triggering handling process. KNullUid is returned if
williamr@2:      * the SID has not been previously set. 
williamr@2:      */
williamr@2:     IMPORT_C void GetProcessId( 
williamr@2:         TDes& aFileName, 
williamr@2:         TSecureId& aSecureId ) const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the identity of the trigger handling process.
williamr@2:      *
williamr@2:      * @param[in] aFileName A descriptor containing the full path name of
williamr@2:      * the executable to be loaded when the start-up trigger is fired. If 
williamr@2:      * this name has no file extension, an extension of .exe is appended. 
williamr@2:      * The length of the resulting full path name must not be greater 
williamr@2:      * than @p KMaxFileName. The length of the file name itself must not be 
williamr@2:      * greater than KMaxOsName. If no path is specified, the system will 
williamr@2:      * look in system executable directories on all local drives, in the  
williamr@2:      * same search order as specified in TFindFile::FindByPath().
williamr@2:      * @param[in] aSecureId The SID of the trigger handling process.
williamr@2:      * If the specified value is KNullUid or a wrong value is specified,
williamr@2:      * the trigger handling process would not be able to access the 
williamr@2:      * trigger.
williamr@2:      * @panic ELbtErrArgument The length of aFileName is greater than
williamr@2:      * @p KMaxFileName.
williamr@2:      */
williamr@2:     IMPORT_C void SetProcessId( 
williamr@2:         const TDesC& aFileName, 
williamr@2:         const TSecureId& aSecureId );
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the command-line argument string.
williamr@2:      *
williamr@2:      * @return The command-line argument string. Empty string is returned
williamr@2:      * if the command-line argument string has not been set
williamr@2:      */
williamr@2:     IMPORT_C const TDesC& CommandLine() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the command-line argument string.
williamr@2:      * 
williamr@2:      * @param[in] aCommandLine The command-line argument string. It can
williamr@2:      * be an empty string.
williamr@2:      */
williamr@2:     IMPORT_C void SetCommandLineL( const TDesC& aCommandLine );
williamr@2:     
williamr@2:     
williamr@2: protected:
williamr@2:     
williamr@2:     /**
williamr@2:      * Internalize method that subclass must implement.
williamr@2:      * @param[in] aStream Stream from which the object should be internalized.
williamr@2:      */
williamr@2:     virtual void DoInternalizeL(RReadStream& aStream);
williamr@2:     
williamr@2:     /**
williamr@2:      * Externalize method that subclass must implement.
williamr@2:      * @param[in] aStream Stream to which the object should be externalized.
williamr@2:      */
williamr@2:     virtual void DoExternalizeL(RWriteStream& aStream) const;  
williamr@2: 
williamr@2:          
williamr@2: 
williamr@2: private:
williamr@2:     /**
williamr@2:      * Default constructor
williamr@2:      */
williamr@2:     CLbtStartupTrigger(); 
williamr@2:         
williamr@2:     /**
williamr@2:      * By default, prohibit copy constructor
williamr@2:      */
williamr@2:     CLbtStartupTrigger( const CLbtStartupTrigger& );
williamr@2:     
williamr@2:     /**
williamr@2:      * Prohibit assigment operator
williamr@2:      */
williamr@2:     CLbtStartupTrigger& operator= ( const CLbtStartupTrigger& );
williamr@2:     
williamr@2:     /**
williamr@2:      * Symbian 2nd phase constructor
williamr@2:      */
williamr@2:     void ConstructL();
williamr@2:     
williamr@2:     /**
williamr@2:      * Symbian 2nd phase constructor
williamr@2:      */
williamr@2:     void ConstructL(const TDesC& aName,
williamr@2:         TLbtTriggerState aState,
williamr@2:         CRequestor::TRequestorType aRequestorType,
williamr@2:         CRequestor::TRequestorFormat aRequestorFormat,
williamr@2:         const TDesC& aRequestorData,
williamr@2:         TUid aManagerUi,
williamr@2:         CLbtTriggerConditionBase* aCondition,
williamr@2:         const TDesC& aFileName, 
williamr@2:         const TSecureId& aSecureId ,
williamr@2:         const TDesC& aCommandLine);
williamr@2:     
williamr@2:     /**
williamr@2:      * Symbian 2nd phase constructor
williamr@2:      */    
williamr@2:     void CLbtStartupTrigger::ConstructL( const TDesC& aName,
williamr@2:         CLbtTriggerEntry::TLbtTriggerState aState,
williamr@2:         const RRequestorStack& aRequestors,
williamr@2:         TUid aManagerUi,
williamr@2:         CLbtTriggerConditionBase* aCondition,
williamr@2:         const TDesC& aFileName, 
williamr@2:         const TSecureId& aSecureId ,
williamr@2:         const TDesC& aCommandLine);
williamr@2:         
williamr@2: private:
williamr@2:     /**
williamr@2:      * Process file name 
williamr@2:      */
williamr@2:     TFileName iProcessFileName;
williamr@2:     
williamr@2:     /**
williamr@2:      * Secure Id
williamr@2:      */
williamr@2:     TSecureId iSecureId;
williamr@2:     
williamr@2:     /**
williamr@2:      * Command line arguement
williamr@2:      */
williamr@2:     HBufC* iCommandLine;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: #endif // LBTSTARTUPTRIGGER_H