1251876Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251876Speter * contributor license agreements. See the NOTICE file distributed with 3251876Speter * this work for additional information regarding copyright ownership. 4251876Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251876Speter * (the "License"); you may not use this file except in compliance with 6251876Speter * the License. You may obtain a copy of the License at 7251876Speter * 8251876Speter * http://www.apache.org/licenses/LICENSE-2.0 9251876Speter * 10251876Speter * Unless required by applicable law or agreed to in writing, software 11251876Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251876Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251876Speter * See the License for the specific language governing permissions and 14251876Speter * limitations under the License. 15251876Speter */ 16251876Speter 17251876Speter#ifndef APR_XLATE_H 18251876Speter#define APR_XLATE_H 19251876Speter 20251876Speter#include "apu.h" 21251876Speter#include "apr_pools.h" 22251876Speter#include "apr_errno.h" 23251876Speter 24251876Speter#ifdef __cplusplus 25251876Speterextern "C" { 26251876Speter#endif /* __cplusplus */ 27251876Speter 28251876Speter/** 29251876Speter * @file apr_xlate.h 30251876Speter * @brief APR I18N translation library 31251876Speter */ 32251876Speter 33251876Speter/** 34251876Speter * @defgroup APR_XLATE I18N translation library 35251876Speter * @ingroup APR 36251876Speter * @{ 37251876Speter */ 38251876Speter/** Opaque translation buffer */ 39251876Spetertypedef struct apr_xlate_t apr_xlate_t; 40251876Speter 41251876Speter/** 42251876Speter * Set up for converting text from one charset to another. 43251876Speter * @param convset The handle to be filled in by this function 44251876Speter * @param topage The name of the target charset 45251876Speter * @param frompage The name of the source charset 46251876Speter * @param pool The pool to use 47251876Speter * @remark 48251876Speter * Specify APR_DEFAULT_CHARSET for one of the charset 49251876Speter * names to indicate the charset of the source code at 50251876Speter * compile time. This is useful if there are literal 51251876Speter * strings in the source code which must be translated 52251876Speter * according to the charset of the source code. 53251876Speter * APR_DEFAULT_CHARSET is not useful if the source code 54251876Speter * of the caller was not encoded in the same charset as 55251876Speter * APR at compile time. 56251876Speter * 57251876Speter * @remark 58251876Speter * Specify APR_LOCALE_CHARSET for one of the charset 59251876Speter * names to indicate the charset of the current locale. 60251876Speter * 61251876Speter * @remark 62251876Speter * Return APR_EINVAL if unable to procure a convset, or APR_ENOTIMPL 63251876Speter * if charset transcoding is not available in this instance of 64251876Speter * apr-util at all (i.e., APR_HAS_XLATE is undefined). 65251876Speter */ 66251876SpeterAPU_DECLARE(apr_status_t) apr_xlate_open(apr_xlate_t **convset, 67251876Speter const char *topage, 68251876Speter const char *frompage, 69251876Speter apr_pool_t *pool); 70251876Speter 71251876Speter/** 72251876Speter * This is to indicate the charset of the sourcecode at compile time 73251876Speter * names to indicate the charset of the source code at 74251876Speter * compile time. This is useful if there are literal 75251876Speter * strings in the source code which must be translated 76251876Speter * according to the charset of the source code. 77251876Speter */ 78251876Speter#define APR_DEFAULT_CHARSET (const char *)0 79251876Speter/** 80251876Speter * To indicate charset names of the current locale 81251876Speter */ 82251876Speter#define APR_LOCALE_CHARSET (const char *)1 83251876Speter 84251876Speter/** 85251876Speter * Find out whether or not the specified conversion is single-byte-only. 86251876Speter * @param convset The handle allocated by apr_xlate_open, specifying the 87251876Speter * parameters of conversion 88251876Speter * @param onoff Output: whether or not the conversion is single-byte-only 89251876Speter * @remark 90251876Speter * Return APR_ENOTIMPL if charset transcoding is not available 91251876Speter * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 92251876Speter */ 93251876SpeterAPU_DECLARE(apr_status_t) apr_xlate_sb_get(apr_xlate_t *convset, int *onoff); 94251876Speter 95251876Speter/** 96251876Speter * Convert a buffer of text from one codepage to another. 97251876Speter * @param convset The handle allocated by apr_xlate_open, specifying 98251876Speter * the parameters of conversion 99251876Speter * @param inbuf The address of the source buffer 100251876Speter * @param inbytes_left Input: the amount of input data to be translated 101251876Speter * Output: the amount of input data not yet translated 102251876Speter * @param outbuf The address of the destination buffer 103251876Speter * @param outbytes_left Input: the size of the output buffer 104251876Speter * Output: the amount of the output buffer not yet used 105251876Speter * @remark 106251876Speter * Returns APR_ENOTIMPL if charset transcoding is not available 107251876Speter * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 108251876Speter * Returns APR_INCOMPLETE if the input buffer ends in an incomplete 109251876Speter * multi-byte character. 110251876Speter * 111251876Speter * To correctly terminate the output buffer for some multi-byte 112251876Speter * character set encodings, a final call must be made to this function 113251876Speter * after the complete input string has been converted, passing 114251876Speter * the inbuf and inbytes_left parameters as NULL. (Note that this 115251876Speter * mode only works from version 1.1.0 onwards) 116251876Speter */ 117251876SpeterAPU_DECLARE(apr_status_t) apr_xlate_conv_buffer(apr_xlate_t *convset, 118251876Speter const char *inbuf, 119251876Speter apr_size_t *inbytes_left, 120251876Speter char *outbuf, 121251876Speter apr_size_t *outbytes_left); 122251876Speter 123251876Speter/* @see apr_file_io.h the comment in apr_file_io.h about this hack */ 124251876Speter#ifdef APR_NOT_DONE_YET 125251876Speter/** 126251876Speter * The purpose of apr_xlate_conv_char is to translate one character 127251876Speter * at a time. This needs to be written carefully so that it works 128251876Speter * with double-byte character sets. 129251876Speter * @param convset The handle allocated by apr_xlate_open, specifying the 130251876Speter * parameters of conversion 131251876Speter * @param inchar The character to convert 132251876Speter * @param outchar The converted character 133251876Speter */ 134251876SpeterAPU_DECLARE(apr_status_t) apr_xlate_conv_char(apr_xlate_t *convset, 135251876Speter char inchar, char outchar); 136251876Speter#endif 137251876Speter 138251876Speter/** 139251876Speter * Convert a single-byte character from one charset to another. 140251876Speter * @param convset The handle allocated by apr_xlate_open, specifying the 141251876Speter * parameters of conversion 142251876Speter * @param inchar The single-byte character to convert. 143251876Speter * @warning This only works when converting between single-byte character sets. 144251876Speter * -1 will be returned if the conversion can't be performed. 145251876Speter */ 146251876SpeterAPU_DECLARE(apr_int32_t) apr_xlate_conv_byte(apr_xlate_t *convset, 147251876Speter unsigned char inchar); 148251876Speter 149251876Speter/** 150251876Speter * Close a codepage translation handle. 151251876Speter * @param convset The codepage translation handle to close 152251876Speter * @remark 153251876Speter * Return APR_ENOTIMPL if charset transcoding is not available 154251876Speter * in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). 155251876Speter */ 156251876SpeterAPU_DECLARE(apr_status_t) apr_xlate_close(apr_xlate_t *convset); 157251876Speter 158251876Speter/** @} */ 159251876Speter#ifdef __cplusplus 160251876Speter} 161251876Speter#endif 162251876Speter 163251876Speter#endif /* ! APR_XLATE_H */ 164