/*
 *	The contents of this file are subject to the Netscape Public License 
 *	Version 1.0 (the "License"); you may not use this file except in compliance 
 *	with the License. You may obtain a copy of the License at 
 *	http://www.mozilla.org/NPL/. 
 *	
 *	Software distributed under the License is distributed on an "AS IS" basis, 
 *	WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 
 *	for the specific language governing rights and limitations under the License. 
 *	
 *	The Original Code is the Netscape Messaging Access SDK Version 3.5 code, 
 *	released on or about June 15, 1998. 
 *	
 *	The Initial Developer of the Original Code is Netscape Communications 
 *	Corporation. Portions created by Netscape are Copyright (C) 1998 Netscape 
 *	Communications Corporation. All Rights Reserved. 
 *	
 *	Contributor(s): ______________________________________. 
*/
  
/*
* Copyright (c) 1997 and 1998 Netscape Communications Corporation
* (http://home.netscape.com/misc/trademarks.html)
*/


/* input output stream utilities
 * nsStream.h
 * @author prasad@netscape.com
 * @version 1.0
 */
 
#ifndef NSIOSTREAM_H
#define NSIOSTREAM_H
 
#include "nsmail.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Creates an input-stream from a file that can be passed to all messaging 
 * SDK API calls that require a parameter of type nsmail_inputstream_t.
 * Implements the stream and the associated internal functions for read(),
 * rewind() and close().
 * 
 * Params:
 * =======
 *
 * in_fileName:           Full path name of the file to create the input-stream on. 
 *			  The file must exist.
 * out_ppRetInputStream:  The created input-stream is returned here.
 * RETURN Value:	  0 on success < 0 on failure. See nsmail.h for possible err codes.
 *
 *  USAGE:
 *  ======
 *  nsmail_inputstream_t * pInputStream;
 *
 *  ret_value = file_inputStream_create (<file-name>, &pInputStream);
 *
 *  ret_value = mime_basicPart_setDataStream (<other-params>, pInputStream);
 *
 *  When done close and free the stream.
 *  ----------------------------------
 *  pInputStream->close (pInputStream->rock);
 *  nsStream_free (pInputStream); pInputStream = NULL;
 *
 */
int file_inputStream_create (char * in_fileName, 
			     nsmail_inputstream_t ** out_ppRetInputStream);



/*
 * Creates an input-stream from a buffer that can be passed to all messaging 
 * SDK API calls that require a parameter of type nsmail_inputstream_t.
 * Implements the stream and the associated internal functions for read(),
 * rewind() and close().
 * 
 * Params:
 * =======
 *
 * in_pDataBuf:           Data buf to base the input-stream on. Should not be NULL.
 *                        A reference to the buffer is stored in the stream. Hence
 *                        The buffer should not be freed until the stream is closed.
 * in_data_size		  Size of data in in_pDataBuf.
 * out_ppRetInputStream:  The created input-stream is returned here.
 * RETURN Value:	  0 on success < 0 on failure. See nsmail.h for possible err codes.
 *
 *
 *  USAGE:
 *  ======
 *  
 *  Same as file_inputStream above.
 *
 */
int buf_inputStream_create (char * in_pDataBuf, 
			    long in_data_size,
			    nsmail_inputstream_t ** out_ppRetInputStream);


 
/*
 * Creates an output-stream from a file that can be passed to all messaging 
 * SDK API calls that require a parameter of type nsmail_outputstream_t.
 * 
 * Params:
 * =======
 *
 * in_fileName:           Full path name of the file to create the output-stream on. 
 *			  Creates the file if needed. Blows away any previous data in the file.
 * out_ppRetInputStream:  The created output-stream is returned here.
 * RETURN Value:	  0 on success < 0 on failure. See nsmail.h for possible err codes.
 * 
 *  USAGE:
 *  ======
 *  nsmail_outputstream_t * pOutputStream;
 *
 *  ret_value = file_outputStream_create (<file-name>, &pOutputStream);
 *
 *  ret_value = mime_message_putByteStream (<other-params>, pOutputStream);
 *
 *  When done close and free the stream.
 *  ----------------------------------
 *  pOutputStream->close (pOutputStream->rock);   
 *  nsStream_free (pOutputStream); pOutputStream = NULL;
 * 
 *  NOTE: The file under the stream needs to be removed separately.
 */
int file_outputStream_create (char * in_fileName, 
			      nsmail_outputstream_t ** out_ppRetOutputStream);


/* free the memory allocated for the (input/output) stream */
void nsStream_free (void * pMem);

#ifdef __cplusplus
}
#endif
 
 
#endif /* NSIOSTREAM_H */