gecko-dev/xpcom/io/nsIUnicharInputStream.idl
cbiesinger%web.de 2e7e16befb Bug 295047 Want unicode stream readers/writers: Makes nsIUnicharInputStream and
nsIConverterInputStream scriptable, and adds nsIUnicharOutputStream and
nsIConverterOutputStream (together with implementations).
r=jshin sr=darin a=chofmann
2005-06-24 19:44:50 +00:00

156 lines
6.2 KiB
Plaintext

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (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/MPL/
*
* 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 mozilla.org code.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 1998
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsIUnicharInputStream;
%{C++
/**
* The signature of the writer function passed to ReadSegments. This
* is the "consumer" of data that gets read from the stream's buffer.
*
* @param aInStream stream being read
* @param aClosure opaque parameter passed to ReadSegments
* @param aFromSegment pointer to memory owned by the input stream
* @param aToOffset amount already read (since ReadSegments was called)
* @param aCount length of fromSegment
* @param aWriteCount number of bytes read
*
* Implementers should return the following:
*
* @return NS_OK and (*aWriteCount > 0) if consumed some data
* @return <any-error> if not interested in consuming any data
*
* Errors are never passed to the caller of ReadSegments.
*
* NOTE: returning NS_OK and (*aWriteCount = 0) has undefined behavior.
*/
typedef NS_CALLBACK(nsWriteUnicharSegmentFun)(nsIUnicharInputStream *aInStream,
void *aClosure,
const PRUnichar *aFromSegment,
PRUint32 aToOffset,
PRUint32 aCount,
PRUint32 *aWriteCount);
%}
native nsWriteUnicharSegmentFun(nsWriteUnicharSegmentFun);
/**
* Abstract unicode character input stream
* @see nsIInputStream
*/
[scriptable, uuid(d5e3bd80-6723-4b92-b0c9-22f6162fd94f)]
interface nsIUnicharInputStream : nsISupports {
/**
* Reads into a caller-provided character array.
*
* @return The number of characters that were successfully read. May be less
* than aCount, even if there is more data in the input stream.
* A return value of 0 means EOF.
*
* @note To read more than 2^32 characters, call this method multiple times.
*/
[noscript] unsigned long read([array, size_is(aCount)] in PRUnichar aBuf,
in unsigned long aCount);
/**
* Low-level read method that has access to the stream's underlying buffer.
* The writer function may be called multiple times for segmented buffers.
* ReadSegments is expected to keep calling the writer until either there is
* nothing left to read or the writer returns an error. ReadSegments should
* not call the writer with zero characters to consume.
*
* @param aWriter the "consumer" of the data to be read
* @param aClosure opaque parameter passed to writer
* @param aCount the maximum number of characters to be read
*
* @return number of characters read (may be less than aCount)
* @return 0 if reached end of file (or if aWriter refused to consume data)
*
* @throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would
* block the calling thread (non-blocking mode only)
* @throws <other-error> on failure
*
* NOTE: this function may be unimplemented if a stream has no underlying
* buffer
*/
[noscript] unsigned long readSegments(in nsWriteUnicharSegmentFun aWriter,
in voidPtr aClosure,
in unsigned long aCount);
/**
* Read into a string object.
* @param aCount The number of characters that should be read
* @return The number of characters that were read.
*/
unsigned long readString(in unsigned long aCount, out AString aString);
/**
* Close the stream and free associated resources. This also closes the
* underlying stream, if any.
*/
void close();
};
%{C++
#include "nsStringFwd.h"
class nsIInputStream;
/**
* Create a nsIUnicharInputStream that wraps up a string. Data is fed
* from the string out until the done. When this object is destroyed
* it destroys the string by calling |delete| on the pointer if
* aTakeOwnership is set. If aTakeOwnership is not set, you must
* ensure that the string outlives the stream!
*/
extern NS_COM nsresult
NS_NewStringUnicharInputStream(nsIUnicharInputStream** aInstancePtrResult,
const nsAString* aString,
PRBool aTakeOwnership);
/**
* Create a new nsUnicharInputStream that provides a converter for the
* byte input stream aStreamToWrap. If no converter can be found then
* nsnull is returned and the error code is set to
* NS_INPUTSTREAM_NO_CONVERTER.
*/
extern NS_COM nsresult
NS_NewUTF8ConverterStream(nsIUnicharInputStream** aInstancePtrResult,
nsIInputStream* aStreamToWrap,
PRInt32 aBufferSize = 0);
%}