libhci

[Iain Hibbert]

On Thu, 5 Mar 2009, Maksim Yevmenkin wrote:
>  [v2]

seems fine, some documentation comments

+The
+.Fn bt_devenum
+function enumerates up to
+.Dv HCI_DEVMAX
+Bluetooth devices present in the system.

This should not be in the function API but in a CAVEATS or BUGS section as
its implementation dependent :)

+The
+.Fn bt_devenum
+uses the same socket for the duration of enumeration.

Likewise I don't think this should be part of the specification as some
implementations might not be able to reuse the socket. Perhaps just say
that the socket handle provided will only be valid during the callback to
make sure that the callback doesn't store it? (can put it in CAVEATS
section that it is reused if you like?)

+The function guarantees that the socket,
+passed to the callback function,
+will be bound and connected to the Bluetooth device being enumerated.
+The function returns number of successfully enumerated devices,
+otherwise -1.

can we say 'or -1 if an error occurred', as I think it could be valid to
successfully enumerate 0 devices..?

+#define	HCI_DEVFEATURES_SIZE		NG_HCI_FEATURES_SIZE

when I ported the include files I just chopped off the NG_, is there
any gain in having another definition?

+	uint32_t	state;

I guess state is impementation dependent? (some kind of device flags not
mentioned here?)

+	uint8_t		_padding[20];	/* make it 128 bytes in size */

that comment shoud be 'leave space for future additions' rather than
specifying the size as some platforms won't actually be that size anyway..

regards,
iain