libsmbclient for Samba4: initial design issues

[tridge at samba.org]

Michael,

 >   int client_sendrecv(struct client *client,
 >         struct request *request,
 >         struct response *response,
 >         int flags);

I'm afraid that won't work for async calls. The problem is that an
'int' cannot represent the state of a in-flight async operation, or at
least it can't do it without using some table which would break the
'pure function' nature of the code.

The interface we have used in the Samba4 libcli/raw/ library looks
like this:

struct smbcli_request *smb_raw_OPERATION_send(struct smbcli_tree *tree,
  	                                      union smb_OPERATION *parms);
NTSTATUS smb_raw_OPERATION_recv(struct smbcli_request *req,
			        union smb_OPERERATION *parms);
NTSTATUS smb_raw_OPERATION(struct smbcli_tree *tree,
			   union smb_OPERERATION *parms);

these 3 functions are repeated for each 'OPERATION' in the library,
with 'OPERATION' being a high level operation, such as 'open' not a
low level specific call like ntcreatex or openx.

The 3 functions do this:

 1) the _send function queues an async request, returning a pointer to
    a smbcli_request structure that holds the state of the
    request. Internally the request might involve several network
    packets (think about trans2) but that is hidden from the caller.

 2) the _recv function waits for completion of a previously started
    async request, and return the status. For async callers, the usual
    pattern is to only call the _recv function once the async callback
    has triggered (the struct smbcli_request has an async substructure
    used to setup async completion callbacks).

 3) the 3rd function is the synchronous varient, and just calls the
    first 2 one after the other.

I have found that this form for smb client calls works really well,
and I'd be quite reluctant to change it now unless there is a very
good reason.

Cheers, Tridge