source: icXML/icXML-devel/src/xercesc/framework/MemBufInputSource.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

File size: 8.8 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/*
19 * $Id: MemBufInputSource.hpp 932887 2010-04-11 13:04:59Z borisk $
20 */
21
22
23#if !defined(XERCESC_INCLUDE_GUARD_MEMBUFINPUTSOURCE_HPP)
24#define XERCESC_INCLUDE_GUARD_MEMBUFINPUTSOURCE_HPP
25
26#include <xercesc/sax/InputSource.hpp>
27
28XERCES_CPP_NAMESPACE_BEGIN
29
30class BinInputStream;
31
32
33/**
34 *  This class is a derivative of the standard InputSource class. It provides
35 *  for the parser access to data stored in a memory buffer. The type of
36 *  buffer and its host specific attributes are of little concern here. The
37 *  only real requirement is that the memory be readable by the current
38 *  process.
39 *
40 *  Note that the memory buffer size is expressed in <b>bytes</b>, not in
41 *  characters. If you pass it text data, you must account for the bytes
42 *  per character when indicating the buffer size.
43 *
44 *  As with all InputSource derivatives. The primary objective of an input
45 *  source is to create an input stream via which the parser can spool in
46 *  data from the referenced source. In this case, there are two options
47 *  available.
48 *
49 *  The passed buffer can be adopted or merely referenced. If it is adopted,
50 *  then it must be dynamically allocated and will be destroyed when the
51 *  input source is destroyed (no reference counting!.) If not adopted, the
52 *  caller must insure that it remains valid until the input source object
53 *  is destroyed.
54 *
55 *  The other option indicates whether each stream created for this input
56 *  source should get its own copy of the data, or whether it should just
57 *  stream the data directly from this object's copy of the data. The same
58 *  rules apply here, in that the buffer must either be copied by the
59 *  stream or it must remain valid until the stream is destroyed.
60 */
61class XMLPARSER_EXPORT MemBufInputSource : public InputSource
62{
63public :
64    // -----------------------------------------------------------------------
65    //  Constructors and Destructor
66    // -----------------------------------------------------------------------
67
68    /** @name Constructors */
69    //@{
70
71    /**
72      * A memory buffer input source is constructed from a buffer of byte
73      * data, and the count of bytes in that buffer. The parser will parse
74      * from this memory buffer until it has eaten the indicated number of
75      * bytes.
76      *
77      * Note that the system id provided serves two purposes. Firstly it is
78      * going to be displayed in error messages as the source of the error.
79      * And secondly, any entities which are referred to from this entity
80      * via relative paths/URLs will be relative to this fake system id.
81      *
82      * @param  srcDocBytes     The actual data buffer to be parsed from.
83      * @param  byteCount       The count of bytes (not characters, bytes!)
84      *                         in the buffer.
85      * @param  bufId           A fake system id for the buffer.
86      * @param  adoptBuffer     Indicates whether this object should adopt
87      *                         the buffer (i.e. become responsible for
88      * deletion) or just
89      *                         use it in place.
90      * @param  manager         Pointer to the memory manager to be used to
91      *                         allocate objects.
92      */
93    MemBufInputSource
94    (
95        const   XMLByte* const  srcDocBytes
96        , const XMLSize_t       byteCount
97        , const XMLCh* const    bufId
98        , const bool            adoptBuffer = false
99        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
100    );
101
102    /**
103      * This constructor is identical to the previous one, except that it takes
104      * the fake system id in local code page form and transcodes it internally.
105      */
106    MemBufInputSource
107    (
108        const   XMLByte* const  srcDocBytes
109        , const XMLSize_t       byteCount
110        , const char* const     bufId
111        , const bool            adoptBuffer = false
112        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
113    );
114    //@}
115
116    /** @name Destructor */
117    //@{
118    /**
119      * If the buffer was adopted, the copy made during construction is deleted
120      * at this point.
121      */
122    ~MemBufInputSource();
123    //@}
124
125
126    // -----------------------------------------------------------------------
127    //  Virtual input source interface
128    // -----------------------------------------------------------------------
129
130    /** @name Virtual methods */
131    //@{
132
133    /**
134      * This method will return a binary input stream derivative that will
135      * parse from the memory buffer. If setCopyBufToStream() has been set,
136      * then the stream will make its own copy. Otherwise, it will use the
137      * buffer as is (in which case it must remain valid until the stream
138      * is no longer in use, i.e. the parse completes.)
139      *
140      * @return A dynamically allocated binary input stream derivative that
141      *         can parse from the memory buffer.
142      */
143    BinInputStream* makeStream() const;
144
145    //@}
146
147
148    // -----------------------------------------------------------------------
149    //  Setter methods
150    // -----------------------------------------------------------------------
151
152    /** @name Setter methods */
153
154    //@{
155
156    /**
157      * By default, for safety's sake, each newly created stream from this
158      * input source will make its own copy of the buffer to stream from. This
159      * avoids having to deal with aliasing of the buffer for simple work. But,
160      * for higher performance applications or for large buffers, this is
161      * obviously not optimal.
162      *
163      * In such cases, you can call this method to turn off that default
164      * action. Once turned off, the streams will just get a pointer to the
165      * buffer and parse directly from that. In this case, you must insure that
166      * the buffer remains valid for as long as any parse events are still
167      * using it.
168      *
169      * @param  newState    The new boolean flag state to set.
170      */
171    void setCopyBufToStream(const bool newState);
172
173    /**
174      * This methods allows the MemBufInputSource to be used for more than
175      * one input source, instead of destructing/constructing another
176      * MemBufInputSource.
177      *
178      * @param  srcDocBytes     The actual data buffer to be parsed from.
179      * @param  byteCount       The count of bytes (not characters, bytes!)
180      *                         in the buffer.     
181      */
182    void resetMemBufInputSource(const   XMLByte* const  srcDocBytes
183                                , const XMLSize_t       byteCount);
184    //@}
185
186
187private :
188    // -----------------------------------------------------------------------
189    //  Unimplemented constructors and operators
190    // -----------------------------------------------------------------------
191    MemBufInputSource(const MemBufInputSource&);
192    MemBufInputSource& operator=(const MemBufInputSource&);
193
194    // -----------------------------------------------------------------------
195    //  Private data members
196    //
197    //  fAdopted
198    //      Indicates whether the buffer is adopted or not. If so, then it
199    //      is destroyed when the input source is destroyed.
200    //
201    //  fByteCount
202    //      The size of the source document.
203    //
204    //  fCopyBufToStream
205    //      This defaults to true (the safe option), which causes it to
206    //      give a copy of the buffer to any streams it creates. If you set
207    //      it to false, it will allow the streams to just reference the
208    //      buffer (in which case this input source must stay alive as long
209    //      as the buffer is in use by the stream.)
210    //
211    //  fSrcBytes
212    //      The source memory buffer that is being spooled from. Whether it
213    //      belongs to the this input source or not is controlled by the
214    //      fAdopted flag.
215    // -----------------------------------------------------------------------
216    bool            fAdopted;
217    XMLSize_t       fByteCount;
218    bool            fCopyBufToStream;
219    const XMLByte*  fSrcBytes;
220};
221
222
223inline void MemBufInputSource::setCopyBufToStream(const bool newState)
224{
225    fCopyBufToStream = newState;
226}
227
228XERCES_CPP_NAMESPACE_END
229
230#endif
Note: See TracBrowser for help on using the repository browser.