Q: What is the meaning of `NeedResults`?

[CarstenLeue]

Some methods, e.g. NetworkGetDhcpLeases have a NeedResults parameter of type int32. What is the meaning of this parameter, is this a flag indicating that we need a result list, so I should pass in 1 or is this the number (max?) of results to be expected?

[sihensel]

@CarstenLeue we stumbled over the same question.
NeedResults specifies whether the method should return the actual result list or not and is used as a boolean flag.

This behavior is implemented in libvirt here: https://github.com/libvirt/libvirt/blob/40ebade891a0d2c08e82dac126822d5ee57f4281/src/rpc/gendispatch.pl#L994
If need_results is set (i.e. contains any non-zero value) the result list will be returned, otherwise the return value is NULL.

Furthermore, most methods that fetch data from libvirt take a pointer to a data buffer as input. If the pointer is valid (i.e. not NULL), need_results will be set to 1:
https://github.com/libvirt/libvirt/blob/40ebade891a0d2c08e82dac126822d5ee57f4281/src/rpc/gendispatch.pl#L1729
Sidenote: !! converts any non-zero value to 1 while making sure that 0 remains 0.

This behavior is also documented in the docs, e.g. for virConnectListAllDomains:
https://libvirt.org/html/libvirt-libvirt-domain.html#virConnectListAllDomains
Note the description of the domains parameter:

Pointer to a variable to store the array containing domain objects or NULL if the list is not required (just returns number of guests).

Go-libvirt emulates this behavior and returns an empty list if NeedResults is set to 0, while returning the actual objects if it is set to 1.
This could have been mentioned in the docs here somewhere though.