Annotation of win32/apache22/srclib/apr-util/include/apr_xlate.h, revision 1.1
1.1 ! moko 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
! 25: extern "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 */
! 39: typedef 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: */
! 66: APU_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: */
! 93: APU_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: */
! 117: APU_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: */
! 134: APU_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: */
! 146: APU_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: */
! 156: APU_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 */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_xlate.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr-util / include