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*/
43typedef UINT8 byte;
44 /**Definition for the "boolean" as unsigned char*/
45typedef BOOLEAN boolean;
46 /**Definition for the "JemDate" as INT64*/
47typedef 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  */
61inline 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*/
75template<typename T> class JemSmartPtr
76{
77  T * m_pData;
78public:
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
248private:
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  */
265template<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  */
282template<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*/
295class JemBaseObject
296{
297  INT64 m_nRefCount;
298
299protected:
300  /**
301  * Protected destructor, since this is reference counted object and nobody should delete it manually.
302  */
303  virtual ~JemBaseObject(){}
304
305public:
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 */
365typedef JemSmartPtr<JemBaseObject> PJemBaseObject;
366
367// some additional smart pointers:
368class DmtTree;
369class DmtNode;
370
371/**  Defines PDmtNode  as  a smart pointer for DmtNode class */
372typedef JemSmartPtr<DmtTree> PDmtTree;
373
374/** Defines PDmtTree as a smartpointer type for DmtTree class*/
375typedef 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  */
389inline 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  */
403inline 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
422inline void JemBaseObject::DecRef()
423{
424  if ( this == NULL )
425    return;
426
427  if ( --m_nRefCount <= 0 )
428    delete this;
429}
430
431#endif
432