getInstancesWithInfo

Edit online

Retrieves the list of instances available in the SCM and the metadata associated with those instances. This is an optional function. The RAM should implement this function if the SCM provides the metadata with the list of instances. The RAM is required to implement getInstances even if getInstancesWithInfo is implemented.

int getInstancesWithInfo(DescriptorWithInfo** records, 
                 int* numRecords, void** params, void*** customReturn, 
                 char filter[256], char error[256])

Variable	Function	Description
`DescriptorWithInfo** records`	Output	This should be allocated and filled with the IDs and names of the available instances. For each instance, the metadata information should be allocated and filled.
`int* numRecords`	Output	The number of records that have been allocated and returned.
`void** params`	Input	Pointer to an array of custom parameters (see Handling custom parameters and return values).
`void*** customReturn`	Output	Used to reference an array of custom return values (see Handling custom parameters and return values).
`char filter[256]`	Input	This can be passed from the client to filter out sets of instances.
`char error[256]`	Output	If an error occurs, this should be filled with a description of the error.

Operation:

Query the SCM for its list of instances and metadata, possibly applying a filter.

Allocate the records array. If developing a RAM in C, use the following code:

*records = (DescriptorWithInfo*) 
                      malloc(sizeof(DescriptorWithInfo) * *numRecords);

For each record in the array, do the following:
1. Fill the id and name of the instance
2. Set the infoCount to the number of metadata key-value pairs associated with that instance.
3. Allocate the info array. If developing a RAM in C, use the following code, where i is the zero-based index of the instance you are working with:
```
(*records)[i].info = (KeyValPair *) 
									malloc(sizeof(KeyValPair) * (*records)[i].infocount);
```
4. Fill in the info array with the metadata key-value pairs for the instance.

If it is not possible to query the SCM for instances, it may be useful to have the client pass in a list of known instances using the filter buffer. The RAM should then check the list and return the instances in the records array. The instances can be hard-coded if they are constant for the SCM.

Note: If the getInstancesWithInfo function requires custom parameters or custom returns, set up the function to use the same custom parameters and custom returns as the getInstances function. This allows the CARMA client to call the appropriate function with no additional input from the user.