http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Release Info

Installation
Download
Build

FAQs
Samples
API Docs

DOM C++ Binding
Programming
Migration Guide

Feedback
Bug-Reporting
PDF Document

CVS Repository
Mail Archive

API Docs for SAX and DOM
 

Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

TransService.hpp

Go to the documentation of this file.
00001 /*
00002  * Copyright 1999-2001,2004 The Apache Software Foundation.
00003  * 
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  * 
00008  *      http://www.apache.org/licenses/LICENSE-2.0
00009  * 
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /*
00018  * $Log: TransService.hpp,v $
00019  * Revision 1.14  2004/09/08 13:56:23  peiyongz
00020  * Apache License Version 2.0
00021  *
00022  * Revision 1.13  2004/05/19 20:51:20  peiyongz
00023  * XML1.0-3rd Edition: UTF_8
00024  *
00025  * Revision 1.12  2004/01/29 11:48:46  cargilld
00026  * Code cleanup changes to get rid of various compiler diagnostic messages.
00027  *
00028  * Revision 1.11  2003/12/24 15:24:13  cargilld
00029  * More updates to memory management so that the static memory manager.
00030  *
00031  * Revision 1.10  2003/11/24 19:52:06  neilg
00032  * allow classes derived from XMLTransService to tailor the intrinsic maps to their taste.
00033  *
00034  * Revision 1.9  2003/06/03 18:12:29  knoaman
00035  * Add default value for memory manager argument.
00036  *
00037  * Revision 1.8  2003/05/15 19:07:45  knoaman
00038  * Partial implementation of the configurable memory manager.
00039  *
00040  * Revision 1.7  2003/03/07 18:11:55  tng
00041  * Return a reference instead of void for operator=
00042  *
00043  * Revision 1.6  2003/02/04 22:11:52  peiyongz
00044  * bug#16784: Obsolete documentation on XMLTranscoder -- reported by
00045  * Colin Paul Adams, Preston Lancashire
00046  *
00047  * Revision 1.5  2002/11/25 21:27:52  tng
00048  * Performance: use XMLRecognizer::Encodings enum to make new transcode, faster than comparing the encoding string every time.
00049  *
00050  * Revision 1.4  2002/11/04 15:22:04  tng
00051  * C++ Namespace Support.
00052  *
00053  * Revision 1.3  2002/07/18 20:05:31  knoaman
00054  * Add a new feature to control strict IANA encoding name.
00055  *
00056  * Revision 1.2  2002/04/09 15:44:00  knoaman
00057  * Add lower case string support.
00058  *
00059  * Revision 1.1.1.1  2002/02/01 22:22:13  peiyongz
00060  * sane_include
00061  *
00062  * Revision 1.14  2001/11/01 23:37:07  jasons
00063  * 2001-11-01  Jason E. Stewart  <jason@openinformatics.com>
00064  *
00065  *  * src/util/TransService.hpp (Repository):
00066  *  Updated Doxygen documentation for XMLTranscoder class
00067  *
00068  * Revision 1.13  2001/05/11 13:26:30  tng
00069  * Copyright update.
00070  *
00071  * Revision 1.12  2001/01/25 19:19:32  tng
00072  * Let user add their encoding to the intrinsic mapping table.  Added by Khaled Noaman.
00073  *
00074  * Revision 1.11  2000/04/12 22:57:45  roddey
00075  * A couple of fixes to comments and parameter names to make them
00076  * more correct.
00077  *
00078  * Revision 1.10  2000/03/28 19:43:19  roddey
00079  * Fixes for signed/unsigned warnings. New work for two way transcoding
00080  * stuff.
00081  *
00082  * Revision 1.9  2000/03/17 23:59:54  roddey
00083  * Initial updates for two way transcoding support
00084  *
00085  * Revision 1.8  2000/03/02 19:54:46  roddey
00086  * This checkin includes many changes done while waiting for the
00087  * 1.1.0 code to be finished. I can't list them all here, but a list is
00088  * available elsewhere.
00089  *
00090  * Revision 1.7  2000/02/24 20:05:25  abagchi
00091  * Swat for removing Log from API docs
00092  *
00093  * Revision 1.6  2000/02/06 07:48:04  rahulj
00094  * Year 2K copyright swat.
00095  *
00096  * Revision 1.5  2000/01/25 22:49:55  roddey
00097  * Moved the supportsSrcOfs() method from the individual transcoder to the
00098  * transcoding service, where it should have been to begin with.
00099  *
00100  * Revision 1.4  2000/01/25 19:19:07  roddey
00101  * Simple addition of a getId() method to the xcode and netacess abstractions to
00102  * allow each impl to give back an id string.
00103  *
00104  * Revision 1.3  1999/12/18 00:18:10  roddey
00105  * More changes to support the new, completely orthagonal support for
00106  * intrinsic encodings.
00107  *
00108  * Revision 1.2  1999/12/15 19:41:28  roddey
00109  * Support for the new transcoder system, where even intrinsic encodings are
00110  * done via the same transcoder abstraction as external ones.
00111  *
00112  * Revision 1.1.1.1  1999/11/09 01:05:16  twl
00113  * Initial checkin
00114  *
00115  * Revision 1.2  1999/11/08 20:45:16  rahul
00116  * Swat for adding in Product name and CVS comment log variable.
00117  *
00118  */
00119 
00120 #ifndef TRANSSERVICE_HPP
00121 #define TRANSSERVICE_HPP
00122 
00123 #include <xercesc/util/XMemory.hpp>
00124 #include <xercesc/util/PlatformUtils.hpp>
00125 #include <xercesc/framework/XMLRecognizer.hpp>
00126 #include <xercesc/util/RefHashTableOf.hpp>
00127 #include <xercesc/util/RefVectorOf.hpp>
00128 
00129 XERCES_CPP_NAMESPACE_BEGIN
00130 
00131 // Forward references
00132 //class XMLPlatformUtils;
00133 class XMLLCPTranscoder;
00134 class XMLTranscoder;
00135 class ENameMap;
00136 
00137 
00138 //
00139 //  This class is an abstract base class which are used to abstract the
00140 //  transcoding services that Xerces uses. The parser's actual transcoding
00141 //  needs are small so it is desirable to allow different implementations
00142 //  to be provided.
00143 //
00144 //  The transcoding service has to provide a couple of required string
00145 //  and character operations, but its most important service is the creation
00146 //  of transcoder objects. There are two types of transcoders, which are
00147 //  discussed below in the XMLTranscoder class' description.
00148 //
00149 class  XMLTransService : public XMemory
00150 {
00151 public :
00152     // -----------------------------------------------------------------------
00153     //  Class specific types
00154     // -----------------------------------------------------------------------
00155     enum Codes
00156     {
00157         Ok
00158         , UnsupportedEncoding
00159         , InternalFailure
00160         , SupportFilesNotFound
00161     };
00162 
00163     struct TransRec
00164     {
00165         XMLCh       intCh;
00166         XMLByte     extCh;
00167     };
00168 
00169 
00170     // -----------------------------------------------------------------------
00171     //  Public constructors and destructor
00172     // -----------------------------------------------------------------------
00173     virtual ~XMLTransService();
00174 
00175 
00176     // -----------------------------------------------------------------------
00177     //  Non-virtual API
00178     // -----------------------------------------------------------------------
00179     XMLTranscoder* makeNewTranscoderFor
00180     (
00181         const   XMLCh* const            encodingName
00182         ,       XMLTransService::Codes& resValue
00183         , const unsigned int            blockSize
00184         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
00185     );
00186 
00187     XMLTranscoder* makeNewTranscoderFor
00188     (
00189         const   char* const             encodingName
00190         ,       XMLTransService::Codes& resValue
00191         , const unsigned int            blockSize
00192         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
00193     );
00194 
00195     XMLTranscoder* makeNewTranscoderFor
00196     (
00197         XMLRecognizer::Encodings        encodingEnum
00198         ,       XMLTransService::Codes& resValue
00199         , const unsigned int            blockSize
00200         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
00201     );
00202 
00203 
00204     // -----------------------------------------------------------------------
00205     //  The virtual transcoding service API
00206     // -----------------------------------------------------------------------
00207     virtual int compareIString
00208     (
00209         const   XMLCh* const    comp1
00210         , const XMLCh* const    comp2
00211     ) = 0;
00212 
00213     virtual int compareNIString
00214     (
00215         const   XMLCh* const    comp1
00216         , const XMLCh* const    comp2
00217         , const unsigned int    maxChars
00218     ) = 0;
00219 
00220     virtual const XMLCh* getId() const = 0;
00221 
00222     virtual bool isSpace(const XMLCh toCheck) const = 0;
00223 
00224     virtual XMLLCPTranscoder* makeNewLCPTranscoder() = 0;
00225 
00226     virtual bool supportsSrcOfs() const = 0;
00227 
00228     virtual void upperCase(XMLCh* const toUpperCase) const = 0;
00229     virtual void lowerCase(XMLCh* const toLowerCase) const = 0;
00230 
00231     // -----------------------------------------------------------------------
00232     //  Allow users to add their own encodings to the intrinsinc mapping
00233     //  table
00234     //  Usage:
00235     //      XMLTransService::addEncoding (
00236     //          gMyEncodingNameString
00237     //          , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
00238     //      );
00239     // -----------------------------------------------------------------------
00240     static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
00241 
00242 
00243 protected :
00244     // -----------------------------------------------------------------------
00245     //  Hidden constructors
00246     // -----------------------------------------------------------------------
00247     XMLTransService();
00248 
00249 
00250     // -----------------------------------------------------------------------
00251     //  Protected virtual methods.
00252     // -----------------------------------------------------------------------
00253     virtual XMLTranscoder* makeNewXMLTranscoder
00254     (
00255         const   XMLCh* const            encodingName
00256         ,       XMLTransService::Codes& resValue
00257         , const unsigned int            blockSize
00258         , MemoryManager* const          manager
00259     ) = 0;
00260 
00261     // -----------------------------------------------------------------------
00262     //  Protected init method for platform utils to call
00263     // -----------------------------------------------------------------------
00264     friend class XMLPlatformUtils;
00265     virtual void initTransService();
00266 
00267     // -----------------------------------------------------------------------
00268     // protected static members
00269     //  gMappings
00270     //      This is a hash table of ENameMap objects. It is created and filled
00271     //      in when the platform init calls our initTransService() method.
00272     //
00273     //  gMappingsRecognizer
00274     //      This is an array of ENameMap objects, predefined for those
00275     //      already recognized by XMLRecognizer::Encodings.
00276     //
00277 
00278     static RefHashTableOf<ENameMap>*    gMappings;
00279     static RefVectorOf<ENameMap>*       gMappingsRecognizer;
00280 
00281 private :
00282     // -----------------------------------------------------------------------
00283     //  Unimplemented constructors and operators
00284     // -----------------------------------------------------------------------
00285     XMLTransService(const XMLTransService&);
00286     XMLTransService& operator=(const XMLTransService&);
00287 
00288     // -----------------------------------------------------------------------
00289     //  Hidden method to enable/disable strict IANA encoding check
00290     //  Caller: XMLPlatformUtils
00291     // -----------------------------------------------------------------------
00292     void strictIANAEncoding(const bool newState);
00293     bool isStrictIANAEncoding();
00294     static void reinitMappings();
00295     static void reinitMappingsRecognizer();
00296 
00297 };
00298 
00299 
00300 
00317 class  XMLTranscoder : public XMemory
00318 {
00319 public :
00320 
00328     enum UnRepOpts
00329     {
00330         UnRep_Throw     
00331         , UnRep_RepChar     
00332     };
00333 
00334 
00337 
00342     virtual ~XMLTranscoder();
00344 
00345 
00346 
00349 
00369     virtual unsigned int transcodeFrom
00370     (
00371         const   XMLByte* const          srcData
00372         , const unsigned int            srcCount
00373         ,       XMLCh* const            toFill
00374         , const unsigned int            maxChars
00375         ,       unsigned int&           bytesEaten
00376         ,       unsigned char* const    charSizes
00377     ) = 0;
00378 
00392     virtual unsigned int transcodeTo
00393     (
00394         const   XMLCh* const    srcData
00395         , const unsigned int    srcCount
00396         ,       XMLByte* const  toFill
00397         , const unsigned int    maxBytes
00398         ,       unsigned int&   charsEaten
00399         , const UnRepOpts       options
00400     ) = 0;
00401 
00407     virtual bool canTranscodeTo
00408     (
00409         const   unsigned int    toCheck
00410     )   const = 0;
00411 
00413 
00416 
00421     unsigned int getBlockSize() const;
00422 
00428     const XMLCh* getEncodingName() const;
00430 
00433 
00441     MemoryManager* getMemoryManager() const;
00442 
00444 
00445 protected :
00446     // -----------------------------------------------------------------------
00447     //  Hidden constructors
00448     // -----------------------------------------------------------------------
00449     XMLTranscoder
00450     (
00451         const   XMLCh* const    encodingName
00452         , const unsigned int    blockSize
00453         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00454     );
00455 
00456 
00457     // -----------------------------------------------------------------------
00458     //  Protected helper methods
00459     // -----------------------------------------------------------------------
00460     // As the body of this function is commented out it could be removed.
00461     // However, currently all calls to it are guarded by #if defined(XERCES_DEBUG)
00462     // so will leave it for now.
00463     void checkBlockSize(const unsigned int toCheck);
00464 
00465 
00466 private :
00467     // -----------------------------------------------------------------------
00468     //  Unimplemented constructors and operators
00469     // -----------------------------------------------------------------------
00470     XMLTranscoder(const XMLTranscoder&);
00471     XMLTranscoder& operator=(const XMLTranscoder&);
00472 
00473     // -----------------------------------------------------------------------
00474     //  Private data members
00475     //
00476     //  fBlockSize
00477     //      This is the block size indicated in the constructor.
00478     //
00479     //  fEncodingName
00480     //      This is the name of the encoding this encoder is for. All basic
00481     //      XML transcoder's are for named encodings.
00482     // -----------------------------------------------------------------------
00483     unsigned int    fBlockSize;
00484     XMLCh*          fEncodingName;
00485     MemoryManager*  fMemoryManager;
00486 };
00487 
00488 
00489 //
00490 //  This class is a specialized transcoder that only transcodes between
00491 //  the internal XMLCh format and the local code page. It is specialized
00492 //  for the very common job of translating data from the client app's
00493 //  native code page to the internal format and vice versa.
00494 //
00495 class  XMLLCPTranscoder : public XMemory
00496 {
00497 public :
00498     // -----------------------------------------------------------------------
00499     //  Public constructors and destructor
00500     // -----------------------------------------------------------------------
00501     virtual ~XMLLCPTranscoder();
00502 
00503 
00504     // -----------------------------------------------------------------------
00505     //  The virtual transcoder API
00506     //
00507     //  NOTE:   All these APIs don't include null terminator characters in
00508     //          their parameters. So calcRequiredSize() returns the number
00509     //          of actual chars, not including the null. maxBytes and maxChars
00510     //          parameters refer to actual chars, not including the null so
00511     //          its assumed that the buffer is physically one char or byte
00512     //          larger.
00513     // -----------------------------------------------------------------------
00514     virtual unsigned int calcRequiredSize(const char* const srcText
00515         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
00516 
00517     virtual unsigned int calcRequiredSize(const XMLCh* const srcText
00518         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
00519 
00520     virtual char* transcode(const XMLCh* const toTranscode) = 0;
00521     virtual char* transcode(const XMLCh* const toTranscode,
00522                             MemoryManager* const manager) = 0;
00523 
00524     virtual XMLCh* transcode(const char* const toTranscode) = 0;
00525     virtual XMLCh* transcode(const char* const toTranscode,
00526                              MemoryManager* const manager) = 0;
00527 
00528     virtual bool transcode
00529     (
00530         const   char* const     toTranscode
00531         ,       XMLCh* const    toFill
00532         , const unsigned int    maxChars
00533         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00534     ) = 0;
00535 
00536     virtual bool transcode
00537     (
00538         const   XMLCh* const    toTranscode
00539         ,       char* const     toFill
00540         , const unsigned int    maxBytes
00541         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00542     ) = 0;
00543 
00544 
00545 protected :
00546     // -----------------------------------------------------------------------
00547     //  Hidden constructors
00548     // -----------------------------------------------------------------------
00549     XMLLCPTranscoder();
00550 
00551 
00552 private :
00553     // -----------------------------------------------------------------------
00554     //  Unimplemented constructors and operators
00555     // -----------------------------------------------------------------------
00556     XMLLCPTranscoder(const XMLLCPTranscoder&);
00557     XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
00558 };
00559 
00560 
00561 // ---------------------------------------------------------------------------
00562 //  XMLTranscoder: Getter methods
00563 // ---------------------------------------------------------------------------
00564 inline MemoryManager* XMLTranscoder::getMemoryManager() const
00565 {
00566     return fMemoryManager;
00567 }
00568 
00569 // ---------------------------------------------------------------------------
00570 //  XMLTranscoder: Protected helper methods
00571 // ---------------------------------------------------------------------------
00572 inline unsigned int XMLTranscoder::getBlockSize() const
00573 {
00574     return fBlockSize;
00575 }
00576 
00577 inline const XMLCh* XMLTranscoder::getEncodingName() const
00578 {
00579     return fEncodingName;
00580 }
00581 
00582 XERCES_CPP_NAMESPACE_END
00583 
00584 #endif


Copyright © 1994-2004 The Apache Software Foundation. All Rights Reserved.