inputsource.h

This software aims to create an applet and panel tools to manage a wireless interface card, such as

//
// InputSource.h
//
// $Id: //poco/Main/XML/include/SAX/InputSource.h#5 $
//
// SAX InputSource - A single input source for an XML entity.
//
// Copyright (c) 2004, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef SAX_InputSource_INCLUDED
#define SAX_InputSource_INCLUDED


#ifndef XML_XML_INCLUDED
#include "XML/XML.h"
#endif
#ifndef XML_XMLString_INCLUDED
#include "XML/XMLString.h"
#endif
#ifndef XML_XMLStream_INCLUDED
#include "XML/XMLStream.h"
#endif


XML_BEGIN


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;
}


XML_END


#endif // SAX_InputSource_INCLUDED