list_object* json_find_members_value_string	(	list_object *	json_data,
		const char *	member_name,
		const boolean	partial_name,
		const char *	string_value,
		const boolean	partial_value
	)

=================================================================

JSON Support Functions for JSON Parser D-List hierarchical lists.

Please note: All these functions are fully thread / MP safe. ---——— However, it is still the callers responsibility to ensure that multiple threads do not attempt to simultaneously modify and access the same data structures or list_object(s) used by these JSON functions. This should be done by using mutex locks, semaphores, gates, barriers etc, or whatever mechanisms you deem fit.

---

Special Note regarding the scope of these JSON Object Member search functions

These JSON Object Member search functions will find members of JSON Objects and apply the search criteria to the direct member values only. To illustrate exactly what this means, consider the following examples.

Searching for Member name "fred" and value 10. If this member is found it would be returned as a match

{   "bob" : 52,
    "fred" : 10,
    "amy" : [ 15, 25, 42 ], ... } 

as the 10 is the direct value of the Member name we matched against. The following example would also return a match

{   "bob" : 52,
    "fred" : [ 20, 52, 10, "a string value" ],
    "amy" : [ 15, 25, 42 ], ... } 

as the value 10 was found as a direct value of "fred" even though the value is part of an array, that array is semantically a direct value of the member name. In the following example there would be no match made

{   "bob" : 52,
    "fred" : [ 20, [ 52, 10], "a string value" ],
    "amy" : [ 15, 25, 42 ], ... }

as in this case the value 10 is not a direct value of the Member name, but a value of an array which is itself a direct value. This general purpose search tool is limited to finding same level matches of values, and only the caller is going to understand the implied semantics of various obscure JSON data layouts. It would be unreasonable to expect a general purpose search tool to be able to devine the semantics of such layouts or structures.

Please also bear in mind that a match would be made in the following example

{   "bob" : 52,
    "fred" : [ 20, [ { "fred": ["fred's cousin",52,10] } ], "a string" ],
    "amy" : [ 15, 25, 42 ], ... }

but it would be a match on the Member of the JSON Object inside the array (fred's cousin) not the Member at the top level JSON Object. Using the provided search criteria, search the JSON data and locate all object members in the list hierarchy that match the criteria, returning them in a new list_object to the caller.

This function can be called to search only JSON Object Member names, or it can search for Member names and a string value criteria as well. For example, it can search the entire hierarchy for all JSON Object Members with the name "handle" and return a list of all Object Members found. Alternatively it could search for all Object Members with the name "roles" and the value "technical", which would return all the Object Members named "roles" that also has a string value of "technical". The value of course could be a data value in an JSON Array, depending on what the found Object Member had as a data value.

This function may be called with an option to perform partial JSON Object Name and/or string value matches, so for the above example, a partial Object Name match for "role" would return all Object Members including, "role", roles" etc.

Upon return if Object Members were found that matched the search criteria, a list containing elements of the type json_member_list_t would be provided one element in the list for each match found. When the caller has finished with the list, it must erased with list_erase() and then freed.

Parameters

[in]	json_data	A D-List list_object that describes the JSON data to be searched. This can be a root list_object, or it can be any subordinate list_object within that hierarchy. It can be an Array or an Object list. The search is confined to the list(s) covered by this top level list_object.
[in]	member_name	Pointer to a nul terminated string to use as a match against the JSON Object Member names in the JSON data list.
[in]	partial_name	TRUE perform the search using member_name as a partial name match, FALSE perform the search looking only for a complete match with member_name.
[in]	string_value	Optional pointer to a nul terminated string to use as a match against the JSON Object Member values in the JSON data list, that have already matched with member_name, and have the value type of JSON_string. NULL to perform a search for only JSON OObject Member names, and not involving any search of Object Member values.
[in]	partial_value	TRUE perform the search using string_value as a partial string value match, only value if string_value is not NULL. FALSE perform the search looking only for a complete string value match with string_value.

Return values

list_object	contains the JSON Object Members found that matched the search criteria. This list was created with LIST_COPY_DATA option, so element's storage will be managed as described by D-List depending on what functions you use to access or manage this list. list_erase() will release ay internal and element storage remaining when called.
NULL	No JSON Object Members were found that matched the search criteria. No list_object was created.