1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef __DMTTREEFACTORY_H__ 18 #define __DMTTREEFACTORY_H__ 19 20 #ifndef __cplusplus 21 #error "This is a C++ header file; it requires C++ to compile." 22 #endif 23 24 /** 25 \file dmtTreeFactory.hpp 26 \brief The dmtTreeFactory.hpp header file contains DmtTreeFactory class definition. \n 27 This class represents a tree factory. It is used to create a DmtTree from a given Principal. 28 */ 29 30 #include "jem_defs.hpp" 31 #include "dmtPrincipal.hpp" 32 #include "dmtNotification.hpp" 33 #include "dmtSessionProp.hpp" 34 #include "dmtEvent.hpp" 35 #include "dmtEventData.hpp" 36 37 /** 38 * DmtTreeFactory represents a tree factory. 39 * It is used to create a DmtTree from a given Principal. 40 * \par Category: General 41 * \par Persistence: Transient 42 * \par Security: Non-Secure 43 * \par Migration State: FINAL 44 */ 45 class DmtTreeFactory 46 { 47 public: 48 /** 49 * Enumaration that presents Device management tree lock types. 50 */ 51 enum 52 { 53 /** Lock type "Shared"*/ 54 LOCK_TYPE_SHARED = SYNCML_DM_LOCK_TYPE_SHARED, 55 /** Lock type "Exclusive"*/ 56 LOCK_TYPE_EXCLUSIVE = SYNCML_DM_LOCK_TYPE_EXCLUSIVE, 57 /** Lock type "Automatic"*/ 58 LOCK_TYPE_AUTOMATIC = SYNCML_DM_LOCK_TYPE_AUTOMATIC 59 }; 60 61 62 /** 63 * Initialization - calls this function prior any other function. 64 * \par Sync (or) Async: 65 * This is a Synchronous function. 66 * \par Secure (or) Non-Secure (or) N/A: 67 * This is a Non-Secure function. 68 * \return result as BOOLTYPE 69 * - true - indicates success and Dmt functions are ready to be called. \n 70 * - false - indicates failure and no more Dmt functions can be called. \n 71 * typical cause of failure is due to invalid Dmt root file path from "dm_setting_root" environment variable. 72 * \par Prospective Clients: 73 * All potential applications that require configuration settings. 74 */ 75 static BOOLTYPE Initialize(); 76 77 78 /** 79 * Clean up resources. 80 * \par Important Notes: 81 * - Note: no one Dmt function can be called after clean up. 82 * - Note: all tree and node handles should be released prior Uninitialized call 83 * \par Sync (or) Async: 84 * This is a Synchronous function. 85 * \par Secure (or) Non-Secure (or) N/A: 86 * This is a Non-Secure function. 87 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 88 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 89 * - All other codes indicates failure. The description can be found in dmtError.h 90 * \par Prospective Clients: 91 * All potential applications that require configuration settings and Internal Classes. 92 */ 93 static SYNCML_DM_RET_STATUS_T Uninitialize(); 94 95 /** 96 * Gets a logic DmtTree for a given principal. 97 * \par Sync (or) Async: 98 * This is a Synchronous function. 99 * \par Secure (or) Non-Secure (or) N/A: 100 * This is a Non-Secure function. 101 * \param principal [in] - DMT principal 102 * \param ptrTree [out] - pointer to DMT 103 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 104 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 105 * - All other codes indicates failure. The description can be found in dmtError.h \n 106 * Make sure Initialize() function is called successfully prior to calling this function. 107 * \par Example of how this function would be called 108 * 109 * \code 110 * DmtPrincipal principal("localhost"); 111 * PDmtTree ptrTree; 112 * SYNCML_DM_RET_STATUS_T ret_status; 113 * 114 * if ( (ret_status = DmtFactory::GetTree(principal, ptrTree ) ) != SYNCML_DM_SUCCESS ) 115 * { 116 * ... error handling 117 * return; 118 * } 119 * 120 * \endcode 121 * \par Prospective Clients: 122 * All potential applications that require configuration settings and Internal Classes. 123 */ 124 static SYNCML_DM_RET_STATUS_T GetTree(const DmtPrincipal& principal, 125 PDmtTree& ptrTree); 126 127 /** 128 * Gets a logic part of DmtTree for a given principal; This tree 129 * object gives access only to subtree located by path. 130 * \par Sync (or) Async: 131 * This is a Synchronous function. 132 * \par Secure (or) Non-Secure (or) N/A: 133 * This is a Non-Secure function. 134 * \param principal [in] - DMT principal 135 * \param szSubtreeRoot [in] - sub tree root name 136 * \param ptrTree [out] - pointer to sub tree 137 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 138 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 139 * - All other codes indicates failure. The description can be found in dmtError.h \n 140 * Make sure Initialize() function is called successfully prior to calling this function. \n 141 * This function will return error for invalid subtree path. 142 * 143 * \par Example of how GetSubtree() function would be called 144 * 145 * \code 146 * DmtPrincipal principal("localhost"); 147 * PDmtTree ptrTree; 148 * SYNCML_DM_RET_STATUS_T ret_status; 149 * if ( (ret_status =DmtTreeFactory::GetSubtree(principal, "./SyncML/DMAcc, ptrTree))!=SYNCML_DM_SUCCESS ){ 150 * ... error processing here 151 * return; 152 * } 153 * \endcode 154 * 155 * \par Prospective Clients: 156 * All potential applications that require configuration settings and Internal Classes. 157 */ 158 static SYNCML_DM_RET_STATUS_T GetSubtree(const DmtPrincipal& principal, 159 CPCHAR szSubtreeRoot, 160 PDmtTree& ptrTree); 161 162 /** 163 * Gets a logic part of DmtTree for a given principal 164 * This tree object gives access only to subtree located by path. 165 * All path access to subtree should be NOT have "./" or "/" before the path ! 166 * Additional parameter lockType allows to specify desired access to the tree. 167 * If lockType is "shared" tree is read-only and any "Set" function will throw an exception. 168 * \par Sync (or) Async: 169 * This is a Synchronous function. 170 * \par Secure (or) Non-Secure (or) N/A: 171 * This is a Non-Secure function. 172 * \param principal [in] - DMT principal 173 * \param szSubtreeRoot [in] - sub tree root name 174 * \param nLockType [in] - tree lock type 175 * \param ptrTree [out] - pointer to sub tree 176 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 177 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 178 * - All other codes indicates failure. The description can be found in dmtError.h 179 * Make sure Initialize() function is called successfully prior to calling this function. \n 180 * This function will return error for invalid subtree path. 181 * 182 * \par Example of how GetSubtreeEx() function would be called 183 * 184 * \code 185 * DmtPrincipal principal("localhost"); 186 * PDmtTree ptrTree; 187 * SYNCML_DM_RET_STATUS_T ret_status; 188 * if ( (ret_status =DmtTreeFactory::GetSubtree(principal, "./SyncML/DMAcc, DmtTreeFactory::LOCK_TYPE_EXCLUSIVE, ptrTree))!=SYNCML_DM_SUCCESS ){ 189 * ... error processing here 190 * return; 191 * } 192 * \endcode 193 * 194 * \par Prospective Clients: 195 * All potential applications that require configuration settings and Internal Classes. 196 */ 197 static SYNCML_DM_RET_STATUS_T GetSubtreeEx(const DmtPrincipal& principal, 198 CPCHAR szSubtreeRoot, 199 SYNCML_DM_TREE_LOCK_TYPE_T nLockType, 200 PDmtTree& ptrTree); 201 202 /** 203 * Reads SyncML scripts from the InputStream then process to the tree 204 * \warning This functions is for internal usage only!!! 205 * \par Sync (or) Async: 206 * This is a Synchronous function. 207 * \par Secure (or) Non-Secure (or) N/A: 208 * This is a Non-Secure function. 209 * \param principal [in] - DMT principal 210 * \param buf [in] - input stream 211 * \param len [in] - length of the input stream 212 * \param isWBXML [in] - flag to use binary xml 213 * \param oResult [out] - string with error description 214 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 215 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 216 * - All other codes indicates failure. The description can be found in dmtError.h \n 217 * 218 * \par Example of how ProcessScript() function would be called 219 * 220 * \code 221 * const char* szFile = <path to file>; 222 * DmtPrincipal principal ("localhost"); 223 * DMString oResult; 224 * char* szBuf = <script> 225 * int n = <size of 'script'> 226 * SYNCML_DM_RET_STATUS_T res = DmtTreeFactory::ProcessScript( principal , (const byte*)szBuf, n, false, oResult); 227 * \endcode 228 * \par Prospective Clients: 229 * All potential applications that require configuration settings and Internal Classes. 230 */ 231 232 static SYNCML_DM_RET_STATUS_T ProcessScript(const DmtPrincipal& principal, 233 const UINT8 * buf, 234 INT32 len, 235 BOOLEAN isWBXML, 236 DMString& oResult); 237 238 /** 239 * Reads SyncML scripts from the InputStream then process to the tree and set the result 240 * in binary format. 241 * \warning This functions is for internal usage only!!! 242 * \par Sync (or) Async: 243 * This is a Synchronous function. 244 * \par Secure (or) Non-Secure (or) N/A: 245 * This is a Non-Secure function. 246 * \param principal [in] - DMT principal 247 * \param buf [in] - input stream 248 * \param len [in] - length of the input stream 249 * \param isWBXML [in] - to use binary xml 250 * \param oResult [out] - DMVector<UINT8> with error code 251 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 252 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 253 * - All other codes indicates failure. The description can be found in the dmtError.h 254 * \par Prospective Clients: 255 * All potential applications that require configuration settings and Internal Classes. 256 */ 257 258 static SYNCML_DM_RET_STATUS_T ProcessScript(const DmtPrincipal& principal, 259 const UINT8 * buf, 260 INT32 len, 261 BOOLEAN isWBXML, 262 DMVector<UINT8> & oResult); 263 264 265 /** 266 * Starts communication with Syncml DM server 267 * \warning This functions is for internal usage only!!! 268 * \par Sync (or) Async: 269 * This is a Synchronous function. 270 * \par Secure (or) Non-Secure (or) N/A: 271 * This is a Non-Secure function. 272 * \param principal [in] - Syncml DM server ID 273 * \param sessionProp [in] - additional session parameters 274 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 275 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 276 * - All other codes indicates failure. The description can be found in dmtError.h 277 * 278 * \par Example of how StartServerSession() function would be called 279 * 280 * \code 281 * DmtSessionProp oClInitiated( true ); 282 * DmtPrincipal principal(ServerID); 283 * SYNCML_DM_RET_STATUS_T ret_status; 284 * 285 * if ( (ret_status=DmtTreeFactory::StartServerSession(principal, oClInitiated )) == SYNCML_DM_SUCCESS ) 286 * .....OK 287 * else 288 * .....Error 289 * ); 290 * \endcode 291 * 292 * \par Prospective Clients: 293 * All potential applications that require configuration settings and Internal Classes. 294 */ 295 static SYNCML_DM_RET_STATUS_T StartServerSession(const DmtPrincipal& principal, 296 const DmtSessionProp& sessionProp); 297 298 /** 299 * Notification for the DMT 300 * \warning This functions is for internal usage only!!! 301 * \par Sync (or) Async: 302 * This is a Synchronous function. 303 * \par Secure (or) Non-Secure (or) N/A: 304 * This is a Non-Secure function. 305 * \param principal [in] - Syncml DM server ID 306 * \param buf [in] - input stream 307 * \param len [in] - length of the input stream 308 * \param notification [out] - string with a notification 309 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 310 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 311 * - All other codes indicates failure. The description can be found in dmtError.h 312 * \par Prospective Clients: 313 * All potential applications that require configuration settings and Internal Classes. 314 */ 315 static SYNCML_DM_RET_STATUS_T ProcessNotification(const DmtPrincipal& principal, 316 const UINT8 *buf, 317 INT32 len, 318 DmtNotification & notification); 319 320 321 /** 322 * Notification for the process 323 * \warning This functions is for internal usage only!!! 324 * \par Sync (or) Async: 325 * This is a Synchronous function. 326 * \par Secure (or) Non-Secure (or) N/A: 327 * This is a Non-Secure function. 328 * \param principal [in] - Syncml DM server ID 329 * \param buf [in] - input stream 330 * \param len [in] - length of the input stream 331 * \param isWBXML [in] - to use binary xml 332 * \param isProcess [in] - flag to process script 333 * \param serverID [out] - reference to string with server ID 334 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 335 * - SYNCML_DM_SUCCESS - indicate that operation has completed successfully. \n 336 * - All other codes indicates failure. The description can be found in dmtError.h 337 * \par Prospective Clients: 338 * All potential applications that require configuration settings and Internal Classes. 339 */ 340 static SYNCML_DM_RET_STATUS_T Bootstrap(const DmtPrincipal& principal, 341 const UINT8 * buf, 342 INT32 len, 343 BOOLEAN isWBXML, 344 BOOLEAN isProcess, 345 DMString & serverID); 346 347 348 /** 349 * Checks if DMT is locked 350 * \par Sync (or) Async: 351 * This is a Synchronous function. 352 * \par Secure (or) Non-Secure (or) N/A: 353 * This is a Non-Secure function. 354 * \return "true" if locked 355 * \par Prospective Clients: 356 * All potential applications that require configuration settings and Internal Classes. 357 */ 358 359 static BOOLEAN IsLocked(); 360 361 362 /** 363 * Check if OTA DM session is in progress 364 * \par Sync (or) Async: 365 * This is a Synchronous function. 366 * \par Secure (or) Non-Secure (or) N/A: 367 * This is a Non-Secure function. 368 * \return "true" if session is started 369 * \par Prospective Clients: 370 * All potential applications that require configuration settings and Internal Classes. 371 */ 372 373 static BOOLEAN IsSessionInProgress(); 374 375 376 /** 377 * Subscribes on DMT update event (tells DM engine to track updates on specific node or sub tree 378 * \par Sync (or) Async: 379 * This is a Synchronous function. 380 * \par Secure (or) Non-Secure (or) N/A: 381 * This is a Non-Secure function. 382 * \param szPath [in] - node path 383 * \param oEvent [in] - event subscription 384 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 385 * - SYNCML_DM_SUCCESS - indicate that operation is completed successfully. \n 386 * - All other codes indicate failure. The description can be found in dmtError.h 387 * \par Prospective Clients: 388 * All potential applications that require configuration settings and Internal Classes. 389 */ 390 static SYNCML_DM_RET_STATUS_T SubscribeEvent(CPCHAR szPath, 391 const DmtEventSubscription & oEvent); 392 393 /** 394 * Unsubscribes from DMT update event (tells DM engine to stop tracking updates on specific node or sub tree 395 * \par Sync (or) Async: 396 * This is a Synchronous function. 397 * \par Secure (or) Non-Secure (or) N/A: 398 * This is a Non-Secure function. 399 * \param szPath [in] - node path 400 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 401 * - SYNCML_DM_SUCCESS - indicate that operation is completed successfully. \n 402 * - All other codes indicate failure. The description can be found in dmtError.h 403 * \par Prospective Clients: 404 * All potential applications that require configuration settings and Internal Classes. 405 */ 406 static SYNCML_DM_RET_STATUS_T UnSubscribeEvent(CPCHAR szPath); 407 408 /** 409 * Retrieves event subscription for specific path 410 * \par Sync (or) Async: 411 * This is a Synchronous function. 412 * \par Secure (or) Non-Secure (or) N/A: 413 * This is a Non-Secure function. 414 * \param szPath [in] - node path 415 * \param oEvent [out] - event subscription 416 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 417 * - SYNCML_DM_SUCCESS - indicate that operation is completed successfully. \n 418 * - All other codes indicate failure. The description can be found in dmtError.h 419 * \par Prospective Clients: 420 * All potential applications that require configuration settings and Internal Classes. 421 */ 422 static SYNCML_DM_RET_STATUS_T GetEventSubscription(CPCHAR szPath, 423 DmtEventSubscription & oEvent); 424 425 426 /** 427 * Parses data received by application about DMT update on sub tree 428 * \par Sync (or) Async: 429 * This is a Synchronous function. 430 * \par Secure (or) Non-Secure (or) N/A: 431 * This is a Non-Secure function. 432 * \param pBuffer [in] - pointer on a data buffer 433 * \param size [in] - size of a buffer 434 * \param aEventMap [out] - map of events for sub tree 435 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 436 * - SYNCML_DM_SUCCESS - indicate that operation is completed successfully. \n 437 * - All other codes indicate failure. The description can be found in dmtError.h 438 * \par Prospective Clients: 439 * All potential applications that require configuration settings and Internal Classes. 440 */ 441 442 static SYNCML_DM_RET_STATUS_T ParseUpdateEvent(UINT8 * pBuffer, 443 UINT32 size, 444 DmtEventMap & aEventMap); 445 446 447 448 449 }; 450 451 #endif 452
