diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/lbtstartuptrigger.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/lbtstartuptrigger.h Tue Mar 16 16:12:26 2010 +0000 @@ -0,0 +1,385 @@ +/* +* Copyright (c) 2006 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Concrete class representing start-up trigger entries. +* +*/ + + +#ifndef LBTSTARTUPTRIGGER_H +#define LBTSTARTUPTRIGGER_H + +#include +#include + +/** + * 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. + * + * @see RLbt + * + * @lib lbt.lib + * @since S60 5.1 + */ +class CLbtStartupTrigger : public CLbtTriggerEntry + { +public: + /** + * 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 + * + * @return Pointer to the new start-up trigger entry. + */ + IMPORT_C static CLbtStartupTrigger* NewL(); + + /** + * 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 + * + * @return Pointer to the new start-up trigger entry. + */ + IMPORT_C static CLbtStartupTrigger* NewLC(); + + /** + * Allocates and constructs a new start-up trigger entry. + * + * @param[in] aName The name of the trigger entry. + * @param[in] aState The state of trigger entry. + * @param[in] aRequestorType Identifies the type of requestor, a + * service or a contact. + * @param[in] aRequestorFormat Determines the type of data held + * in aRequestorData + * @param[in] aRequestorData Requestor data. Can be a telephone + * number, a URL etc. + * @param[in] aManagerUi The UID of manager UI. + * @param[in] aCondition Pointer of the new trigger condition object. + * This object takes the ownership of aCondition. + * @param[in] 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(). + * @param[in] 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. + * @param[in] aCommandLine Command-line argument string. + * @return Pointer to the new start-up trigger entry. + * @leave KErrArgument If the name of the trigger is longer than + * @p KLbtMaxNameLength. + * @leave Other standard symbian error code, such as KErrNoMemory, + * KErrGeneral, etc. + * @panic ELbtErrArgument The length of aFileName is longer than + * @p KMaxFileName. + */ + IMPORT_C static 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() ); + + /** + * Allocates and construct a new start-up trigger entry. + * + * @panic ELbtErrArgument The length of aFileName is greater than + * @p KMaxFileName. + * + * @param[in] aName The name of the trigger entry. + * @param[in] aState The state of trigger entry. + * @param[in] aRequestors The requestor for the service. This object + * does not take the ownership of aRequestor. + * @param[in] aManagerUi The UID of manager UI. + * @param[in] aCondition Pointer of the new trigger condition object. + * This object takes the ownership of aCondition. + * @param[in] 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(). + * @param[in] 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. + * @param[in] aCommandLine Command-line argument string. + * @return Pointer to the new start-up trigger entry. + * @leave KErrArgument If the name of the trigger is longer than + * @p KLbtMaxNameLength. + * @leave Other standard symbian error code, such as KErrNoMemory, + * KErrGeneral, etc. + */ + IMPORT_C static 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() ); + + /** + * Destructor + */ + IMPORT_C ~CLbtStartupTrigger(); + + /** + * Gets the type of trigger entry, CLbtTriggerEntry::EStartup. + * + * @return CLbtTriggerEntry::EStartup. + */ + IMPORT_C TType Type() const; + + /** + * Gets identity of the trigger handling process. + * + * @param[out] 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. + * @param[out] aSecureId On return contains the SID of + * the triggering handling process. KNullUid is returned if + * the SID has not been previously set. + */ + IMPORT_C void GetProcessId( + TDes& aFileName, + TSecureId& aSecureId ) const; + + /** + * Sets the identity of the trigger handling process. + * + * @param[in] 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 @p 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(). + * @param[in] 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. + * @panic ELbtErrArgument The length of aFileName is greater than + * @p KMaxFileName. + */ + IMPORT_C void SetProcessId( + const TDesC& aFileName, + const TSecureId& aSecureId ); + + /** + * Gets the command-line argument string. + * + * @return The command-line argument string. Empty string is returned + * if the command-line argument string has not been set + */ + IMPORT_C const TDesC& CommandLine() const; + + /** + * Sets the command-line argument string. + * + * @param[in] aCommandLine The command-line argument string. It can + * be an empty string. + */ + IMPORT_C void SetCommandLineL( const TDesC& aCommandLine ); + + +protected: + + /** + * Internalize method that subclass must implement. + * @param[in] aStream Stream from which the object should be internalized. + */ + virtual void DoInternalizeL(RReadStream& aStream); + + /** + * Externalize method that subclass must implement. + * @param[in] aStream Stream to which the object should be externalized. + */ + virtual void DoExternalizeL(RWriteStream& aStream) const; + + + +private: + /** + * Default constructor + */ + CLbtStartupTrigger(); + + /** + * By default, prohibit copy constructor + */ + CLbtStartupTrigger( const CLbtStartupTrigger& ); + + /** + * Prohibit assigment operator + */ + CLbtStartupTrigger& operator= ( const CLbtStartupTrigger& ); + + /** + * Symbian 2nd phase constructor + */ + void ConstructL(); + + /** + * Symbian 2nd phase constructor + */ + void ConstructL(const TDesC& aName, + TLbtTriggerState aState, + CRequestor::TRequestorType aRequestorType, + CRequestor::TRequestorFormat aRequestorFormat, + const TDesC& aRequestorData, + TUid aManagerUi, + CLbtTriggerConditionBase* aCondition, + const TDesC& aFileName, + const TSecureId& aSecureId , + const TDesC& aCommandLine); + + /** + * Symbian 2nd phase constructor + */ + void CLbtStartupTrigger::ConstructL( const TDesC& aName, + CLbtTriggerEntry::TLbtTriggerState aState, + const RRequestorStack& aRequestors, + TUid aManagerUi, + CLbtTriggerConditionBase* aCondition, + const TDesC& aFileName, + const TSecureId& aSecureId , + const TDesC& aCommandLine); + +private: + /** + * Process file name + */ + TFileName iProcessFileName; + + /** + * Secure Id + */ + TSecureId iSecureId; + + /** + * Command line arguement + */ + HBufC* iCommandLine; + }; + + +#endif // LBTSTARTUPTRIGGER_H