00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 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 #ifndef APR_XLATE_H 00018 #define APR_XLATE_H 00019 00020 #include "apu.h" 00021 #include "apr_pools.h" 00022 #include "apr_errno.h" 00023 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif /* __cplusplus */ 00027 00028 /** 00029 * @file apr_xlate.h 00030 * @brief APR I18N translation library 00031 */ 00032 00033 /** 00034 * @defgroup APR_XLATE I18N translation library 00035 * @ingroup APR 00036 * @{ 00037 */ 00038 /** Opaque translation buffer */ 00039 typedef struct apr_xlate_t apr_xlate_t; 00040 00041 /** 00042 * Set up for converting text from one charset to another. 00043 * @param convset The handle to be filled in by this function 00044 * @param topage The name of the target charset 00045 * @param frompage The name of the source charset 00046 * @param pool The pool to use 00047 * @remark 00048 * Specify APR_DEFAULT_CHARSET for one of the charset 00049 * names to indicate the charset of the source code at 00050 * compile time. This is useful if there are literal 00051 * strings in the source code which must be translated 00052 * according to the charset of the source code. 00053 * APR_DEFAULT_CHARSET is not useful if the source code 00054 * of the caller was not encoded in the same charset as 00055 * APR at compile time. 00056 * 00057 * @remark 00058 * Specify APR_LOCALE_CHARSET for one of the charset 00059 * names to indicate the charset of the current locale. 00060 * 00061 * @remark 00062 * Return APR_EINVAL if unable to procure a convset, or APR_ENOTIMPL 00063 * if charset transcoding is not available in this instance of 00064 * apr-util at all (i.e., APR_HAS_XLATE is undefined). 00065 */ 00066 APU_DECLARE(apr_status_t) apr_xlate_open(apr_xlate_t **convset, 00067 const char *topage, 00068 const char *frompage, 00069 apr_pool_t *pool); 00070 00071 /** 00072 * This is to indicate the charset of the sourcecode at compile time 00073 * names to indicate the charset of the source code at 00074 * compile time. This is useful if there are literal 00075 * strings in the source code which must be translated 00076 * according to the charset of the source code. 00077 */ 00078 #define APR_DEFAULT_CHARSET (const char *)0 00079 /** 00080 * To indicate charset names of the current locale 00081 */ 00082 #define APR_LOCALE_CHARSET (const char *)1 00083 00084 /** 00085 * Find out whether or not the specified conversion is single-byte-only. 00086 * @param convset The handle allocated by apr_xlate_open, specifying the 00087 * parameters of conversion 00088 * @param onoff Output: whether or not the conversion is single-byte-only 00089 * @remark 00090 * Return APR_ENOTIMPL if charset transcoding is not available 00091 * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 00092 */ 00093 APU_DECLARE(apr_status_t) apr_xlate_sb_get(apr_xlate_t *convset, int *onoff); 00094 00095 /** 00096 * Convert a buffer of text from one codepage to another. 00097 * @param convset The handle allocated by apr_xlate_open, specifying 00098 * the parameters of conversion 00099 * @param inbuf The address of the source buffer 00100 * @param inbytes_left Input: the amount of input data to be translated 00101 * Output: the amount of input data not yet translated 00102 * @param outbuf The address of the destination buffer 00103 * @param outbytes_left Input: the size of the output buffer 00104 * Output: the amount of the output buffer not yet used 00105 * @remark 00106 * Returns APR_ENOTIMPL if charset transcoding is not available 00107 * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 00108 * Returns APR_INCOMPLETE if the input buffer ends in an incomplete 00109 * multi-byte character. 00110 * 00111 * To correctly terminate the output buffer for some multi-byte 00112 * character set encodings, a final call must be made to this function 00113 * after the complete input string has been converted, passing 00114 * the inbuf and inbytes_left parameters as NULL. (Note that this 00115 * mode only works from version 1.1.0 onwards) 00116 */ 00117 APU_DECLARE(apr_status_t) apr_xlate_conv_buffer(apr_xlate_t *convset, 00118 const char *inbuf, 00119 apr_size_t *inbytes_left, 00120 char *outbuf, 00121 apr_size_t *outbytes_left); 00122 00123 /* @see apr_file_io.h the comment in apr_file_io.h about this hack */ 00124 #ifdef APR_NOT_DONE_YET 00125 /** 00126 * The purpose of apr_xlate_conv_char is to translate one character 00127 * at a time. This needs to be written carefully so that it works 00128 * with double-byte character sets. 00129 * @param convset The handle allocated by apr_xlate_open, specifying the 00130 * parameters of conversion 00131 * @param inchar The character to convert 00132 * @param outchar The converted character 00133 */ 00134 APU_DECLARE(apr_status_t) apr_xlate_conv_char(apr_xlate_t *convset, 00135 char inchar, char outchar); 00136 #endif 00137 00138 /** 00139 * Convert a single-byte character from one charset to another. 00140 * @param convset The handle allocated by apr_xlate_open, specifying the 00141 * parameters of conversion 00142 * @param inchar The single-byte character to convert. 00143 * @warning This only works when converting between single-byte character sets. 00144 * -1 will be returned if the conversion can't be performed. 00145 */ 00146 APU_DECLARE(apr_int32_t) apr_xlate_conv_byte(apr_xlate_t *convset, 00147 unsigned char inchar); 00148 00149 /** 00150 * Close a codepage translation handle. 00151 * @param convset The codepage translation handle to close 00152 * @remark 00153 * Return APR_ENOTIMPL if charset transcoding is not available 00154 * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 00155 */ 00156 APU_DECLARE(apr_status_t) apr_xlate_close(apr_xlate_t *convset); 00157 00158 /** @} */ 00159 #ifdef __cplusplus 00160 } 00161 #endif 00162 00163 #endif /* ! APR_XLATE_H */