Samba4 libsmb* design draft

[Tom Jansen]

Hello everyone,

I've been browsing through the samba4 libcli/* code the last few days
and I must say that I'm impressed by  it's cleanness.

First, a random question:

Why is sock->port = 445 in cli_sock_init() while we could be more
failsafe by using sock->port = 0 because  cli_sock_connect tries 445 and
139 (in that order) when port==0 ?

Draft design for libsmb*:

- libsmbcli: 
The lower level API. Uses the lowest level cli_raw* functions to talk to
SMB servers. The API should be  completely async. This is quite a large
job but adding asyncness will be very usefull. If everything is async,
the need for reentrant code at this level is low, locking can be done on
large structures (for example  cli_state structures) because we will not
be waiting for IO operations to complete. This will be a minor
performance impact, but it greatly simplifies locking and thus reduces
the probability of deadlock-bugs and  its friends.
As I already mentioned, everything that does IO should be async. It
should be useable by client apps like smbclient so bugs have to be fixed
at one single point.


- libsmbclient_async
This lib will have a posix-like API that can use the power of asyncness.
It will not be reentrant because  that's not necessary. You can call it
posix with callback if you like. Commands will be given in structure's
that can look like:

struct SMBC_ASYNC_COMMAND {
	/* Id to track this command */
	unsigned int id;

	enum {SMBCLIENT_OPEN, SMBCLIENT_READ, SMBCLIENT_WRITE,
SMBCLIENT_CLOSE, SMBCLIENT_READDIR....} type;

	union command_parms {
		struct open {
			const char *pathname;
			int flags;
			mode_t mode;
			SMBC_FILE *retval;
		};
		struct read {
			SMBC_FILE *fd;
			void  *buf;
			size_t count;
			ssize_t retval;
		};
		etc..
	};

	/* Error that occured in various formats */
	struct error error;

	struct async {
		void (*fn)(struct SMBC_ASYNC_COMMAND *);
		void *private;
	}
}

an example function definition for an open call would look like:

int smbc_ctx_async_open(SMBC_ASYNC_CTX * ctx, SMBC_ASYNC_COMMAND * cmd);

If everything is succesful the unique id is returned. If the command is
completed the callback 
It will be reentrant by using a async mechanism from libsmbcli with
locking.
Connection caching and management will be transparant to the user by
default, but it'll be controllable. For example, a callback for a broken
connection can be called and depending on it's retval the connection can
be automagically reestablished or terminated.
			

- libsmbclient_posix:
The highest level API that behaves just like the samba3 libsmbclient but
without the "unexpected features" :)
It will be reentrant by using a async mechanism from libsmbcli with
locking.
Connection caching and management will be transparant to the user by
default, but it'll be controllable. For example, custom caching
functionality like samba3-libsmbclient can be available.

Of course, this is just a draft. I would really like advise, views,
comments (and flames :)!

Yours,
	Tom