RFC: NamedPipes emulation API

[Luke Kenneth Casson Leighton]

this is an RFC document describing an API that may be
used to provide Windows NT Style "NamedPipe" functionality.
it will be of interest to samba, wine, freedce and win32
developers wishing to port applications to unix (via the
wine win32 implementation of NamedPipes).

the functionality described in this document is equivalent
to, if you have access to the MSDN, the following 
(incomplete list of) Win32 functions:

- CreateNamedPipe (returns a file handle)

- TransactNamedPipe

- a read operation on the named pipe file handle, above

- a write operation on the named pipe file handle, above

- a close operation on the named pipe file handle, above

- WaitNamedPipe

there follows a list of function declarations.

these are samba-specific functions that are only of use
to SAMBA 3 developers.  

int named_pipe_create(
		connection_struct *connection, /* contains all info needed,
		                                  e.g. user security context */
		const char *pipe_name, /* e.g. \\server\PIPE\pipe_name or
		                               \\.\PIPE\pipe_name */
);

this function returns -1 on failure or an SMB file index
(fnum) on success.

it is called when an SMBopenX or NTcreateX is received.

from memory, the access point is api_pipe_open(), in pipe.c
or reply.c.


STATUS named_pipe_transact(connection_struct *connection,
		int fnum, /* the SMB file index from the named_pipe_create */
		const char *transact_data_to_send, /* smb data received, to
		                                      send to NamedPipe service */
		int transact_data_length, /* zero or more bytes */
		char *transact_receive_buffer, /* NamedPipe data received,
		                                  to be sent over SMB */
		int *transact_receive_length); /* zero or more bytes */

this function returns an NT status code.

if there is more data to be received, then the function
must return ERROR_MORE_DATA.  NT_STATUS_OK is returned
on success.

from memory, the access point is api_pipe_readwrite() or
reply_trans2(), or maybe reply_pipe_trans().  i don't recall
which.  again, it'll be in pipe.c or reply.c.

STATUS named_pipe_read(connection_struct *connection,
		int fnum, /* the SMB file index from the named_pipe_create */
		char *transact_receive_buffer, /* NamedPipe data received,
		                                  to be sent over SMB */
		int *transact_receive_length); /* zero or more bytes */

this function returns an NT status code.

NT_STATUS_OK is returned on success.

this one's to be called by pipe_read() (api_pipe_read()?)


STATUS named_pipe_write(connection_struct *connection,
		int fnum, /* the SMB file index from the named_pipe_create */
		const char *transact_data_to_send, /* smb data received, to
		                                      send to NamedPipe service */
		int transact_data_length); /* zero or more bytes */

this function returns an NT status code.

NT_STATUS_OK is returned on success.

this one's to be called by pipe_write() (api_pipe_write()?)


the use of this API is quite simple, and provides a clean
"cut-off" point between samba and all NamedPipe transactions.

lkcl