| 1 |
ConstBuffer Requirements |
| 2 |
================ |
| 3 |
|
| 4 |
|
| 5 |
## Overview |
| 6 |
|
| 7 |
ConstBuffer is a module that implements a read-only buffer of bytes (unsigned char). |
| 8 |
Once created, the buffer can no longer be changed. The buffer is ref counted so further _Clone calls result in |
| 9 |
zero copy. |
| 10 |
|
| 11 |
|
| 12 |
## References |
| 13 |
[refcount](../inc/refcount.h) |
| 14 |
|
| 15 |
[buffer](buffer_requirements.md) |
| 16 |
|
| 17 |
## Exposed API |
| 18 |
```c |
| 19 |
/*this is the handle*/ |
| 20 |
typedef struct CONSTBUFFER_HANDLE_DATA_TAG* CONSTBUFFER_HANDLE; |
| 21 |
|
| 22 |
/*this is what is returned when the content of the buffer needs access*/ |
| 23 |
typedef struct CONSTBUFFER_TAG |
| 24 |
{ |
| 25 |
const unsigned char* buffer; |
| 26 |
size_t size; |
| 27 |
} CONSTBUFFER; |
| 28 |
|
| 29 |
/*this creates a new constbuffer from a memory area*/ |
| 30 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_Create, const unsigned char*, source, size_t, size); |
| 31 |
|
| 32 |
/*this creates a new constbuffer from an existing BUFFER_HANDLE*/ |
| 33 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateFromBuffer, BUFFER_HANDLE, buffer); |
| 34 |
|
| 35 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateWithMoveMemory, unsigned char*, source, size_t, size); |
| 36 |
|
| 37 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateWithCustomFree, const unsigned char*, source, size_t, size, CONSTBUFFER_CUSTOM_FREE_FUNC, customFreeFunc, void*, customFreeFuncContext); |
| 38 |
|
| 39 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateFromOffsetAndSize, CONSTBUFFER_HANDLE, handle, size_t, offset, size_t, size) |
| 40 |
|
| 41 |
MOCKABLE_FUNCTION(, void, CONSTBUFFER_IncRef, CONSTBUFFER_HANDLE, constbufferHandle); |
| 42 |
|
| 43 |
MOCKABLE_FUNCTION(, void, CONSTBUFFER_DecRef, CONSTBUFFER_HANDLE, constbufferHandle); |
| 44 |
|
| 45 |
MOCKABLE_FUNCTION(, const CONSTBUFFER*, CONSTBUFFER_GetContent, CONSTBUFFER_HANDLE, constbufferHandle); |
| 46 |
|
| 47 |
MOCKABLE_FUNCTION(, bool, CONSTBUFFER_HANDLE_contain_same, CONSTBUFFER_HANDLE, left, CONSTBUFFER_HANDLE, right); |
| 48 |
``` |
| 49 |
|
| 50 |
### CONSTBUFFER_Create |
| 51 |
```c |
| 52 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_Create, const unsigned char*, source, size_t, size); |
| 53 |
``` |
| 54 |
**SRS_CONSTBUFFER_02_001: [** If `source` is NULL and `size` is different than 0 then CONSTBUFFER_Create shall fail and return NULL. **]** |
| 55 |
|
| 56 |
**SRS_CONSTBUFFER_02_002: [** Otherwise, `CONSTBUFFER_Create` shall create a copy of the memory area pointed to by `source` having `size` bytes. **]** |
| 57 |
|
| 58 |
**SRS_CONSTBUFFER_02_003: [** If creating the copy fails then `CONSTBUFFER_Create` shall return NULL. **]** |
| 59 |
|
| 60 |
**SRS_CONSTBUFFER_02_004: [** Otherwise `CONSTBUFFER_Create` shall return a non-NULL handle. **]** |
| 61 |
|
| 62 |
**SRS_CONSTBUFFER_02_005: [** The non-NULL handle returned by `CONSTBUFFER_Create` shall have its ref count set to "1". **]** |
| 63 |
|
| 64 |
### CONSTBUFFER_CreateFromBuffer |
| 65 |
```c |
| 66 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateFromBuffer, BUFFER_HANDLE, buffer); |
| 67 |
``` |
| 68 |
**SRS_CONSTBUFFER_02_006: [** If `buffer` is NULL then `CONSTBUFFER_CreateFromBuffer` shall fail and return NULL. **]** |
| 69 |
|
| 70 |
**SRS_CONSTBUFFER_02_007: [** Otherwise, `CONSTBUFFER_CreateFromBuffer` shall copy the content of `buffer`. **]** |
| 71 |
|
| 72 |
**SRS_CONSTBUFFER_02_008: [** If copying the content fails, then `CONSTBUFFER_CreateFromBuffer` shall fail and return NULL. **]** |
| 73 |
|
| 74 |
**SRS_CONSTBUFFER_02_009: [** Otherwise, `CONSTBUFFER_CreateFromBuffer` shall return a non-NULL handle. **]** |
| 75 |
|
| 76 |
**SRS_CONSTBUFFER_02_010: [** The non-NULL handle returned by `CONSTBUFFER_CreateFromBuffer` shall have its ref count set to "1". **]** |
| 77 |
|
| 78 |
### CONSTBUFFER_CreateWithMoveMemory |
| 79 |
```c |
| 80 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateWithMoveMemory, unsigned char*, source, size_t, size); |
| 81 |
``` |
| 82 |
|
| 83 |
`CONSTBUFFER_CreateWithMoveMemory` creates a CONST buffer with move semantics for the memory given as argument (if succesfull, the const buffer owns the memory from that point on). |
| 84 |
The memory is assumed to be freeable by a call to `free`. |
| 85 |
|
| 86 |
**SRS_CONSTBUFFER_01_001: [** If `source` is NULL and `size` is different than 0 then `CONSTBUFFER_CreateWithMoveMemory` shall fail and return NULL. **]** |
| 87 |
|
| 88 |
**SRS_CONSTBUFFER_01_004: [** If `source` is non-NULL and `size` is 0, the `source` pointer shall be owned (and freed) by the newly created instance of const buffer. **]** |
| 89 |
|
| 90 |
**SRS_CONSTBUFFER_01_002: [** `CONSTBUFFER_CreateWithMoveMemory` shall store the `source` and `size` and return a non-NULL handle to the newly created const buffer. **]** |
| 91 |
|
| 92 |
**SRS_CONSTBUFFER_01_003: [** The non-NULL handle returned by `CONSTBUFFER_CreateWithMoveMemory` shall have its ref count set to "1". **]** |
| 93 |
|
| 94 |
**SRS_CONSTBUFFER_01_005: [** If any error occurs, `CONSTBUFFER_CreateWithMoveMemory` shall fail and return NULL. **]** |
| 95 |
|
| 96 |
### CONSTBUFFER_CreateWithCustomFree |
| 97 |
|
| 98 |
```c |
| 99 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateWithCustomFree, const unsigned char*, source, size_t, size, CONSTBUFFER_CUSTOM_FREE_FUNC, customFreeFunc, void*, customFreeFuncContext); |
| 100 |
``` |
| 101 |
|
| 102 |
`CONSTBUFFER_CreateWithCustomFree` creates a CONST buffer with move semantics for the memory given as argument (if succesfull, the const buffer owns the memory from that point on). |
| 103 |
The memory has to be free by calling the custom free function passed as argument. |
| 104 |
|
| 105 |
**SRS_CONSTBUFFER_01_006: [** If `source` is NULL and `size` is different than 0 then `CONSTBUFFER_CreateWithCustomFree` shall fail and return NULL. **]** |
| 106 |
|
| 107 |
**SRS_CONSTBUFFER_01_013: [** If `customFreeFunc` is NULL, `CONSTBUFFER_CreateWithCustomFree` shall fail and return NULL. **]** |
| 108 |
|
| 109 |
**SRS_CONSTBUFFER_01_014: [** `customFreeFuncContext` shall be allowed to be NULL. **]** |
| 110 |
|
| 111 |
**SRS_CONSTBUFFER_01_007: [** If `source` is non-NULL and `size` is 0, the `source` pointer shall be owned (and freed) by the newly created instance of const buffer. **]** |
| 112 |
|
| 113 |
**SRS_CONSTBUFFER_01_008: [** `CONSTBUFFER_CreateWithCustomFree` shall store the `source` and `size` and return a non-NULL handle to the newly created const buffer. **]** |
| 114 |
|
| 115 |
**SRS_CONSTBUFFER_01_009: [** `CONSTBUFFER_CreateWithCustomFree` shall store `customFreeFunc` and `customFreeFuncContext` in order to use them to free the memory when the CONST buffer resources are freed. **]** |
| 116 |
|
| 117 |
**SRS_CONSTBUFFER_01_010: [** The non-NULL handle returned by `CONSTBUFFER_CreateWithCustomFree` shall have its ref count set to 1. **]** |
| 118 |
|
| 119 |
**SRS_CONSTBUFFER_01_011: [** If any error occurs, `CONSTBUFFER_CreateWithMoveMemory` shall fail and return NULL. **]** |
| 120 |
|
| 121 |
### CONSTBUFFER_CreateFromOffsetAndSize |
| 122 |
```c |
| 123 |
MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, CONSTBUFFER_CreateFromOffsetAndSize, CONSTBUFFER_HANDLE, handle, size_t, offset, size_t, size) |
| 124 |
``` |
| 125 |
|
| 126 |
Given an existing `handle` `CONSTBUFFER_CreateFromOffsetAndSize` creates another `CONSTBUFFER_HANDLE` from `size` bytes `handle` starting at `offset`. |
| 127 |
|
| 128 |
**SRS_CONSTBUFFER_02_025: [** If `handle` is `NULL` then `CONSTBUFFER_CreateFromOffsetAndSize` shall fail and return `NULL`. **]** |
| 129 |
|
| 130 |
**SRS_CONSTBUFFER_02_033: [** If `offset` is greater than `handles`'s size then `CONSTBUFFER_CreateFromOffsetAndSize` shall fail and return `NULL`. **]** |
| 131 |
|
| 132 |
**SRS_CONSTBUFFER_02_027: [** If `offset` + `size` exceed `handles`'s size then `CONSTBUFFER_CreateFromOffsetAndSize` shall fail and return `NULL`. **]** |
| 133 |
|
| 134 |
**SRS_CONSTBUFFER_02_028: [** `CONSTBUFFER_CreateFromOffsetAndSize` shall allocate memory for a new `CONSTBUFFER_HANDLE`'s content. **]** |
| 135 |
|
| 136 |
**SRS_CONSTBUFFER_02_029: [** `CONSTBUFFER_CreateFromOffsetAndSize` shall set the ref count of the newly created `CONSTBUFFER_HANDLE` to the initial value. **]** |
| 137 |
|
| 138 |
**SRS_CONSTBUFFER_02_030: [** `CONSTBUFFER_CreateFromOffsetAndSize` shall increment the reference count of `handle`. **]** |
| 139 |
|
| 140 |
**SRS_CONSTBUFFER_02_031: [** `CONSTBUFFER_CreateFromOffsetAndSize` shall succeed and return a non-`NULL` value. **]** |
| 141 |
|
| 142 |
**SRS_CONSTBUFFER_02_032: [** If there are any failures then `CONSTBUFFER_CreateFromOffsetAndSize` shall fail and return `NULL`. **]** |
| 143 |
|
| 144 |
|
| 145 |
### CONSTBUFFER_IncRef |
| 146 |
```c |
| 147 |
MOCKABLE_FUNCTION(, void, CONSTBUFFER_IncRef, CONSTBUFFER_HANDLE, constbufferHandle); |
| 148 |
``` |
| 149 |
**SRS_CONSTBUFFER_02_013: [** If `constbufferHandle` is NULL then `CONSTBUFFER_IncRef` shall return. **]** |
| 150 |
|
| 151 |
**SRS_CONSTBUFFER_02_014: [** Otherwise, `CONSTBUFFER_IncRef` shall increment the reference count. **]** |
| 152 |
|
| 153 |
### CONSTBUFFER_DecRef |
| 154 |
```c |
| 155 |
MOCKABLE_FUNCTION(, void, CONSTBUFFER_DecRef, CONSTBUFFER_HANDLE, constbufferHandle); |
| 156 |
``` |
| 157 |
**SRS_CONSTBUFFER_02_015: [** If `constbufferHandle` is NULL then `CONSTBUFFER_DecRef` shall do nothing. **]** |
| 158 |
|
| 159 |
**SRS_CONSTBUFFER_02_016: [** Otherwise, `CONSTBUFFER_DecRef` shall decrement the refcount on the `constbufferHandle` handle. **]** |
| 160 |
|
| 161 |
**SRS_CONSTBUFFER_02_017: [** If the refcount reaches zero, then `CONSTBUFFER_DecRef` shall deallocate all resources used by the CONSTBUFFER_HANDLE. **]** |
| 162 |
|
| 163 |
**SRS_CONSTBUFFER_01_012: [** If the buffer was created by calling `CONSTBUFFER_CreateWithCustomFree`, the `customFreeFunc` function shall be called to free the memory, while passed `customFreeFuncContext` as argument. **]** |
| 164 |
|
| 165 |
**SRS_CONSTBUFFER_02_024: [** If the `constbufferHandle` was created by calling `CONSTBUFFER_CreateFromOffsetAndSize` then `CONSTBUFFER_DecRef` shall decrement the ref count of the original `handle` passed to `CONSTBUFFER_CreateFromOffsetAndSize`. **]** |
| 166 |
|
| 167 |
### CONSTBUFFER_GetContent |
| 168 |
```c |
| 169 |
MOCKABLE_FUNCTION(, const CONSTBUFFER*, CONSTBUFFER_GetContent, CONSTBUFFER_HANDLE, constbufferHandle); |
| 170 |
``` |
| 171 |
**SRS_CONSTBUFFER_02_011: [** If `constbufferHandle` is NULL then CONSTBUFFER_GetContent shall return NULL. **]** |
| 172 |
|
| 173 |
**SRS_CONSTBUFFER_02_012: [** Otherwise, `CONSTBUFFER_GetContent` shall return a `const CONSTBUFFER*` that matches byte by byte the original bytes used to created the const buffer and has the same length. **]** |
| 174 |
|
| 175 |
### CONSTBUFFER_HANDLE_contain_same |
| 176 |
```c |
| 177 |
MOCKABLE_FUNCTION(, bool, CONSTBUFFER_HANDLE_contain_same, CONSTBUFFER_HANDLE, left, CONSTBUFFER_HANDLE, right); |
| 178 |
``` |
| 179 |
|
| 180 |
`CONSTBUFFER_HANDLE_contain_same` returns `true` if `left` and `right` have the same content. |
| 181 |
|
| 182 |
**SRS_CONSTBUFFER_02_018: [** If `left` is `NULL` and `right` is `NULL` then `CONSTBUFFER_HANDLE_contain_same` shall return `true`. **]** |
| 183 |
|
| 184 |
**SRS_CONSTBUFFER_02_019: [** If `left` is `NULL` and `right` is not `NULL` then `CONSTBUFFER_HANDLE_contain_same` shall return `false`. **]** |
| 185 |
|
| 186 |
**SRS_CONSTBUFFER_02_020: [** If `left` is not `NULL` and `right` is `NULL` then `CONSTBUFFER_HANDLE_contain_same` shall return `false`. **]** |
| 187 |
|
| 188 |
**SRS_CONSTBUFFER_02_021: [** If `left`'s size is different than `right`'s size then `CONSTBUFFER_HANDLE_contain_same` shall return `false`. **]** |
| 189 |
|
| 190 |
**SRS_CONSTBUFFER_02_022: [** If `left`'s buffer is contains different bytes than `rights`'s buffer then `CONSTBUFFER_HANDLE_contain_same` shall return `false`. **]** |
| 191 |
|
| 192 |
**SRS_CONSTBUFFER_02_023: [** `CONSTBUFFER_HANDLE_contain_same` shall return `true`. **]** |