Signed-off-by: Volker Lendecke <vl@samba.org> Reviewed-by: Michael Adam <obnox@samba.org> Autobuild-User(master): Volker Lendecke <vl@samba.org> Autobuild-Date(master): Fri Jun 21 19:57:06 CEST 2013 on sn-devel-104
Guenther
- James suggested using gcc's "deprecated" attribute to mark the context structure fields to generate warnings. This creates a scenario with the best of all worlds. I'm able to move to an organization that more easily allows future enhancements, while avoiding any mandatory changes by applications. Thanks, James! - Updated WHATSNEW.txt so that it accurately reflects the current state of affairs. Derrell (This used to be commit a67f96fbe9683b46c2149f7cb439d13f7f0e6ecd)
(This used to be commit 23cb9c49e3724cecaa66655ef64c3111bf14c552)
- Ensured that all public functions have documentation in libsmbclient.h - Reformatted for "proper" indentation - Re-added temporarily-disabled alternate authentication function capability Derrell (This used to be commit 64b7150d92849a1e1e2416b9dcc12fae8d6bea99)
Given the tacit (if that) approval by some people, and clear disapproval by others for my proposed clean-up and reorganization of libsmbclient, I've come up with a slightly different approach. This commit changes back to the original libsmbclient.h SMBCCTX structure which will maintain ABI compatibility. I retain, here, the setter and getter functions which all new code should use. Older programs already compiled should continue to work fine. Older programs being recompiled will encounter compile-time errors (intentionally!) so that the code can be corrected to use the setter/getter interfaces. Although this doesn't clean up the interface in the way I had wanted, the code reorganization and requirement for new programs to use the setters and getters allows future progress to be made on libsmbclient without further muddying up the interface, while retaining the ABI compatibility that was the big issue causing disapproval. I hope that this compromise is adequate. Derrell (This used to be commit 56429a3d60b2a48963342f6340b3c01469a892c6)
The libsmbclient interface has suffered from difficulty of improvement and
feature enrichment without causing ABI breakage. Although there were a number
of issues, the primary ones were:
(a) the user of the library would manually manipulate the context structure
members, meaning that nothing in the context structure could change other
than adding stuff at the end;
(b) there were three methods of setting options: setting bits in a flags field
within the context structure, setting explicit options variables within an
options structure in the context structure, and by calling the
smbc_option_set() function;
(c) the authentication callback did not traditionally provide enough
information to the callee which required adding an option for a callback
with a different signature, and now there are requests for even more
information at the callback, requiring yet a third signature and option to
set it (if we implement that feature).
This commit provides a reorganization of the code which fixes (a) and (b).
The context structure is now entirely opaque, and there are setter and getter
functions for manipulating it. This makes maintaining ABI consistency much,
much easier.
Additionally, the options setting/getting has been unified into a single
mechanism using smbc_option_set() and smbc_option_get().
Yet to be completed is a refactoring of the authentication callback (c).
The test programs in examples/libsmbclient have been modified (if necessary;
some applications require no changes at all) for the new API and a few have
been minimally tested.
Derrell
(This used to be commit d4b4bae8ded824d06ad5ab0e219f71187ee5c771)
(This used to be commit b0132e94fc5fef936aa766fb99a306b3628e9f07)