|
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 the SIF API. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 /** |
|
21 @file |
|
22 @publishedAll |
|
23 @released |
|
24 */ |
|
25 |
|
26 #ifndef SIF_H |
|
27 #define SIF_H |
|
28 |
|
29 #include <usif/sif/siftransportclient.h> |
|
30 |
|
31 namespace Usif |
|
32 { |
|
33 /** |
|
34 The RSoftwareInstall class provides an asynchronous interface to the Software |
|
35 Install Framework. This class wraps all the details of client-server communication |
|
36 with the SIF server residing in a separate process. This API is asynchronous and |
|
37 therefore clients may issue concurrect requests. However, the SIF constrains |
|
38 concurrent operations by default. A client issuing an Install or Uninstall request |
|
39 may set the aExclusiveOperation flag to EFalse in order to allow for concurrent |
|
40 execution of his request. However, even if this flag is set to EFalse, a request |
|
41 may fail with KErrServerBusy if a corresponding underlying installer doesn't |
|
42 support concurrent operations. |
|
43 |
|
44 This class is intended to be used by SIF client applications, for example, application |
|
45 or device managers. |
|
46 |
|
47 Software @see TComponentId needed for the Uninstall/Activate/Deactivate APIs is a unique |
|
48 identifier of an installed component regardless of its type across the system. When installing |
|
49 a package containing other embedded packages each embedded component gets its own @see |
|
50 TComponentId in the descending order. For example, we have a package P1 that contains an |
|
51 embedded package P2 that contains yet another embedded package P3. |
|
52 After installation the components may be identified by the following Ids: |
|
53 - Id of Component 1 (Package 1): 6 (example value) |
|
54 - Id of Component 2 (Package 2): 7 |
|
55 - Id of Component 3 (Package 3): 8 |
|
56 Component 3 with Id = 8 is the last installed/most embedded component and therefore its id |
|
57 is the highest. |
|
58 |
|
59 All the SIF operations may require special capabilities in order to complete successfully. |
|
60 This check may be implemented in a SIF plug-in. For example, a silent installation may require |
|
61 the TrustedUI capability. However, this is expected behavour that standard operations |
|
62 don't require any capabilities. Please see @see Usif::CSifPlugin description for further details |
|
63 if there are any deviations from this rule. |
|
64 */ |
|
65 |
|
66 class RSoftwareInstall |
|
67 { |
|
68 public: |
|
69 IMPORT_C RSoftwareInstall(); |
|
70 |
|
71 /** |
|
72 Connects a client to the SIF server. |
|
73 |
|
74 @return Symbian OS error code where KErrNone indicates |
|
75 success and any other value indicates failure. |
|
76 */ |
|
77 IMPORT_C TInt Connect(); |
|
78 |
|
79 /** |
|
80 Disconnects a client from the SIF server. |
|
81 */ |
|
82 IMPORT_C void Close(); |
|
83 |
|
84 /** |
|
85 Returns the details of a component to be installed by file name |
|
86 |
|
87 @param aFileName The file name of a component to be queried |
|
88 @param aComponentInfo On return, contains the details of a component |
|
89 @param aStatus The request status. KErrNone, if successful, otherwise |
|
90 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
91 */ |
|
92 IMPORT_C void GetComponentInfo(const TDesC& aFileName, CComponentInfo& aComponentInfo, |
|
93 TRequestStatus& aStatus); |
|
94 |
|
95 /** |
|
96 * Returns the details of a component to be installed by file handle |
|
97 |
|
98 @param aFileHandle The file handle of a component to be queried |
|
99 @param aComponentInfo On return, contains the details of a component |
|
100 @param aStatus The request status. KErrNone, if successful, otherwise |
|
101 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
102 */ |
|
103 IMPORT_C void GetComponentInfo(RFile& aFileHandle, CComponentInfo& aComponentInfo, |
|
104 TRequestStatus& aStatus); |
|
105 |
|
106 /** |
|
107 Installs a component by file name |
|
108 |
|
109 @param aFileName The file name of a component to be installed |
|
110 @param aStatus The request status. KErrNone, if successful, otherwise |
|
111 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
112 @param aExclusiveOperation If this flag is set to ETrue, the Install |
|
113 operation is executed in the Exclusive mode. In this mode the SIF |
|
114 Server executes only one operation at a time. If there is another |
|
115 operation in progress the SIF Server returns KErrServerBusy. |
|
116 If this flag is set to EFalse, the SIF Server executes the operation |
|
117 even if there is a concurrent operation in progress. The default value |
|
118 is ETrue. |
|
119 */ |
|
120 IMPORT_C void Install(const TDesC& aFileName, TRequestStatus& aStatus, |
|
121 TBool aExclusiveOperation = ETrue); |
|
122 |
|
123 /** |
|
124 Installs a component by file name using opaque arguments/results |
|
125 |
|
126 @param aFileName The file name of a component to be installed |
|
127 @param aArguments The array of opaque params for a SIF plug-in. An empty |
|
128 array may be passed. The following param is defined for the "SCOMO Install |
|
129 Inactive" operation: |
|
130 Name: InstallInactive, Type: Int, Value: ETrue |
|
131 @param aResults The array of opaque params returned from a SIF plug-in. |
|
132 The following return param is defined for the id of an installed component: |
|
133 Name: ComponentId, Type: Int |
|
134 For packages containing embedded components, the returned param contains |
|
135 the id of the last/most embedded component. |
|
136 @param aStatus The request status. KErrNone, if successful, otherwise |
|
137 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
138 @param aExclusiveOperation If this flag is set to ETrue, the Install |
|
139 operation is executed in the Exclusive mode. In this mode the SIF |
|
140 Server executes only one operation at a time. If there is another |
|
141 operation in progress the SIF Server returns KErrServerBusy. |
|
142 If this flag is set to EFalse, the SIF Server executes the operation |
|
143 even if there is a concurrent operation in progress. The default value |
|
144 is ETrue. |
|
145 */ |
|
146 IMPORT_C void Install(const TDesC& aFileName, const COpaqueNamedParams& aArguments, |
|
147 COpaqueNamedParams& aResults, TRequestStatus& aStatus, |
|
148 TBool aExclusiveOperation = ETrue); |
|
149 |
|
150 /** |
|
151 Installs a component by file handle |
|
152 |
|
153 @param aFileHandle The file handle of a component to be installed |
|
154 @param aStatus The request status. KErrNone, if successful, otherwise |
|
155 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
156 @param aExclusiveOperation If this flag is set to ETrue, the Install |
|
157 operation is executed in the Exclusive mode. In this mode the SIF |
|
158 Server executes only one operation at a time. If there is another |
|
159 operation in progress the SIF Server returns KErrServerBusy. |
|
160 If this flag is set to EFalse, the SIF Server executes the operation |
|
161 even if there is a concurrent operation in progress. The default value |
|
162 is ETrue. |
|
163 */ |
|
164 IMPORT_C void Install(RFile& aFileHandle, TRequestStatus& aStatus, |
|
165 TBool aExclusiveOperation = ETrue); |
|
166 |
|
167 /** |
|
168 Installs a component by file handle using opaque arguments/results |
|
169 |
|
170 @param aFileHandle The file handle of a component to be installed |
|
171 @param aArguments The array of opaque params for a SIF plug-in. An empty |
|
172 array may be passed. The following param is defined for the "SCOMO Install |
|
173 Inactive" operation: |
|
174 Name: InstallInactive, Type: Int, Value: ETrue |
|
175 @param aResults The array of opaque params returned from a SIF plug-in. |
|
176 The following return param is defined for the id of an installed component: |
|
177 Name: ComponentId, Type: Int |
|
178 For packages containing embedded components, the returned param contains |
|
179 the id of the last/most embedded component. |
|
180 @param aStatus The request status. KErrNone, if successful, otherwise |
|
181 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
182 @param aExclusiveOperation If this flag is set to ETrue, the Install |
|
183 operation is executed in the Exclusive mode. In this mode the SIF |
|
184 Server executes only one operation at a time. If there is another |
|
185 operation in progress the SIF Server returns KErrServerBusy. |
|
186 If this flag is set to EFalse, the SIF Server executes the operation |
|
187 even if there is a concurrent operation in progress. The default value |
|
188 is ETrue. |
|
189 */ |
|
190 IMPORT_C void Install(RFile& aFileHandle, const COpaqueNamedParams& aArguments, |
|
191 COpaqueNamedParams& aResults, TRequestStatus& aStatus, |
|
192 TBool aExclusiveOperation = ETrue); |
|
193 |
|
194 /** |
|
195 Uninstalls a component |
|
196 |
|
197 @param aComponentId The id of a component to be uninstalled |
|
198 @param aStatus The request status. KErrNone, if successful, otherwise |
|
199 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
200 @param aExclusiveOperation If this flag is set to ETrue, the Uninstall |
|
201 operation is executed in the Exclusive mode. In this mode the SIF |
|
202 Server executes only one operation at a time. If there is another |
|
203 operation in progress the SIF Server returns KErrServerBusy. |
|
204 If this flag is set to EFalse, the SIF Server executes the operation |
|
205 even if there is a concurrent operation in progress. The default value |
|
206 is ETrue. |
|
207 */ |
|
208 IMPORT_C void Uninstall(TComponentId aComponentId, TRequestStatus& aStatus, |
|
209 TBool aExclusiveOperation = ETrue); |
|
210 |
|
211 /** |
|
212 Uninstalls a component |
|
213 |
|
214 @param aComponentId The id of a component to be uninstalled |
|
215 @param aArguments The array of opaque params for a SIF plug-in. An empty |
|
216 array may be passed. |
|
217 @param aResults The array of opaque results returned from a SIF plug-in. |
|
218 @param aStatus The request status. KErrNone, if successful, otherwise |
|
219 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
220 @param aExclusiveOperation If this flag is set to ETrue, the Uninstall |
|
221 operation is executed in the Exclusive mode. In this mode the SIF |
|
222 Server executes only one operation at a time. If there is another |
|
223 operation in progress the SIF Server returns KErrServerBusy. |
|
224 If this flag is set to EFalse, the SIF Server executes the operation |
|
225 even if there is a concurrent operation in progress. The default value |
|
226 is ETrue. |
|
227 */ |
|
228 IMPORT_C void Uninstall(TComponentId aComponentId, const COpaqueNamedParams& aArguments, |
|
229 COpaqueNamedParams& aResults, TRequestStatus& aStatus, |
|
230 TBool aExclusiveOperation = ETrue); |
|
231 |
|
232 /** |
|
233 Activates a component. |
|
234 |
|
235 The SCOMO state of a component can be changed at any time through the SIF API. However, capability |
|
236 checking may apply depending on the particular installer. For example, a Python installer may require the |
|
237 ECapabilityWriteUserData capability to activate or deactivate a Python component. |
|
238 |
|
239 @param aComponentId The id of a component to be activated |
|
240 @param aStatus The request status. KErrNone, if successful, otherwise |
|
241 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
242 */ |
|
243 IMPORT_C void Activate(TComponentId aComponentId, TRequestStatus& aStatus); |
|
244 |
|
245 /** |
|
246 Deactivates a component. |
|
247 |
|
248 The SCOMO state of a component can be changed at any time through the SIF API. However, capability |
|
249 checking may apply depending on the particular installer. For example, a Python installer may require the |
|
250 ECapabilityWriteUserData capability to activate or deactivate a Python component. |
|
251 |
|
252 @param aComponentId The id of a component to be deactivated |
|
253 @param aStatus The request status. KErrNone, if successful, otherwise |
|
254 one of the other system-wide or SIF error codes defined in usiferror.h. |
|
255 */ |
|
256 IMPORT_C void Deactivate(TComponentId aComponentId, TRequestStatus& aStatus); |
|
257 |
|
258 /** |
|
259 Cancels an ongoing asynchronous request |
|
260 |
|
261 This is a synchronous call. When it returns the original asynchronous call is completed. |
|
262 */ |
|
263 IMPORT_C void CancelOperation(); |
|
264 |
|
265 #ifdef _DEBUG |
|
266 friend class CSifOperationStep; |
|
267 #endif //_DEBUG |
|
268 |
|
269 private: |
|
270 RSifTransportClient iTransport; |
|
271 }; |
|
272 |
|
273 } // namespace Usif |
|
274 |
|
275 #endif // SIF_H |