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-2011, 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 <iconv.h>
00028 #include <string>
00029 
00030 namespace Barry {
00031 
00032 class IConverter;
00033 
00034 //
00035 // IConvHandle class
00036 //
00037 /// Wrapper class for a two-way iconv_t handle pair.  Automatically
00038 /// handles closing in the destructor.
00039 //
00040 class BXEXPORT IConvHandle
00041 {
00042         friend class IConverter;
00043 
00044         iconv_t m_handle;
00045 
00046 private:
00047         // private constructor, used only by IConverter
00048         IConvHandle(const char *fromcode, const char *tocode);
00049 
00050 public:
00051         // custom conversions from any to IConverter's 'tocode'
00052         IConvHandle(const char *fromcode, const IConverter &ic);
00053         // custom conversions from IConverter's 'tocode' to any
00054         IConvHandle(const IConverter &ic, const char *tocode);
00055         ~IConvHandle();
00056 };
00057 
00058 //
00059 // IConverter
00060 //
00061 /// Main charset conversion class, primarily focused on converting
00062 /// between the Blackberry charset and an application-specified one.
00063 /// Additional conversions are possible through custom IConvHandle,
00064 /// but the goal of this class design is to deal with _one_
00065 /// application defined charset, and provide a means to convert
00066 /// to/from that charset to/from any other charset needed by
00067 /// the Blackberry.
00068 ///
00069 /// By default, this class assumes the Blackberry's charset is
00070 /// WINDOWS-1252, but some data, such as SMS message bodies, can have
00071 /// custom charsets as specified by the records.  To convert from
00072 /// such a custom charset, use:
00073 ///
00074 ///      // application sets up IConverter
00075 ///      IConverter ic("UTF-8");
00076 ///
00077 ///      // somewhere in the library, needing to convert
00078 ///      // from UCS2 to whatever the application selected
00079 ///      IConvHandle ucs2("UCS2", ic);
00080 ///      application_string = ic.Convert(ucs2, ucs2_string_data);
00081 ///
00082 ///      // and to convert back...
00083 ///      IConvHandle ucs2_reverse(ic, "UCS2");
00084 ///      ucs2_string = ic.Convert(ucs2_reverse, application_string_data);
00085 ///
00086 class BXEXPORT IConverter
00087 {
00088         friend class IConvHandle;
00089 
00090         IConvHandle m_from;
00091         IConvHandle m_to;
00092         std::string m_tocode;
00093 
00094         // internal buffer for fast conversions
00095         mutable Data m_buffer;
00096 
00097         bool m_throw_on_conv_err;
00098 
00099 private:
00100         std::string Convert(iconv_t cd, const std::string &str) const;
00101 
00102 public:
00103         /// Always throws ErrnoError if unable to open iconv.
00104         /// If throw_on_conv_err is true, then string conversion operations
00105         /// that fail will also throw ErrnoError.
00106         explicit IConverter(const char *tocode = "UTF-8", bool throw_on_conv_err = false);
00107         ~IConverter();
00108 
00109         std::string FromBB(const std::string &str) const;
00110         std::string ToBB(const std::string &str) const;
00111 
00112         // Custom override functions, meant for converting between
00113         // non-BLACKBERRY_CHARSET charsets and the tocode set by the
00114         // IConverter constructor
00115         std::string Convert(const IConvHandle &custom, const std::string &str) const;
00116 };
00117 
00118 } // namespace Barry
00119 
00120 #endif
00121