Debian Codegraph @

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

raw
1
2 # umockcallrecorder requirements
3
4 # Overview
5
6 umockcallrecorder is a module that implements recording the expected and actual calls.
7
8 # Exposed API
9
10 ```c
11 typedef struct UMOCKCALLRECORDER_TAG* UMOCKCALLRECORDER_HANDLE;
12
13 UMOCKCALLRECORDER_HANDLE umockcallrecorder_create(void);
14 void umockcallrecorder_destroy(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
15 int umockcallrecorder_reset_all_calls(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
16 int umockcallrecorder_add_expected_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder, UMOCKCALL_HANDLE mock_call);
17 int umockcallrecorder_add_actual_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder, UMOCKCALL_HANDLE mock_call, UMOCKCALL_HANDLE* matched_call);
18 const char* umockcallrecorder_get_actual_calls(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
19 const char* umockcallrecorder_get_expected_calls(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
20 UMOCKCALL_HANDLE umockcallrecorder_get_last_expected_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
21 UMOCKCALLRECORDER_HANDLE umockcallrecorder_clone(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
22 int umockcallrecorder_get_expected_call_count(UMOCKCALLRECORDER_HANDLE umock_call_recorder, size_t* expected_call_count);
23 int umockcallrecorder_fail_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder, size_t index);
24 int umockcallrecorder_can_call_fail(UMOCKCALLRECORDER_HANDLE umock_call_recorder, size_t index, int* can_call_fail);
25 ```
26
27 ## umockcallrecorder_create
28
29 ```c
30 UMOCKCALLRECORDER_HANDLE umockcallrecorder_create(void);
31 ```
32
33 **SRS_UMOCKCALLRECORDER_01_001: [** umockcallrecorder_create shall create a new instance of a call recorder and return a non-NULL handle to it on success. **]**
34
35 **SRS_UMOCKCALLRECORDER_01_002: [** If allocating memory for the call recorder fails, umockcallrecorder_create shall return NULL. **]**
36
37 ## umockcallrecorder_destroy
38
39 ```c
40 void umockcallrecorder_destroy(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
41 ```
42
43 **SRS_UMOCKCALLRECORDER_01_003: [** umockcallrecorder_destroy shall free the resources associated with a the call recorder identified by the umock_call_recorder argument. **]**
44
45 **SRS_UMOCKCALLRECORDER_01_004: [** If umock_call_recorder is NULL, umockcallrecorder_destroy shall do nothing. **]**
46
47 ## umockcallrecorder_reset_all_calls
48
49 ```c
50 int umockcallrecorder_reset_all_calls(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
51 ```
52
53 **SRS_UMOCKCALLRECORDER_01_005: [** umockcallrecorder_reset_all_calls shall free all the expected and actual calls for the call recorder identified by umock_call_recorder. **]**
54
55 **SRS_UMOCKCALLRECORDER_01_006: [** On success umockcallrecorder_reset_all_calls shall return 0. **]**
56
57 **SRS_UMOCKCALLRECORDER_01_007: [** If umock_call_recorder is NULL, umockcallrecorder_reset_all_calls shall fail and return a non-zero value. **]**
58
59 ## umockcallrecorder_add_expected_call
60
61 ```c
62 int umockcallrecorder_add_expected_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder, UMOCKCALL_HANDLE mock_call);
63 ```
64
65 **SRS_UMOCKCALLRECORDER_01_008: [** umockcallrecorder_add_expected_call shall add the mock_call call to the expected call list maintained by the call recorder identified by umock_call_recorder. **]**
66
67 **SRS_UMOCKCALLRECORDER_01_009: [** On success umockcallrecorder_add_expected_call shall return 0. **]**
68
69 **SRS_UMOCKCALLRECORDER_01_012: [** If any of the arguments is NULL, umockcallrecorder_add_expected_call shall fail and return a non-zero value. **]**
70
71 **SRS_UMOCKCALLRECORDER_01_013: [** If allocating memory for the expected calls fails, umockcallrecorder_add_expected_call shall fail and return a non-zero value. **]**
72
73 ## umockcallrecorder_add_actual_call
74
75 ```c
76 int umockcallrecorder_add_actual_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder, UMOCKCALL_HANDLE mock_call, UMOCKCALL_HANDLE* matched_call);
77 ```
78
79 **SRS_UMOCKCALLRECORDER_01_014: [** umockcallrecorder_add_actual_call shall check whether the call mock_call matches any of the expected calls maintained by umock_call_recorder. **]**
80
81 **SRS_UMOCKCALLRECORDER_01_015: [** If the call does not match any of the expected calls, then umockcallrecorder_add_actual_call shall add the mock_call call to the actual call list maintained by umock_call_recorder. **]**
82
83 **SRS_UMOCKCALLRECORDER_01_016: [** If the call matches one of the expected calls, a handle to the matched call shall be filled into the matched_call argument. **]**
84
85 **SRS_UMOCKCALLRECORDER_01_017: [** Comparing the calls shall be done by calling umockcall_are_equal. **]**
86
87 **SRS_UMOCKCALLRECORDER_01_018: [** When no error is encountered, umockcallrecorder_add_actual_call shall return 0. **]**
88
89 **SRS_UMOCKCALLRECORDER_01_019: [** If any of the arguments is NULL, umockcallrecorder_add_actual_call shall fail and return a non-zero value. **]**
90
91 **SRS_UMOCKCALLRECORDER_01_020: [** If allocating memory for the actual calls fails, umockcallrecorder_add_actual_call shall fail and return a non-zero value. **]**
92
93 **SRS_UMOCKCALLRECORDER_01_021: [** If umockcall_are_equal fails, umockcallrecorder_add_actual_call shall fail and return a non-zero value. **]**
94
95 **SRS_UMOCKCALLRECORDER_01_057: [** If any expected call has `ignore_all_calls` set and the actual call is equal to it when comparing the 2 calls, then the call shall be considered matched and not added to the actual calls list. **]**
96
97 **SRS_UMOCKCALLRECORDER_01_058: [** If getting `ignore_all_calls` by calling `umockcall_get_ignore_all_calls` fails, `umockcallrecorder_add_actual_call` shall fail and return a non-zero value. **]**
98
99 ## umockcallrecorder_get_actual_calls
100
101 ```c
102 const char* umockcallrecorder_get_actual_calls(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
103 ```
104
105 **SRS_UMOCKCALLRECORDER_01_022: [** umockcallrecorder_get_actual_calls shall return a pointer to the string representation of all the actual calls. **]**
106
107 **SRS_UMOCKCALLRECORDER_01_023: [** The string for each call shall be obtained by calling umockcall_stringify. **]**
108
109 **SRS_UMOCKCALLRECORDER_01_024: [** If the umock_call_recorder is NULL, umockcallrecorder_get_actual_calls shall fail and return NULL. **]**
110
111 **SRS_UMOCKCALLRECORDER_01_025: [** If umockcall_stringify fails, umockcallrecorder_get_actual_calls shall fail and return NULL. **]**
112
113 **SRS_UMOCKCALLRECORDER_01_026: [** If allocating memory for the resulting string fails, umockcallrecorder_get_actual_calls shall fail and return NULL. **]**
114
115 ## umockcallrecorder_get_expected_calls
116
117 ```c
118 const char* umockcallrecorder_get_expected_calls(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
119 ```
120
121 **SRS_UMOCKCALLRECORDER_01_027: [** umockcallrecorder_get_expected_calls shall return a pointer to the string representation of all the expected calls. **]**
122
123 **SRS_UMOCKCALLRECORDER_01_028: [** The string for each call shall be obtained by calling umockcall_stringify. **]**
124
125 **SRS_UMOCKCALLRECORDER_01_029: [** If the umock_call_recorder is NULL, umockcallrecorder_get_expected_calls shall fail and return NULL. **]**
126
127 **SRS_UMOCKCALLRECORDER_01_030: [** If umockcall_stringify fails, umockcallrecorder_get_expected_calls shall fail and return NULL. **]**
128
129 **SRS_UMOCKCALLRECORDER_01_031: [** If allocating memory for the resulting string fails, umockcallrecorder_get_expected_calls shall fail and return NULL. **]**
130
131 **SRS_UMOCKCALLRECORDER_01_054: [** Calls that have the `ignore_all_calls` property set shall not be reported in the expected call list. **]**
132
133 **SRS_UMOCKCALLRECORDER_01_055: [** Getting the `ignore_all_calls` property shall be done by calling `umockcall_get_ignore_all_calls`. **]**
134
135 **SRS_UMOCKCALLRECORDER_01_056: [** If `umockcall_get_ignore_all_calls` returns a negative value then `umockcallrecorder_get_expected_calls` shall fail and return NULL. **]**
136
137 ## umockcallrecorder_get_last_expected_call
138
139 ```c
140 UMOCKCALL_HANDLE umockcallrecorder_get_last_expected_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
141 ```
142
143 **SRS_UMOCKCALLRECORDER_01_032: [** umockcallrecorder_get_last_expected_call shall return the last expected call for the umock_call_recorder call recorder. **]**
144
145 **SRS_UMOCKCALLRECORDER_01_033: [** If umock_call_recorder is NULL, umockcallrecorder_get_last_expected_call shall fail and return NULL. **]**
146
147 **SRS_UMOCKCALLRECORDER_01_034: [** If no expected call has been recorded for umock_call_recorder then umockcallrecorder_get_last_expected_call shall fail and return NULL. **]**
148
149 ## umockcallrecorder_clone
150
151 ```c
152 UMOCKCALLRECORDER_HANDLE umockcallrecorder_clone(UMOCKCALLRECORDER_HANDLE umock_call_recorder);
153 ```
154
155 **SRS_UMOCKCALLRECORDER_01_035: [** umockcallrecorder_clone shall clone a call recorder and return a handle to the newly cloned call recorder. **]**
156
157 **SRS_UMOCKCALLRECORDER_01_036: [** If the umock_call_recorder argument is NULL, umockcallrecorder_clone shall fail and return NULL. **]**
158
159 **SRS_UMOCKCALLRECORDER_01_037: [** If allocating memory for the new umock call recorder instance fails, umockcallrecorder_clone shall fail and return NULL. **]**
160
161 **SRS_UMOCKCALLRECORDER_01_038: [** umockcallrecorder_clone shall clone all the expected calls. **]**
162
163 **SRS_UMOCKCALLRECORDER_01_039: [** Each expected call shall be cloned by calling umockcall_clone. **]**
164
165 **SRS_UMOCKCALLRECORDER_01_040: [** If cloning an expected call fails, umockcallrecorder_clone shall fail and return NULL. **]**
166
167 **SRS_UMOCKCALLRECORDER_01_041: [** umockcallrecorder_clone shall clone all the actual calls. **]**
168
169 **SRS_UMOCKCALLRECORDER_01_042: [** Each actual call shall be cloned by calling umockcall_clone. **]**
170
171 **SRS_UMOCKCALLRECORDER_01_043: [** If cloning an actual call fails, umockcallrecorder_clone shall fail and return NULL. **]**
172
173 **SRS_UMOCKCALLRECORDER_01_052: [** If allocating memory for the expected calls fails, umockcallrecorder_clone shall fail and return NULL. **]**
174
175 **SRS_UMOCKCALLRECORDER_01_053: [** If allocating memory for the actual calls fails, umockcallrecorder_clone shall fail and return NULL. **]**
176
177 ## umockcallrecorder_get_expected_call_count
178
179 ```c
180 int umockcallrecorder_get_expected_call_count(UMOCKCALLRECORDER_HANDLE umock_call_recorder, size_t* expected_call_count);
181 ```
182
183 **SRS_UMOCKCALLRECORDER_01_044: [** umockcallrecorder_get_expected_call_count shall return in the expected_call_count argument the number of expected calls associated with the call recorder. **]**
184
185 **SRS_UMOCKCALLRECORDER_01_045: [** On success umockcallrecorder_get_expected_call_count shall return 0. **]**
186
187 **SRS_UMOCKCALLRECORDER_01_046: [** If any of the arguments is NULL, umockcallrecorder_get_expected_call_count shall return a non-zero value. **]**
188
189 ## umockcallrecorder_fail_call
190
191 ```c
192 int umockcallrecorder_fail_call(UMOCKCALLRECORDER_HANDLE umock_call_recorder, size_t index);
193 ```
194
195 **SRS_UMOCKCALLRECORDER_01_047: [** umockcallrecorder_fail_call shall mark an expected call as to be failed by calling umockcall_set_fail_call with a 1 value for fail_call. **]**
196
197 **SRS_UMOCKCALLRECORDER_01_048: [** On success, umockcallrecorder_fail_call shall return 0. **]**
198
199 **SRS_UMOCKCALLRECORDER_01_049: [** If umock_call_recorder is NULL, umockcallrecorder_fail_call shall return a non-zero value. **]**
200
201 **SRS_UMOCKCALLRECORDER_01_050: [** If index is invalid, umockcallrecorder_fail_call shall return a non-zero value. **]**
202
203 **SRS_UMOCKCALLRECORDER_01_051: [** If umockcall_set_fail_call fails, umockcallrecorder_fail_call shall return a non-zero value. **]**
204
205
206 ## umockcallrecorder_can_call_fail
207
208 ```c
209 int umockcallrecorder_can_call_fail(UMOCKCALLRECORDER_HANDLE umock_call_recorder, size_t index, int* can_call_fail);
210 ```
211
212
213 **SRS_UMOCKCALLRECORDER_31_056: [** If umock_call_recorder or call_can_fail is NULL, umockcallrecorder_can_call_fail shall return a non-zero value. **]**
214
215 **SRS_UMOCKCALLRECORDER_31_057: [** If index is greater or equal to the current expected calls count, umockcallrecorder_can_call_fail shall return a non-zero value. **]**
216
217 **SRS_UMOCKCALLRECORDER_31_061: [** umockcallrecorder_can_call_fail shall determine whether given call can fail or not by calling umockcall_get_call_can_fail. **]**
218
219 **SRS_UMOCKCALLRECORDER_31_058: [** If umockcall_get_call_can_fail returns -1, umockcallrecorder_can_call_fail shall return an error to the caller **]**
220
221 **SRS_UMOCKCALLRECORDER_31_059: [** umockcallrecorder_can_call_fail shall return in the can_call_fail argument whether the call can fail or not. **]**
222
223 **SRS_UMOCKCALLRECORDER_31_060: [** On success umockcallrecorder_can_call_fail shall return 0. ]*/
224