| 1 |
BUFFER Requirements |
| 2 |
================ |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
The BUFFER object encapsulastes a unsigned char* variable. |
| 7 |
|
| 8 |
## Exposed API |
| 9 |
```c |
| 10 |
typedef void* BUFFER_HANDLE; |
| 11 |
|
| 12 |
extern BUFFER_HANDLE BUFFER_new(void); |
| 13 |
|
| 14 |
extern void BUFFER_delete(BUFFER_HANDLE handle); |
| 15 |
extern BUFFER_HANDLE BUFFER_create(const unsigned char* source, size_t size); |
| 16 |
extern BUFFER_HANDLE BUFFER_create_with_size(size_t buff_size) |
| 17 |
extern int BUFFER_pre_build(BUFFER_HANDLE handle, size_t size); |
| 18 |
extern int BUFFER_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size); |
| 19 |
extern int BUFFER_unbuild(BUFFER_HANDLE handle); |
| 20 |
extern int BUFFER_enlarge(BUFFER_HANDLE handle, size_t enlargeSize); |
| 21 |
extern int BUFFER_content(BUFFER_HANDLE handle, const unsigned char** content); |
| 22 |
extern int BUFFER_size(BUFFER_HANDLE handle, size_t* size); |
| 23 |
extern int BUFFER_append(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2); |
| 24 |
extern int BUFFER_prepend(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2); |
| 25 |
extern unsigned char* BUFFER_u_char(BUFFER_HANDLE handle); |
| 26 |
extern size_t BUFFER_length(BUFFER_HANDLE handle); |
| 27 |
extern BUFFER_HANDLE BUFFER_clone(BUFFER_HANDLE handle); |
| 28 |
extern int BUFFER_fill(BUFFER_HANDLE handle, unsigned char fill_char); |
| 29 |
|
| 30 |
``` |
| 31 |
|
| 32 |
### BUFFER_new |
| 33 |
```c |
| 34 |
BUFFER_HANDLE BUFFER_new(void) |
| 35 |
``` |
| 36 |
|
| 37 |
**SRS_BUFFER_07_001: [** BUFFER_new shall allocate a BUFFER_HANDLE that will contain a NULL unsigned char*. **]** |
| 38 |
|
| 39 |
### BUFFER_create |
| 40 |
|
| 41 |
```c |
| 42 |
extern BUFFER_HANDLE BUFFER_create(const unsigned char* source, size_t size); |
| 43 |
``` |
| 44 |
|
| 45 |
BUFFER_create creates a new buffer from the memory at source, having size "size". |
| 46 |
|
| 47 |
**SRS_BUFFER_02_001: [** If source is NULL then BUFFER_create shall return NULL. **]** |
| 48 |
|
| 49 |
**SRS_BUFFER_02_002: [** Otherwise, BUFFER_create shall allocate memory to hold size bytes and shall copy from source size bytes into the newly allocated memory. **]** |
| 50 |
|
| 51 |
**SRS_BUFFER_02_003: [** If allocating memory fails, then BUFFER_create shall return NULL. **]** |
| 52 |
|
| 53 |
**SRS_BUFFER_02_004: [** Otherwise, BUFFER_create shall return a non-NULL handle. **]** |
| 54 |
|
| 55 |
### BUFFER_create_with_size |
| 56 |
|
| 57 |
|
| 58 |
|
| 59 |
```c |
| 60 |
extern BUFFER_HANDLE BUFFER_create_with_size(size_t buff_size) |
| 61 |
``` |
| 62 |
|
| 63 |
**SRS_BUFFER_07_029: [** BUFFER_create_with_size shall create a BUFFER_HANDLE with a pre allocated underlying buffer size. **]** |
| 64 |
|
| 65 |
**SRS_BUFFER_07_030: [** If buff_size is 0 BUFFER_create_with_size shall create a valid non-NULL handle of zero size. **]** |
| 66 |
|
| 67 |
**SRS_BUFFER_07_031: [** BUFFER_create_with_size shall allocate a buffer of buff_size. **]** |
| 68 |
|
| 69 |
**SRS_BUFFER_07_032: [** If allocating memory fails, then BUFFER_create_with_size shall return NULL. **]** |
| 70 |
|
| 71 |
**SRS_BUFFER_07_033: [** Otherwise, BUFFER_create_with_size shall return a non-NULL handle. **]** |
| 72 |
|
| 73 |
### BUFFER_delete |
| 74 |
|
| 75 |
```c |
| 76 |
void BUFFER_delete(BUFFER_HANDLE handle) |
| 77 |
``` |
| 78 |
|
| 79 |
**SRS_BUFFER_07_003: [** BUFFER_delete shall delete the data associated with the BUFFER_HANDLE along with the Buffer. **]** |
| 80 |
|
| 81 |
**SRS_BUFFER_07_004: [** BUFFER_delete shall not delete any BUFFER_HANDLE that is NULL. **]** |
| 82 |
|
| 83 |
### BUFFER_pre_build |
| 84 |
```c |
| 85 |
int BUFFER_pre_build(BUFFER_HANDLE handle, size_t size) |
| 86 |
``` |
| 87 |
|
| 88 |
**SRS_BUFFER_07_005: [** BUFFER_pre_build allocates size_t bytes of BUFFER_HANDLE and returns zero on success. **]** |
| 89 |
|
| 90 |
**SRS_BUFFER_07_006: [** If handle is NULL or size is 0 then BUFFER_pre_build shall return a nonzero value. **]** |
| 91 |
|
| 92 |
**SRS_BUFFER_07_007: [** BUFFER_pre_build shall return nonzero if the buffer has been previously allocated and is not NULL. **]** |
| 93 |
|
| 94 |
**SRS_BUFFER_07_013: [** BUFFER_pre_build shall return nonzero if any error is encountered. **]** |
| 95 |
|
| 96 |
### BUFFER_build |
| 97 |
|
| 98 |
```c |
| 99 |
int BUFFER_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size) |
| 100 |
``` |
| 101 |
|
| 102 |
**SRS_BUFFER_07_008: [** BUFFER_build allocates size_t bytes, copies the unsigned char* into the buffer and returns zero on success. **]** |
| 103 |
|
| 104 |
**SRS_BUFFER_07_009: [** BUFFER_build shall return nonzero if handle is NULL **]** |
| 105 |
|
| 106 |
**SRS_BUFFER_01_001: [** If size is positive and source is NULL, BUFFER_build shall return nonzero **]** |
| 107 |
|
| 108 |
**SRS_BUFFER_01_002: [** The size argument can be zero, in which case the underlying buffer held by the buffer instance shall be freed. **]** |
| 109 |
|
| 110 |
**SRS_BUFFER_01_003: [** If size is zero, source can be NULL. **]** |
| 111 |
|
| 112 |
**SRS_BUFFER_07_010: [** BUFFER_build shall return nonzero if any error is encountered. **]** |
| 113 |
|
| 114 |
**SRS_BUFFER_07_011: [** BUFFER_build shall overwrite previous contents if the buffer has been previously allocated. **]** |
| 115 |
|
| 116 |
### BUFFER_append_build |
| 117 |
|
| 118 |
```c |
| 119 |
int BUFFER_append_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size) |
| 120 |
``` |
| 121 |
|
| 122 |
**SRS_BUFFER_07_029: [** `BUFFER_append_build` shall return nonzero if handle or source are NULL or if size is 0. **]** |
| 123 |
|
| 124 |
**SRS_BUFFER_07_030: [** if handle->buffer is NULL `BUFFER_append_build` shall allocate the a buffer of size bytes... **]** |
| 125 |
|
| 126 |
**SRS_BUFFER_07_031: [** ... and copy the contents of source to handle->buffer. **]** |
| 127 |
|
| 128 |
**SRS_BUFFER_07_032: [** if handle->buffer is not NULL `BUFFER_append_build` shall realloc the buffer to be the handle->size + size **]** |
| 129 |
|
| 130 |
**SRS_BUFFER_07_033: [** ... and copy the contents of source to the end of the buffer. **]** |
| 131 |
|
| 132 |
**SRS_BUFFER_07_034: [** On success `BUFFER_append_build` shall return 0 **]** |
| 133 |
|
| 134 |
**SRS_BUFFER_07_035: [** If any error is encountered `BUFFER_append_build` shall return a non-null value. **]** |
| 135 |
|
| 136 |
### BUFFER_unbuild |
| 137 |
|
| 138 |
```c |
| 139 |
int BUFFER_unbuild(BUFFER_HANDLE b) |
| 140 |
``` |
| 141 |
|
| 142 |
**SRS_BUFFER_07_012: [** BUFFER_unbuild shall clear the underlying unsigned char* data associated with the BUFFER_HANDLE this will return zero on success. **]** |
| 143 |
|
| 144 |
**SRS_BUFFER_07_014: [** BUFFER_unbuild shall return a nonzero value if BUFFER_HANDLE is NULL. **]** |
| 145 |
|
| 146 |
**SRS_BUFFER_07_015: [** BUFFER_unbuild shall always return success if the unsigned char* referenced by BUFFER_HANDLE is NULL. **]** |
| 147 |
|
| 148 |
### BUFFER_enlarge |
| 149 |
|
| 150 |
```c |
| 151 |
int BUFFER_enlarge(BUFFER_HANDLE handle, size_t enlargeSize) |
| 152 |
``` |
| 153 |
|
| 154 |
**SRS_BUFFER_07_016: [** BUFFER_enlarge shall increase the size of the unsigned char* referenced by BUFFER_HANDLE. **]** |
| 155 |
|
| 156 |
**SRS_BUFFER_07_017: [** BUFFER_enlarge shall return a nonzero result if any parameters are NULL or zero. **]** |
| 157 |
|
| 158 |
**SRS_BUFFER_07_018: [** BUFFER_enlarge shall return a nonzero result if any error is encountered. **]** |
| 159 |
|
| 160 |
### BUFFER_shrink |
| 161 |
|
| 162 |
```c |
| 163 |
int BUFFER_shrink(BUFFER_HANDLE handle, size_t decreaseSize, bool fromEnd) |
| 164 |
``` |
| 165 |
|
| 166 |
**SRS_BUFFER_07_036: [** if handle is NULL, `BUFFER_shrink` shall return a non-null value **]** |
| 167 |
|
| 168 |
**SRS_BUFFER_07_037: [** If decreaseSize is equal zero, `BUFFER_shrink` shall return a non-null value **]** |
| 169 |
|
| 170 |
**SRS_BUFFER_07_038: [** If decreaseSize is less than the size of the buffer, `BUFFER_shrink` shall return a non-null value **]** |
| 171 |
|
| 172 |
**SRS_BUFFER_07_039: [** `BUFFER_shrink` shall allocate a temporary buffer of existing buffer size minus decreaseSize. **]** |
| 173 |
|
| 174 |
**SRS_BUFFER_07_040: [** if the fromEnd variable is true, `BUFFER_shrink` shall remove the end of the buffer of size decreaseSize. **]** |
| 175 |
|
| 176 |
**SRS_BUFFER_07_041: [** if the fromEnd variable is false, `BUFFER_shrink` shall remove the beginning of the buffer of size decreaseSize. **]** |
| 177 |
|
| 178 |
**SRS_BUFFER_07_042: [** If a failure is encountered, `BUFFER_shrink` shall return a non-null value **]** |
| 179 |
|
| 180 |
**SRS_BUFFER_07_043: [** If the decreaseSize is equal the buffer size , `BUFFER_shrink` shall deallocate the buffer and set the size to zero. **]** |
| 181 |
### BUFFER_content |
| 182 |
|
| 183 |
```c |
| 184 |
int BUFFER_content(BUFFER_HANDLE handle, unsigned char** content) |
| 185 |
``` |
| 186 |
|
| 187 |
**SRS_BUFFER_07_019: [** BUFFER_content shall return the data contained within the BUFFER_HANDLE. **]** |
| 188 |
|
| 189 |
**SRS_BUFFER_07_020: [** If the handle and/or content*is NULL BUFFER_content shall return nonzero. **]** |
| 190 |
|
| 191 |
### BUFFER_size |
| 192 |
```c |
| 193 |
int BUFFER_size(BUFFER_HANDLE b, size_t* size) |
| 194 |
``` |
| 195 |
|
| 196 |
**SRS_BUFFER_07_021: [** BUFFER_size shall place the size of the associated buffer in the size variable and return zero on success. **]** |
| 197 |
|
| 198 |
**SRS_BUFFER_07_022: [** BUFFER_size shall return a nonzero value for any error that is encountered. **]** |
| 199 |
|
| 200 |
### BUFFER_append |
| 201 |
```c |
| 202 |
int BUFFER_append(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2) |
| 203 |
``` |
| 204 |
|
| 205 |
**SRS_BUFFER_07_024: [** BUFFER_append concatenates b2 onto b1 without modifying b2 and shall return zero on success. **]** |
| 206 |
|
| 207 |
**SRS_BUFFER_07_023: [** BUFFER_append shall return a nonzero upon any error that is encountered. **]** |
| 208 |
|
| 209 |
### BUFFER_prepend |
| 210 |
```c |
| 211 |
int BUFFER_prepend(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2) |
| 212 |
``` |
| 213 |
|
| 214 |
**SRS_BUFFER_01_004: [** BUFFER_prepend concatenates handle1 onto handle2 without modifying handle1 and shall return zero on success. **]** |
| 215 |
|
| 216 |
**SRS_BUFFER_01_005: [** BUFFER_prepend shall return a non-zero upon value any error that is encountered. **]** |
| 217 |
|
| 218 |
### BUFFER_fill |
| 219 |
|
| 220 |
```c |
| 221 |
extern int BUFFER_fill(BUFFER_HANDLE handle, unsigned char fill_char); |
| 222 |
``` |
| 223 |
|
| 224 |
**SRS_BUFFER_07_001: [** `BUFFER_fill` shall fill the supplied `BUFFER_HANDLE` with the supplied fill character. **]** |
| 225 |
|
| 226 |
**SRS_BUFFER_07_002: [** If `handle` is NULL `BUFFER_fill` shall return a non-zero value. **]** |
| 227 |
|
| 228 |
### BUFFER_u_char |
| 229 |
|
| 230 |
```c |
| 231 |
unsigned char* BUFFER_u_char(BUFFER_HANDLE handle) |
| 232 |
``` |
| 233 |
|
| 234 |
**SRS_BUFFER_07_025: [** BUFFER_u_char shall return a pointer to the underlying unsigned char*. **]** |
| 235 |
|
| 236 |
**SRS_BUFFER_07_026: [** BUFFER_u_char shall return NULL for any error that is encountered. **]** |
| 237 |
|
| 238 |
### BUFFER_length |
| 239 |
|
| 240 |
```c |
| 241 |
size_t BUFFER_length(BUFFER_HANDLE handle) |
| 242 |
``` |
| 243 |
|
| 244 |
**SRS_BUFFER_07_027: [** BUFFER_length shall return the size of the underlying buffer. **]** |
| 245 |
|
| 246 |
**SRS_BUFFER_07_028: [** BUFFER_length shall return zero for any error that is encountered. **]** |