rubbos/app/apache2/include/apr_xlate.h

   1 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
   2  * applicable.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * 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 /** @deprecated @see apr_xlate_sb_get */
  96 APU_DECLARE(apr_status_t) apr_xlate_get_sb(apr_xlate_t *convset, int *onoff);
  97
  98 /**
  99  * Convert a buffer of text from one codepage to another.
 100  * @param convset The handle allocated by apr_xlate_open, specifying
 101  *                the parameters of conversion
 102  * @param inbuf The address of the source buffer
 103  * @param inbytes_left Input: the amount of input data to be translated
 104  *                     Output: the amount of input data not yet translated
 105  * @param outbuf The address of the destination buffer
 106  * @param outbytes_left Input: the size of the output buffer
 107  *                      Output: the amount of the output buffer not yet used
 108  * @remark
 109  *  Return APR_ENOTIMPL if charset transcoding is not available
 110  *  in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
 111  */
 112 APU_DECLARE(apr_status_t) apr_xlate_conv_buffer(apr_xlate_t *convset,
 113                                                 const char *inbuf,
 114                                                 apr_size_t *inbytes_left,
 115                                                 char *outbuf,
 116                                                 apr_size_t *outbytes_left);
 117
 118 /* @see apr_file_io.h the comment in apr_file_io.h about this hack */
 119 #ifdef APR_NOT_DONE_YET
 120 /**
 121  * The purpose of apr_xlate_conv_char is to translate one character
 122  * at a time.  This needs to be written carefully so that it works
 123  * with double-byte character sets.
 124  * @param convset The handle allocated by apr_xlate_open, specifying the
 125  *                parameters of conversion
 126  * @param inchar The character to convert
 127  * @param outchar The converted character
 128  */
 129 APU_DECLARE(apr_status_t) apr_xlate_conv_char(apr_xlate_t *convset,
 130                                               char inchar, char outchar);
 131 #endif
 132
 133 /**
 134  * Convert a single-byte character from one charset to another.
 135  * @param convset The handle allocated by apr_xlate_open, specifying the
 136  *                parameters of conversion
 137  * @param inchar The single-byte character to convert.
 138  * @warning This only works when converting between single-byte character sets.
 139  *          -1 will be returned if the conversion can't be performed.
 140  */
 141 APU_DECLARE(apr_int32_t) apr_xlate_conv_byte(apr_xlate_t *convset,
 142                                              unsigned char inchar);
 143
 144 /**
 145  * Close a codepage translation handle.
 146  * @param convset The codepage translation handle to close
 147  * @remark
 148  *  Return APR_ENOTIMPL if charset transcoding is not available
 149  *  in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
 150  */
 151 APU_DECLARE(apr_status_t) apr_xlate_close(apr_xlate_t *convset);
 152
 153 /** @} */
 154 #ifdef __cplusplus
 155 }
 156 #endif
 157
 158 #endif  /* ! APR_XLATE_H */