| 1 |
# OptionHandler |
| 2 |
|
| 3 |
# Overview |
| 4 |
|
| 5 |
Option Handler is a module that builds a container of options relevant to a module. The options can be later retrieved. |
| 6 |
It does so by asking the module to clone its options or to destroy them. `OptionHandler` is agnostic to the module it serves. |
| 7 |
|
| 8 |
|
| 9 |
## Exposed API |
| 10 |
|
| 11 |
```c |
| 12 |
#define OPTIONHANDLER_RESULT_VALUES |
| 13 |
OPTIONHANDLER_OK, |
| 14 |
OPTIONHANDLER_ERROR, |
| 15 |
OPTIONHANDLER_INVALIDARG |
| 16 |
|
| 17 |
MU_DEFINE_ENUM(OPTIONHANDLER_RESULT, OPTIONHANDLER_RESULT_VALUES) |
| 18 |
|
| 19 |
#ifdef __cplusplus |
| 20 |
extern "C" { |
| 21 |
#endif /* __cplusplus */ |
| 22 |
|
| 23 |
#include "umock_c/umock_c_prod.h" |
| 24 |
|
| 25 |
typedef struct OPTIONHANDLER_HANDLE_DATA_TAG* OPTIONHANDLER_HANDLE; |
| 26 |
|
| 27 |
/*the following function pointer points to a function that produces a clone of the option specified by name and value (that is, a clone of void* value)*/ |
| 28 |
/*returns NULL if it failed to produce a clone, otherwise returns a non-NULL value*/ |
| 29 |
/*to be implemented by every module*/ |
| 30 |
typedef void* (*pfCloneOption)(const char* name, const void* value); |
| 31 |
|
| 32 |
/*the following function pointer points to a function that frees resources allocated for an option*/ |
| 33 |
/*to be implemented by every module*/ |
| 34 |
typedef void (*pfDestroyOption)(const char* name, const void* value); |
| 35 |
|
| 36 |
/*the following function pointer points to a function that sets an option for a module*/ |
| 37 |
/*to be implemented by every module*/ |
| 38 |
/*returns 0 if _SetOption succeeded, any other value is error, if the option is not intended for that module, returns 0*/ |
| 39 |
typedef int (*pfSetOption)(void* handle, const char* name, const void* value); |
| 40 |
|
| 41 |
MOCKABLE_FUNCTION(,OPTIONHANDLER_HANDLE, OptionHandler_Create, pfCloneOption, cloneOption, pfDestroyOption, destroyOption, pfSetOption setOption); |
| 42 |
MOCKABLE_FUNCTION(, OPTIONHANDLER_HANDLE, OptionHandler_Clone, OPTIONHANDLER_HANDLE, handler); |
| 43 |
MOCKABLE_FUNCTION(,OPTIONHANDLER_RESULT, OptionHandler_AddOption, OPTIONHANDLER_HANDLE, handle, const char*, name, void*, value); |
| 44 |
MOCKABLE_FUNCTION(,OPTIONHANDLER_RESULT, OptionHandler_FeedOptions, OPTIONHANDLER_HANDLE, handle, void*, destinationHandle); |
| 45 |
MOCKABLE_FUNCTION(,void, OptionHandler_Destroy, OPTIONHANDLER_HANDLE, handle); |
| 46 |
|
| 47 |
#ifdef __cplusplus |
| 48 |
} |
| 49 |
#endif /* __cplusplus */ |
| 50 |
|
| 51 |
### OptionHandler_Create |
| 52 |
```c |
| 53 |
OPTIONHANDLER_HANDLE OptionHandler_Create(pfCloneOption cloneOption, pfDestroyOption destroyOption, pfSetOption setOption) |
| 54 |
``` |
| 55 |
|
| 56 |
**SRS_OPTIONHANDLER_02_001: [** `OptionHandler_Create` shall fail and retun `NULL` if any parameters are `NULL`. **]** |
| 57 |
|
| 58 |
**SRS_OPTIONHANDLER_02_002: [** `OptionHandler_Create` shall create an empty VECTOR that will hold pairs of `const char*` and `void*`. **]** |
| 59 |
|
| 60 |
**SRS_OPTIONHANDLER_02_003: [** If all the operations succeed then `OptionHandler_Create` shall succeed and return a non-`NULL` handle. **]** |
| 61 |
|
| 62 |
**SRS_OPTIONHANDLER_02_004: [** Otherwise, `OptionHandler_Create` shall fail and return `NULL`. **]** |
| 63 |
|
| 64 |
### OptionHandler_Clone |
| 65 |
|
| 66 |
```c |
| 67 |
OPTIONHANDLER_HANDLE OptionHandler_Clone(OPTIONHANDLER_HANDLE handler); |
| 68 |
``` |
| 69 |
|
| 70 |
**SRS_OPTIONHANDLER_01_001: [** `OptionHandler_Clone` shall clone an existing option handler instance. **]** |
| 71 |
|
| 72 |
**SRS_OPTIONHANDLER_01_002: [** On success it shall return a non-NULL handle. **]** |
| 73 |
|
| 74 |
**SRS_OPTIONHANDLER_01_010: [** If `handler` is NULL, OptionHandler_Clone shall fail and return NULL. **]** |
| 75 |
|
| 76 |
**SRS_OPTIONHANDLER_01_003: [** `OptionHandler_Clone` shall allocate memory for the new option handler instance. **]** |
| 77 |
|
| 78 |
**SRS_OPTIONHANDLER_01_004: [** If allocating memory fails, `OptionHandler_Clone` shall return NULL. **]** |
| 79 |
|
| 80 |
**SRS_OPTIONHANDLER_01_005: [** `OptionHandler_Clone` shall iterate through all the options stored by the option handler to be cloned by using VECTOR's iteration mechanism. **]** |
| 81 |
|
| 82 |
**SRS_OPTIONHANDLER_01_006: [** For each option the option name shall be cloned by calling `mallocAndStrcpy_s`. **]** |
| 83 |
|
| 84 |
**SRS_OPTIONHANDLER_01_007: [** For each option the value shall be cloned by using the cloning function associated with the source option handler `handler`. **]** |
| 85 |
|
| 86 |
**SRS_OPTIONHANDLER_01_008: [** If cloning one of the option names fails, `OptionHandler_Clone` shall return NULL. **]** |
| 87 |
|
| 88 |
**SRS_OPTIONHANDLER_01_009: [** If cloning one of the option values fails, `OptionHandler_Clone` shall return NULL. **]** |
| 89 |
|
| 90 |
**SRS_OPTIONHANDLER_01_011: [** When adding one of the newly cloned options to the option handler storage vector fails, `OptionHandler_Clone` shall return NULL. **]** |
| 91 |
|
| 92 |
### OptionHandler_AddOption |
| 93 |
```c |
| 94 |
OPTIONHANDLER_RESULT OptionHandler_AddOption(OPTIONHANDLER_HANDLE handle, const char* name, void* value) |
| 95 |
``` |
| 96 |
|
| 97 |
**SRS_OPTIONHANDLER_02_005: [** `OptionHandler_AddOption` shall fail and return `OPTIONHANDLER_INVALIDARG` if any parameter is NULL. **]** |
| 98 |
|
| 99 |
**SRS_OPTIONHANDLER_02_006: [** OptionHandler_AddOption shall call `pfCloneOption` passing `name` and `value`. **]** |
| 100 |
|
| 101 |
**SRS_OPTIONHANDLER_02_007: [** OptionHandler_AddOption shall use `VECTOR` APIs to save the `name` and the newly created clone of `value`. **]** |
| 102 |
|
| 103 |
**SRS_OPTIONHANDLER_02_008: [** If all the operations succed then `OptionHandler_AddOption` shall succeed and return `OPTIONHANDLER_OK`. **]** |
| 104 |
|
| 105 |
**SRS_OPTIONHANDLER_02_009: [** Otherwise, `OptionHandler_AddOption` shall succeed and return `OPTIONHANDLER_ERROR`. **]** |
| 106 |
|
| 107 |
### OptionHandler_FeedOptions |
| 108 |
```c |
| 109 |
OPTIONHANDLER_RESULT OptionHandler_FeedOptions(OPTIONHANDLER_HANDLE handle, void* destinationHandle); |
| 110 |
``` |
| 111 |
|
| 112 |
**SRS_OPTIONHANDLER_02_010: [** `OptionHandler_FeedOptions` shall fail and return `OPTIONHANDLER_INVALIDARG` if any argument is `NULL`. **]** |
| 113 |
|
| 114 |
**SRS_OPTIONHANDLER_02_011: [** Otherwise, `OptionHandler_FeedOptions` shall use `VECTOR`'s iteration mechanisms to retrieve pairs of name, value (`const char*` and `void*`). **]** |
| 115 |
|
| 116 |
**SRS_OPTIONHANDLER_02_012: [** `OptionHandler_FeedOptions` shall call for every pair of name,value `setOption` passing `destinationHandle`, name and value. **]** |
| 117 |
|
| 118 |
**SRS_OPTIONHANDLER_02_013: [** If all the operations succeed then `OptionHandler_FeedOptions` shall succeed and return `OPTIONHANDLER_OK`. **]** |
| 119 |
|
| 120 |
**SRS_OPTIONHANDLER_02_014: [** Otherwise, `OptionHandler_FeedOptions` shall fail and return `OPTIONHANDLER_ERROR`. **]** |
| 121 |
|
| 122 |
### OptionHandler_Destroy |
| 123 |
```c |
| 124 |
void OptionHandler_Destroy(OPTIONHANDLER_HANDLE handle) |
| 125 |
``` |
| 126 |
**SRS_OPTIONHANDLER_02_015: [** OptionHandler_Destroy shall do nothing if parameter `handle` is `NULL`. **]** |
| 127 |
|
| 128 |
**SRS_OPTIONHANDLER_02_016: [** Otherwise, OptionHandler_Destroy shall free all used resources. **]** |