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 __DMTTREE_H__ 18 #define __DMTTREE_H__ 19 20 #ifndef __cplusplus 21 #error "This is a C++ header file; it requires C++ to compile." 22 #endif 23 24 /** 25 \file dmtTree.hpp 26 \brief The dmtTree.hpp header file contains DmtTree class definition. <br> 27 DmtTree is the object carrying atomicity (when supported) and<br> 28 authentication functionality associated with DMT access, as well<br> 29 as basic node access. 30 */ 31 32 #include "jem_defs.hpp" 33 34 #include "dmt.hpp" 35 36 37 /** 38 DmtTree is the object carrying atomicity (when supported) and 39 authentication functionality associated with DMT access, as well 40 as basic node access. The object is obtained from the static create() 41 method of the DmtTree's implementation class. 42 Almost all methods return a smart pointer to the 43 error description object if failed, NULL if succeeded 44 45 \par Category: General 46 47 \par Persistence: Transient 48 49 \par Security: Non-Secure 50 51 \par Migration State: FINAL 52 53 54 \par Creating DmtTree object 55 56 The factory class DmtTreeFactory is used to create a tree object. \n 57 Alternatively, a sub-tree can be created using the GetSubTree method 58 to minimize blocking. 59 60 \par Release DmtTree object 61 62 DmtTree is a smart-pointer. Smart-pointers are used in the DMT API to 63 return references to DmtTree, DmtNode and DmtErrorDescription. Usually you 64 can treat it as a normal pointer to a class, but in fact, its a small class 65 which takes care of the objects life time. Here are some simple rules for 66 working with smart pointers:\n\n 67 68 - warning never call delete on a smart pointer\n 69 - warning assign NULL to a smart pointer as soon as you dont need the object anymore \n\n 70 71 After you have got a hold of a DmtTree object, you can access its child nodes and 72 read and modify them as desired. However it is important to release the object by 73 assigning NULL to it after you have finished get operations, i.e. read only type of 74 operations. In case you have done set operations, i.e. write type of operations, a 75 call to Flush() will commit the change and release the lock on the tree. \n 76 Remember to:\n 77 - release (assign NULL) after read\n 78 - call Flush() after write\n 79 80 \par Example using DMT functions 81 82 \code 83 DmtPrincipal principal("localhost"); 84 PDmtTree ptrTree; 85 SYNCML_DM_RET_STATUS_T ret_status; 86 87 if ( (ret_status = DmtFactory::GetTree(principal, ptrTree ) ) != SYNCML_DM_SUCCESS ) 88 { 89 ... error handling 90 return; 91 } 92 93 PDmtNode ptrNode; 94 95 if ( (ret_status = ptrTree->GetNode( "./SyncML/DMAcc/GUID/AddrType", ptrNode ) ) != SYNCML_DM_SUCCESS ) 96 { 97 ... error handling 98 return; 99 } 100 101 std::string str; 102 if ( (ret_status = ptrNode->GetStringValue( str )) != SYNCML_DM_SUCCESS ) 103 { 104 ... error handling 105 return; 106 } 107 108 printf( "String value is %`s\n", str.c_str() ); 109 \endcode 110 111 */ 112 113 114 class DmtTree : public JemBaseObject 115 { 116 protected: 117 /** Destructor - freeing all dynamic resources */ 118 virtual ~DmtTree(){} 119 120 public: 121 /** 122 * Locates and return node by specified path. 123 * \par Sync (or) Async: 124 * This is a Synchronous function. 125 * \par Secure (or) Non-Secure (or) N/A: 126 * This is a Non-Secure function. 127 * \param path [in] - full path to the node 128 * \param ptrNode [out] - result node 129 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 130 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 131 * - All other codes indicates failure. The description can be found in dmtError.h \n 132 * \par Prospective Clients: 133 * All potential applications that require configuration settings and Internal Classes. 134 */ 135 virtual SYNCML_DM_RET_STATUS_T GetNode(CPCHAR path, PDmtNode& ptrNode )=0; 136 137 /** 138 * Deletes a node according to the specified path 139 * \par Sync (or) Async: 140 * This is a Synchronous function. 141 * \par Secure (or) Non-Secure (or) N/A: 142 * This is a Non-Secure function. 143 * \param path [in] - full path to the node 144 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 145 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 146 * - All other codes indicates failure. The description can be found in dmtError.h 147 * \par Prospective Clients: 148 * All potential applications that require configuration settings and Internal Classes. 149 * \par Example of how DeleteNode() function would be called 150 * 151 * \code 152 * PDmtTree ptrTree; 153 * SYNCML_DM_RET_STATUS_T ret_status; 154 * if ( (ret_status=DmtTreeFactory::GetSubtree(principal, "./SyncML/DMAcc, ptrTree))!=SYNCML_DM_SUCCESS ){ 155 * ... error processing here 156 * return; 157 * } 158 * if ( (ret_status=ptrTree->DeleteNode( "TEST" ) ) != SYNCML_DM_SUCCESS) { 159 * ... error 160 * return; 161 * } 162 * \endcode 163 */ 164 virtual SYNCML_DM_RET_STATUS_T DeleteNode(CPCHAR path )=0; 165 166 167 /** 168 * Creates a sibling of the node specified by its URI "path". 169 * This new node's name is user-specified as "szNewNodename". 170 * \par Sync (or) Async: 171 * This is a Synchronous function. 172 * \par Secure (or) Non-Secure (or) N/A: 173 * This is a Non-Secure function. 174 * \param path [in] - URI of node to be cloned. 175 * \param szNewNodename [in] - new node name as specified by user. 176 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 177 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 178 * - All other codes indicates failure. The description can be found in dmtError.h 179 * \par Prospective Clients: 180 * All potential applications that require configuration settings and Internal Classes. 181 */ 182 virtual SYNCML_DM_RET_STATUS_T Clone(CPCHAR path, CPCHAR szNewNodename) = 0; 183 184 185 /** 186 * Changes node's name. For example: RenameNode( "./SyncML/DMAcc/Test", "NewTest" ); 187 * \par Sync (or) Async: 188 * This is a Synchronous function. 189 * \par Secure (or) Non-Secure (or) N/A: 190 * This is a Non-Secure function. 191 * \param path [in] - path to the node 192 * \param szNewNodeName [in] - new node name 193 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 194 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 195 * - All other codes indicates failure. The description can be found in dmtError.h 196 * \par Prospective Clients: 197 * All potential applications that require configuration settings and Internal Classes. 198 */ 199 virtual SYNCML_DM_RET_STATUS_T RenameNode(CPCHAR path, CPCHAR szNewNodeName ) = 0; 200 201 /** 202 * Creates a leaf node in the tree. 203 * \par Sync (or) Async: 204 * This is a Synchronous function. 205 * \par Secure (or) Non-Secure (or) N/A: 206 * This is a Non-Secure function. 207 * \param path [in] - path to the node 208 * \param ptrCreatedNode [out] - new created node 209 * \param value [in] - data value DmtData type 210 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 211 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 212 * - All other codes indicates failure. The description can be found in dmtError.h \n 213 * \par Prospective Clients: 214 * All potential applications that require configuration settings and Internal Classes. 215 * \par Example of how this function would be called 216 * 217 * \code 218 * DmtPrincipal principal("localhost"); 219 * PDmtTree ptrTree; 220 * SYNCML_DM_RET_STATUS_T ret_status; 221 * 222 * if ( (ret_status = DmtFactory::GetTree(principal, ptrTree ) ) != SYNCML_DM_SUCCESS ) 223 * { 224 * ... error handling 225 * return; 226 * } 227 * PDmtNode ptrNode; 228 * if ( (ret_status =ptrTree->CreateLeafNode( "./SyncML/DMAcc/TESTLeaf", ptrNode, DmtData(123) ) ) != SYNCML_DM_SUCCESS) ){ 229 * error handling 230 * return; 231 * } 232 * if ( (ret_statu= ptrTree->Flush() SYNCML_DM_SUCCESS) ){ 233 * .... error processing here 234 * } 235 * \endcode 236 * 237 */ 238 virtual SYNCML_DM_RET_STATUS_T CreateLeafNode(CPCHAR path, PDmtNode& ptrCreatedNode, const DmtData& value )=0; 239 240 /** 241 * Creates a External Storage leaf node in the tree. 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 path [in] - path to the node 247 * \param ptrCreatedNode [out] - new created node 248 * \param value [in] - data value DmtData type 249 * \param isESN [in] - flag to indicate that it is External Storage Node 250 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 251 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 252 * - All other codes indicates failure. The description can be found in dmtError.h \n 253 * \par Prospective Clients: 254 * All potential applications that require configuration settings and Internal Classes. 255 * 256 * \code 257 * DmtPrincipal principal("localhost"); 258 * PDmtTree ptrTree; 259 * SYNCML_DM_RET_STATUS_T ret_status; 260 * 261 * if ( (ret_status = DmtFactory::GetTree(principal, ptrTree ) ) != SYNCML_DM_SUCCESS ) 262 * { 263 * ... error handling 264 * return; 265 * } 266 * PDmtNode ptrNode; 267 * if ( (ret_status =ptrTree->CreateLeafNode( "./SyncML/DMAcc/TESTLeaf", ptrNode, DmtData(123), TRUE ) ) != SYNCML_DM_SUCCESS) ){ 268 * error handling 269 * return; 270 * } 271 * if ( (ret_statu= ptrTree->Flush() SYNCML_DM_SUCCESS) ){ 272 * .... error processing here 273 * } 274 * \endcode 275 */ 276 virtual SYNCML_DM_RET_STATUS_T CreateLeafNode(CPCHAR path, PDmtNode& ptrCreatedNode, const DmtData& value , BOOLEAN isESN)=0; 277 278 /** 279 * Creates an interior node in the tree. 280 * \par Sync (or) Async: 281 * This is a Synchronous function. 282 * \par Secure (or) Non-Secure (or) N/A: 283 * This is a Non-Secure function. 284 * \param path [in] - path to the node 285 * \param ptrCreatedNode [out] - new created node 286 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 287 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 288 * - All other codes indicates failure. The description can be found in dmtError.h 289 * \par Prospective Clients: 290 * All potential applications that require configuration settings and Internal Classes. 291 * 292 * \par Example of how this function would be called 293 * 294 * \code 295 * DmtPrincipal principal("localhost"); 296 * PDmtTree ptrTree; 297 * SYNCML_DM_RET_STATUS_T ret_status; 298 * 299 * if ( (ret_status = DmtFactory::GetTree(principal, ptrTree ) ) != SYNCML_DM_SUCCESS ) 300 * { 301 * ... error handling 302 * return; 303 * } 304 * PDmtNode ptrNode; 305 * if ( ((ret_status =ptrTree->CreateInteriorNode( "./SyncML/DMAcc/TEST", ptrNode ) ) != SYNCML_DM_SUCCESS) { 306 * ... error handling 307 * return; 308 * } 309 * if ( (ret_statu= ptrTree->Flush() SYNCML_DM_SUCCESS) ){ 310 * .... error processing here 311 * } 312 * \endcode 313 * 314 */ 315 virtual SYNCML_DM_RET_STATUS_T CreateInteriorNode(CPCHAR path, PDmtNode& ptrCreatedNode )=0; 316 317 /** 318 * This is a helper method. It returns a table of all leaf nodes for the current node. 319 * The table key is the child node name, and value is the string node value. It sets leaf nodes only 320 * \par Sync (or) Async: 321 * This is a Synchronous function. 322 * \par Secure (or) Non-Secure (or) N/A: 323 * This is a Non-Secure function. 324 * \param path [in] - path to the node 325 * \param mapNodes [out] - map with leaf nodes only 326 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 327 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 328 * - All other codes indicates failure. The description can be found in dmtError.h 329 * \par Prospective Clients: 330 * All potential applications that require configuration settings and Internal Classes. 331 * 332 * \par Example of how GetChildValuesMap() function would be called 333 * 334 * \code 335 * PDmtTree ptrTree; 336 * PDmtNode ptrNode; 337 * DMString strDefaultProfile; 338 * SYNCML_DM_RET_STATUS_T ret_status; 339 * .... initialisation ptrTree and ptrNode... 340 * 341 * if ( (ret_status=ptrNode->GetStringValue(strDefaultProfile) ) != SYNCML_DM_SUCCESS) { 342 * ... error 343 * return; 344 *} 345 * DMString strProfileURI = Profiles/; 346 * strProfileURI += strDefaultProfile; 347 * DMMap<DMString, DmtData> map; 348 * if ( (ret_status=ptrTree-> GetChildValuesMap (strProfileURI, map ))!=SYNCML_DM_SUCCESS ){ 349 * ...error 350 * return; 351 * } 352 * \endcode 353 */ 354 virtual SYNCML_DM_RET_STATUS_T GetChildValuesMap(CPCHAR path, DMMap<DMString, DmtData>& mapNodes ) = 0; 355 356 357 /** 358 * This is a helper method. It deletes all leaf nodes and creates new ones, provided in the map. The table key is the child node name, and value is the node value. 359 * It changes leaf nodes only 360 * \par Sync (or) Async: 361 * This is a Synchronous function. 362 * \par Secure (or) Non-Secure (or) N/A: 363 * This is a Non-Secure function. 364 * \param path [in] - path to the node 365 * \param mapNodes [in] - map with leaf nodes only 366 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 367 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 368 * - All other codes indicates failure. The description can be found in dmtError.h 369 * \par Prospective Clients: 370 * All potential applications that require configuration settings and Internal Classes. 371 * 372 * \par Example of how GetChildValuesMap() function would be called 373 * 374 * \code 375 * ... all init the same as with GetChildValuesMap() function... 376 * if ( (ret_status=ptrTree-> SetChildValuesMap (strProfileURI, map ))!=SYNCML_DM_SUCCESS ){ 377 * ...error 378 * return; 379 * } 380 * \endcode 381 */ 382 virtual SYNCML_DM_RET_STATUS_T SetChildValuesMap(CPCHAR path, const DMMap<DMString, DmtData>& mapNodes ) = 0; 383 384 /** 385 * This is a helper method. It sets an array of all child node names for the current node. 386 * \par Sync (or) Async: 387 * This is a Synchronous function. 388 * \par Secure (or) Non-Secure (or) N/A: 389 * This is a Non-Secure function. 390 * \param path [in] - path to the node 391 * \param mapNodes [out] - map with leaf nodes only 392 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 393 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 394 * - All other codes indicates failure. The description can be found in dmtError.h 395 * \par Prospective Clients: 396 * All potential applications that require configuration settings and Internal Classes. 397 */ 398 virtual SYNCML_DM_RET_STATUS_T GetChildNodeNames(CPCHAR path, DMStringVector& mapNodes ) = 0; 399 400 /** 401 * Flush all changes to the persistent layer and check the constrains. 402 * \par Sync (or) Async: 403 * This is a Synchronous function. 404 * \par Secure (or) Non-Secure (or) N/A: 405 * This is a Non-Secure function. 406 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 407 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 408 * - All other codes indicates failure. The description can be found in dmtError.h 409 * \par Prospective Clients: 410 * All potential applications that require configuration settings and Internal Classes. 411 */ 412 virtual SYNCML_DM_RET_STATUS_T Flush()=0; 413 414 /** 415 * Commits a series of atomic operations. 416 * \par Sync (or) Async: 417 * This is a Synchronous function. 418 * \par Secure (or) Non-Secure (or) N/A: 419 * This is a Non-Secure function. 420 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 421 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 422 * - All other codes indicates failure. The description can be found in dmtError.h 423 * \par Prospective Clients: 424 * All potential applications that require configuration settings and Internal Classes. 425 */ 426 virtual SYNCML_DM_RET_STATUS_T Commit()=0; 427 428 /** 429 * Rollbacks a series of atomic operations 430 * \par Sync (or) Async: 431 * This is a Synchronous function. 432 * \par Secure (or) Non-Secure (or) N/A: 433 * This is a Non-Secure function. 434 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 435 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 436 * - All other codes indicates failure. The description can be found in dmtError.h 437 * \par Prospective Clients: 438 * All potential applications that require configuration settings and Internal Classes. 439 */ 440 virtual SYNCML_DM_RET_STATUS_T Rollback()=0; 441 442 /** 443 * Begins an atomic operation that will end with commit() or rollback(); 444 * \warning An error code will be returned if a transaction is running already. 445 * \par Sync (or) Async: 446 * This is a Synchronous function. 447 * \par Secure (or) Non-Secure (or) N/A: 448 * This is a Non-Secure function. 449 * \return Return Type (SYNCML_DM_RET_STATUS_T) \n 450 * - SYNCML_DM_SUCCESS - indicates that the operation is completed successfully. \n 451 * - All other codes indicates failure. The description can be found in dmtError.h 452 * \par Prospective Clients: 453 * All potential applications that require configuration settings and Internal Classes. 454 */ 455 virtual SYNCML_DM_RET_STATUS_T Begin()=0; 456 457 /** 458 * Checks for atomicity. 459 * \par Sync (or) Async: 460 * This is a Synchronous function. 461 * \par Secure (or) Non-Secure (or) N/A: 462 * This is a Non-Secure function. 463 * \return 'true' if the begin() was invoked, but no commit() or rollback(). 464 * \par Prospective Clients: 465 * All potential applications that require configuration settings and Internal Classes. 466 */ 467 virtual BOOLEAN IsAtomic() const =0; 468 469 /** 470 * Retrieves a principal 471 * \par Sync (or) Async: 472 * This is a Synchronous function. 473 * \par Secure (or) Non-Secure (or) N/A: 474 * This is a Non-Secure function. 475 * \return the DmtPrincipal object that the session was created with. 476 * \par Prospective Clients: 477 * All potential applications that require configuration settings and Internal Classes. 478 */ 479 virtual DmtPrincipal GetPrincipal() const =0; 480 481 /** 482 * Function checks if specified path is "gettable" in the context of current tree 483 * \par Sync (or) Async: 484 * This is a Synchronous function. 485 * \par Secure (or) Non-Secure (or) N/A: 486 * This is a Non-Secure function. 487 * \param path [in] - path to a node 488 * \return "true" if corresponding call GetNode is successful, otherwise "false" 489 * \par Prospective Clients: 490 * All potential applications that require configuration settings and Internal Classes. 491 */ 492 inline BOOLEAN IsValidNode ( const char* path ) { 493 PDmtNode ptrNode; 494 return (GetNode( path, ptrNode ) == SYNCML_DM_SUCCESS ? TRUE : FALSE) ; 495 } 496 }; 497 498 #endif 499
