libsmbclient for Samba4: initial design issues

[tridge at samba.org]

Derrell,

 >  - Provide the full capability of the "raw" interface in Samba4.

yep, this is important. The obvious way to do that is to allow callers
to make direct calls into the libcli/raw/ functions, mixing this with
whatever higher level calls you want to offer. 

 >  - Add a layer on top of the "raw" interface that provides "simpler" usage
 >    than the "raw" interface provides.  This layer will be along the lines of
 >    the current Samba4 libcli/* functions, which use a "typical" set of
 >    parameters to each of the functions to make them easier to use.  A mix of
 >    these higher-level functions and the "raw" functions will work.

sounds good

 >  - Allow for an asynchronous interface with event notification.

I think it would be reasonable to say that if the caller wants async
calls, then they should call the 'raw' interface. 

If you do want to expose the async nature of the library in the higher
level calls then I think it would be best to follow the existing
_send()/_recv() convention. Otherwise mixing the two layers will get
very confusing.

 > I'd like to see all public symbols be given a module descriptor of "smb_".
 > BlockSignals() would then become smb_BlockSignals(); cli_credentials_init()
 > would become smb_cli_credentials_init(), etc.

I don't mind BlockSignals() being changed so being something like
sys_block_signals(), but I wouldn't like cli_credentials_init() to be
changed. The problem with smb_cli_credentials_init() is that it has 3
levels of prefix, which is just too many!

smb -> we're in samba
cli -> we're in the samba client lib
credentials -> we're in the credentials subsystem
init -> yeah, we are actually going to do something in this cave we've dug

already 'cli_credentials' is quite sufficient as a qualifier, please
don't go down the track of want us to specify every level. That just
discourages modularity, as when you split up a subsystem into two
pieces you then add another level of prefix to every call, and
eventually your function names don't fit on a line of code.

 > if I understand how it's used, would become
 > SMB_auth_anonymous_server_info() because it is intended for use
 > only within the Samba core itself and not by external callers.

sorry, I don't like this. It's taking prefixing beyond the bounds of
being reasonable. C does not provide perfect protection in its name
space, and having n+1 levels of prefix instead of n doesn't change
that, but it does annoy programmers. I don't mind 2 levels, but any
more is getting silly.

Cheers, Tridge