|
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 |