Debian Codegraph @

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

raw
1 #connectionstringparser requirements
2 ====================================
3
4 ## Overview
5
6 connection_parser is module that parses key/value pairs from a connection string.
7 The format of the connection string is:
8 [key1]=[value1];[key2]=[value2]; ...
9
10 ## Exposed API
11
12 ```c
13 extern MAP_HANDLE connectionstringparser_parse_from_char(const char* connection_string);
14 extern MAP_HANDLE connectionstringparser_parse(STRING_HANDLE connection_string);
15 extern int connectionstringparser_splitHostName_from_char(const char* hostName, STRING_HANDLE nameString, STRING_HANDLE suffixString);
16 extern int connectionstringparser_splitHostName(STRING_HANDLE hostNameString, STRING_HANDLE nameString, STRING_HANDLE suffixString);
17 ```
18
19 ### connectionstringparser_parse
20
21 ```c
22 extern MAP_HANDLE connectionstringparser_parse(STRING_HANDLE connection_string);
23 ```
24
25 **SRS_CONNECTIONSTRINGPARSER_01_001: [** connectionstringparser_parse shall parse all key value pairs from the connection_string passed in as argument and return a new map that holds the key/value pairs. **]**
26
27 **SRS_CONNECTIONSTRINGPARSER_01_018: [** If creating the result map fails, then connectionstringparser_parse shall return NULL. **]**
28
29 **SRS_CONNECTIONSTRINGPARSER_01_002: [** If connection_string is NULL then connectionstringparser_parse shall fail and return NULL. **]**
30
31 **SRS_CONNECTIONSTRINGPARSER_01_003: [** connectionstringparser_parse shall create a STRING tokenizer to be used for parsing the connection string, by calling STRING_TOKENIZER_create. **]**
32
33 **SRS_CONNECTIONSTRINGPARSER_01_015: [** If STRING_TOKENIZER_create fails, connectionstringparser_parse shall fail and return NULL. **]**
34
35 **SRS_CONNECTIONSTRINGPARSER_01_004: [** connectionstringparser_parse shall start scanning at the beginning of the connection string. **]**
36
37 **SRS_CONNECTIONSTRINGPARSER_01_016: [** 2 STRINGs shall be allocated in order to hold the to be parsed key and value tokens. **]**
38
39 **SRS_CONNECTIONSTRINGPARSER_01_017: [** If allocating the STRINGs fails connectionstringparser_parse shall fail and return NULL. **]**
40
41 **SRS_CONNECTIONSTRINGPARSER_01_005: [** The following actions shall be repeated until parsing is complete: **]**
42
43 **SRS_CONNECTIONSTRINGPARSER_01_006: [** connectionstringparser_parse shall find a token (the key of the key/value pair) delimited by the `=` character, by calling STRING_TOKENIZER_get_next_token. **]**
44
45 **SRS_CONNECTIONSTRINGPARSER_01_007: [** If STRING_TOKENIZER_get_next_token fails, parsing shall be considered complete. **]**
46
47 **SRS_CONNECTIONSTRINGPARSER_01_008: [** connectionstringparser_parse shall find a token (the value of the key/value pair) delimited by the `;` character, by calling STRING_TOKENIZER_get_next_token. **]**
48
49 **SRS_CONNECTIONSTRINGPARSER_01_009: [** If STRING_TOKENIZER_get_next_token fails, connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
50
51 **SRS_CONNECTIONSTRINGPARSER_01_010: [** The key and value shall be added to the result map by using Map_Add. **]**
52
53 **SRS_CONNECTIONSTRINGPARSER_01_011: [** The C strings for the key and value shall be extracted from the previously parsed STRINGs by using STRING_c_str. **]**
54
55 **SRS_CONNECTIONSTRINGPARSER_01_019: [** If the key length is zero then connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
56
57 **SRS_CONNECTIONSTRINGPARSER_01_012: [** If Map_Add fails connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
58
59 **SRS_CONNECTIONSTRINGPARSER_01_013: [** If STRING_c_str fails then connectionstringparser_parse shall fail and return NULL (freeing the allocated result map). **]**
60
61 **SRS_CONNECTIONSTRINGPARSER_01_014: [** After the parsing is complete the previously allocated STRINGs and STRING tokenizer shall be freed by calling STRING_TOKENIZER_destroy. **]**
62
63
64 ### connectionstringparser_parse_from_char
65
66 ```c
67 extern MAP_HANDLE connectionstringparser_parse_from_char(const char* connection_string);
68 ```
69
70 **SRS_CONNECTIONSTRINGPARSER_21_020: [** connectionstringparser_parse_from_char shall create a STRING_HANDLE from the connection_string passed in as argument and parse it using the connectionstringparser_parse. **]**
71
72 **SRS_CONNECTIONSTRINGPARSER_21_021: [** If connectionstringparser_parse_from_char get error creating a STRING_HANDLE, it shall return NULL. **]**
73
74
75 ### connectionstringparser_splitHostName_from_char
76
77 ```c
78 extern int connectionstringparser_splitHostName_from_char(const char* hostName, STRING_HANDLE nameString, STRING_HANDLE suffixString);
79 ```
80
81 **SRS_CONNECTIONSTRINGPARSER_21_022: [** connectionstringparser_splitHostName_from_char shall split the provided hostName in name and suffix. **]**
82
83 **SRS_CONNECTIONSTRINGPARSER_21_023: [** connectionstringparser_splitHostName_from_char shall copy all characters, from the beginning of the hostName to the first `.` to the nameString. **]**
84
85 **SRS_CONNECTIONSTRINGPARSER_21_024: [** connectionstringparser_splitHostName_from_char shall copy all characters, from the first `.` to the end of the hostName, to the suffixString. **]**
86
87 **SRS_CONNECTIONSTRINGPARSER_21_025: [** If connectionstringparser_splitHostName_from_char get success splitting the hostName, it shall return 0. **]**
88
89 **SRS_CONNECTIONSTRINGPARSER_21_026: [** If the hostName is NULL, connectionstringparser_splitHostName_from_char shall return MU_FAILURE. **]**
90
91 **SRS_CONNECTIONSTRINGPARSER_21_027: [** If the hostName is an empty string, connectionstringparser_splitHostName_from_char shall return MU_FAILURE. **]**
92
93 **SRS_CONNECTIONSTRINGPARSER_21_028: [** If the nameString is NULL, connectionstringparser_splitHostName_from_char shall return MU_FAILURE. **]**
94
95 **SRS_CONNECTIONSTRINGPARSER_21_029: [** If the suffixString is NULL, connectionstringparser_splitHostName_from_char shall return MU_FAILURE. **]**
96
97 **SRS_CONNECTIONSTRINGPARSER_21_030: [** If the hostName is not a valid host name, connectionstringparser_splitHostName_from_char shall return MU_FAILURE. **]**
98
99 **SRS_CONNECTIONSTRINGPARSER_21_031: [** If connectionstringparser_splitHostName_from_char get error copying the name to the nameString, it shall return MU_FAILURE. **]**
100
101 **SRS_CONNECTIONSTRINGPARSER_21_032: [** If connectionstringparser_splitHostName_from_char get error copying the suffix to the suffixString, it shall return MU_FAILURE. **]**
102
103
104 ### connectionstringparser_splitHostName
105
106 ```c
107 extern int connectionstringparser_splitHostName(STRING_HANDLE hostNameString, STRING_HANDLE nameString, STRING_HANDLE suffixString);
108 ```
109
110 **SRS_CONNECTIONSTRINGPARSER_21_033: [** connectionstringparser_splitHostName shall convert the hostNameString to a connection_string passed in as argument, and call connectionstringparser_splitHostName_from_char. **]**
111
112 **SRS_CONNECTIONSTRINGPARSER_21_034: [** If the hostNameString is NULL, connectionstringparser_splitHostName shall return MU_FAILURE. **]**