Proposal: libsmbclient API

[Andreas Schneider]

On Tuesday 24 March 2009 14:06:38 you wrote:
> Hi Andreas,

Hi Derrell,

> I've reviewed your provided attachments. Unless I'm missing something, it
> seems that the only real substantive change is a per-context errno value.
> Am I reading that correctly?

the plan is to get rid of the static context and all global variables. This 
will be the easiest way to make libsmbclient thread-safe, pass the context to 
every function.

> As to the separation of the options, do you envision having multiple sets
> of options? I can't really see that as a common requirement, so it seems
> cleaner to me to keep the options in the context structure itself, but
> cleanliness is a matter of personal preference. :-) Personal preference not
> withstanding, though, I believe that we can do all changes to libsmbclient
> in a backward-compatible fashion, and that should be a major goal of this
> project. There are many (non-threaded) applications already written that
> should continue to work without change. The API should change only where
> absolutely necessary to meet the new goals.

Well I think you can create a struct in the smbc_context_s too. I would prefer 
it this way. I think it makes it more clear that the options are separate from 
the context. I'm sure we will find a way which will suit everyone.

> As an example of the type of backward-compatible change I propose... You
> pointed out that errno is not thread safe in many environments. There are,
> however, non-threaded applications depending on looking at errno so they
> should continue to be able to do so. To solve both issues, and assuming the
> addition of a smbc_set_errno() function like you propose, we can change all
> of the internal code to call smbc_set_errno() instead of assigning to errno
> directly, but smbc_set_errno() should assign to errno in addition to
> assigning to the context-specific errno member. Non-threaded (existing)
> applications then continue to operate as they do currently and can retrieve
> errno, and new, threaded applications, can make use of the smbc_get_errno()
> function to retrieve the thread- or more accurately, context-specific errno
> value.
>
> Sound reasonable?

I've changed nearly every function in the header files to break the backward-
compatibility by intention. I've tried to create sane names and uses names 
that make clear what the function does. Nearly everything changes in master so 
I think we should start with a cleaned up API for libsmbclient.

For example:

smbc_bool smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
to
smbc_bool smbc_options_get_auto_anonymous_login(SMBCOPT *o);

The negation is not needed.

All functions for file manipulation use the context directly to get rid of the 
global static context.

Will you be at SambaXP?

>
> Derrell

Cheers,

	-- andreas

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
Url : http://lists.samba.org/archive/samba-technical/attachments/20090324/4076b701/attachment.bin