Debian Codegraph @

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

raw
1 # umockcall requirements
2
3 # Overview
4
5 umockcall is a module that encapsulates a umock call.
6
7 # Exposed API
8
9 ```c
10 typedef struct UMOCKCALL_TAG* UMOCKCALL_HANDLE;
11 typedef void*(*UMOCKCALL_DATA_COPY_FUNC)(void* umockcall_data);
12 typedef void(*UMOCKCALL_DATA_FREE_FUNC)(void* umockcall_data);
13 typedef char*(*UMOCKCALL_DATA_STRINGIFY_FUNC)(void* umockcall_data);
14 typedef int(*UMOCKCALL_DATA_ARE_EQUAL_FUNC)(void* left, void* right);
15
16 UMOCKCALL_HANDLE umockcall_create(const char* function_name, void* umockcall_data, UMOCKCALL_DATA_COPY_FUNC umockcall_data_copy, UMOCKCALL_DATA_FREE_FUNC umockcall_data_free, UMOCKCALL_DATA_STRINGIFY_FUNC umockcall_data_stringify, UMOCKCALL_DATA_ARE_EQUAL_FUNC umockcall_data_are_equal);
17 void umockcall_destroy(UMOCKCALL_HANDLE umockcall);
18 int umockcall_are_equal(UMOCKCALL_HANDLE left, UMOCKCALL_HANDLE right);
19 char* umockcall_stringify(UMOCKCALL_HANDLE umockcall);
20 void* umockcall_get_call_data(UMOCKCALL_HANDLE umockcall);
21 UMOCKCALL_HANDLE umockcall_clone(UMOCKCALL_HANDLE umockcall);
22 int umockcall_set_fail_call(UMOCKCALL_HANDLE umockcall, int fail_call);
23 int umockcall_get_fail_call(UMOCKCALL_HANDLE umockcall);
24 int umockcall_set_ignore_all_calls(UMOCKCALL_HANDLE umockcall, int ignore_all_calls);
25 int umockcall_get_ignore_all_calls(UMOCKCALL_HANDLE umockcall);
26 int umockcall_set_call_can_fail(UMOCKCALL_HANDLE umockcall, int call_can_fail);
27 int umockcall_get_call_can_fail(UMOCKCALL_HANDLE umockcall);
28 ```
29
30 ## umockcall_create
31
32 ```c
33 UMOCKCALL_HANDLE umockcall_create(const char* function_name, void* umockcall_data, UMOCKCALL_DATA_COPY_FUNC umockcall_data_copy, UMOCKCALL_DATA_FREE_FUNC umockcall_data_free, UMOCKCALL_DATA_STRINGIFY_FUNC umockcall_data_stringify, UMOCKCALL_DATA_ARE_EQUAL_FUNC umockcall_data_are_equal);
34 ```
35
36 **SRS_UMOCKCALL_01_001: [** umockcall_create shall create a new instance of a umock call and on success it shall return a non-NULL handle to it. **]**
37
38 **SRS_UMOCKCALL_01_002: [** If allocating memory for the umock call instance fails, umockcall_create shall return NULL. **]**
39
40 **SRS_UMOCKCALL_01_003: [** If any of the arguments are NULL, umockcall_create shall fail and return NULL. **]**
41
42 ## umockcall_destroy
43
44 ```c
45 void umockcall_destroy(UMOCKCALL_HANDLE umockcall);
46 ```
47
48 **SRS_UMOCKCALL_01_004: [** umockcall_destroy shall free a previously allocated umock call instance. **]**
49
50 **SRS_UMOCKCALL_01_005: [** If the umockcall argument is NULL then umockcall_destroy shall do nothing. **]**
51
52 ## umockcall_are_equal
53
54 ```c
55 int umockcall_are_equal(UMOCKCALL_HANDLE left, UMOCKCALL_HANDLE right);
56 ```
57
58 **SRS_UMOCKCALL_01_006: [** umockcall_are_equal shall compare the two mock calls and return whether they are equal or not. **]**
59
60 **SRS_UMOCKCALL_01_024: [** If both left and right pointers are equal, umockcall_are_equal shall return 1. **]**
61
62 **SRS_UMOCKCALL_01_015: [** If only one of the left or right arguments are NULL, umockcall_are_equal shall return 0. **]**
63
64 **SRS_UMOCKCALL_01_025: [** If the function name does not match for the 2 calls, umockcall_are_equal shall return 0. **]**
65
66 **SRS_UMOCKCALL_01_026: [** The call data shall be evaluated by calling the umockcall_data_are_equal function passed in umockcall_create while passing as arguments the umockcall_data associated with each call handle. **]**
67
68 **SRS_UMOCKCALL_01_027: [** If the underlying umockcall_data_are_equal returns 1, then umockcall_are_equal shall return 1. **]**
69
70 **SRS_UMOCKCALL_01_028: [** If the underlying umockcall_data_are_equal returns 0, then umockcall_are_equal shall return 0. **]**
71
72 **SRS_UMOCKCALL_01_029: [** If the underlying umockcall_data_are_equal fails (returns anything else than 0 or 1), then umockcall_are_equal shall fail and return -1. **]**
73
74 **SRS_UMOCKCALL_01_014: [** If the two calls have different are_equal functions that have been passed to umockcall_create then the calls shall be considered different and 0 shall be returned. **]**
75
76 ## umockcall_to_string
77
78 ```c
79 char* umockcall_stringify(UMOCKCALL_HANDLE umockcall);
80 ```
81
82 **SRS_UMOCKCALL_01_016: [** umockcall_stringify shall return a string representation of the mock call in the form `"[function_name(arguments)]"`. **]**
83
84 **SRS_UMOCKCALL_01_018: [** The returned string shall be a newly allocated string and it is to be freed by the caller. **]**
85
86 **SRS_UMOCKCALL_01_017: [** If the umockcall argument is NULL, umockcall_stringify shall return NULL. **]**
87
88 **SRS_UMOCKCALL_01_019: [** To obtain the arguments string, umockcall_stringify shall call the umockcall_data_stringify function passed to umockcall_create and pass to it the umockcall_data pointer (also given in umockcall_create). **]**
89
90 **SRS_UMOCKCALL_01_030: [** umockcall_stringify shall free the string obtained from umockcall_data_stringify. **]**
91
92 **SRS_UMOCKCALL_01_020: [** If the underlying umockcall_data_stringify call fails, umockcall_stringify shall fail and return NULL. **]**
93
94 **SRS_UMOCKCALL_01_021: [** If not enough memory can be allocated for the string to be returned, umockcall_stringify shall fail and return NULL. **]**
95
96 ## umockcall_get_call_data
97
98 ```c
99 void* umockcall_get_call_data(UMOCKCALL_HANDLE umockcall);
100 ```
101
102 **SRS_UMOCKCALL_01_022: [** umockcall_get_call_data shall return the associated umock call data that was passed to umockcall_create. **]**
103
104 **SRS_UMOCKCALL_01_023: [** If umockcall is NULL, umockcall_get_call_data shall return NULL. **]**
105
106 ## umockcall_clone
107
108 ```c
109 UMOCKCALL_HANDLE umockcall_clone(UMOCKCALL_HANDLE umockcall);
110 ```
111
112 **SRS_UMOCKCALL_01_031: [** umockcall_clone shall clone a umock call and on success it shall return a handle to the newly cloned call. **]**
113
114 **SRS_UMOCKCALL_01_032: [** If umockcall is NULL, umockcall_clone shall return NULL. **]**
115
116 **SRS_UMOCKCALL_01_033: [** The call data shall be cloned by calling the umockcall_data_copy function passed in umockcall_create and passing as argument the umockcall_data value passed in umockcall_create. **]**
117
118 **SRS_UMOCKCALL_01_043: [** If allocating memory for the new umock call fails, umockcall_clone shall return NULL. **]**
119
120 **SRS_UMOCKCALL_01_034: [** If umockcall_data_copy fails then umockcall_clone shall return NULL. **]**
121
122 **SRS_UMOCKCALL_01_035: [** umockcall_clone shall copy also the function name. **]**
123
124 **SRS_UMOCKCALL_01_036: [** If allocating memory for the function name fails, umockcall_clone shall return NULL. **]**
125
126 **SRS_UMOCKCALL_01_037: [** umockcall_clone shall also copy all the functions passed to umockcall_create (umockcall_data_copy, umockcall_data_free, umockcall_data_are_equal, umockcall_data_stringify). **]**
127
128 ## umockcall_set_fail_call
129
130 ```c
131 int umockcall_set_fail_call(UMOCKCALL_HANDLE umockcall, int fail_call);
132 ```
133
134 **SRS_UMOCKCALL_01_038: [** umockcall_set_fail_call shall store the fail_call value, associating it with the umockcall call instance. **]**
135
136 **SRS_UMOCKCALL_01_044: [** On success umockcall_set_fail_call shall return 0. **]**
137
138 **SRS_UMOCKCALL_01_039: [** If umockcall is NULL, umockcall_set_fail_call shall return a non-zero value. **]**
139
140 **SRS_UMOCKCALL_01_040: [** If a value different than 0 and 1 is passed as fail_call, umockcall_set_fail_call shall return a non-zero value. **]**
141
142 ```c
143 int umockcall_get_fail_call(UMOCKCALL_HANDLE umockcall);
144 ```
145
146 **SRS_UMOCKCALL_01_041: [** umockcall_get_fail_call shall retrieve the fail_call value, associated with the umockcall call instance. **]**
147
148 **SRS_UMOCKCALL_01_042: [** If umockcall is NULL, umockcall_get_fail_call shall return -1. **]**
149
150 ## umockcall_set_fail_call
151
152 ```c
153 int umockcall_set_ignore_all_calls(UMOCKCALL_HANDLE umockcall, int ignore_all_calls);
154 ```
155
156 **SRS_UMOCKCALL_01_045: [** umockcall_set_ignore_all_calls shall store the ignore_all_calls value, associating it with the umockcall call instance. **]**
157
158 **SRS_UMOCKCALL_01_046: [** On success umockcall_set_ignore_all_calls shall return 0. **]**
159
160 **SRS_UMOCKCALL_01_047: [** If umockcall is NULL, umockcall_set_ignore_all_calls shall return a non-zero value. **]**
161
162 **SRS_UMOCKCALL_01_048: [** If a value different than 0 and 1 is passed as ignore_all_calls, umockcall_set_ignore_all_calls shall return a non-zero value. **]**
163
164 ```c
165 int umockcall_get_ignore_all_calls(UMOCKCALL_HANDLE umockcall);
166 ```
167
168 **SRS_UMOCKCALL_01_049: [** umockcall_get_ignore_all_calls shall retrieve the ignore_all_calls value, associated with the umockcall call instance. **]**
169
170 **SRS_UMOCKCALL_01_050: [** If umockcall is NULL, umockcall_get_ignore_all_calls shall return -1. **]**
171
172 ## umockcall_set_call_can_fail
173
174 ```c
175 int umockcall_set_call_can_fail(UMOCKCALL_HANDLE umockcall, int call_can_fail);
176 ```
177
178 **SRS_UMOCKCALL_31_051: [** If umockcall is NULL, umockcall_set_call_can_fail shall return -1. **]**
179
180 **SRS_UMOCKCALL_31_052: [** If a value different than 0 and 1 is passed as umockcall_set_call_can_fail, umockcall_set_call_can_fail shall return -1. **]**
181
182 **SRS_UMOCKCALL_31_053: [** umockcall_set_call_can_fail shall store the call_can_fail value, associating it with the umockcall call instance. **]**
183
184
185
186 ## umockcall_get_call_can_fail
187
188 ```c
189 int umockcall_get_call_can_fail(UMOCKCALL_HANDLE umockcall);
190 ```
191
192
193 **SRS_UMOCKCALL_31_054: [** If umockcall is NULL, umockcall_get_call_can_fail shall return -1. **]**
194
195 **SRS_UMOCKCALL_31_055: [** umockcall_get_call_can_fail shall retrieve the call_can_fail value, associated with the umockcall call instance. **]**
196
197
198
199
200