Debian Codegraph @

src/vendor/azure-uamqp-c/deps/umock-c/devdoc/umock_c_requirements.md

raw
1 # umock_c requirements
2
3 # Overview
4
5 umock_c is a module that exposes the user facing API for umock_c.
6 It exposes a set of macros and APIs that allow:
7 - initializing/deinitializing the library
8 - resetting the calls
9 - getting the expected calls string
10 - getting the actual calls string
11
12 # Exposed API
13
14 ```c
15 typedef enum UMOCK_C_ERROR_CODE_TAG
16 {
17 UMOCK_C_ARG_INDEX_OUT_OF_RANGE,
18 UMOCK_C_MALLOC_ERROR,
19 UMOCK_C_INVALID_ARGUMENT_BUFFER,
20 UMOCK_C_COMPARE_CALL_ERROR,
21 UMOCK_C_RESET_CALLS_ERROR,
22 UMOCK_C_ERROR
23 } UMOCK_C_ERROR_CODE;
24
25 typedef void(*ON_UMOCK_C_ERROR)(UMOCK_C_ERROR_CODE error_code);
26
27 #define IGNORED_PTR_ARG (NULL)
28 #define IGNORED_NUM_ARG (0)
29
30 #define MOCKABLE_FUNCTION(result, function, ...) \
31 ...
32
33 #define REGISTER_GLOBAL_MOCK_HOOK(mock_function, mock_hook_function) \
34 ...
35
36 #define REGISTER_GLOBAL_MOCK_RETURN(mock_function, return_value) \
37 ...
38
39 #define REGISTER_GLOBAL_MOCK_FAIL_RETURN(mock_function, fail_return_value) \
40 ...
41
42 #define REGISTER_GLOBAL_MOCK_RETURNS(mock_function, return_value, fail_return_value) \
43 ...
44
45 #define STRICT_EXPECTED_CALL(call) \
46 ...
47
48 #define EXPECTED_CALL(call) \
49 ...
50
51 #define DECLARE_UMOCK_POINTER_TYPE_FOR_TYPE(value_type, alias) \
52 ...
53
54 #define REGISTER_UMOCK_VALUE_TYPE(value_type, stringify_func, are_equal_func, copy_func, free_func) \
55 ...
56
57 int umock_c_init(ON_UMOCK_C_ERROR on_umock_c_error);
58 void umock_c_deinit(void);
59 void umock_c_reset_all_calls(void);
60 const char* umock_c_get_actual_calls(void);
61 const char* umock_c_get_expected_calls(void);
62 UMOCKCALL_HANDLE umock_c_get_last_expected_call(void);
63 int umock_c_add_expected_call(UMOCKCALL_HANDLE mock_call);
64 int umock_c_add_actual_call(UMOCKCALL_HANDLE mock_call, UMOCKCALL_HANDLE* matched_call);
65 UMOCKCALLRECORDER_HANDLE umock_c_get_call_recorder(void);
66 int umock_c_set_call_recorder(UMOCKCALLRECORDER_HANDLE call_recorder);
67 ```
68
69 ## umock_c_init
70
71 ```c
72 int umock_c_init(ON_UMOCK_C_ERROR on_umock_c_error);
73 ```
74
75 **SRS_UMOCK_C_01_001: [** umock_c_init shall initialize the umock library. **]**
76
77 **SRS_UMOCK_C_01_023: [** umock_c_init shall initialize the umock types by calling umocktypes_init. **]**
78
79 **SRS_UMOCK_C_01_002: [** umock_c_init shall register the C naive types by calling umocktypes_c_register_types. **]**
80
81 **SRS_UMOCK_C_01_003: [** umock_c_init shall create a call recorder by calling umockcallrecorder_create. **]**
82
83 **SRS_UMOCK_C_01_004: [** On success, umock_c_init shall return 0. **]**
84
85 **SRS_UMOCK_C_01_005: [** If any of the calls fails, umock_c_init shall fail and return a non-zero value. **]**
86
87 **SRS_UMOCK_C_01_006: [** The on_umock_c_error callback shall be stored to be used for later error callbacks. **]**
88
89 **SRS_UMOCK_C_01_007: [** umock_c_init when umock is already initialized shall fail and return a non-zero value. **]**
90
91 **SRS_UMOCK_C_01_024: [** on_umock_c_error shall be optional. **]**
92
93 ## umock_c_deinit
94
95 ```c
96 void umock_c_deinit(void);
97 ```
98
99 **SRS_UMOCK_C_01_008: [** umock_c_deinit shall deinitialize the umock types by calling umocktypes_deinit. **]**
100
101 **SRS_UMOCK_C_01_009: [** umock_c_deinit shall free the call recorder created in umock_c_init. **]**
102
103 **SRS_UMOCK_C_01_010: [** If the module is not initialized, umock_c_deinit shall do nothing. **]**
104
105 ## umock_c_reset_all_calls
106
107 ```c
108 void umock_c_reset_all_calls(void);
109 ```
110
111 **SRS_UMOCK_C_01_011: [** umock_c_reset_all_calls shall reset all calls by calling umockcallrecorder_reset_all_calls on the call recorder created in umock_c_init. **]**
112
113 **SRS_UMOCK_C_01_025: [** If the underlying umockcallrecorder_reset_all_calls fails, the on_umock_c_error callback shall be triggered with UMOCK_C_RESET_CALLS_ERROR. **]**
114
115 **SRS_UMOCK_C_01_012: [** If the module is not initialized, umock_c_reset_all_calls shall do nothing. **]**
116
117 ## umock_c_get_actual_calls
118
119 ```c
120 const char* umock_c_get_actual_calls(void);
121 ```
122
123 **SRS_UMOCK_C_01_013: [** umock_c_get_actual_calls shall return the string for the recorded actual calls by calling umockcallrecorder_get_actual_calls on the call recorder created in umock_c_init. **]**
124
125 **SRS_UMOCK_C_01_014: [** If the module is not initialized, umock_c_get_actual_calls shall return NULL. **]**
126
127 ## umock_c_get_expected_calls
128
129 ```c
130 const char* umock_c_get_expected_calls(void);
131 ```
132
133 **SRS_UMOCK_C_01_015: [** umock_c_get_expected_calls shall return the string for the recorded expected calls by calling umockcallrecorder_get_expected_calls on the call recorder created in umock_c_init. **]**
134
135 **SRS_UMOCK_C_01_016: [** If the module is not initialized, umock_c_get_expected_calls shall return NULL. **]**
136
137 ## umock_c_get_last_expected_call
138
139 ```c
140 UMOCKCALL_HANDLE umock_c_get_last_expected_call(void);
141 ```
142
143 **SRS_UMOCK_C_01_017: [** umock_c_get_last_expected_call shall return the last expected call by calling umockcallrecorder_get_last_expected_call on the call recorder created in umock_c_init. **]**
144
145 **SRS_UMOCK_C_01_018: [** If the module is not initialized, umock_c_get_last_expected_call shall return NULL. **]**
146
147 ## umock_c_add_expected_call
148
149 ```c
150 int umock_c_add_expected_call(UMOCKCALL_HANDLE mock_call);
151 ```
152
153 **SRS_UMOCK_C_01_019: [** umock_c_add_expected_call shall add an expected call by calling umockcallrecorder_add_expected_call on the call recorder created in umock_c_init. **]**
154
155 **SRS_UMOCK_C_01_020: [** If the module is not initialized, umock_c_add_expected_call shall return a non-zero value. **]**
156
157 ## umock_c_add_actual_call
158
159 ```c
160 int umock_c_add_actual_call(UMOCKCALL_HANDLE mock_call, UMOCKCALL_HANDLE* matched_call);
161 ```
162
163 **SRS_UMOCK_C_01_021: [** umock_c_add_actual_call shall add an actual call by calling umockcallrecorder_add_actual_call on the call recorder created in umock_c_init. **]**
164
165 **SRS_UMOCK_C_01_022: [** If the module is not initialized, umock_c_add_actual_call shall return a non-zero value. **]**
166
167 ## umock_c_get_call_recorder
168
169 ```c
170 UMOCKCALLRECORDER_HANDLE umock_c_get_call_recorder(void);
171 ```
172
173 **SRS_UMOCK_C_01_026: [** umock_c_get_call_recorder shall return the handle to the currently used call recorder. **]**
174
175 **SRS_UMOCK_C_01_027: [** If the module is not initialized, umock_c_get_call_recorder shall return NULL. **]**
176
177 ## umock_c_set_call_recorder
178
179 ```c
180 int umock_c_set_call_recorder(UMOCKCALLRECORDER_HANDLE call_recorder);
181 ```
182
183 **SRS_UMOCK_C_01_028: [** umock_c_set_call_recorder shall replace the currently used call recorder with the one identified by the call_recorder argument. **]**
184
185 **SRS_UMOCK_C_01_029: [** On success, umock_c_set_call_recorder shall return 0. **]**
186
187 **SRS_UMOCK_C_01_030: [** If call_recorder is NULL, umock_c_set_call_recorder shall return a non-zero value. **]**
188
189 **SRS_UMOCK_C_01_031: [** umock_c_set_call_recorder shall make a copy of call_recorder by calling umockcallrecorder_clone and use the copy for future actions. **]**
190
191 **SRS_UMOCK_C_01_032: [** If umockcallrecorder_clone fails, umock_c_set_call_recorder shall return a non-zero value. **]**
192
193 **SRS_UMOCK_C_01_033: [** If the module is not initialized, umock_c_set_call_recorder shall return a non-zero value. **]**
194
195 **SRS_UMOCK_C_01_034: [** The previously used call recorder shall be destroyed by calling umockcallrecorder_destroy. **]**