1 /*

     2 * Copyright (c) 2008-2009 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 the License "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: 

    15 * This file defines common types for the SIF APIs.

    16 *

    17 */

    18 

    19 

    20 /**

    21  @file

    22  @publishedAll

    23  @released

    24 */

    25 

    26 #ifndef SIFCOMMON_H

    27 #define SIFCOMMON_H

    28 

    29 #include <ct/rcpointerarray.h>

    30 #include <s32strm.h>

    31 #include <usif/usifcommon.h>

    32 

    33 namespace Usif

    34 	{

    35 

    36 	/**

    37 		This enumeration defines the possible values of the status of an installation package. This status

    38 		can be obtained from a @see CComponentInfo object using the @see CComponentInfo::InstallStatusL()

    39 		method.

    40 	 */

    41 	enum TInstallStatus

    42 		{

    43 		ENewComponent,					///< New installation; the component is not present in the system

    44 		EUpgrade,						///< This is a valid upgrade of an existing component

    45 		EAlreadyInstalled,				///< Component with the same version is already installed

    46 		ENewerVersionAlreadyInstalled,	///< A newer version of the component is already installed

    47 		EInvalid						///< Package is not valid and cannot be installed, for example,

    48 										///< it may be an upgrade of an uninstalled component or the

    49 										///< package may be corrupt

    50 		};

    51 

    52 	/**

    53 		This enumeration defines the possible values of the authenticity of an installation package. This authenticity

    54 		can be obtained from a @see CComponentInfo object using the @see CComponentInfo::Authenticity()

    55 		method.

    56 	 */

    57 	enum TAuthenticity

    58 		{

    59 		ENotAuthenticated,			///< Component could not be authenticated by the installer, e.g. unsigned or self-signed

    60 		EAuthenticated,				///< Component is authenticated

    61 		};

    62 

    63 	/**

    64 		The TSecurityContext class allows SIF plug-ins to verify the capabilities and secure Ids of SIF clients.

    65 		For example, when a SIF client requests silent installation a SIF plug-in may verify that that the client

    66 		has the TrustedUI capability.

    67 	 */

    68 	class TSecurityContext

    69 		{

    70 	public:

    71 		/**

    72 			Checks if the SIF client has a given capability.

    73 

    74 			@param aCapability The capability to test.

    75 			@return ETrue if the SIF client has the capability, EFalse otherwise.

    76 		*/

    77 		IMPORT_C TBool HasCapability(TCapability aCapability) const;

    78 

    79 		/**

    80 			Checks if the SIF client has a given capability.

    81 

    82 			@param aCapability The capability to test.

    83 			@leave KErrPermissionDenied If the SIF client does not have the capability.

    84 		*/

    85 		IMPORT_C void HasCapabilityL(TCapability aCapability) const;

    86 

    87 		/**

    88 			Returns the secure Id of a SIF client.

    89 		*/

    90 		IMPORT_C TSecureId SecureId() const;

    91 

    92 	private:

    93 		friend class CSifTransportRequest;

    94 		IMPORT_C TSecurityContext(const RMessage2& aMessage);

    95 

    96 		const RMessagePtr2 iMsg;

    97 		};

    98 

    99 	/**

   100 		This class provides information about a software package. Returned by RSoftwareInstall::GetComponentInfo()."

   101 	 */

   102 	class CComponentInfo : public CBase

   103 		{

   104 	public:

   105 

   106 		class CNode : public CBase

   107 			{

   108 		public:

   109 			/**

   110 				Initializes the object with the details of a component.

   111 

   112 				@param aSoftwareTypeName The name of the software type of a component.

   113 				@param aComponentName The name of a component.

   114 				@param aVersion The version of a component.

   115 				@param aVendor The name of a component vendor.

   116 				@param aScomoState The SCOMO state of a component.

   117 				@param TInstallStatus The installation status of a component.

   118 				@param aComponentId The Id of a component.

   119 				@param aGlobalComponentId The global Id of a component.

   120 				@param aAuthenticity The authenticity of a component.

   121 				@param aUserGrantableCaps User grantable capabilities of a component.

   122 				@param aHasExe Whether component has an executable.

   123 				@param aChildren Child nodes describing embedded components of a component. This method

   124 				passes the ownership of the child nodes to this new node and empties the aChildren array.

   125 				However, if the leave occurs the caller must delete the child nodes in the array.

   126 				@leave KErrOverflow it the total length of aName, aVersion and aVendor exceeds 512 characters.

   127 				@leave Or other system wide error code

   128 			*/

   129 			IMPORT_C static CNode* NewLC(const TDesC& aSoftwareTypeName, const TDesC& aComponentName,

   130 								const TDesC& aVersion, const TDesC& aVendor, TScomoState aScomoState,

   131 								TInstallStatus aInstallStatus, TComponentId aComponentId,

   132 								const TDesC& aGlobalComponentId, TAuthenticity aAuthenticity,

   133 								const TCapabilitySet& aUserGrantableCaps, TInt aMaxInstalledSize,

   134 								TBool aHasExe,

   135 								RPointerArray<CNode>* aChildren = NULL);

   136 

   137 			/**

   138 				Adds a child node to this node. This method passes the ownership of the child node

   139 				to this node so the caller must pop it from the cleanup stack but not delete.

   140 

   141 				@return The pointer to the child node to be added.

   142 				@leave System wide error code

   143 			*/

   144 			IMPORT_C void AddChildL(CNode* aChild);

   145 

   146 			/**

   147 				Returns the name of software type of a component.

   148 

   149 				@return The name of the software type of a component.

   150 				@leave System wide error code

   151 			*/

   152 			IMPORT_C const TDesC& SoftwareTypeName() const;

   153 

   154 			/**

   155 				Returns the name of a component.

   156 

   157 				@return The name of a component.

   158 				@leave System wide error code

   159 			*/

   160 			IMPORT_C const TDesC& ComponentName() const;

   161 

   162 			/**

   163 				Returns the version of a component.

   164 

   165 				@return The version of a component.

   166 				@leave System wide error code

   167 			*/

   168 			IMPORT_C const TDesC& Version() const;

   169 

   170 			/**

   171 				Returns the name of the component vendor.

   172 

   173 				@return The name of the component vendor.

   174 				@leave System wide error code

   175 			*/

   176 			IMPORT_C const TDesC& Vendor() const;

   177 

   178 			/**

   179 				Returns the SCOMO state of a component. This has meaning only if the installStatus of the component

   180 				is not EInvalid or ENewComponent.

   181 

   182 				@return The SCOMO state of a component.

   183 				@leave System wide error code

   184 			*/

   185 			IMPORT_C TScomoState ScomoState() const;

   186 

   187 			/**

   188 				Returns the installation status of a component.

   189 

   190 				@return The installation status of a component.

   191 				@leave System wide error code

   192 			*/

   193 			IMPORT_C TInstallStatus InstallStatus() const;

   194 

   195 			/**

   196 				Returns the Id of a component.

   197 

   198 				@return The Id of a component.

   199 				@leave System wide error code

   200 			*/

   201 			IMPORT_C TComponentId ComponentId() const;

   202 

   203 			/**

   204 				Returns the global Id of a component.

   205 

   206 				@return The global Id of a component.

   207 				@leave System wide error code

   208 			*/

   209 			IMPORT_C const TDesC& GlobalComponentId() const;

   210 

   211 			/**

   212 				Returns the authenticity of a component.

   213 

   214 				@return The authenticity of a component.

   215 				@leave System wide error code

   216 			*/

   217 			IMPORT_C TAuthenticity Authenticity() const;

   218 

   219 			/**

   220 				Returns user capabilities required by a component.

   221 

   222 				@return The user grantable capabilities.

   223 				@leave System wide error code

   224 			*/

   225 			IMPORT_C const TCapabilitySet& UserGrantableCaps() const;

   226 

   227 			/**

   228 				Returns the maximum size of a component after installation.

   229 

   230 				@return The maximum size of a component.

   231 				@leave System wide error code

   232 			*/

   233 			IMPORT_C TInt MaxInstalledSize() const;

   234 

   235 			/**

   236 				Returns the array of CComponentInfo objects for the components embedded

   237 				in the component being queried.

   238 

   239 				@return The array of the embedded CComponentInfo objects.

   240 				@leave System wide error code

   241 			*/

   242 			IMPORT_C const RPointerArray<CNode>& Children() const;

   243 

   244 			/**

   245 				Destructor.

   246 			*/

   247 			IMPORT_C virtual ~CNode();

   248 			/**

   249 				Returns the HasExecutable Flag which indicates whether the

   250 				component has an executable.

   251 

   252 				@return The HasExecutable TBool Flag .

   253 			*/

   254 			IMPORT_C TBool HasExecutable() const;

   255 

   256 		private:

   257 			friend class CComponentInfo;

   258 

   259 			CNode();

   260 			CNode& operator=(const CNode& other);

   261 			CNode(const CNode& other);

   262 

   263 			static CNode* NewL(RReadStream& aStream);

   264 			void ExternalizeL(RWriteStream& aStream) const;

   265 

   266 			HBufC* iSoftwareTypeName;				///< The name of software type of the component

   267 			HBufC* iComponentName;					///< The name of the software component

   268 			HBufC* iVersion;						///< The Version of the software component 

   269 			HBufC* iVendor;							///< The of the vendor of the software component

   270 			HBufC* iGlobalComponentId;				///< The global id of the component if already installed

   271 			TScomoState iScomoState;				///< The SCOMO status of the component

   272 			TInstallStatus iInstallStatus;			///< Informs whether the component is already installed or upgradeable

   273 			TComponentId iComponentId;				///< The unique id of the component if already installed

   274 			TAuthenticity iAuthenticity;			///< The authenticity of the component

   275 			TCapabilitySet iUserGrantableCaps;		///< User grantable capabilities required be the component

   276 			TInt iMaxInstalledSize;					///< The maximum size of the component after installation

   277 			TBool iHasExe;							///< Indicates Whether the component has an executable

   278 			RCPointerArray<CNode> iChildren;		///< The array of components embedded in the component being queried

   279 			};

   280 

   281 	public:

   282 

   283 		/**

   284 			Creates a new instance of the CComponentInfo class.

   285 

   286 			@leave System wide error code

   287 		 */

   288 		IMPORT_C static CComponentInfo* NewL();

   289 

   290 		/**

   291 			Creates a new instance of the CComponentInfo class.

   292 

   293 			@leave System wide error code

   294 		 */

   295 		IMPORT_C static CComponentInfo* NewLC();

   296 

   297 		/**

   298 			Returns the root node of this CComponentInfo object.

   299 

   300 			@return The root node of this CComponentInfo object.

   301 			@leave System wide error code

   302 		 */

   303 		IMPORT_C const CNode& RootNodeL() const;

   304 

   305 		/**

   306 			Sets a node as the root node of this component info. This method passes the

   307 			ownership of the root node to this object so the caller must pop it from the

   308 			cleanup stack but not delete.

   309 			

   310 			@return The pointer to the root node to be set.

   311 			@leave System wide error code

   312 		 */

   313 		IMPORT_C void SetRootNodeL(CNode* aRootNode);

   314 

   315 		/**

   316 			Returns the pointer to the root node of this object. The caller takes the ownership

   317 			of this node and must delete it when no longer needed. After this call the CComponentInfo

   318 			object doesn't contain a root node. Hence, calling RootNodeL() results in the leave with

   319 			 KErrNotFound.

   320 			

   321 			@return The pointer to the root node.

   322 			@leave System wide error code

   323 		 */

   324 		IMPORT_C void SetRootNodeAsChildL(CNode& aParentNode);

   325 

   326 		/**

   327 			Externalises an object of this class to a write stream.

   328 

   329 			@param aStream Stream to which the object should be externalised.

   330 			@leave System wide error code

   331 		 */

   332 		IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   333 

   334 		/**

   335 			Allocates a buffer for serialized CComponentInfo and registers it in the @see TIpcArgs class.

   336 			The SIF server serializes a @see CComponentInfo object into this buffer.

   337 

   338 			@param aIpcArgs Arguments to be sent to the SIF Server.

   339 			@param aIndex An index value that identifies the slot in the array of arguments into which

   340 			the argument value is to be placed. This must be a value in the range 0 to 3.

   341 			@leave System wide error code

   342 		*/

   343 		IMPORT_C void PrepareForIpcL(TIpcArgs& aIpcArgs, TInt aIndex);

   344 

   345 		/**

   346 			Destructor.

   347 		*/

   348 		IMPORT_C virtual ~CComponentInfo();

   349 

   350 	private:

   351 		CComponentInfo();

   352 		CComponentInfo& operator=(const CComponentInfo& other);

   353 		CComponentInfo(const CComponentInfo& other);

   354 

   355 		void InternalizeFromExternalBufferL() const;

   356 		void ConstInternalizeL(RReadStream& aStream) const;

   357 		void CleanupExternalBuffer() const;

   358 

   359 		CNode* iRootNode;

   360 

   361 		mutable HBufC8* iExternalBuffer;

   362 		mutable TPtr8 iExternalBufferPtr;

   363 		mutable TBool iDeferredInternalization;

   364 

   365 		enum

   366 			{

   367 			// An arbitrary limit for the length of a single descriptor, for example aComponentName, aVersion or aVendor.

   368 			KMaxDescriptorLength = 256,

   369 			// An arbitrary limit for the total length of iSoftwareTypeName, iComponentName, iVersion, iVendor and iGlobalComponentId.

   370 			KMaxHeapBufLength = 2048,

   371 			// An arbitrary size of the internal buffer for sending the component info across the process boundary

   372 			KMaxComponentInfoStreamedSize = 2*KMaxHeapBufLength+6*sizeof(TInt)+sizeof(TInt8),

   373 			};

   374 		};

   375 

   376 

   377 	/**

   378 		The COpaqueNamedParams class is a container for integer and string values identified by name.

   379 

   380 		This class is designed for sending opaque params across the process boundary. For example, a SIF

   381 		client may use it to send custom arguments to the SIF server or receive custom results.

   382 	*/

   383 	class COpaqueNamedParams : public CBase

   384 		{

   385 	public:

   386 		/**

   387 			Creates a new instance of the COpaqueNamedParams class.

   388 

   389 			@leave System wide error code

   390 		 */

   391 		IMPORT_C static COpaqueNamedParams* NewL();

   392 

   393 		/**

   394 			Creates a new instance of the COpaqueNamedParams class.

   395 

   396 			@leave System wide error code

   397 		 */

   398 		IMPORT_C static COpaqueNamedParams* NewLC();

   399 

   400 		/**

   401 			Externalises an object of this class to a write stream.

   402 

   403 			@param aStream Stream to which the object should be externalised.

   404 			@leave System wide error code

   405 		 */

   406 		IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   407 

   408 		/**

   409 			Internalises an object of this class from a read stream.

   410 

   411 			@param aStream Stream from which the object should be internalised.

   412 			@leave System wide error code

   413 		 */

   414 		IMPORT_C void InternalizeL(RReadStream& aStream);

   415 

   416 		/**

   417 			Allocates a buffer and serializes the params of this object into it. The buffer is registered

   418 			in the @see TIpcArgs class in order to be sent to the SIF Server.

   419 

   420 			@param aIpcArgs Ipc arguments to be sent to the SIF Server.

   421 			@param aIndex An index value that identifies the slot in the array of arguments into which

   422 			the argument value is to be placed. This must be a value in the range 0 to 3.

   423 			@leave System wide error code

   424 		*/

   425 		IMPORT_C void PrepareArgumentsForIpcL(TIpcArgs& aIpcArgs, TInt aIndex) const;

   426 

   427 		/**

   428 			Allocates a buffer for serialized opaque results and registers it in the TIpcArgs class.

   429 			The SIF server serializes opaque results into this buffer.

   430 

   431 			@param aIpcArgs Arguments to be sent to the SIF Server.

   432 			@param aIndex An index value that identifies the slot in the array of arguments into which

   433 			the argument value is to be placed. This must be a value in the range 0 to 3.

   434 			@leave System wide error code

   435 		*/

   436 		IMPORT_C void PrepareResultsForIpcL(TIpcArgs& aIpcArgs, TInt aIndex);

   437 

   438 		/**

   439 			Returns the number of the opaque params added to this object.

   440 			@leave System wide error code

   441 		*/

   442 		IMPORT_C TInt CountL() const;

   443 

   444 		/**

   445 			Adds a string param to this object. If a param with the same name already exists it gets overwritten.

   446 

   447 			@param aName The name of the string param to be added.

   448 			@param aValue The value of the string param to be added.

   449 			@leave KErrOverflow if the size of the name or value of the string param being added exceeds 128 bytes or

   450 			the memory allocated for all the params added to this container exceeds 512 bytes.

   451 			@leave System wide error code

   452 		*/

   453 		IMPORT_C void AddStringL(const TDesC& aName, const TDesC& aValue);

   454 

   455 		/**

   456 			Adds an integer param to this object. If a param with the same name already exists it gets overwritten.

   457 

   458 			@param aName The name of the integer param to be added.

   459 			@param aValue The value of the integer param to be added.

   460 			@leave KErrOverflow if the size of the name the integer param being added exceeds 128 bytes or

   461 			the memory allocated for all the params added to this container exceeds 512 bytes.

   462 			@leave System wide error code

   463 		*/

   464 		IMPORT_C void AddIntL(const TDesC& aName, TInt aValue);

   465 

   466 		/**

   467 			Returns the list of the names of params added to the object.

   468 

   469 			@param aNames The list of the names of params. The caller is responsible for the instantiation

   470 			and cleanup of RPointerArray<HBufC>. The caller must also destroy all the elements of aNames added

   471 			by this method.

   472 			@leave System wide error code

   473 		*/

   474 		IMPORT_C void GetNamesL(RPointerArray<HBufC>& aNames) const; 

   475 

   476 		/**

   477 			Gets a reference to the string param identified by aName.

   478 

   479 			@param aName The name of the string param to be obtained.

   480 			@return The value of the string param or KNullDesC if not found.

   481 			@leave System wide error code

   482 		*/

   483 		IMPORT_C const TDesC& StringByNameL(const TDesC& aName) const;

   484 

   485 		/**

   486 			Returns the integer param identified by aName.

   487 

   488 			@param aName The name of the integer param to be obtained.

   489 			@param aValue The value of the integer param returned by this method.

   490 			@return Indicates if the requested param has been found.

   491 			@leave System wide error code

   492 		*/

   493 		IMPORT_C TBool GetIntByNameL(const TDesC& aName, TInt& aValue) const;

   494 

   495 		/**

   496 			Returns the integer param identified by aName.

   497 

   498 			@param aName The name of the integer param to be obtained.

   499 			@return The value of the integer param.

   500 			@leave KErrNotFound if not found

   501 			@leave Or other system-wide error code.

   502 		*/

   503 		IMPORT_C TInt IntByNameL(const TDesC& aName) const;

   504 

   505 		/**

   506 			Empties the container and frees all memory allocated to the params.

   507 		*/

   508 		IMPORT_C void Cleanup();

   509 

   510 		/**

   511 			Destructor.

   512 		*/

   513 		IMPORT_C virtual ~COpaqueNamedParams();

   514 

   515 	private:

   516 		COpaqueNamedParams();

   517 		COpaqueNamedParams& operator=(const COpaqueNamedParams& other);

   518 		COpaqueNamedParams(const COpaqueNamedParams& other);

   519 		

   520 		void InternalizeFromExternalBufferL() const;

   521 		void ConstInternalizeL(RReadStream& aStream) const;

   522 		void ConstCleanup() const;

   523 		void CleanupExternalBuffer() const;

   524 		void VerifyExternalizedSizeForNewParamL(TInt aNameSize, TInt aValueSize) const;

   525 		void VerifyExternalizedSizeForExistingParamL(TInt aOldValueSize, TInt aNewValueSize) const;

   526 

   527 		struct TItem

   528 			{

   529 			HBufC* iName;

   530 			HBufC* iValue;

   531 			};

   532 		RArray<TItem> iParams;

   533 

   534 		mutable HBufC8* iExternalBuffer;

   535 		mutable TPtr8 iExternalBufferPtr;

   536 		mutable TBool iDeferredInternalization;

   537 		mutable TInt iExternalizedSize;

   538 

   539 		enum

   540 			{

   541 			// An arbitrary limit for the length of a single descriptor (the name or value of a param)

   542 			KMaxDescriptorLength = 128,

   543 			// An arbitrary size of the internal buffer for sending the component info across the process boundary

   544 			KMaxExternalizedSize = 512

   545 			};

   546 

   547 		};

   548 

   549 	/**

   550 		Pre-defined opaque arguments and results:

   551 		"InstallInactive" - If provided in the opaque installation parameters, requests the installation of

   552 		a component without activating it. Otherwise, components are activeted after installation by default.

   553 		"InstallSilently" - If provided in the opaque installation parameters, requests a silent installation,

   554 		i.e. one which avoids interaction with the user whenever possible. Please note that this may involve

   555 		additional security checks, and is not necessarily supported by all installers.

   556 		"ComponentId" - If returned in the custom results, provides the id of the newly added component

   557 		after an install. Please note that not all installers (i.e. SIF Plugins) may support this.

   558 		"ExtendedErrCode" - If returned in the custom results gives the extended error information, that is 

   559 		specific to a software component type.

   560 	*/

   561 	_LIT(KSifInParam_InstallInactive, "InstallInactive");

   562 	_LIT(KSifInParam_InstallSilently, "InstallSilently");

   563 	_LIT(KSifOutParam_ComponentId, "ComponentId");

   564 	_LIT(KSifOutParam_ExtendedErrCode, "ExtendedErrCode");

   565 

   566 	/**

   567 		SIF Server Secure ID

   568 	

   569 		Installers should use this id to verify that installation requests come from the SIF Server.

   570 	*/

   571 	_LIT_SECURE_ID(KSifServerUid,0x10285BCB);

   572 

   573 	} // namespace Usif

   574 

   575 #endif // USIF_SIF_COMMON_H