Xerces-C++ 3.1.2

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

TransService.hpp
Go to the documentation of this file.
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: TransService.hpp 1662885 2015-02-28 02:16:39Z scantor $
20 */
21
22 #if !defined(XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP)
23 #define XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP
24
25 #include <xercesc/util/XMemory.hpp>
26 #include <xercesc/util/PlatformUtils.hpp>
27 #include <xercesc/framework/XMLRecognizer.hpp>
28 #include <xercesc/util/RefHashTableOf.hpp>
29 #include <xercesc/util/RefVectorOf.hpp>
30
31 XERCES_CPP_NAMESPACE_BEGIN
32
33 // Forward references
34 //class XMLPlatformUtils;
35 class XMLLCPTranscoder;
36 class XMLTranscoder;
37 class ENameMap;
38
39
40 //
41 // This class is an abstract base class which are used to abstract the
42 // transcoding services that Xerces uses. The parser's actual transcoding
43 // needs are small so it is desirable to allow different implementations
44 // to be provided.
45 //
46 // The transcoding service has to provide a couple of required string
47 // and character operations, but its most important service is the creation
48 // of transcoder objects. There are two types of transcoders, which are
49 // discussed below in the XMLTranscoder class' description.
50 //
51 class XMLUTIL_EXPORT XMLTransService : public XMemory
52 {
53 public :
54 // -----------------------------------------------------------------------
55 // Class specific types
56 // -----------------------------------------------------------------------
57 enum Codes
58 {
59 Ok
60 , UnsupportedEncoding
61 , InternalFailure
62 , SupportFilesNotFound
63 };
64
65 struct TransRec
66 {
67 XMLCh intCh;
68 XMLByte extCh;
69 };
70
71
72 // -----------------------------------------------------------------------
73 // Public constructors and destructor
74 // -----------------------------------------------------------------------
75 virtual ~XMLTransService();
76
77
78 // -----------------------------------------------------------------------
79 // Non-virtual API
80 // -----------------------------------------------------------------------
81 XMLTranscoder* makeNewTranscoderFor
82 (
83 const XMLCh* const encodingName
84 , XMLTransService::Codes& resValue
85 , const XMLSize_t blockSize
86 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
87 );
88
89 XMLTranscoder* makeNewTranscoderFor
90 (
91 const char* const encodingName
92 , XMLTransService::Codes& resValue
93 , const XMLSize_t blockSize
94 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
95 );
96
97 XMLTranscoder* makeNewTranscoderFor
98 (
99 XMLRecognizer::Encodings encodingEnum
100 , XMLTransService::Codes& resValue
101 , const XMLSize_t blockSize
102 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
103 );
104
105
106 // -----------------------------------------------------------------------
107 // The virtual transcoding service API
108 // -----------------------------------------------------------------------
109 virtual int compareIString
110 (
111 const XMLCh* const comp1
112 , const XMLCh* const comp2
113 ) = 0;
114
115 virtual int compareNIString
116 (
117 const XMLCh* const comp1
118 , const XMLCh* const comp2
119 , const XMLSize_t maxChars
120 ) = 0;
121
122 virtual const XMLCh* getId() const = 0;
123
124 // -----------------------------------------------------------------------
125 // Create a new transcoder for the local code page.
126 //
127 // @param manager The memory manager to use.
128 // -----------------------------------------------------------------------
129 virtual XMLLCPTranscoder* makeNewLCPTranscoder(MemoryManager* manager) = 0;
130
131 virtual bool supportsSrcOfs() const = 0;
132
133 virtual void upperCase(XMLCh* const toUpperCase) = 0;
134 virtual void lowerCase(XMLCh* const toLowerCase) = 0;
135
136 // -----------------------------------------------------------------------
137 // Allow users to add their own encodings to the intrinsic mapping
138 // table
139 // Usage:
140 // XMLTransService::addEncoding (
141 // gMyEncodingNameString
142 // , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
143 // );
144 // -----------------------------------------------------------------------
145 static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
146
147
148 protected :
149 // -----------------------------------------------------------------------
150 // Hidden constructors
151 // -----------------------------------------------------------------------
152 XMLTransService();
153
154
155 // -----------------------------------------------------------------------
156 // Protected virtual methods.
157 // -----------------------------------------------------------------------
158 #ifdef OS390
159 friend class Uniconv390TransService;
160 #endif
161 virtual XMLTranscoder* makeNewXMLTranscoder
162 (
163 const XMLCh* const encodingName
164 , XMLTransService::Codes& resValue
165 , const XMLSize_t blockSize
166 , MemoryManager* const manager
167 ) = 0;
168
169 // -----------------------------------------------------------------------
170 // Protected init method for platform utils to call
171 // -----------------------------------------------------------------------
172 friend class XMLPlatformUtils;
173 virtual void initTransService();
174
175 // -----------------------------------------------------------------------
176 // protected static members
177 // gMappings
178 // This is a hash table of ENameMap objects. It is created and filled
179 // in when the platform init calls our initTransService() method.
180 //
181 // gMappingsRecognizer
182 // This is an array of ENameMap objects, predefined for those
183 // already recognized by XMLRecognizer::Encodings.
184 //
185
186 static RefHashTableOf<ENameMap>* gMappings;
187 static RefVectorOf<ENameMap>* gMappingsRecognizer;
188
189 private :
190 // -----------------------------------------------------------------------
191 // Unimplemented constructors and operators
192 // -----------------------------------------------------------------------
193 XMLTransService(const XMLTransService&);
194 XMLTransService& operator=(const XMLTransService&);
195
196 // -----------------------------------------------------------------------
197 // Hidden method to enable/disable strict IANA encoding check
198 // Caller: XMLPlatformUtils
199 // -----------------------------------------------------------------------
200 void strictIANAEncoding(const bool newState);
201 bool isStrictIANAEncoding();
202
203 friend class XMLInitializer;
204 };
205
214 class XMLUTIL_EXPORT XMLTranscoder : public XMemory
215 {
216 public :
217
225 enum UnRepOpts
226 {
227 UnRep_Throw
228 , UnRep_RepChar
229 };
230
231
234
239 virtual ~XMLTranscoder();
241
242
243
246
266 virtual XMLSize_t transcodeFrom
267 (
268 const XMLByte* const srcData
269 , const XMLSize_t srcCount
270 , XMLCh* const toFill
271 , const XMLSize_t maxChars
272 , XMLSize_t& bytesEaten
273 , unsigned char* const charSizes
274 ) = 0;
275
289 virtual XMLSize_t transcodeTo
290 (
291 const XMLCh* const srcData
292 , const XMLSize_t srcCount
293 , XMLByte* const toFill
294 , const XMLSize_t maxBytes
295 , XMLSize_t& charsEaten
296 , const UnRepOpts options
297 ) = 0;
298
304 virtual bool canTranscodeTo
305 (
306 const unsigned int toCheck
307 ) = 0;
308
310
313
318 XMLSize_t getBlockSize() const;
319
325 const XMLCh* getEncodingName() const;
327
330
338 MemoryManager* getMemoryManager() const;
339
341
342 protected :
343 // -----------------------------------------------------------------------
344 // Hidden constructors
345 // -----------------------------------------------------------------------
346 XMLTranscoder
347 (
348 const XMLCh* const encodingName
349 , const XMLSize_t blockSize
350 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
351 );
352
353
354 // -----------------------------------------------------------------------
355 // Protected helper methods
356 // -----------------------------------------------------------------------
357
358 private :
359 // -----------------------------------------------------------------------
360 // Unimplemented constructors and operators
361 // -----------------------------------------------------------------------
362 XMLTranscoder(const XMLTranscoder&);
363 XMLTranscoder& operator=(const XMLTranscoder&);
364
365 // -----------------------------------------------------------------------
366 // Private data members
367 //
368 // fBlockSize
369 // This is the block size indicated in the constructor.
370 //
371 // fEncodingName
372 // This is the name of the encoding this encoder is for. All basic
373 // XML transcoder's are for named encodings.
374 // -----------------------------------------------------------------------
375 XMLSize_t fBlockSize;
376 XMLCh* fEncodingName;
377 MemoryManager* fMemoryManager;
378 };
379
380
381 //
382 // This class is a specialized transcoder that only transcodes between
383 // the internal XMLCh format and the local code page. It is specialized
384 // for the very common job of translating data from the client app's
385 // native code page to the internal format and vice versa.
386 //
387 class XMLUTIL_EXPORT XMLLCPTranscoder : public XMemory
388 {
389 public :
390 // -----------------------------------------------------------------------
391 // Public constructors and destructor
392 // -----------------------------------------------------------------------
393 virtual ~XMLLCPTranscoder();
394
395
396 // -----------------------------------------------------------------------
397 // The virtual transcoder API
398 //
399 // NOTE: All these APIs don't include null terminator characters in
400 // their parameters. So calcRequiredSize() returns the number
401 // of actual chars, not including the null. maxBytes and maxChars
402 // parameters refer to actual chars, not including the null so
403 // its assumed that the buffer is physically one char or byte
404 // larger.
405 // -----------------------------------------------------------------------
406
407 // -----------------------------------------------------------------------
408 // The 'normal' way to transcode a XMLCh-string from/to local string
409 // representation
410 //
411 // NOTE: Both methods return a string allocated via the MemoryManager.
412 // It is the responsibility of the calling environment to
413 // release this string after use.
414 // -----------------------------------------------------------------------
415 virtual char* transcode(const XMLCh* const toTranscode,
416 MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
417
418 virtual XMLCh* transcode(const char* const toTranscode,
419 MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
420
421
422 // -----------------------------------------------------------------------
423 // DEPRECATED old transcode interface
424 // -----------------------------------------------------------------------
425 virtual XMLSize_t calcRequiredSize(const char* const srcText
426 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
427
428 virtual XMLSize_t calcRequiredSize(const XMLCh* const srcText
429 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
430
431 virtual bool transcode
432 (
433 const char* const toTranscode
434 , XMLCh* const toFill
435 , const XMLSize_t maxChars
436 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
437 ) = 0;
438
439 virtual bool transcode
440 (
441 const XMLCh* const toTranscode
442 , char* const toFill
443 , const XMLSize_t maxBytes
444 , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
445 ) = 0;
446
447
448 protected :
449 // -----------------------------------------------------------------------
450 // Hidden constructors
451 // -----------------------------------------------------------------------
452 XMLLCPTranscoder();
453
454
455 private :
456 // -----------------------------------------------------------------------
457 // Unimplemented constructors and operators
458 // -----------------------------------------------------------------------
459 XMLLCPTranscoder(const XMLLCPTranscoder&);
460 XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
461 };
462
463 //
464 // This class can be used to transcode to a target encoding. It manages the
465 // memory allocated for the transcode in an exception safe manner, automatically
466 // deleting it when the class goes out of scope.
467 //
468 class XMLUTIL_EXPORT TranscodeToStr
469 {
470 public:
471 // -----------------------------------------------------------------------
472 // Public constructors and destructor
473 // -----------------------------------------------------------------------
474
481 TranscodeToStr(const XMLCh *in, const char *encoding,
482 MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
483
491 TranscodeToStr(const XMLCh *in, XMLSize_t length, const char *encoding,
492 MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
493
500 TranscodeToStr(const XMLCh *in, XMLTranscoder* trans,
501 MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
502
510 TranscodeToStr(const XMLCh *in, XMLSize_t length, XMLTranscoder* trans,
511 MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
512
513 ~TranscodeToStr();
514
517
521 const XMLByte *str() const;
522
527 XMLByte *adopt();
528
533 XMLSize_t length () const;
534
536
537 private:
538 // -----------------------------------------------------------------------
539 // Unimplemented constructors and operators
540 // -----------------------------------------------------------------------
541 TranscodeToStr(const TranscodeToStr &);
542 TranscodeToStr &operator=(const TranscodeToStr &);
543
544 // -----------------------------------------------------------------------
545 // Private helper methods
546 // -----------------------------------------------------------------------
547 void transcode(const XMLCh *in, XMLSize_t len, XMLTranscoder* trans);
548
549 // -----------------------------------------------------------------------
550 // Private data members
551 //
552 // fString
553 // The transcoded string
554 //
555 // fBytesWritten
556 // The length of the transcoded string in bytes
557 // -----------------------------------------------------------------------
558 XMLByte *fString;
559 XMLSize_t fBytesWritten;
560 MemoryManager *fMemoryManager;
561 };
562
563 //
564 // This class can be used to transcode from a source encoding. It manages the
565 // memory allocated for the transcode in an exception safe manner, automatically
566 // deleting it when the class goes out of scope.
567 //
568 class XMLUTIL_EXPORT TranscodeFromStr
569 {
570 public:
571 // -----------------------------------------------------------------------
572 // Public constructors and destructor
573 // -----------------------------------------------------------------------
574
582 TranscodeFromStr(const XMLByte *data, XMLSize_t length, const char *encoding,
583 MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
584
592 TranscodeFromStr(const XMLByte *data, XMLSize_t length, XMLTranscoder *trans,
593 MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
594
595 ~TranscodeFromStr();
596
599
603 const XMLCh *str() const;
604
609 XMLCh *adopt();
610
615 XMLSize_t length() const;
616
618
619 private:
620 // -----------------------------------------------------------------------
621 // Unimplemented constructors and operators
622 // -----------------------------------------------------------------------
623 TranscodeFromStr(const TranscodeFromStr &);
624 TranscodeFromStr &operator=(const TranscodeFromStr &);
625
626 // -----------------------------------------------------------------------
627 // Private helper methods
628 // -----------------------------------------------------------------------
629 void transcode(const XMLByte *in, XMLSize_t length, XMLTranscoder *trans);
630
631 // -----------------------------------------------------------------------
632 // Private data members
633 //
634 // fString
635 // The transcoded string
636 //
637 // fCharsWritten
638 // The length of the transcoded string in characters
639 // -----------------------------------------------------------------------
640 XMLCh *fString;
641 XMLSize_t fCharsWritten;
642 MemoryManager *fMemoryManager;
643 };
644
645 // ---------------------------------------------------------------------------
646 // XMLTranscoder: Getter methods
647 // ---------------------------------------------------------------------------
648 inline MemoryManager* XMLTranscoder::getMemoryManager() const
649 {
650 return fMemoryManager;
651 }
652
653 // ---------------------------------------------------------------------------
654 // XMLTranscoder: Protected helper methods
655 // ---------------------------------------------------------------------------
656 inline XMLSize_t XMLTranscoder::getBlockSize() const
657 {
658 return fBlockSize;
659 }
660
661 inline const XMLCh* XMLTranscoder::getEncodingName() const
662 {
663 return fEncodingName;
664 }
665
666 // ---------------------------------------------------------------------------
667 // TranscodeToStr: Getter methods
668 // ---------------------------------------------------------------------------
669 inline const XMLByte *TranscodeToStr::str() const
670 {
671 return fString;
672 }
673
674 inline XMLByte *TranscodeToStr::adopt()
675 {
676 XMLByte *tmp = fString;
677 fString = 0;
678 return tmp;
679 }
680
681 inline XMLSize_t TranscodeToStr::length () const
682 {
683 return fBytesWritten;
684 }
685
686 // ---------------------------------------------------------------------------
687 // TranscodeFromStr: Getter methods
688 // ---------------------------------------------------------------------------
689 inline const XMLCh *TranscodeFromStr::str() const
690 {
691 return fString;
692 }
693
694 inline XMLCh *TranscodeFromStr::adopt()
695 {
696 XMLCh *tmp = fString;
697 fString = 0;
698 return tmp;
699 }
700
701 inline XMLSize_t TranscodeFromStr::length() const
702 {
703 return fCharsWritten;
704 }
705
706 XERCES_CPP_NAMESPACE_END
707
708 #endif
TranscodeFromStr::length
XMLSize_t length() const
Returns the length of the transcoded string in characters.
Definition: TransService.hpp:701
XMemory
This class makes it possible to override the C++ memory management by adding new/delete operators to ...
Definition: XMemory.hpp:40
XMLTranscoder::getBlockSize
XMLSize_t getBlockSize() const
Get the internal block size.
Definition: TransService.hpp:656
XMLTransService::TransRec::extCh
XMLByte extCh
Definition: TransService.hpp:68
XMLPlatformUtils::fgMemoryManager
static MemoryManager * fgMemoryManager
The configurable memory manager.
Definition: PlatformUtils.hpp:121
XMLTranscoder::UnRepOpts
UnRepOpts
This enum is used by the transcodeTo() method to indicate how to react to unrepresentable characters...
Definition: TransService.hpp:225
TranscodeFromStr::adopt
XMLCh * adopt()
Returns the transcoded, null terminated string - adopting the memory allocated to it from the Transco...
Definition: TransService.hpp:694
XMLInitializer
Utilities that must be implemented in a class-specific way.
Definition: XMLInitializer.hpp:37
TranscodeFromStr::str
const XMLCh * str() const
Returns the transcoded, null terminated string.
Definition: TransService.hpp:689
XMLTranscoder::getMemoryManager
MemoryManager * getMemoryManager() const
Get the plugged-in memory manager.
Definition: TransService.hpp:648
TranscodeFromStr
Definition: TransService.hpp:568
XMLTransService::Codes
Codes
Definition: TransService.hpp:57
TranscodeToStr
Definition: TransService.hpp:468
XMLPlatformUtils::isStrictIANAEncoding
static bool isStrictIANAEncoding()
Returns whether a strict IANA encoding name check is enabled or disabled.
TranscodeToStr::length
XMLSize_t length() const
Returns the length of the transcoded string in bytes.
Definition: TransService.hpp:681
XMLTranscoder
XMLTranscoder is for transcoding non-local code page encodings, i.e.
Definition: TransService.hpp:214
XMLTransService::TransRec::intCh
XMLCh intCh
Definition: TransService.hpp:67
XMLPlatformUtils::strictIANAEncoding
static void strictIANAEncoding(const bool state)
This function enables/disables strict IANA encoding names checking.
TranscodeToStr::str
const XMLByte * str() const
Returns the transcoded, null terminated string.
Definition: TransService.hpp:669
PlatformUtils.hpp
MemoryManager
Configurable memory manager.
Definition: MemoryManager.hpp:39
XMLTranscoder::getEncodingName
const XMLCh * getEncodingName() const
Get the encoding name.
Definition: TransService.hpp:661
XMLSize_t
SIZE_T XMLSize_t
Definition: Xerces_autoconf_config.borland.hpp:86
XERCES_CPP_NAMESPACE_BEGIN
#define XERCES_CPP_NAMESPACE_BEGIN
Definition: XercesDefs.hpp:112
XMLPlatformUtils
Utilities that must be implemented in a platform-specific way.
Definition: PlatformUtils.hpp:68
XMLCh
wchar_t XMLCh
Definition: Xerces_autoconf_config.borland.hpp:92
XMLTransService
Definition: TransService.hpp:51
XMLByte
unsigned char XMLByte
Definition: XercesDefs.hpp:65
TranscodeToStr::adopt
XMLByte * adopt()
Returns the transcoded, null terminated string - adopting the memory allocated to it from the Transco...
Definition: TransService.hpp:674
XMLUTIL_EXPORT
#define XMLUTIL_EXPORT
Definition: XercesDefs.hpp:162
XMLTransService::TransRec
Definition: TransService.hpp:65
XERCES_CPP_NAMESPACE_END
#define XERCES_CPP_NAMESPACE_END
Definition: XercesDefs.hpp:113
XMLLCPTranscoder
Definition: TransService.hpp:387
XMemory.hpp
XMLTransService::gMappingsRecognizer
static RefVectorOf< ENameMap > * gMappingsRecognizer
Definition: TransService.hpp:187
XMLTransService::gMappings
static RefHashTableOf< ENameMap > * gMappings
Definition: TransService.hpp:186