iconv.h

Go to the documentation of this file.
00001 ///
00002 /// \file       iconv.h
00003 ///             iconv wrapper class, and pluggable interface for records
00004 ///
00005 
00006 /*
00007     Copyright (C) 2008-2012, Net Direct Inc. (http://www.netdirect.ca/)
00008 
00009     This program is free software; you can redistribute it and/or modify
00010     it under the terms of the GNU General Public License as published by
00011     the Free Software Foundation; either version 2 of the License, or
00012     (at your option) any later version.
00013 
00014     This program is distributed in the hope that it will be useful,
00015     but WITHOUT ANY WARRANTY; without even the implied warranty of
00016     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00017 
00018     See the GNU General Public License in the COPYING file at the
00019     root directory of this project for more details.
00020 */
00021 
00022 #ifndef __BARRY_ICONV_H__
00023 #define __BARRY_ICONV_H__
00024 
00025 #include "dll.h"
00026 #include "data.h"
00027 #include <string>
00028 #include <memory>
00029 
00030 namespace Barry {
00031 
00032 class IConverter;
00033 class IConvHandlePrivate;
00034 
00035 //
00036 // IConvHandle class
00037 //
00038 /// Wrapper class for a two-way iconv_t handle pair.  Automatically
00039 /// handles closing in the destructor.
00040 //
00041 class BXEXPORT IConvHandle
00042 {
00043         friend class IConverter;
00044 
00045         std::auto_ptr<IConvHandlePrivate> m_priv;
00046 
00047         bool m_throw_on_conv_err;
00048 
00049 private:
00050         // no copying
00051         IConvHandle(const IConvHandle &other);
00052         IConvHandle& operator=(const IConvHandle &other);
00053 
00054         // private constructor, used only by IConverter
00055         IConvHandle(const char *fromcode, const char *tocode, bool throwable);
00056 
00057         // the heart of the conversion
00058         std::string Convert(Data &tmp, const std::string &str) const;
00059 
00060 public:
00061         // custom conversions from any to IConverter's 'tocode'
00062         IConvHandle(const char *fromcode, const IConverter &ic,
00063                 bool throw_on_conv_err = false);
00064         // custom conversions from IConverter's 'tocode' to any
00065         IConvHandle(const IConverter &ic, const char *tocode,
00066                 bool throw_on_conv_err = false);
00067         ~IConvHandle();
00068 };
00069 
00070 //
00071 // IConverter
00072 //
00073 /// Main charset conversion class, primarily focused on converting
00074 /// between the Blackberry charset and an application-specified one.
00075 /// Additional conversions are possible through custom IConvHandle,
00076 /// but the goal of this class design is to deal with _one_
00077 /// application defined charset, and provide a means to convert
00078 /// to/from that charset to/from any other charset needed by
00079 /// the Blackberry.
00080 ///
00081 /// By default, this class assumes the Blackberry's charset is
00082 /// WINDOWS-1252, but some data, such as SMS message bodies, can have
00083 /// custom charsets as specified by the records.  To convert from
00084 /// such a custom charset, use:
00085 ///
00086 ///      // application sets up IConverter
00087 ///      IConverter ic("UTF-8");
00088 ///
00089 ///      // somewhere in the library, needing to convert
00090 ///      // from UCS2 to whatever the application selected
00091 ///      IConvHandle ucs2("UCS2", ic);
00092 ///      application_string = ic.Convert(ucs2, ucs2_string_data);
00093 ///
00094 ///      // and to convert back...
00095 ///      IConvHandle ucs2_reverse(ic, "UCS2");
00096 ///      ucs2_string = ic.Convert(ucs2_reverse, application_string_data);
00097 ///
00098 class BXEXPORT IConverter
00099 {
00100         friend class IConvHandle;
00101 
00102         IConvHandle m_from;
00103         IConvHandle m_to;
00104         std::string m_tocode;
00105 
00106         // internal buffer for fast conversions
00107         mutable Data m_buffer;
00108 
00109 public:
00110         /// Always throws ErrnoError if unable to open iconv.
00111         /// If throw_on_conv_err is true, then string conversion operations
00112         /// that fail will also throw ErrnoError.
00113         explicit IConverter(const char *tocode = "UTF-8",
00114                 bool throw_on_conv_err = false);
00115         ~IConverter();
00116 
00117         std::string FromBB(const std::string &str) const;
00118         std::string ToBB(const std::string &str) const;
00119 
00120         // Custom override functions, meant for converting between
00121         // non-BLACKBERRY_CHARSET charsets and the tocode set by the
00122         // IConverter constructor
00123         std::string Convert(const IConvHandle &custom, const std::string &str) const;
00124 };
00125 
00126 } // namespace Barry
00127 
00128 #endif
00129