Proposal: libsmbclient API

[Derrell Lipman]

On Fri, Mar 20, 2009 at 2:11 PM, Andreas Schneider <mail at cynapses.org>wrote:

> Hi Derrell,
>
> we already talked about making libsmbclient thread-safe and cleaning up the
> API. I've created two header files and an example how to use it.
>
> I've separated the options from the context. I think this makes it cleaner.
> I
> think the most important is, that the context is always passed between the
> functions and that there is a function to set errno and get it. errno is
> only
> thread safe in glibc.
>
> I haven't checked the doxygen documentation completely yet.
>
> Every kind of comment is welcome ;)


Hi Andreas,

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?

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.

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?

Derrell