apr_xlate.h revision 251876
1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_XLATE_H 18#define APR_XLATE_H 19 20#include "apu.h" 21#include "apr_pools.h" 22#include "apr_errno.h" 23 24#ifdef __cplusplus 25extern "C" { 26#endif /* __cplusplus */ 27 28/** 29 * @file apr_xlate.h 30 * @brief APR I18N translation library 31 */ 32 33/** 34 * @defgroup APR_XLATE I18N translation library 35 * @ingroup APR 36 * @{ 37 */ 38/** Opaque translation buffer */ 39typedef struct apr_xlate_t apr_xlate_t; 40 41/** 42 * Set up for converting text from one charset to another. 43 * @param convset The handle to be filled in by this function 44 * @param topage The name of the target charset 45 * @param frompage The name of the source charset 46 * @param pool The pool to use 47 * @remark 48 * Specify APR_DEFAULT_CHARSET for one of the charset 49 * names to indicate the charset of the source code at 50 * compile time. This is useful if there are literal 51 * strings in the source code which must be translated 52 * according to the charset of the source code. 53 * APR_DEFAULT_CHARSET is not useful if the source code 54 * of the caller was not encoded in the same charset as 55 * APR at compile time. 56 * 57 * @remark 58 * Specify APR_LOCALE_CHARSET for one of the charset 59 * names to indicate the charset of the current locale. 60 * 61 * @remark 62 * Return APR_EINVAL if unable to procure a convset, or APR_ENOTIMPL 63 * if charset transcoding is not available in this instance of 64 * apr-util at all (i.e., APR_HAS_XLATE is undefined). 65 */ 66APU_DECLARE(apr_status_t) apr_xlate_open(apr_xlate_t **convset, 67 const char *topage, 68 const char *frompage, 69 apr_pool_t *pool); 70 71/** 72 * This is to indicate the charset of the sourcecode at compile time 73 * names to indicate the charset of the source code at 74 * compile time. This is useful if there are literal 75 * strings in the source code which must be translated 76 * according to the charset of the source code. 77 */ 78#define APR_DEFAULT_CHARSET (const char *)0 79/** 80 * To indicate charset names of the current locale 81 */ 82#define APR_LOCALE_CHARSET (const char *)1 83 84/** 85 * Find out whether or not the specified conversion is single-byte-only. 86 * @param convset The handle allocated by apr_xlate_open, specifying the 87 * parameters of conversion 88 * @param onoff Output: whether or not the conversion is single-byte-only 89 * @remark 90 * Return APR_ENOTIMPL if charset transcoding is not available 91 * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 92 */ 93APU_DECLARE(apr_status_t) apr_xlate_sb_get(apr_xlate_t *convset, int *onoff); 94 95/** 96 * Convert a buffer of text from one codepage to another. 97 * @param convset The handle allocated by apr_xlate_open, specifying 98 * the parameters of conversion 99 * @param inbuf The address of the source buffer 100 * @param inbytes_left Input: the amount of input data to be translated 101 * Output: the amount of input data not yet translated 102 * @param outbuf The address of the destination buffer 103 * @param outbytes_left Input: the size of the output buffer 104 * Output: the amount of the output buffer not yet used 105 * @remark 106 * Returns APR_ENOTIMPL if charset transcoding is not available 107 * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 108 * Returns APR_INCOMPLETE if the input buffer ends in an incomplete 109 * multi-byte character. 110 * 111 * To correctly terminate the output buffer for some multi-byte 112 * character set encodings, a final call must be made to this function 113 * after the complete input string has been converted, passing 114 * the inbuf and inbytes_left parameters as NULL. (Note that this 115 * mode only works from version 1.1.0 onwards) 116 */ 117APU_DECLARE(apr_status_t) apr_xlate_conv_buffer(apr_xlate_t *convset, 118 const char *inbuf, 119 apr_size_t *inbytes_left, 120 char *outbuf, 121 apr_size_t *outbytes_left); 122 123/* @see apr_file_io.h the comment in apr_file_io.h about this hack */ 124#ifdef APR_NOT_DONE_YET 125/** 126 * The purpose of apr_xlate_conv_char is to translate one character 127 * at a time. This needs to be written carefully so that it works 128 * with double-byte character sets. 129 * @param convset The handle allocated by apr_xlate_open, specifying the 130 * parameters of conversion 131 * @param inchar The character to convert 132 * @param outchar The converted character 133 */ 134APU_DECLARE(apr_status_t) apr_xlate_conv_char(apr_xlate_t *convset, 135 char inchar, char outchar); 136#endif 137 138/** 139 * Convert a single-byte character from one charset to another. 140 * @param convset The handle allocated by apr_xlate_open, specifying the 141 * parameters of conversion 142 * @param inchar The single-byte character to convert. 143 * @warning This only works when converting between single-byte character sets. 144 * -1 will be returned if the conversion can't be performed. 145 */ 146APU_DECLARE(apr_int32_t) apr_xlate_conv_byte(apr_xlate_t *convset, 147 unsigned char inchar); 148 149/** 150 * Close a codepage translation handle. 151 * @param convset The codepage translation handle to close 152 * @remark 153 * Return APR_ENOTIMPL if charset transcoding is not available 154 * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 155 */ 156APU_DECLARE(apr_status_t) apr_xlate_close(apr_xlate_t *convset); 157 158/** @} */ 159#ifdef __cplusplus 160} 161#endif 162 163#endif /* ! APR_XLATE_H */ 164