resource/c_common/oic_malloc/include/oic_malloc.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 #ifndef OIC_MALLOC_H_
  22 #define OIC_MALLOC_H_
  23
  24 // The purpose of this module is to allow custom dynamic memory allocation
  25 // code to easily be added to the TB Stack by redefining the OICMalloc and
  26 // OICFree functions.  Examples of when this might be needed are on TB
  27 // platforms that do not support dynamic allocation or if a memory pool
  28 // needs to be added.
  29 //
  30 // Note that these functions are intended to be used ONLY within the TB
  31 // stack and NOT by the application code.  The application should be
  32 // responsible for its own dynamic allocation.
  33
  34 //-----------------------------------------------------------------------------
  35 // Includes
  36 //-----------------------------------------------------------------------------
  37 #include <stdio.h>
  38
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #endif // __cplusplus
  43 //-----------------------------------------------------------------------------
  44 // Defines
  45 //-----------------------------------------------------------------------------
  46
  47 //-----------------------------------------------------------------------------
  48 // Typedefs
  49 //-----------------------------------------------------------------------------
  50
  51 //-----------------------------------------------------------------------------
  52 // Function prototypes
  53 //-----------------------------------------------------------------------------
  54
  55 /**
  56  * Allocates a block of size bytes, returning a pointer to the beginning of
  57  * the allocated block.
  58  *
  59  * NOTE: This function is intended to be used internally by the TB Stack.
  60  *       It is not intended to be used by applications.
  61  *
  62  * @param size - Size of the memory block in bytes, where size > 0
  63  *
  64  * @return
  65  *     on success, a pointer to the allocated memory block
  66  *     on failure, a null pointer is returned
  67  */
  68 void *OICMalloc(size_t size);
  69
  70 /**
  71  * Re-allocates a block of memory, pointed to by ptr to the size specified
  72  * in size.  The returned value contains a pointer to the new location, with
  73  * all data copied into it.  If the new size of the memory-object require movement,
  74  * the previous space is freed.  If the new size is larger, the newly allocated
  75  * area has non-deterministic content. If the space cannot be allocated, the value
  76  * ptr is left unchanged.
  77  *
  78  * @param ptr - Pointer to a block of memory previously allocated by OICCalloc,
  79  *              OICMalloc, or a previous call to this function.  If this value is
  80  *              NULL, this function will work identically to a call to OICMalloc.
  81  *
  82  * @param size - Size of the new memory block in bytes, where size > 0
  83  *
  84  * @return
  85  *      on success, a pointer to the newly sized memory block
  86  *      on failure, a null pointer is returned, and the memory pointed to by *ptr is untouched
  87  */
  88 void *OICRealloc(void *ptr, size_t size);
  89
  90 /**
  91  * Allocates a block of memory for an array of num elements, each of them
  92  * size bytes long and initializes all its bits to zero.
  93  *
  94  * @param num - The number of elements
  95  * @param size - Size of the element type in bytes, where size > 0
  96  *
  97  * @return
  98  *     on success, a pointer to the allocated memory block
  99  *     on failure, a null pointer is returned
 100  */
 101 void *OICCalloc(size_t num, size_t size);
 102
 103 /**
 104  * Deallocate a block of memory previously allocated by a call to OCMalloc
 105  *
 106  * NOTE: This function is intended to be used internally by the TB Stack.
 107  *       It is not intended to be used by applications.
 108  *
 109  * @param ptr - Pointer to block of memory previously allocated by OICMalloc.
 110  *              If ptr is a null pointer, the function does nothing.
 111  */
 112 void OICFree(void *ptr);
 113
 114 #ifdef __cplusplus
 115 }
 116 #endif // __cplusplus
 117 #endif /* OIC_MALLOC_H_ */
 118