Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/optionhandler_requirements.md

raw
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. **]**