1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/lbtstartuptrigger.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,385 @@
1.4 +/*
1.5 +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* 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
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: Concrete class representing start-up trigger entries.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef LBTSTARTUPTRIGGER_H
1.23 +#define LBTSTARTUPTRIGGER_H
1.24 +
1.25 +#include <lbttriggerentry.h>
1.26 +#include <lbs.h>
1.27 +
1.28 +/**
1.29 + * Concrete class representing start-up trigger entries.
1.30 + *
1.31 + * When a start-up trigger is fired, Location Triggering Server tries to
1.32 + * launch a new instance of the trigger handling process. Trigger handling
1.33 + * process is specified by the client application when the trigger is
1.34 + * created. The command line arguments, if specified, are passed to the
1.35 + * thread function of the new process's main thread. If the specified
1.36 + * process can't be launched when the trigger is fired, Location Triggering
1.37 + * Server will try to launch the process next time when the trigger is
1.38 + * fired again.
1.39 + *
1.40 + * Start-up trigger has following additional attributes
1.41 + *
1.42 + * - <B>Trigger handling process identity</B> Trigger handling process
1.43 + * identity consists of the executable name of the trigger handling process.
1.44 + * The process is launched when the start-up trigger is fired. This attribute
1.45 + * can't be modified after the start-up trigger is created.
1.46 + *
1.47 + * - <B> SID of the trigger handling process</B> When SID of the trigger
1.48 + * handling process is specified when the trigger is created, the trigger
1.49 + * handling process is able to access the trigger. If the SID is not specified,
1.50 + * the trigger handling process can't access the trigger. This attribute
1.51 + * cannot be modified after the start-up trigger is created.
1.52 + *
1.53 + * - <B>Command-line argument string</B> Command-line argument string is passed
1.54 + * as an argument to the main thread of the launched process, when it's
1.55 + * first scheduled. Command-line argument string is passed to the launched
1.56 + * process as it is specified. Location Triggering Server doesn't interpret any
1.57 + * special character. This attribute can be modified after the trigger is
1.58 + * created.
1.59 + *
1.60 + * Trigger handling process identity must be specified when the trigger
1.61 + * is created in Location Triggering Server. SID of the trigger handling
1.62 + * process and Command-line argument string is optional.
1.63 + *
1.64 + * If the trigger handling process is not the owner process of the trigger and
1.65 + * the SID of the trigger handling process is not specified when the trigger
1.66 + * is created, it can't access the firing trigger
1.67 + * information. In this case, if the trigger handling process needs to
1.68 + * get information of the firing trigger, it can get it either from
1.69 + * command-line argument string which is set when the trigger is created
1.70 + * or request a service from the owner process.
1.71 + *
1.72 + * If a UIKON based UI application is specified as trigger handling process,
1.73 + * the UIKON framework will prevent starting a new instance of the application if
1.74 + * it's already running. In this case, the trigger handling process (UI application)
1.75 + * shall issue trigger firing event notification request to Location Triggering
1.76 + * Server when it's started.
1.77 + *
1.78 + * If the owner process, Manager UI or trigger handling process
1.79 + * of a trigger is removed from the system, the trigger becomes
1.80 + * invalid. The process can be removed for example when the process's
1.81 + * executable resides in removable media (like MMC), and that media is
1.82 + * removed from the terminal. An invalid trigger is not supervised by
1.83 + * the system. If a trigger has been invalid longer than the predefined system
1.84 + * clean up time, the trigger is removed from the system. System clean up time
1.85 + * is defined by system and cant' be accessed by client application.
1.86 + *
1.87 + * @see RLbt
1.88 + *
1.89 + * @lib lbt.lib
1.90 + * @since S60 5.1
1.91 + */
1.92 +class CLbtStartupTrigger : public CLbtTriggerEntry
1.93 + {
1.94 +public:
1.95 + /**
1.96 + * Allocates and constructs a new start-up trigger entry.
1.97 + * Default values are assigned to the attributes.
1.98 + * The default values are
1.99 + *
1.100 + * - Trigger Id is KLbtNullTriggerId.
1.101 + *
1.102 + * - Trigger Name is an empty string.
1.103 + *
1.104 + * - Trigger State CLbtTriggerEntry::EStateEnabled.
1.105 + *
1.106 + * - Requestors are not set.
1.107 + *
1.108 + * - Manager UI is not set(KNullUid).
1.109 + *
1.110 + * - Trigger condition is not set.
1.111 + *
1.112 + * - Trigger handling process file name is empty string.
1.113 + *
1.114 + * - SID of the trigger handling process is KNullUid.
1.115 + *
1.116 + * - Command-line argument string is an empty string
1.117 + *
1.118 + * @return Pointer to the new start-up trigger entry.
1.119 + */
1.120 + IMPORT_C static CLbtStartupTrigger* NewL();
1.121 +
1.122 + /**
1.123 + * Allocates and constructs a new start-up trigger entry. The
1.124 + * constructed object is pushed onto cleanup stack.
1.125 + * Default values are assigned to the attributes.
1.126 + * The default values are
1.127 + *
1.128 + * - Trigger Id is KLbtNullTriggerId.
1.129 + *
1.130 + * - Trigger Name is an empty string.
1.131 + *
1.132 + * - Trigger State CLbtTriggerEntry::EStateEnabled.
1.133 + *
1.134 + * - Requestors are not set.
1.135 + *
1.136 + * - Manager UI is not set(KNullUid).
1.137 + *
1.138 + * - Trigger condition is not set.
1.139 + *
1.140 + * - Trigger handling process file name is empty string.
1.141 + *
1.142 + * - SID of the trigger handling process is KNullUid.
1.143 + *
1.144 + * - Command-line argument string is an empty string
1.145 + *
1.146 + * @return Pointer to the new start-up trigger entry.
1.147 + */
1.148 + IMPORT_C static CLbtStartupTrigger* NewLC();
1.149 +
1.150 + /**
1.151 + * Allocates and constructs a new start-up trigger entry.
1.152 + *
1.153 + * @param[in] aName The name of the trigger entry.
1.154 + * @param[in] aState The state of trigger entry.
1.155 + * @param[in] aRequestorType Identifies the type of requestor, a
1.156 + * service or a contact.
1.157 + * @param[in] aRequestorFormat Determines the type of data held
1.158 + * in aRequestorData
1.159 + * @param[in] aRequestorData Requestor data. Can be a telephone
1.160 + * number, a URL etc.
1.161 + * @param[in] aManagerUi The UID of manager UI.
1.162 + * @param[in] aCondition Pointer of the new trigger condition object.
1.163 + * This object takes the ownership of aCondition.
1.164 + * @param[in] aFileName A descriptor containing the full path name of
1.165 + * the executable to be loaded when the start-up trigger is fired. If
1.166 + * this name has no file extension, an extension of .exe is appended.
1.167 + * The length of the resulting full path name must not be greater
1.168 + * than KMaxFileName. The length of the file name itself must not be
1.169 + * greater than KMaxOsName. If no path is specified, the system will
1.170 + * look in system executable directories on all local drives, in the
1.171 + * same search order as specified in TFindFile::FindByPath().
1.172 + * @param[in] aSecureId The SID of the trigger handling process.
1.173 + * If the specified value is KNullUid or a wrong value is specified,
1.174 + * the trigger handling process would not be able to access the
1.175 + * trigger.
1.176 + * @param[in] aCommandLine Command-line argument string.
1.177 + * @return Pointer to the new start-up trigger entry.
1.178 + * @leave KErrArgument If the name of the trigger is longer than
1.179 + * @p KLbtMaxNameLength.
1.180 + * @leave Other standard symbian error code, such as KErrNoMemory,
1.181 + * KErrGeneral, etc.
1.182 + * @panic ELbtErrArgument The length of aFileName is longer than
1.183 + * @p KMaxFileName.
1.184 + */
1.185 + IMPORT_C static CLbtStartupTrigger* NewL(
1.186 + const TDesC& aName,
1.187 + TLbtTriggerState aState,
1.188 + CRequestor::TRequestorType aRequestorType,
1.189 + CRequestor::TRequestorFormat aRequestorFormat,
1.190 + const TDesC& aRequestorData,
1.191 + TUid aManagerUi,
1.192 + CLbtTriggerConditionBase* aCondition,
1.193 + const TDesC& aFileName,
1.194 + const TSecureId& aSecureId = KNullUid,
1.195 + const TDesC& aCommandLine = KNullDesC() );
1.196 +
1.197 + /**
1.198 + * Allocates and construct a new start-up trigger entry.
1.199 + *
1.200 + * @panic ELbtErrArgument The length of aFileName is greater than
1.201 + * @p KMaxFileName.
1.202 + *
1.203 + * @param[in] aName The name of the trigger entry.
1.204 + * @param[in] aState The state of trigger entry.
1.205 + * @param[in] aRequestors The requestor for the service. This object
1.206 + * does not take the ownership of aRequestor.
1.207 + * @param[in] aManagerUi The UID of manager UI.
1.208 + * @param[in] aCondition Pointer of the new trigger condition object.
1.209 + * This object takes the ownership of aCondition.
1.210 + * @param[in] aFileName A descriptor containing the full path name of
1.211 + * the executable to be loaded when the start-up trigger is fired. If
1.212 + * this name has no file extension, an extension of .exe is appended.
1.213 + * The length of the resulting full path name must not be greater
1.214 + * than KMaxFileName. The length of the file name itself must not be
1.215 + * greater than KMaxOsName. If no path is specified, the system will
1.216 + * look in system executable directories on all local drives, in the
1.217 + * same search order as specified in TFindFile::FindByPath().
1.218 + * @param[in] aSecureId The SID of the trigger handling process.
1.219 + * If the specified value is KNullUid or a wrong value is specified,
1.220 + * the trigger handling process would not be able to access the
1.221 + * trigger.
1.222 + * @param[in] aCommandLine Command-line argument string.
1.223 + * @return Pointer to the new start-up trigger entry.
1.224 + * @leave KErrArgument If the name of the trigger is longer than
1.225 + * @p KLbtMaxNameLength.
1.226 + * @leave Other standard symbian error code, such as KErrNoMemory,
1.227 + * KErrGeneral, etc.
1.228 + */
1.229 + IMPORT_C static CLbtStartupTrigger* NewL(
1.230 + const TDesC& aName,
1.231 + TLbtTriggerState aState,
1.232 + const RRequestorStack& aRequestors,
1.233 + TUid aManagerUi,
1.234 + CLbtTriggerConditionBase* aCondition,
1.235 + const TDesC& aFileName,
1.236 + const TSecureId& aSecureId = KNullUid,
1.237 + const TDesC& aCommandLine = KNullDesC() );
1.238 +
1.239 + /**
1.240 + * Destructor
1.241 + */
1.242 + IMPORT_C ~CLbtStartupTrigger();
1.243 +
1.244 + /**
1.245 + * Gets the type of trigger entry, CLbtTriggerEntry::EStartup.
1.246 + *
1.247 + * @return CLbtTriggerEntry::EStartup.
1.248 + */
1.249 + IMPORT_C TType Type() const;
1.250 +
1.251 + /**
1.252 + * Gets identity of the trigger handling process.
1.253 + *
1.254 + * @param[out] aFileName On return contains the full path name
1.255 + * of the executable of trigger handling process. Maximum length
1.256 + * of the resulting full path name is KMaxFileName. Client gets
1.257 + * panic USER 11 if the length of executable full path name is
1.258 + * greater than the maximum length of aFileName. Empty string
1.259 + * is returned if the attribute has not been set.
1.260 + * @param[out] aSecureId On return contains the SID of
1.261 + * the triggering handling process. KNullUid is returned if
1.262 + * the SID has not been previously set.
1.263 + */
1.264 + IMPORT_C void GetProcessId(
1.265 + TDes& aFileName,
1.266 + TSecureId& aSecureId ) const;
1.267 +
1.268 + /**
1.269 + * Sets the identity of the trigger handling process.
1.270 + *
1.271 + * @param[in] aFileName A descriptor containing the full path name of
1.272 + * the executable to be loaded when the start-up trigger is fired. If
1.273 + * this name has no file extension, an extension of .exe is appended.
1.274 + * The length of the resulting full path name must not be greater
1.275 + * than @p KMaxFileName. The length of the file name itself must not be
1.276 + * greater than KMaxOsName. If no path is specified, the system will
1.277 + * look in system executable directories on all local drives, in the
1.278 + * same search order as specified in TFindFile::FindByPath().
1.279 + * @param[in] aSecureId The SID of the trigger handling process.
1.280 + * If the specified value is KNullUid or a wrong value is specified,
1.281 + * the trigger handling process would not be able to access the
1.282 + * trigger.
1.283 + * @panic ELbtErrArgument The length of aFileName is greater than
1.284 + * @p KMaxFileName.
1.285 + */
1.286 + IMPORT_C void SetProcessId(
1.287 + const TDesC& aFileName,
1.288 + const TSecureId& aSecureId );
1.289 +
1.290 + /**
1.291 + * Gets the command-line argument string.
1.292 + *
1.293 + * @return The command-line argument string. Empty string is returned
1.294 + * if the command-line argument string has not been set
1.295 + */
1.296 + IMPORT_C const TDesC& CommandLine() const;
1.297 +
1.298 + /**
1.299 + * Sets the command-line argument string.
1.300 + *
1.301 + * @param[in] aCommandLine The command-line argument string. It can
1.302 + * be an empty string.
1.303 + */
1.304 + IMPORT_C void SetCommandLineL( const TDesC& aCommandLine );
1.305 +
1.306 +
1.307 +protected:
1.308 +
1.309 + /**
1.310 + * Internalize method that subclass must implement.
1.311 + * @param[in] aStream Stream from which the object should be internalized.
1.312 + */
1.313 + virtual void DoInternalizeL(RReadStream& aStream);
1.314 +
1.315 + /**
1.316 + * Externalize method that subclass must implement.
1.317 + * @param[in] aStream Stream to which the object should be externalized.
1.318 + */
1.319 + virtual void DoExternalizeL(RWriteStream& aStream) const;
1.320 +
1.321 +
1.322 +
1.323 +private:
1.324 + /**
1.325 + * Default constructor
1.326 + */
1.327 + CLbtStartupTrigger();
1.328 +
1.329 + /**
1.330 + * By default, prohibit copy constructor
1.331 + */
1.332 + CLbtStartupTrigger( const CLbtStartupTrigger& );
1.333 +
1.334 + /**
1.335 + * Prohibit assigment operator
1.336 + */
1.337 + CLbtStartupTrigger& operator= ( const CLbtStartupTrigger& );
1.338 +
1.339 + /**
1.340 + * Symbian 2nd phase constructor
1.341 + */
1.342 + void ConstructL();
1.343 +
1.344 + /**
1.345 + * Symbian 2nd phase constructor
1.346 + */
1.347 + void ConstructL(const TDesC& aName,
1.348 + TLbtTriggerState aState,
1.349 + CRequestor::TRequestorType aRequestorType,
1.350 + CRequestor::TRequestorFormat aRequestorFormat,
1.351 + const TDesC& aRequestorData,
1.352 + TUid aManagerUi,
1.353 + CLbtTriggerConditionBase* aCondition,
1.354 + const TDesC& aFileName,
1.355 + const TSecureId& aSecureId ,
1.356 + const TDesC& aCommandLine);
1.357 +
1.358 + /**
1.359 + * Symbian 2nd phase constructor
1.360 + */
1.361 + void CLbtStartupTrigger::ConstructL( const TDesC& aName,
1.362 + CLbtTriggerEntry::TLbtTriggerState aState,
1.363 + const RRequestorStack& aRequestors,
1.364 + TUid aManagerUi,
1.365 + CLbtTriggerConditionBase* aCondition,
1.366 + const TDesC& aFileName,
1.367 + const TSecureId& aSecureId ,
1.368 + const TDesC& aCommandLine);
1.369 +
1.370 +private:
1.371 + /**
1.372 + * Process file name
1.373 + */
1.374 + TFileName iProcessFileName;
1.375 +
1.376 + /**
1.377 + * Secure Id
1.378 + */
1.379 + TSecureId iSecureId;
1.380 +
1.381 + /**
1.382 + * Command line arguement
1.383 + */
1.384 + HBufC* iCommandLine;
1.385 + };
1.386 +
1.387 +
1.388 +#endif // LBTSTARTUPTRIGGER_H