1.1 --- a/epoc32/include/mw/apacmdln.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/mw/apacmdln.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,9 +1,9 @@
1.4 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 // All rights reserved.
1.6 // This component and the accompanying materials are made available
1.7 -// 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.8 +// under the terms of "Eclipse Public License v1.0"
1.9 // which accompanies this distribution, and is available
1.10 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 //
1.13 // Initial Contributors:
1.14 // Nokia Corporation - initial contribution.
1.15 @@ -11,160 +11,111 @@
1.16 // Contributors:
1.17 //
1.18 // Description:
1.19 +// apacmdln.h
1.20 //
1.21
1.22 -#if !defined(__APACMDLN_H__)
1.23 +#ifndef __APACMDLN_H__
1.24 #define __APACMDLN_H__
1.25
1.26 -#if !defined(__E32BASE_H__)
1.27 -#include <e32base.h>
1.28 -#endif
1.29 +#include <e32base.h> // class CBase
1.30 +#include <apadef.h> // enum TApaCommand
1.31 +#include <f32file.h>
1.32 +#include <s32strm.h>
1.33
1.34 -#if !defined(__APADEF_H__)
1.35 -#include <apadef.h>
1.36 -#endif
1.37
1.38 -#if !defined(__F32FILE_H__)
1.39 -#include <f32file.h>
1.40 -#endif
1.41 -
1.42 -#if !defined(__S32STRM_H__)
1.43 -#include <s32strm.h>
1.44 -#endif
1.45 -
1.46 -
1.47 -class CApaCommandLine : public CBase
1.48 /** Information for launching an application.
1.49
1.50 -This is often referred to as a command line and contains:
1.51 +To start an application, passed a CApaCommandLine object to the RApaLsSession::StartApp() method.
1.52
1.53 -the name of an application EXE to be launched,
1.54 -
1.55 -a document name,
1.56 -
1.57 +This class is often referred to as a command line and contains:
1.58 +the name of an application EXE to be launched, a document name,
1.59 a command code that defines the way the application is launched
1.60 -
1.61 trailing data; the structure of this depends on the application to be launched.
1.62
1.63 -The information is held in a buffer implemented by a heap descriptor.
1.64 +To start an application, startup parameters are set on the CApaCommandLine object that is
1.65 +then externalized into a stream and attached to a new RProcess object. These parameters
1.66 +are then used to re-populate a new CApaCommandLine object inside the process by
1.67 +EikStart::RunApplication() and used to bootstrap the launching application.
1.68
1.69 @publishedAll
1.70 @released */
1.71 +class CApaCommandLine : public CBase
1.72 {
1.73 public:
1.74 - // construction/destruction
1.75 + // Creates an empty command line object
1.76 IMPORT_C static CApaCommandLine* NewL();
1.77 IMPORT_C static CApaCommandLine* NewLC();
1.78 + // Specify how the application is to be started (see TApaCommand in apadef.h)
1.79 + IMPORT_C void SetCommandL(TApaCommand aCommand);
1.80 + IMPORT_C TApaCommand Command() const;
1.81 + // Launch the application associated with the mime-type of the document file
1.82 + IMPORT_C void SetDocumentNameL(const TDesC& aDocName);
1.83 + IMPORT_C TPtrC DocumentName() const;
1.84 + IMPORT_C void SetFileByHandleL(const RFile& aFile);
1.85 + IMPORT_C void GetFileByHandleL(RFile& aFile) const;
1.86 + // Launch the application explicitly named
1.87 + IMPORT_C void SetExecutableNameL(const TDesC& aAppName);
1.88 + IMPORT_C TPtrC ExecutableName() const;
1.89 + // Additional application execution arguments (added to the tail if the command line)
1.90 + IMPORT_C void SetTailEndL(const TDesC8& aTailEnd);
1.91 + IMPORT_C TPtrC8 TailEnd() const;
1.92 + // Set the process id of the application being the conceptual parent.
1.93 + // The child process will be closed down automatically when the parent is.
1.94 + IMPORT_C void SetParentProcessId(TProcessId aProcessId);
1.95 + IMPORT_C TProcessId ParentProcessId() const;
1.96 + // Starting the application on a specific screen
1.97 + IMPORT_C void SetDefaultScreenL(TInt aDefaultScreenNumber);
1.98 + IMPORT_C TInt DefaultScreen() const;
1.99 + IMPORT_C TBool IsDefaultScreenSet() const;
1.100 + // Managed order of applications' window groups.
1.101 + // A child applicatoin's windows will always be kept in front of the parent's windows.
1.102 + IMPORT_C void SetParentWindowGroupID(TInt aParentWindowGroupID);
1.103 + IMPORT_C TInt ParentWindowGroupID() const;
1.104 + // Process environment-slot for public use. These can be used for passing parameters
1.105 + // to the starting application. However, use of the EndTail should be prefered.
1.106 + IMPORT_C static TInt NumberOfEnvironmentSlotsForPublicUse();
1.107 + IMPORT_C static TInt EnvironmentSlotForPublicUse(TInt aIndex);
1.108 +public: // Internal
1.109 IMPORT_C ~CApaCommandLine();
1.110 -
1.111 + // Set opaque data sent to the application being started
1.112 + IMPORT_C void SetOpaqueDataL(const TDesC8& aOpaqueData);
1.113 + IMPORT_C TPtrC8 OpaqueData() const;
1.114 + // Getting/setting the CApaCommandLine to/from a server IPC-message
1.115 + IMPORT_C void GetIpcArgsLC(TIpcArgs& aIpcArgs) const;
1.116 + IMPORT_C void ConstructCmdLineFromMessageL(const RMessage2& aMessage);
1.117 // Getting/setting the CApaCommandLine to/from process environment-slots
1.118 IMPORT_C void SetProcessEnvironmentL(RProcess& aProcess) const;
1.119 IMPORT_C static TInt GetCommandLineFromProcessEnvironment(CApaCommandLine*& aCommandLine);
1.120 -
1.121 - // Getting/setting the CApaCommandLine to/from a server IPC-message
1.122 - IMPORT_C void GetIpcArgsLC(TIpcArgs& aIpcArgs) const;
1.123 - IMPORT_C void ConstructCmdLineFromMessageL(const RMessage2& aMessage);
1.124 -
1.125 - // operations on the document name
1.126 - IMPORT_C void SetDocumentNameL(const TDesC& aDocName);
1.127 - IMPORT_C TPtrC DocumentName() const;
1.128 -
1.129 - // operations on the executable name
1.130 - IMPORT_C void SetExecutableNameL(const TDesC& aAppName);
1.131 - IMPORT_C TPtrC ExecutableName() const;
1.132 -
1.133 - IMPORT_C void SetOpaqueDataL(const TDesC8& aOpaqueData);
1.134 - IMPORT_C TPtrC8 OpaqueData() const;
1.135 -
1.136 - // operations on the tail end
1.137 - IMPORT_C void SetTailEndL(const TDesC8& aTailEnd);
1.138 - IMPORT_C TPtrC8 TailEnd() const;
1.139 -
1.140 - // operations on the command
1.141 - IMPORT_C void SetCommandL(TApaCommand aCommand);
1.142 - IMPORT_C TApaCommand Command() const;
1.143 -
1.144 - // operations on the parent process id
1.145 - IMPORT_C void SetParentProcessId(TProcessId aProcessId);
1.146 - IMPORT_C TProcessId ParentProcessId() const;
1.147 -
1.148 - // operations on the file passed by handle
1.149 - IMPORT_C void SetFileByHandleL(const RFile& aFile);
1.150 - IMPORT_C void GetFileByHandleL(RFile& aFile) const;
1.151 -public:
1.152 -
1.153 + // operations to support passing memory-allocation failure settings in to applications
1.154 + IMPORT_C void SetDebugMemFailL(TInt aDebugMemFail);
1.155 + IMPORT_C TInt DebugMemFail() const;
1.156 + // operations to support the instrumentation (i.e. profiling) of application startup
1.157 + IMPORT_C void SetAppStartupInstrumentationEventIdBaseL(TInt aEventIdBase);
1.158 + IMPORT_C TInt AppStartupInstrumentationEventIdBase() const;
1.159 // operations on the server requirement/differentiator number - 0 means no server, non-zero sets the differentiator for the server name
1.160 IMPORT_C void SetServerNotRequiredL();
1.161 IMPORT_C void SetServerRequiredL(TUint aServerDifferentiator);
1.162 IMPORT_C TUint ServerRequired() const;
1.163 -
1.164 - // operations to support starting an application with a specific screen number
1.165 - IMPORT_C void SetDefaultScreenL(TInt aDefaultScreenNumber);
1.166 - IMPORT_C TInt DefaultScreen() const;
1.167 - IMPORT_C TBool IsDefaultScreenSet() const;
1.168 -
1.169 - // Operations to support window chaining
1.170 - IMPORT_C void SetParentWindowGroupID(TInt aParentWindowGroupID);
1.171 - IMPORT_C TInt ParentWindowGroupID() const;
1.172 -
1.173 - // operations to support passing memory-allocation failure settings in to applications
1.174 - IMPORT_C void SetDebugMemFailL(TInt aDebugMemFail);
1.175 - IMPORT_C TInt DebugMemFail() const;
1.176 -
1.177 - // operations to support the instrumentation (i.e. profiling) of application startup
1.178 - IMPORT_C void SetAppStartupInstrumentationEventIdBaseL(TInt aEventIdBase);
1.179 - IMPORT_C TInt AppStartupInstrumentationEventIdBase() const;
1.180 -
1.181 - IMPORT_C static TInt EnvironmentSlotForPublicUse(TInt aIndex);
1.182 -
1.183 -private:
1.184 - struct SOption
1.185 - {
1.186 - const TDesC* iToken;
1.187 - TInt* iResult;
1.188 - TRadix iRadix;
1.189 - HBufC8* iHBufC8Result;
1.190 - };
1.191 -
1.192 private:
1.193 CApaCommandLine();
1.194 - void SetServerDifferentiatorL(TUint aServerDifferentiator);
1.195 void ExternalizeL(RWriteStream& aStream) const;
1.196 void InternalizeL(RReadStream& aStream);
1.197 HBufC8* StreamableAttributesLC() const;
1.198 - void GetCommandLineFromProcessEnvironmentL();
1.199 - TInt Parse(const TDesC& aCmdLine);
1.200 - TPtrC StripQuotes(const TDesC& aDes) const;
1.201 -
1.202 -private:
1.203 - enum
1.204 - {
1.205 - EEnvironmentSlotUnused=0,
1.206 -
1.207 - EEnvironmentSlotMain=1,
1.208 - EEnvironmentSlotFsSession=2,
1.209 - EEnvironmentSlotFile=3,
1.210 -
1.211 - EFirstEnvironmentSlotForPublicUse=8,
1.212 - ENumberOfEnvironmentSlotsForPublicUse=4
1.213 - };
1.214 -
1.215 - enum
1.216 - {
1.217 - EIpcSlotMain=0,
1.218 - EIpcSlotFsSession=1,
1.219 - EIpcSlotFile=2
1.220 - };
1.221 + void DoGetCommandLineFromProcessEnvironmentL();
1.222 + TInt DoGetParametersFromCommandLineString(const TDesC& aCmdLine);
1.223 + static HBufC* NameOfExecutable(const TDesC& aCmdLine, TInt& aEndDocNameOffset);
1.224 + static TPtrC StripQuotes(const TDesC& aDes);
1.225 + void SetServerDifferentiatorL(TUint aServerDifferentiator);
1.226 public:
1.227 - enum
1.228 + enum // for internal use only
1.229 {
1.230 EIpcFirstFreeSlot=3
1.231 };
1.232 private:
1.233 - HBufC* iDocumentName;
1.234 - HBufC* iExecutableName;
1.235 - HBufC8* iOpaqueData;
1.236 - HBufC8* iTailEnd;
1.237 + RBuf iDocumentName;
1.238 + RBuf iExecutableName;
1.239 + RBuf8 iOpaqueData;
1.240 + RBuf8 iTailEnd;
1.241 TApaCommand iCommand;
1.242 TUint iServerDifferentiator;
1.243 TInt iDefaultScreenNumber;
1.244 @@ -175,4 +126,4 @@
1.245 TProcessId iParentProcessId;
1.246 };
1.247
1.248 -#endif
1.249 +#endif // __APACMDLN_H__