Xerces-C++: TransService.hpp Source File

Xerces-C++ 3.2.1

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