--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/locsrv_pub/location_triggering_api/inc/lbtstartuptrigger.h Tue Feb 02 01:06:48 2010 +0200
@@ -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 "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Concrete class representing start-up trigger entries.
+*
+*/
+
+
+#ifndef LBTSTARTUPTRIGGER_H
+#define LBTSTARTUPTRIGGER_H
+
+#include <lbttriggerentry.h>
+#include <lbs.h>
+
+/**
+ * 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
+ *
+ * - <B>Trigger handling process identity</B> 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.
+ *
+ * - <B> SID of the trigger handling process</B> 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.
+ *
+ * - <B>Command-line argument string</B> 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