menu: added new Keywords tag to .desktop files
[barry.git] / src / iconv.h
blobc745606d00965cab09dbbb3530b46c05c69ee06f
1 ///
2 /// \file iconv.h
3 /// iconv wrapper class, and pluggable interface for records
4 ///
6 /*
7 Copyright (C) 2008-2013, Net Direct Inc. (http://www.netdirect.ca/)
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
18 See the GNU General Public License in the COPYING file at the
19 root directory of this project for more details.
22 #ifndef __BARRY_ICONV_H__
23 #define __BARRY_ICONV_H__
25 #include "dll.h"
26 #include "data.h"
27 #include <string>
28 #include <memory>
30 namespace Barry {
32 class IConverter;
33 class IConvHandlePrivate;
36 // IConvHandle class
38 /// Wrapper class for a two-way iconv_t handle pair. Automatically
39 /// handles closing in the destructor.
41 class BXEXPORT IConvHandle
43 friend class IConverter;
45 std::auto_ptr<IConvHandlePrivate> m_priv;
47 bool m_throw_on_conv_err;
49 private:
50 // no copying
51 IConvHandle(const IConvHandle &other);
52 IConvHandle& operator=(const IConvHandle &other);
54 // private constructor, used only by IConverter
55 IConvHandle(const char *fromcode, const char *tocode, bool throwable);
57 // the heart of the conversion
58 std::string Convert(Data &tmp, const std::string &str) const;
60 public:
61 // custom conversions from any to IConverter's 'tocode'
62 IConvHandle(const char *fromcode, const IConverter &ic,
63 bool throw_on_conv_err = false);
64 // custom conversions from IConverter's 'tocode' to any
65 IConvHandle(const IConverter &ic, const char *tocode,
66 bool throw_on_conv_err = false);
67 ~IConvHandle();
71 // IConverter
73 /// Main charset conversion class, primarily focused on converting
74 /// between the Blackberry charset and an application-specified one.
75 /// Additional conversions are possible through custom IConvHandle,
76 /// but the goal of this class design is to deal with _one_
77 /// application defined charset, and provide a means to convert
78 /// to/from that charset to/from any other charset needed by
79 /// the Blackberry.
80 ///
81 /// By default, this class assumes the Blackberry's charset is
82 /// WINDOWS-1252, but some data, such as SMS message bodies, can have
83 /// custom charsets as specified by the records. To convert from
84 /// such a custom charset, use:
85 ///
86 /// // application sets up IConverter
87 /// IConverter ic("UTF-8");
88 ///
89 /// // somewhere in the library, needing to convert
90 /// // from UCS2 to whatever the application selected
91 /// IConvHandle ucs2("UCS2", ic);
92 /// application_string = ic.Convert(ucs2, ucs2_string_data);
93 ///
94 /// // and to convert back...
95 /// IConvHandle ucs2_reverse(ic, "UCS2");
96 /// ucs2_string = ic.Convert(ucs2_reverse, application_string_data);
97 ///
98 class BXEXPORT IConverter
100 friend class IConvHandle;
102 IConvHandle m_from;
103 IConvHandle m_to;
104 std::string m_tocode;
106 // internal buffer for fast conversions
107 mutable Data m_buffer;
109 public:
110 /// Always throws ErrnoError if unable to open iconv.
111 /// If throw_on_conv_err is true, then string conversion operations
112 /// that fail will also throw ErrnoError.
113 explicit IConverter(const char *tocode = "UTF-8",
114 bool throw_on_conv_err = false);
115 ~IConverter();
117 std::string FromBB(const std::string &str) const;
118 std::string ToBB(const std::string &str) const;
120 // Custom override functions, meant for converting between
121 // non-BLACKBERRY_CHARSET charsets and the tocode set by the
122 // IConverter constructor
123 std::string Convert(const IConvHandle &custom, const std::string &str) const;
126 } // namespace Barry
128 #endif