stream.h revision 47f321be8e88a86d67f07f5d13f9a87067990f7f
/** @file
* IPRT - I/O Stream.
*/
/*
* Copyright (C) 2006-2007 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___iprt_stream_h
#define ___iprt_stream_h
/** @defgroup grp_rt_stream RTStrm - File Streams
* @ingroup grp_rt
* @{
*/
/** Pointer to a stream. */
/** Pointer to the standard input stream. */
/** Pointer to the standard error stream. */
/** Pointer to the standard output stream. */
/**
* Opens a file stream.
*
* @returns iprt status code.
* @param pszFilename Path to the file to open.
* @param pszMode The open mode. See fopen() standard.
* Format: <a|r|w>[+][b|t]
* @param ppStream Where to store the opened stream.
*/
/**
* Opens a file stream.
*
* @returns iprt status code.
* @param pszMode The open mode. See fopen() standard.
* Format: <a|r|w>[+][b|t]
* @param ppStream Where to store the opened stream.
* @param pszFilenameFmt Filename path format string.
* @param args Arguments to the format string.
*/
RTR3DECL(int) RTStrmOpenFV(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, va_list args);
/**
* Opens a file stream.
*
* @returns iprt status code.
* @param pszMode The open mode. See fopen() standard.
* Format: <a|r|w>[+][b|t]
* @param ppStream Where to store the opened stream.
* @param pszFilenameFmt Filename path format string.
* @param ... Arguments to the format string.
*/
RTR3DECL(int) RTStrmOpenF(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, ...);
/**
* Closes the specified stream.
*
* @returns iprt status code.
* @param pStream The stream to close.
*/
/**
* Get the pending error of the stream.
*
* @returns iprt status code. of the stream.
* @param pStream The stream.
*/
/**
* Clears stream error condition.
*
* All stream operations save RTStrmClose and this will fail
* while an error is asserted on the stream
*
* @returns iprt status code.
* @param pStream The stream.
*/
/**
* Changes the stream mode.
*
* @returns iprt status code.
* @param pStream The stream.
* @param fBinary The desired binary (@c true) / text mode (@c false).
* Pass -1 to leave it unchanged.
* @param fCurrentCodeSet Whether converting the stream from UTF-8 to the
* current code set is desired (@c true) or not (@c
* false). Pass -1 to leave this property unchanged.
*/
/**
* Rewinds the stream.
*
* Stream errors will be reset on success.
*
* @returns IPRT status code.
*
* @param pStream The stream.
*
* @remarks Not all streams are rewindable and that behavior is currently
* undefined for those.
*/
/**
* Reads from a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to put the read bits.
* Must be cbRead bytes or more.
* @param cbRead Number of bytes to read.
* @param pcbRead Where to store the number of bytes actually read.
* If NULL cbRead bytes are read or an error is returned.
*/
/**
* Writes to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to get the bits to write from.
* @param cbWrite Number of bytes to write.
* @param pcbWritten Where to store the number of bytes actually written.
* If NULL cbWrite bytes are written or an error is returned.
*/
RTR3DECL(int) RTStrmWriteEx(PRTSTREAM pStream, const void *pvBuf, size_t cbWrite, size_t *pcbWritten);
/**
* Reads from a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to put the read bits.
* Must be cbRead bytes or more.
* @param cbRead Number of bytes to read.
*/
{
}
/**
* Writes to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to get the bits to write from.
* @param cbWrite Number of bytes to write.
*/
{
}
/**
* Reads a character from a file stream.
*
* @returns The char as an unsigned char cast to int.
* @returns -1 on failure.
* @param pStream The stream.
*/
/**
* Writes a character to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param ch The char to write.
*/
/**
* Writes a string to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pszString The string to write.
* No newlines or anything is appended or prepended.
* The terminating '\\0' is not written, of course.
*/
/**
* Reads a line from a file stream.
*
* A line ends with a '\\n', '\\r\\n', '\\0' or the end of the file.
*
* @returns iprt status code.
* @retval VINF_BUFFER_OVERFLOW if the buffer wasn't big enough to read an
* entire line.
* @retval VERR_BUFFER_OVERFLOW if a lone '\\r' was encountered at the end of
* the buffer and we ended up dropping the following character.
*
* @param pStream The stream.
* @param pszString Where to store the line.
* The line will *NOT* contain any '\\n'.
* @param cbString The size of the string buffer.
*/
/**
* Flushes a stream.
*
* @returns iprt status code.
* @param pStream The stream to flush.
*/
/**
* Prints a formatted string to the specified stream.
*
* @returns Number of bytes printed.
* @param pStream The stream to print to.
* @param pszFormat Runtime format string.
* @param ... Arguments specified by pszFormat.
*/
/**
* Prints a formatted string to the specified stream.
*
* @returns Number of bytes printed.
* @param pStream The stream to print to.
* @param pszFormat Runtime format string.
* @param args Arguments specified by pszFormat.
*/
/**
* Prints a formatted string to the standard output stream (g_pStdOut).
*
* @returns Number of bytes printed.
* @param pszFormat Runtime format string.
* @param ... Arguments specified by pszFormat.
*/
/**
* Prints a formatted string to the standard output stream (g_pStdOut).
*
* @returns Number of bytes printed.
* @param pszFormat Runtime format string.
* @param args Arguments specified by pszFormat.
*/
/** @} */
#endif