# 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