Apache Portable Runtime
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
File List
Globals
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
usr
include
apr-1
apr_xlate.h
Go to the documentation of this file.
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 */
Generated by
1.8.4