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 __JEM_DEFS_H__ 18 #define __JEM_DEFS_H__ 19 20 #ifndef __cplusplus 21 #error "This is a C++ header file; it requires C++ to compile." 22 #endif 23 24 /** 25 \file jem_defs.hpp 26 \brief Contains JemBaseObject class and JemSmartPtr template class definition 27 28 The jem_defs.hpp header file contains JemBaseObject class and JemSmartPtr \n 29 template class definition. \n 30 This is the utility definition for the Dmt C++ API. It defineds Basic types as byte and boolean.\n 31 Also some standard collection helper class as Date that are used in the API.\n 32 The <b>JemSmartPtr</b> class is a Smart pointer; works with classes derived from JemBaseObject. \n 33 The Smart pointer class keeps tracking counter references to the object and deletes it (via "DecRef" method) \n 34 if no one longer keeps a pointer to this object.\n 35 The <b>JemBaseObject</b> class is a base object for any ref-counted object. 36 */ 37 38 #include "dmtDefs.h" 39 #include "dmstring.h" 40 #include "dmvector.h" 41 42 /**Definition for the "byte" as unsigned char*/ 43 typedef UINT8 byte; 44 /**Definition for the "boolean" as unsigned char*/ 45 typedef BOOLEAN boolean; 46 /**Definition for the "JemDate" as INT64*/ 47 typedef INT64 JemDate; 48 49 /** 50 * Gets "safe" string. If string is NULL then an empy string will be returned. 51 * \par Sync (or) Async: 52 * This is a Synchronous function. 53 * \par Secure (or) Non-Secure (or) N/A: 54 * This is a Non-Secure function. 55 * \par API Migration State: FINAL 56 * \param str [in] - string to be evaluated 57 * \return original (if not null) or an empty string 58 * \par Prospective Clients: 59 * All potential applications that require configuration settings and Internal Classes. 60 */ 61 inline CPCHAR DmtGetSafeStrPtr( CPCHAR str ) 62 { 63 return (str ? str : "" ); 64 } 65 66 /** 67 * Smart pointer; works with classes derived from JemBaseObject. 68 * Smartpointer class keeps tracking refcounter of the object and deletes it 69 * (via "DecRef" method) if no one longer keeps a pointer to this object. 70 * \par Category: General 71 * \par Persistence: Transient 72 * \par Security: Non-Secure 73 * \par Migration State: FINAL 74 */ 75 template<typename T> class JemSmartPtr 76 { 77 T * m_pData; 78 public: 79 /**Definition for the element_type*/ 80 typedef T element_type; 81 82 /** 83 * Default constructor - no memory allocation performed. 84 */ 85 JemSmartPtr(): m_pData(NULL) {} 86 87 /** 88 * Copy constructor. The memory for the "cp" will be allocated. 89 * \param cp [in] - source object 90 */ 91 92 JemSmartPtr( const JemSmartPtr<element_type> & cp): m_pData(cp.m_pData) { _AddRef();} 93 94 /** 95 * Constructor. The memory will be allocated. 96 * \param p [in] - pointer to an element 97 */ 98 JemSmartPtr( element_type * p): m_pData( p ) { _AddRef(); } 99 100 /** 101 * Assignment operator 102 * \par Sync (or) Async: 103 * This is a Synchronous function. 104 * \par Secure (or) Non-Secure (or) N/A: 105 * This is a Non-Secure function. 106 * \param pData [in] - pointer to object 107 * \return constant reference to Smart pointer 108 * \par Prospective Clients: 109 * All potential applications that require configuration settings and Internal Classes. 110 */ 111 const JemSmartPtr<element_type>& operator=( element_type * pData) 112 { 113 if (m_pData != pData){ 114 element_type* pOldData = m_pData; 115 m_pData = pData; 116 _AddRef(); 117 pOldData->DecRef(); 118 } 119 return *this; 120 } 121 122 /** 123 * Assignment operator 124 * \par Sync (or) Async: 125 * This is a Synchronous function. 126 * \par Secure (or) Non-Secure (or) N/A: 127 * This is a Non-Secure function. 128 * \param cp [in] - constant reference to object 129 * \return constant reference to Smart pointer 130 * \par Prospective Clients: 131 * All potential applications that require configuration settings and Internal Classes. 132 */ 133 const JemSmartPtr<element_type>& operator=(const JemSmartPtr<element_type>& cp) 134 { 135 return operator=(cp.m_pData); 136 } 137 138 /** 139 * Destructor - freeing all dynamic resources 140 */ 141 ~JemSmartPtr() 142 { 143 _Release(); 144 } 145 146 /** 147 * Casting to type operator 148 * \return pointer to an element 149 */ 150 operator element_type*() const { return m_pData; } 151 152 /** 153 * Casting to type operator 154 * \par Sync (or) Async: 155 * This is a Synchronous function. 156 * \par Secure (or) Non-Secure (or) N/A: 157 * This is a Non-Secure function. 158 * \return reference to an element 159 * \par Prospective Clients: 160 * All potential applications that require configuration settings and Internal Classes. 161 */ 162 element_type& operator*() const 163 { 164 return *m_pData; 165 } 166 167 /** 168 * Member selection via pointer operator 169 * \par Sync (or) Async: 170 * This is a Synchronous function. 171 * \par Secure (or) Non-Secure (or) N/A: 172 * This is a Non-Secure function. 173 * \return pointer to an element 174 * \par Prospective Clients: 175 * All potential applications that require configuration settings and Internal Classes. 176 */ 177 element_type* operator->() const 178 { 179 return m_pData; 180 } 181 182 /** 183 * Comparison operator (equally) 184 * \par Sync (or) Async: 185 * This is a Synchronous function. 186 * \par Secure (or) Non-Secure (or) N/A: 187 * This is a Non-Secure function. 188 * \param p [in] - pointer to an element for comparison 189 * \return boolean result of comparison 190 * \par Prospective Clients: 191 * All potential applications that require configuration settings and Internal Classes. 192 */ 193 BOOLEAN operator==(element_type* p) const { return m_pData == p; } 194 195 /** 196 * Comparison operator (equally) 197 * \par Sync (or) Async: 198 * This is a Synchronous function. 199 * \par Secure (or) Non-Secure (or) N/A: 200 * This is a Non-Secure function. 201 * \param ptr [in] - constant reference to Smart pointer for comparison 202 * \return boolean result of comparison 203 * \par Prospective Clients: 204 * All potential applications that require configuration settings and Internal Classes. 205 */ 206 BOOLEAN operator==(const JemSmartPtr<element_type>& ptr) const { return operator==(ptr.m_pData);} 207 208 /** 209 * Comparison operator (unequally) 210 * \par Sync (or) Async: 211 * This is a Synchronous function. 212 * \par Secure (or) Non-Secure (or) N/A: 213 * This is a Non-Secure function. 214 * \param p [in] - pointer to an element for comparison 215 * \return boolean result of comparison 216 * \par Prospective Clients: 217 * All potential applications that require configuration settings and Internal Classes. 218 */ 219 BOOLEAN operator!=(element_type* p) const { return !(operator==(p));} 220 221 /** 222 * Comparison operator (unequally) 223 * \par Sync (or) Async: 224 * This is a Synchronous function. 225 * \par Secure (or) Non-Secure (or) N/A: 226 * This is a Non-Secure function. 227 * \param ptr [in] - constant reference to Smart pointer for comparison 228 * \return boolean result of comparison 229 * \par Prospective Clients: 230 * All potential applications that require configuration settings and Internal Classes. 231 */ 232 BOOLEAN operator!=(const JemSmartPtr<element_type> & ptr) const { return !(operator==(ptr));} 233 234 /** 235 * Retrieves pointer to an element 236 * \par Sync (or) Async: 237 * This is a Synchronous function. 238 * \par Secure (or) Non-Secure (or) N/A: 239 * This is a Non-Secure function. 240 * \return pointer to an element 241 * \par Prospective Clients: 242 * All potential applications that require configuration settings and Internal Classes. 243 */ 244 element_type* GetPtr() const { return m_pData; } 245 246 247 248 private: 249 void _Release() { m_pData->DecRef(); } 250 void _AddRef() { m_pData->AddRef(); } 251 }; 252 253 /** 254 * Reverse comparison operators for JemSmartPtr (equally) 255 * \par Sync (or) Async: 256 * This is a Synchronous function. 257 * \par Secure (or) Non-Secure (or) N/A: 258 * This is a Non-Secure function. 259 * \param p [in] - Smart pointer 260 * \param ptr [in] - reference to Smart pointer 261 * \return boolean result of comparison 262 * \par Prospective Clients: 263 * All potential applications that require configuration settings and Internal Classes. 264 */ 265 template<typename T> inline BOOLEAN operator==(T* p, const JemSmartPtr<T>& ptr) 266 { 267 return ptr == p; 268 } 269 270 /** 271 * Reverse comparison operators for JemSmartPtr (unequally) 272 * \par Sync (or) Async: 273 * This is a Synchronous function. 274 * \par Secure (or) Non-Secure (or) N/A: 275 * This is a Non-Secure function. 276 * \param p [in] - Smart pointer 277 * \param ptr [in] - reference to Smart pointer 278 * \return boolean result of comparison 279 * \par Prospective Clients: 280 * All potential applications that require configuration settings and Internal Classes. 281 */ 282 template<typename T> inline BOOLEAN operator!=(T* p, const JemSmartPtr<T>& ptr) 283 { 284 return ptr != p; 285 } 286 287 288 /** 289 * Base object for any ref-counted object. 290 * \par Category: General 291 * \par Persistence: Transient 292 * \par Security: Non-Secure 293 * \par Migration State: FINAL 294 */ 295 class JemBaseObject 296 { 297 INT64 m_nRefCount; 298 299 protected: 300 /** 301 * Protected destructor, since this is reference counted object and nobody should delete it manually. 302 */ 303 virtual ~JemBaseObject(){} 304 305 public: 306 307 /** 308 * Default constructor - no memory allocation performed. 309 */ 310 JemBaseObject(); 311 312 /** 313 * Operator New 314 * \par Sync (or) Async: 315 * This is a Synchronous function. 316 * \par Secure (or) Non-Secure (or) N/A: 317 * This is a Non-Secure function. 318 * \param nSize [in] - requested size 319 * \return void pointer 320 * \par Prospective Clients: 321 * All potential applications that require configuration settings and Internal Classes. 322 */ 323 void* operator new( size_t nSize ) 324 { return DmtMemAlloc( nSize ); } 325 326 /** 327 * Operator Delete 328 * \par Sync (or) Async: 329 * This is a Synchronous function. 330 * \par Secure (or) Non-Secure (or) N/A: 331 * This is a Non-Secure function. 332 * \param p [in] - void pointer 333 * \par Prospective Clients: 334 * All potential applications that require configuration settings and Internal Classes. 335 */ 336 inline void operator delete( void* p ) 337 { DmtMemFree( p ); } 338 339 /** 340 * Increments reference counter 341 * \par Sync (or) Async: 342 * This is a Synchronous function. 343 * \par Secure (or) Non-Secure (or) N/A: 344 * This is a Non-Secure function. 345 * \par API Migration State: FINAL 346 * \par Prospective Clients: 347 * All potential applications that require configuration settings and Internal Classes. 348 */ 349 void AddRef(); 350 351 /** 352 * Decrements reference counter; deletes object if it's the last reference 353 * \par Sync (or) Async: 354 * This is a Synchronous function. 355 * \par Secure (or) Non-Secure (or) N/A: 356 * This is a Non-Secure function. 357 * \par API Migration State: FINAL 358 * \par Prospective Clients: 359 * All potential applications that require configuration settings and Internal Classes. 360 */ 361 void DecRef(); 362 }; 363 364 /** Defines PJemBaseObject as a smart pointer for DmtNode class */ 365 typedef JemSmartPtr<JemBaseObject> PJemBaseObject; 366 367 // some additional smart pointers: 368 class DmtTree; 369 class DmtNode; 370 371 /** Defines PDmtNode as a smart pointer for DmtNode class */ 372 typedef JemSmartPtr<DmtTree> PDmtTree; 373 374 /** Defines PDmtTree as a smartpointer type for DmtTree class*/ 375 typedef JemSmartPtr<DmtNode> PDmtNode; 376 377 378 #ifndef NULL 379 /** Define NULL */ 380 #define NULL ((void*) 0) 381 #endif 382 383 //////////////////////////////////////////////////////////////////// 384 // inline functions for JemBaseObject 385 386 /** 387 * Default constructor for the class JemBaseObject - no memory allocation performed. 388 */ 389 inline JemBaseObject::JemBaseObject() 390 { 391 m_nRefCount = 0; 392 } 393 394 /** 395 * Increments reference counter 396 * \par Sync (or) Async: 397 * This is a Synchronous function. 398 * \par Secure (or) Non-Secure (or) N/A: 399 * This is a Non-Secure function. 400 * \par Prospective Clients: 401 * All potential applications that require configuration settings and Internal Classes. 402 */ 403 inline void JemBaseObject::AddRef() 404 { 405 if ( this == NULL ) 406 return; 407 408 m_nRefCount++; 409 } 410 411 //decrement reference (if == 0 then delete object). 412 /** 413 * Decrements reference counter; delete object if it's the last reference 414 * \par Sync (or) Async: 415 * This is a Synchronous function. 416 * \par Secure (or) Non-Secure (or) N/A: 417 * This is a Non-Secure function. 418 * \par Prospective Clients: 419 * All potential applications that require configuration settings and Internal Classes. 420 */ 421 422 inline void JemBaseObject::DecRef() 423 { 424 if ( this == NULL ) 425 return; 426 427 if ( --m_nRefCount <= 0 ) 428 delete this; 429 } 430 431 #endif 432
