Next round of libsmbclient ...

[Cole, Timothy D.]

> -----Original Message-----
> From: Richard Sharpe [mailto:rsharpe at ns.aus.com]
> Sent: Tuesday, March 19, 2002 12:45
> To: samba-technical at samba.org
> Subject: Next round of libsmbclient ...
> 
> 2. API design issues. There needs to be a separate init 
> routine that inits 
> the package. Then there needs to be a separate client_init 
> routine, that 
> creates a new client and all the data structures it needs. 
> This should 
> return a void * that is a handle to the client, and that 
> handle is passed 
> to all the routines.

I don't think it's actually necessary to discard type saftey for the sake of
opacity.  Rather than have APIs like:

 void *blah_new();
 void blah_free(void *handle);

or

 typedef void *blah_handle;
 blah_handle *blah_new();
 void blah_free(blah_handle handle);

I tend to prefer using incomplete types (struct declared but not defined):

 typedef struct _blah *blah_handle;
 blah_handle *blah_new();
 void blah_free(blah_handle handle);

or

 typedef struct _blah blah;
 blah *blah_new();
 void blah_free(blah *handle);

struct _blah itself would be defined in a header file that was not part of
the public API.

> 4. Currently, if you are not in the library, it does not listen for 
> packets off the wire. I might need a separate thread or 
> something that is 
> always interacting with the server (handling OpLock breaks ...)

For portability's sake, you might want to provide a few API calls:

 1. a blocking call which waits for and snarfs/processes any availible
incoming data [ returns immediately for incomplete packets; only blocks if
nothing availible at all ]
 2. a call or calls which return a list of file descriptors for use with
select()/poll()
 3. a call which returns a boolean indicating the availibility of incoming
packets

A threaded app might create a separate thread that just calls the blocking
call in an infinite loop.  Non-threaded apps have two options:

 A. retrieve a file descriptor mask and wait for the SMB sockets alongside
any other file descriptors they're interested in, then call the "wait/snarf"
call for processing if anything came in on the libsmb fds

 B. (more portable) call the function to determine if any data is waiting,
then call the processing function to determine if it's necessary to call
"wait/snarf"

Real-world applications would most likely use a combination of the two.
Being able to get the list of select()able file descriptors is fairly
important for integrating with the event loops of quite a few environments
(like TCL/Tk), at any rate.

I realize that I have not addressed thread saftey/locking issues.