1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Concrete class representing start-up trigger entries.

    15 *

    16 */

    17 

    18 

    19 #ifndef LBTSTARTUPTRIGGER_H

    20 #define LBTSTARTUPTRIGGER_H

    21 

    22 #include <lbttriggerentry.h>

    23 #include <lbs.h>

    24 

    25 /**

    26  *  Concrete class representing start-up trigger entries.

    27  *

    28  *  When a start-up trigger is fired, Location Triggering Server tries to 

    29  *  launch a new instance of the trigger handling process. Trigger handling

    30  *  process is specified by the client application when the trigger is 

    31  *  created. The command line arguments, if specified, are passed to the 

    32  *  thread function of the new process's main thread. If the specified 

    33  *  process can't be launched when the trigger is fired, Location Triggering 

    34  *  Server will try to launch the process next time when the trigger is 

    35  *  fired again. 

    36  *

    37  *  Start-up trigger has following additional attributes

    38  *

    39  *  -  <B>Trigger handling process identity</B> Trigger handling process 

    40  *  identity consists of the executable name of the trigger handling process.

    41  *  The process is launched when the start-up trigger is fired. This attribute 

    42  *  can't be modified after the start-up trigger is created.

    43  *

    44  *  -  <B> SID of the trigger handling process</B> When SID of the trigger 

    45  *  handling process is specified when the trigger is created, the trigger 

    46  *  handling process is able to access the trigger. If the SID is not specified,

    47  *  the trigger handling process can't access the trigger. This attribute 

    48  *  cannot be modified after the start-up trigger is created.

    49  *

    50  *  -  <B>Command-line argument string</B> Command-line argument string is passed

    51  *  as an argument to the main thread of the launched process, when it's 

    52  *  first scheduled. Command-line argument string is passed to the launched 

    53  *  process as it is specified. Location Triggering Server doesn't interpret any

    54  *  special character. This attribute can be modified after the trigger is

    55  *  created.

    56  *

    57  *  Trigger handling process identity must be specified when the trigger 

    58  *  is created in Location Triggering Server. SID of the trigger handling 

    59  *  process and Command-line argument string is optional.

    60  *

    61  *  If the trigger handling process is not the owner process of the trigger and

    62  *  the SID of the trigger handling process is not specified when the trigger 

    63  *  is created, it can't access the firing trigger

    64  *  information. In this case, if the trigger handling process needs to 

    65  *  get information of the firing trigger, it can get it either from 

    66  *  command-line argument string which is set when the trigger is created 

    67  *  or request a service from the owner process.

    68  *

    69  *  If a UIKON based UI application is specified as trigger handling process,

    70  *  the UIKON framework will prevent starting a new instance of the application if

    71  *  it's already running. In this case, the trigger handling process (UI application)

    72  *  shall issue trigger firing event notification request to Location Triggering 

    73  *  Server when it's started.

    74  *

    75  *  If the owner process, Manager UI or trigger handling process 

    76  *  of a trigger is removed from the system, the trigger becomes 

    77  *  invalid. The process can be removed for example when the process's 

    78  *  executable resides in removable media (like MMC), and that media is 

    79  *  removed from the terminal. An invalid trigger is not supervised by 

    80  *  the system. If a trigger has been invalid longer than the predefined system 

    81  *  clean up time, the trigger is removed from the system. System clean up time 

    82  *  is defined by system and cant' be accessed by client application.

    83  * 

    84  *  @see RLbt

    85  *

    86  *  @lib lbt.lib

    87  *  @since S60 5.1

    88  */

    89 class CLbtStartupTrigger : public CLbtTriggerEntry

    90     {

    91 public:

    92     /**

    93      * Allocates and constructs a new start-up trigger entry.

    94      * Default values are assigned to the attributes. 

    95      * The default values are

    96      * 

    97      *  - Trigger Id is KLbtNullTriggerId.

    98      *

    99      *  - Trigger Name is an empty string.

   100      *

   101      *  - Trigger State CLbtTriggerEntry::EStateEnabled.

   102      *  

   103      *  - Requestors are not set. 

   104      *

   105      *  - Manager UI is not set(KNullUid). 

   106      *

   107      *  - Trigger condition is not set.

   108      *

   109      *  - Trigger handling process file name is empty string.

   110      * 

   111      *  - SID of the trigger handling process is KNullUid.

   112      *

   113      *  - Command-line argument string is an empty string

   114      *

   115      * @return Pointer to the new start-up trigger entry.

   116      */

   117     IMPORT_C static CLbtStartupTrigger* NewL();

   118 

   119     /**

   120      * Allocates and constructs a new start-up trigger entry. The

   121      * constructed object is pushed onto cleanup stack.

   122      * Default values are assigned to the attributes. 

   123      * The default values are

   124      * 

   125      *  - Trigger Id is KLbtNullTriggerId.

   126      *

   127      *  - Trigger Name is an empty string.

   128      *

   129      *  - Trigger State CLbtTriggerEntry::EStateEnabled.

   130      *  

   131      *  - Requestors are not set. 

   132      *

   133      *  - Manager UI is not set(KNullUid). 

   134      *

   135      *  - Trigger condition is not set.

   136      *

   137      *  - Trigger handling process file name is empty string.

   138      * 

   139      *  - SID of the trigger handling process is KNullUid.

   140      *

   141      *  - Command-line argument string is an empty string

   142      *

   143      * @return Pointer to the new start-up trigger entry.

   144      */

   145     IMPORT_C static CLbtStartupTrigger* NewLC();

   146 

   147     /**

   148      * Allocates and constructs a new start-up trigger entry.

   149      *

   150      * @param[in] aName The name of the trigger entry.

   151      * @param[in] aState The state of trigger entry.

   152      * @param[in] aRequestorType Identifies the type of requestor, a

   153      * service or a contact.

   154      * @param[in] aRequestorFormat Determines the type of data held 

   155      * in aRequestorData

   156      * @param[in] aRequestorData Requestor data. Can be a telephone 

   157      * number, a URL etc.

   158      * @param[in] aManagerUi The UID of manager UI. 

   159      * @param[in] aCondition Pointer of the new trigger condition object.

   160      * This object takes the ownership of aCondition.

   161      * @param[in] aFileName A descriptor containing the full path name of

   162      * the executable to be loaded when the start-up trigger is fired. If 

   163      * this name has no file extension, an extension of .exe is appended. 

   164      * The length of the resulting full path name must not be greater 

   165      * than KMaxFileName. The length of the file name itself must not be 

   166      * greater than KMaxOsName. If no path is specified, the system will 

   167      * look in system executable directories on all local drives, in the  

   168      * same search order as specified in TFindFile::FindByPath().

   169      * @param[in] aSecureId The SID of the trigger handling process.

   170      * If the specified value is KNullUid or a wrong value is specified,

   171      * the trigger handling process would not be able to access the 

   172      * trigger.

   173      * @param[in] aCommandLine Command-line argument string.

   174      * @return Pointer to the new start-up trigger entry.

   175      * @leave KErrArgument If the name of the trigger is longer than

   176      *   @p KLbtMaxNameLength.

   177      * @leave Other standard symbian error code, such as KErrNoMemory,

   178      * KErrGeneral, etc.

   179      * @panic ELbtErrArgument The length of aFileName is longer than

   180      * @p KMaxFileName.

   181      */

   182     IMPORT_C static CLbtStartupTrigger* NewL( 

   183         const TDesC& aName,

   184         TLbtTriggerState aState,

   185         CRequestor::TRequestorType aRequestorType,

   186         CRequestor::TRequestorFormat aRequestorFormat,

   187         const TDesC& aRequestorData,

   188         TUid aManagerUi,

   189         CLbtTriggerConditionBase* aCondition,

   190         const TDesC& aFileName, 

   191         const TSecureId& aSecureId = KNullUid,

   192         const TDesC& aCommandLine = KNullDesC() );

   193     

   194     /**

   195      * Allocates and construct a new start-up trigger entry.

   196      *

   197      * @panic ELbtErrArgument The length of aFileName is greater than

   198      * @p KMaxFileName.

   199      *

   200      * @param[in] aName The name of the trigger entry.

   201      * @param[in] aState The state of trigger entry.

   202      * @param[in] aRequestors The requestor for the service. This object

   203      * does not take the ownership of aRequestor.

   204      * @param[in] aManagerUi The UID of manager UI.

   205      * @param[in] aCondition Pointer of the new trigger condition object.

   206      * This object takes the ownership of aCondition.

   207      * @param[in] aFileName A descriptor containing the full path name of

   208      * the executable to be loaded when the start-up trigger is fired. If 

   209      * this name has no file extension, an extension of .exe is appended. 

   210      * The length of the resulting full path name must not be greater 

   211      * than KMaxFileName. The length of the file name itself must not be 

   212      * greater than KMaxOsName. If no path is specified, the system will 

   213      * look in system executable directories on all local drives, in the  

   214      * same search order as specified in TFindFile::FindByPath().

   215      * @param[in] aSecureId The SID of the trigger handling process.

   216      * If the specified value is KNullUid or a wrong value is specified,

   217      * the trigger handling process would not be able to access the 

   218      * trigger.

   219      * @param[in] aCommandLine Command-line argument string.

   220      * @return Pointer to the new start-up trigger entry.

   221      * @leave KErrArgument If the name of the trigger is longer than

   222      * @p KLbtMaxNameLength.

   223      * @leave Other standard symbian error code, such as KErrNoMemory,

   224      * KErrGeneral, etc.

   225      */

   226     IMPORT_C static CLbtStartupTrigger* NewL( 

   227         const TDesC& aName,

   228         TLbtTriggerState aState,

   229         const RRequestorStack& aRequestors,

   230         TUid aManagerUi,

   231         CLbtTriggerConditionBase* aCondition,

   232         const TDesC& aFileName, 

   233         const TSecureId& aSecureId = KNullUid,

   234         const TDesC& aCommandLine = KNullDesC() );

   235 

   236     /**

   237      * Destructor

   238      */

   239     IMPORT_C ~CLbtStartupTrigger();

   240 

   241     /**

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

   243      *

   244      * @return CLbtTriggerEntry::EStartup.

   245      */

   246     IMPORT_C TType Type() const;

   247     

   248     /**

   249      * Gets identity of the trigger handling process.

   250      * 

   251      * @param[out] aFileName On return contains the full path name

   252      * of the executable of trigger handling process. Maximum length 

   253      * of the resulting full path name is KMaxFileName. Client gets 

   254      * panic USER 11 if the length of executable full path name is 

   255      * greater than the maximum length of aFileName. Empty string 

   256      * is returned if the attribute has not been set.

   257      * @param[out] aSecureId On return contains the SID of

   258      * the triggering handling process. KNullUid is returned if

   259      * the SID has not been previously set. 

   260      */

   261     IMPORT_C void GetProcessId( 

   262         TDes& aFileName, 

   263         TSecureId& aSecureId ) const;

   264     

   265     /**

   266      * Sets the identity of the trigger handling process.

   267      *

   268      * @param[in] aFileName A descriptor containing the full path name of

   269      * the executable to be loaded when the start-up trigger is fired. If 

   270      * this name has no file extension, an extension of .exe is appended. 

   271      * The length of the resulting full path name must not be greater 

   272      * than @p KMaxFileName. The length of the file name itself must not be 

   273      * greater than KMaxOsName. If no path is specified, the system will 

   274      * look in system executable directories on all local drives, in the  

   275      * same search order as specified in TFindFile::FindByPath().

   276      * @param[in] aSecureId The SID of the trigger handling process.

   277      * If the specified value is KNullUid or a wrong value is specified,

   278      * the trigger handling process would not be able to access the 

   279      * trigger.

   280      * @panic ELbtErrArgument The length of aFileName is greater than

   281      * @p KMaxFileName.

   282      */

   283     IMPORT_C void SetProcessId( 

   284         const TDesC& aFileName, 

   285         const TSecureId& aSecureId );

   286     

   287     /**

   288      * Gets the command-line argument string.

   289      *

   290      * @return The command-line argument string. Empty string is returned

   291      * if the command-line argument string has not been set

   292      */

   293     IMPORT_C const TDesC& CommandLine() const;

   294     

   295     /**

   296      * Sets the command-line argument string.

   297      * 

   298      * @param[in] aCommandLine The command-line argument string. It can

   299      * be an empty string.

   300      */

   301     IMPORT_C void SetCommandLineL( const TDesC& aCommandLine );

   302     

   303     

   304 protected:

   305     

   306     /**

   307      * Internalize method that subclass must implement.

   308      * @param[in] aStream Stream from which the object should be internalized.

   309      */

   310     virtual void DoInternalizeL(RReadStream& aStream);

   311     

   312     /**

   313      * Externalize method that subclass must implement.

   314      * @param[in] aStream Stream to which the object should be externalized.

   315      */

   316     virtual void DoExternalizeL(RWriteStream& aStream) const;  

   317 

   318          

   319 

   320 private:

   321     /**

   322      * Default constructor

   323      */

   324     CLbtStartupTrigger(); 

   325         

   326     /**

   327      * By default, prohibit copy constructor

   328      */

   329     CLbtStartupTrigger( const CLbtStartupTrigger& );

   330     

   331     /**

   332      * Prohibit assigment operator

   333      */

   334     CLbtStartupTrigger& operator= ( const CLbtStartupTrigger& );

   335     

   336     /**

   337      * Symbian 2nd phase constructor

   338      */

   339     void ConstructL();

   340     

   341     /**

   342      * Symbian 2nd phase constructor

   343      */

   344     void ConstructL(const TDesC& aName,

   345         TLbtTriggerState aState,

   346         CRequestor::TRequestorType aRequestorType,

   347         CRequestor::TRequestorFormat aRequestorFormat,

   348         const TDesC& aRequestorData,

   349         TUid aManagerUi,

   350         CLbtTriggerConditionBase* aCondition,

   351         const TDesC& aFileName, 

   352         const TSecureId& aSecureId ,

   353         const TDesC& aCommandLine);

   354     

   355     /**

   356      * Symbian 2nd phase constructor

   357      */    

   358     void CLbtStartupTrigger::ConstructL( const TDesC& aName,

   359         CLbtTriggerEntry::TLbtTriggerState aState,

   360         const RRequestorStack& aRequestors,

   361         TUid aManagerUi,

   362         CLbtTriggerConditionBase* aCondition,

   363         const TDesC& aFileName, 

   364         const TSecureId& aSecureId ,

   365         const TDesC& aCommandLine);

   366         

   367 private:

   368     /**

   369      * Process file name 

   370      */

   371     TFileName iProcessFileName;

   372     

   373     /**

   374      * Secure Id

   375      */

   376     TSecureId iSecureId;

   377     

   378     /**

   379      * Command line arguement

   380      */

   381     HBufC* iCommandLine;

   382     };

   383 

   384 

   385 #endif // LBTSTARTUPTRIGGER_H