include/apr_xlate.h

   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 */