Samba4 libsmb* design draft

[Stefan Metzmacher]

Tom Jansen wrote:

>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 I would like to have one libsmb.so (libsmb.a)
And it should include the SMB protocol AND the DCERPC protocol
but this lib should offer different interfaces (with providing different 
headers)

>- 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.
>  
>
(#include <libsmb/smb.h>
 #include <libsmb/dcerpc.h>)
Should this be the same API as in the samba internals? so all cli_* 
functions from libcli/raw/*
and librpc/rpc/*
With this a client could be fully controll what he want to send to the 
server...

>- 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. 
>
A unique id for command? how can I check for an error?
What if we run out of id's? Note one app should be able to run over years

>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.
>  
>
(#include <libsmb/smbc.h>)
This should be a full async interface but with posix errors and 
funtions, right? (I'm not shure if I got what you exactly mean...)

Also sync support should be also available if the call_back fn pointer 
is NULL

unsigned int smbc_command(SMBC_COMMAND *cmd);

struct SMBC_COMMAND {
	/* Id to track this command */
	unsigned int id;
	
	/* pointer to our SMBC_CTX */
	SMBC_CTX *ctx;

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

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

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

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

>- 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.
>  
>
Maybe this should be supported but should be marked depricated, new apps 
should use the <libsmb/smbc.h> API!

#include <libsmbclient.h> or <libsmb/smbc_compat.h>

-- 

metze

-------------------------------------------
Stefan (metze) Metzmacher <metze at metzemix.de>