| Subject: | Needed API changes |
There are several issues, and perhaps more than one ticket should be
opened, but I thought I'd start with one as at least a placekeeper.
(1) The documentation is incomplete and simple inaccurate in several places.
(2) The paradigm of return values is not consistent with Perl: it's a
simple 1:1 mapping of the C API. This is not appropriate. In UNIX C,
returning 0 means success. In Perl, returning 0 or undef means failure.
Not respecting the latter is going to confuse a lot of Perl veterans.
An example of this is: $smb->close($fh) || die "..." won't work,
because close() returns < 0 to indicate an error. It should return
undef or 0 to indicate an error.
(3) Having to reference two separate objects per operation (i.e.
"$smb->write($fh, $buf)") is clunky. Why not have open() return an
object that includes the reference to the $smb and the file handle?
(4) Since Perl 5.6, IO::Handle is how most modules elect to do I/O.
$smb->open() should return an IO::Handle-derived object.
(5) A "tell()" method is needed, since different O/S's have different
newline termination, which might cause offsets to be different from one
O/S to another for ASCII files.
(6) A "truncate()" method would also be useful to shrink the file after
rewriting it in place.
(7) Improper type conversion on one of the values returned by the stat()
method (I believe it's the "device type") being unpacked as a float or a
double.