GSocketAddressEnumerator documentation is inconsistent with existing usage
In c3fbfbd2 we added new documentation to GSocketAddressEnumerator:
* Each #GSocketAddressEnumerator can only be enumerated once. Once * g_socket_address_enumerator_next() has returned %NULL (and no error), further * enumeration with that #GSocketAddressEnumerator is not possible, and it can * be unreffed.
This implies that if g_socket_address_enumerator_next() returns NULL with an error, the caller should continue iteration until it returns NULL with no error, indicating that there are no more addresses to enumerate. I've been looking this over and it makes sense to me. I think this new documentation is correct.
Problem is, our existing code doesn't do this. Look at existing users:
- g_network_monitor_base_can_reach() gives up the first time it doesn't receive an address, without checking the error, and does not continue the enumeration.
- Ditto for GSocketClient, in both the sync and async codepaths.
- GSocketConnectable doesn't call this code, but it includes a documentation example demonstrating use of GSocketAddressEnumerator stopping on the first error rather than completing the enumeration.
- Usage in GNetworkService and GProxyAddressEnumerator looks OK. These are GSocketAddressEnumerator implementations that internally use another GSocketAddressEnumerator (a GNetworkAddressAddressEnumerator).
So, if I'm correct, we should change GNetworkMonitor and GSocketClient to finish the enumeration instead of giving up after the first error, and we should change the documentation of GSocketConnectable as well. (Or, if I'm not correct, we should change the documentation of GSocketAddressEnumerator to indicate that the caller should give up after the first error.)
BTW, to check what it's actually doing, GLib's primary implementation of GSocketAddressEnumerator is GNetworkAddressAddressEnumerator in gnetworkaddress.c. That's not easy to find if you don't know where it is. The implementation is a little complex, but I think it doesn't return more results after the first error? Honestly I'm not sure.