Xerces-C++  3.2.3
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$
20  */
21 
22 #if !defined(XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP)
23 #define XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP
24 
25 #include <xercesc/util/XMemory.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 
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 //
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  {
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
88  );
89 
90  XMLTranscoder* makeNewTranscoderFor
91  (
92  const char* const encodingName
93  , XMLTransService::Codes& resValue
94  , const XMLSize_t blockSize
96  );
97 
98  XMLTranscoder* makeNewTranscoderFor
99  (
100  XMLRecognizer::Encodings encodingEnum
101  , XMLTransService::Codes& resValue
102  , const XMLSize_t blockSize
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  // -----------------------------------------------------------------------
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 
216 {
217 public :
218 
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  // -----------------------------------------------------------------------
348  (
349  const XMLCh* const encodingName
350  , const XMLSize_t blockSize
352  );
353 
354 
355  // -----------------------------------------------------------------------
356  // Protected helper methods
357  // -----------------------------------------------------------------------
358 
359 private :
360  // -----------------------------------------------------------------------
361  // Unimplemented constructors and operators
362  // -----------------------------------------------------------------------
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 //
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
438  ) = 0;
439 
440  virtual bool transcode
441  (
442  const XMLCh* const toTranscode
443  , char* const toFill
444  , const XMLSize_t maxBytes
446  ) = 0;
447 
448 
449 protected :
450  // -----------------------------------------------------------------------
451  // Hidden constructors
452  // -----------------------------------------------------------------------
454 
455 
456 private :
457  // -----------------------------------------------------------------------
458  // Unimplemented constructors and operators
459  // -----------------------------------------------------------------------
461  XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
462 };
463 
464 //
465 // This class can be used to transcode to a target encoding. It manages the
466 // memory allocated for the transcode in an exception safe manner, automatically
467 // deleting it when the class goes out of scope.
468 //
470 {
471 public:
472  // -----------------------------------------------------------------------
473  // Public constructors and destructor
474  // -----------------------------------------------------------------------
475 
482  TranscodeToStr(const XMLCh *in, const char *encoding,
484 
492  TranscodeToStr(const XMLCh *in, XMLSize_t length, const char *encoding,
494 
501  TranscodeToStr(const XMLCh *in, XMLTranscoder* trans,
503 
511  TranscodeToStr(const XMLCh *in, XMLSize_t length, XMLTranscoder* trans,
513 
514  ~TranscodeToStr();
515 
518 
522  const XMLByte *str() const;
523 
528  XMLByte *adopt();
529 
534  XMLSize_t length () const;
535 
537 
538 private:
539  // -----------------------------------------------------------------------
540  // Unimplemented constructors and operators
541  // -----------------------------------------------------------------------
543  TranscodeToStr &operator=(const TranscodeToStr &);
544 
545  // -----------------------------------------------------------------------
546  // Private helper methods
547  // -----------------------------------------------------------------------
548  void transcode(const XMLCh *in, XMLSize_t len, XMLTranscoder* trans);
549 
550  // -----------------------------------------------------------------------
551  // Private data members
552  //
553  // fString
554  // The transcoded string
555  //
556  // fBytesWritten
557  // The length of the transcoded string in bytes
558  // -----------------------------------------------------------------------
559  ArrayJanitor<XMLByte> fString;
560  XMLSize_t fBytesWritten;
561  MemoryManager *fMemoryManager;
562 };
563 
564 //
565 // This class can be used to transcode from a source encoding. It manages the
566 // memory allocated for the transcode in an exception safe manner, automatically
567 // deleting it when the class goes out of scope.
568 //
570 {
571 public:
572  // -----------------------------------------------------------------------
573  // Public constructors and destructor
574  // -----------------------------------------------------------------------
575 
583  TranscodeFromStr(const XMLByte *data, XMLSize_t length, const char *encoding,
585 
593  TranscodeFromStr(const XMLByte *data, XMLSize_t length, XMLTranscoder *trans,
595 
596  ~TranscodeFromStr();
597 
600 
604  const XMLCh *str() const;
605 
610  XMLCh *adopt();
611 
616  XMLSize_t length() const;
617 
619 
620 private:
621  // -----------------------------------------------------------------------
622  // Unimplemented constructors and operators
623  // -----------------------------------------------------------------------
625  TranscodeFromStr &operator=(const TranscodeFromStr &);
626 
627  // -----------------------------------------------------------------------
628  // Private helper methods
629  // -----------------------------------------------------------------------
630  void transcode(const XMLByte *in, XMLSize_t length, XMLTranscoder *trans);
631 
632  // -----------------------------------------------------------------------
633  // Private data members
634  //
635  // fString
636  // The transcoded string
637  //
638  // fCharsWritten
639  // The length of the transcoded string in characters
640  // -----------------------------------------------------------------------
641  ArrayJanitor<XMLCh> fString;
642  XMLSize_t fCharsWritten;
643  MemoryManager *fMemoryManager;
644 };
645 
646 // ---------------------------------------------------------------------------
647 // XMLTranscoder: Getter methods
648 // ---------------------------------------------------------------------------
650 {
651  return fMemoryManager;
652 }
653 
654 // ---------------------------------------------------------------------------
655 // XMLTranscoder: Protected helper methods
656 // ---------------------------------------------------------------------------
658 {
659  return fBlockSize;
660 }
661 
663 {
664  return fEncodingName;
665 }
666 
667 // ---------------------------------------------------------------------------
668 // TranscodeToStr: Getter methods
669 // ---------------------------------------------------------------------------
670 inline const XMLByte *TranscodeToStr::str() const
671 {
672  return fString.get();
673 }
674 
676 {
677  fBytesWritten = 0;
678  return fString.release();
679 }
680 
682 {
683  return fBytesWritten;
684 }
685 
686 // ---------------------------------------------------------------------------
687 // TranscodeFromStr: Getter methods
688 // ---------------------------------------------------------------------------
689 inline const XMLCh *TranscodeFromStr::str() const
690 {
691  return fString.get();
692 }
693 
695 {
696  fCharsWritten = 0;
697  return fString.release();
698 }
699 
701 {
702  return fCharsWritten;
703 }
704 
706 
707 #endif
XMLTransService::gMappingsRecognizer
static RefVectorOf< ENameMap > * gMappingsRecognizer
Definition: TransService.hpp:188
XMLPlatformUtils::isStrictIANAEncoding
static bool isStrictIANAEncoding()
Returns whether a strict IANA encoding name check is enabled or disabled.
XMemory
This class makes it possible to override the C++ memory management by adding new/delete operators to ...
Definition: XMemory.hpp:40
XMLTranscoder
XMLTranscoder is for transcoding non-local code page encodings, i.e.
Definition: TransService.hpp:215
XERCES_CPP_NAMESPACE_BEGIN
#define XERCES_CPP_NAMESPACE_BEGIN
Definition: XercesDefs.hpp:112
TranscodeToStr::str
const XMLByte * str() const
Returns the transcoded, null terminated string.
Definition: TransService.hpp:670
XERCES_CPP_NAMESPACE_END
#define XERCES_CPP_NAMESPACE_END
Definition: XercesDefs.hpp:113
XMLPlatformUtils::strictIANAEncoding
static void strictIANAEncoding(const bool state)
This function enables/disables strict IANA encoding names checking.
XMLByte
unsigned char XMLByte
Definition: XercesDefs.hpp:65
XMLUTIL_EXPORT
#define XMLUTIL_EXPORT
Definition: XercesDefs.hpp:162
XMLTranscoder::UnRepOpts
UnRepOpts
This enum is used by the transcodeTo() method to indicate how to react to unrepresentable characters.
Definition: TransService.hpp:226
PlatformUtils.hpp
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:649
TranscodeToStr::adopt
XMLByte * adopt()
Returns the transcoded, null terminated string - adopting the memory allocated to it from the Transco...
Definition: TransService.hpp:675
XMLTransService
Definition: TransService.hpp:52
XMLLCPTranscoder
Definition: TransService.hpp:388
XMLCh
uint16_t XMLCh
Definition: Xerces_autoconf_config.hpp:120
XMLPlatformUtils::fgMemoryManager
static MemoryManager * fgMemoryManager
The configurable memory manager.
Definition: PlatformUtils.hpp:121
XMLSize_t
size_t XMLSize_t
Definition: Xerces_autoconf_config.hpp:112
XMLTranscoder::getBlockSize
XMLSize_t getBlockSize() const
Get the internal block size.
Definition: TransService.hpp:657
XMLPlatformUtils
Utilities that must be implemented in a platform-specific way.
Definition: PlatformUtils.hpp:68
TranscodeFromStr::length
XMLSize_t length() const
Returns the length of the transcoded string in characters.
Definition: TransService.hpp:700
XMLInitializer
Utilities that must be implemented in a class-specific way.
Definition: XMLInitializer.hpp:37
XMLTransService::gMappings
static RefHashTableOf< ENameMap > * gMappings
Definition: TransService.hpp:187
XMLTransService::TransRec::intCh
XMLCh intCh
Definition: TransService.hpp:68
TranscodeFromStr::adopt
XMLCh * adopt()
Returns the transcoded, null terminated string - adopting the memory allocated to it from the Transco...
Definition: TransService.hpp:694
XMLTransService::TransRec
Definition: TransService.hpp:66
MemoryManager
Configurable memory manager.
Definition: MemoryManager.hpp:39
TranscodeToStr
Definition: TransService.hpp:469
XMLTransService::TransRec::extCh
XMLByte extCh
Definition: TransService.hpp:69
TranscodeFromStr
Definition: TransService.hpp:569
XMLTransService::Codes
Codes
Definition: TransService.hpp:58
XMLTranscoder::getEncodingName
const XMLCh * getEncodingName() const
Get the encoding name.
Definition: TransService.hpp:662
TranscodeToStr::length
XMLSize_t length() const
Returns the length of the transcoded string in bytes.
Definition: TransService.hpp:681
XMemory.hpp