Logo Search packages:      
Sourcecode: poco version File versions  Download package

InputSource.h

//
// InputSource.h
//
// $Id: //poco/1.2/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 {


00052 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:
00147       XMLString _publicId;
      XMLString _systemId;
      XMLString _encoding;
      XMLByteInputStream* _bistr;
      XMLCharInputStream* _cistr;
};


//
// inlines
//
00158 inline const XMLString& InputSource::getPublicId() const
{
      return _publicId;
}


00164 inline const XMLString& InputSource::getSystemId() const
{
      return _systemId;
}


00170 inline const XMLString& InputSource::getEncoding() const
{
      return _encoding;
}


00176 inline XMLByteInputStream* InputSource::getByteStream() const
{
      return _bistr;
}


00182 inline XMLCharInputStream* InputSource::getCharacterStream() const
{
      return _cistr;
}


} } // namespace Poco::XML


#endif // SAX_InputSource_INCLUDED

Generated by  Doxygen 1.6.0   Back to index