new trunk (base for 1.5)

windows build only

XML/include/Poco/SAX/InputSource.h

@@ -0,0 +1,191 @@
+//
+// InputSource.h
+//
+// $Id: //poco/1.4/XML/include/Poco/SAX/InputSource.h#1 $
+//
+// Library: XML
+// Package: SAX
+// Module:  SAX
+//
+// SAX InputSource - A single input source for an XML entity.
+//
+// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// Permission is hereby granted, free of charge, to any person or organization
+// obtaining a copy of the software and accompanying documentation covered by
+// this license (the "Software") to use, reproduce, display, distribute,
+// execute, and transmit the Software, and to prepare derivative works of the
+// Software, and to permit third-parties to whom the Software is furnished to
+// do so, all subject to the following:
+// 
+// The copyright notices in the Software and this entire statement, including
+// the above license grant, this restriction and the following disclaimer,
+// must be included in all copies of the Software, in whole or in part, and
+// all derivative works of the Software, unless such copies or derivative
+// works are solely in the form of machine-executable object code generated by
+// a source language processor.
+// 
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+//
+
+
+#ifndef SAX_InputSource_INCLUDED
+#define SAX_InputSource_INCLUDED
+
+
+#include "Poco/XML/XML.h"
+#include "Poco/XML/XMLString.h"
+#include "Poco/XML/XMLStream.h"
+
+
+namespace Poco {
+namespace XML {
+
+
+class XML_API InputSource
+	/// This class allows a SAX application to encapsulate information about an input 
+	/// source in a single object, which may include a public identifier, a system 
+	/// identifier, a byte stream (possibly with a specified encoding), and/or a character 
+	/// stream.
+	/// 
+	/// There are two places that the application can deliver an input source to the 
+	/// parser: as the argument to the Parser.parse method, or as the return value of the 
+	/// EntityResolver::resolveEntity() method.
+	/// 
+	/// The SAX parser will use the InputSource object to determine how to read XML input. 
+	/// If there is a character stream available, the parser will read that stream directly, 
+	/// disregarding any text encoding declaration found in that stream. If there is no character 
+	/// stream, but there is a byte stream, the parser will use that byte stream, using the 
+	/// encoding specified in the InputSource or else (if no encoding is specified) autodetecting 
+	/// the character encoding using an algorithm such as the one in the XML specification. 
+	/// If neither a character stream nor a byte stream is available, the parser will attempt 
+	/// to open a URI connection to the resource identified by the system identifier.
+	/// 
+	/// An InputSource object belongs to the application: the SAX parser shall never modify it in 
+	/// any way (it may modify a copy if necessary). However, standard processing of both byte and 
+	/// character streams is to close them on as part of end-of-parse cleanup, so applications should 
+	/// not attempt to re-use such streams after they have been handed to a parser.
+{
+public:
+	InputSource();
+		/// Zero-argument default constructor.
+		
+	InputSource(const XMLString& systemId);
+		/// Creates a new input source with a system identifier.
+		/// Applications may use setPublicId to include a public identifier as well, 
+		/// or setEncoding to specify the character encoding, if known.
+		/// 
+		/// If the system identifier is a URL, it must be fully resolved (it may not 
+		/// be a relative URL).
+		
+	InputSource(XMLByteInputStream& istr);
+		/// Creates a new input source with a byte stream.
+		/// 
+		/// Application writers should use setSystemId() to provide a base for resolving
+		/// relative URIs, may use setPublicId to include a public identifier, and may use 
+		/// setEncoding to specify the object's character encoding.
+
+	~InputSource();
+		/// Destroys the InputSource.
+
+	void setPublicId(const XMLString& publicId);
+		/// Set the public identifier for this input source.
+		///
+		/// The public identifier is always optional: if the application writer includes one, 
+		/// it will be provided as part of the location information.
+		
+	void setSystemId(const XMLString& systemId);
+		/// Set the system identifier for this input source.
+		///
+		/// The system identifier is optional if there is a byte stream or a character stream, 
+		/// but it is still useful to provide one, since the application can use it to resolve 
+		/// relative URIs and can include it in error messages and warnings (the parser will 
+		/// attempt to open a connection to the URI only if there is no byte stream or character 
+		/// stream specified).
+		/// 
+		/// If the application knows the character encoding of the object pointed to by the system 
+		/// identifier, it can register the encoding using the setEncoding method.
+		/// 
+		/// If the system identifier is a URL, it must be fully resolved (it may not be a relative URL).
+
+	const XMLString& getPublicId() const;
+		/// Get the public identifier for this input source.
+		
+	const XMLString& getSystemId() const;
+		/// Get the system identifier for this input source.
+
+	void setByteStream(XMLByteInputStream& istr);
+		/// Set the byte stream for this input source.
+		/// The SAX parser will ignore this if there is also a character stream specified, but it 
+		/// will use a byte stream in preference to opening a URI connection itself.
+		
+	XMLByteInputStream* getByteStream() const;
+		/// Get the byte stream for this input source.
+
+	void setCharacterStream(XMLCharInputStream& istr);
+		/// Set the character stream for this input source.
+
+	XMLCharInputStream* getCharacterStream() const;
+		/// Get the character stream for this input source.
+
+	void setEncoding(const XMLString& encoding);
+		/// Set the character encoding, if known.
+		/// The encoding must be a string acceptable for an XML encoding declaration 
+		/// (see section 4.3.3 of the XML 1.0 recommendation).
+		
+	const XMLString& getEncoding() const;
+		/// Get the character encoding for a byte stream or URI.
+
+private:
+	XMLString _publicId;
+	XMLString _systemId;
+	XMLString _encoding;
+	XMLByteInputStream* _bistr;
+	XMLCharInputStream* _cistr;
+};
+
+
+//
+// inlines
+//
+inline const XMLString& InputSource::getPublicId() const
+{
+	return _publicId;
+}
+
+
+inline const XMLString& InputSource::getSystemId() const
+{
+	return _systemId;
+}
+
+
+inline const XMLString& InputSource::getEncoding() const
+{
+	return _encoding;
+}
+
+
+inline XMLByteInputStream* InputSource::getByteStream() const
+{
+	return _bistr;
+}
+
+
+inline XMLCharInputStream* InputSource::getCharacterStream() const
+{
+	return _cistr;
+}
+
+
+} } // namespace Poco::XML
+
+
+#endif // SAX_InputSource_INCLUDED