gecko-dev/modules/libnls/headers/nlsenc.h

348 lines
11 KiB
C

/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* The contents of this file are subject to the Netscape Public
* License Version 1.1 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.mozilla.org/NPL/
*
* Software distributed under the License is distributed on an "AS
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
* implied. See the License for the specific language governing
* rights and limitations under the License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is Netscape
* Communications Corporation. Portions created by Netscape are
* Copyright (C) 1998 Netscape Communications Corporation. All
* Rights Reserved.
*
* Contributor(s):
*/
#ifndef _NLSENC_H
#define _NLSENC_H
#include "nlsxp.h"
#include "enconv.h"
NLS_BEGIN_PROTOS
/********************** Library Initialization ***********************/
/* NLS_EncInitialize
*
* Initialize the libcnv library. The dataDirectory is a full or
* partial platform specific path specification under which the library may
* can find the "converters" sub directories.
*
* Status Return
* NLS_SUCCESS
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_EncInitialize(const NLS_ThreadInfo * threadInfo, const char * dataDirectory);
/* NLS_EncTerminate
*
* Terminate the library
*
* Status Return
* NLS_SUCCESS
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_EncTerminate(void);
/*********************************************
Simple Conversion Routines
********************************************/
/* NLS_EncodingConverterExists
*
* Tests for the existence of an encoding converter for the source/target
* encoding conversion. Encoding names will be normalized by this function
* to resolve encoding aliases etc.
*/
NLSCNVAPI_PUBLIC(nlsBool)
NLS_EncodingConverterExists(const char *from_charset, const char *to_charset);
/* NLS_ConvertBuffer
*
* Converts the source buffer/size to the target buffer/size based on the
* source/target encoding information. The encoding names will be normalized
* by this function to resolve encoding aliases etc. Use NLS_GetResultBufferSize
* to calculate the best output buffer size based on the input encoding.
*
* Status Returns
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
* NLS_NEW_CONVERTER_FAILED - Function failed
* NLS_NO_FROM_ENCODING - No to encoding exists
* NLS_NO_TO_ENCODING - No from encoding exists
* NLS_NEW_CONVERTER_FAILED - No converter exists
*
* NLS_RESULT_TRUNCATED - Output buffer was too small,
* result was truncated
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_ConvertBuffer(const char *from_charset, const char *to_charset,
const byte *inputBuffer, size_t inputBufferLength,
byte * outputBuffer, size_t outputBufferLength, size_t * convertedLength);
/*********************************************
Streaming Conversion Routines
********************************************/
/* NLS_NewEncodingConverter
*
* Create a new encoding converter instance. The encoding names will be normalized
* by this function to resolve encoding aliases etc.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
* NLS_NEW_CONVERTER_FAILED - Function failed
* NLS_NO_FROM_ENCODING - No to encoding exists
* NLS_NO_TO_ENCODING - No from encoding exists
* NLS_NEW_CONVERTER_FAILED - No converter exists
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_NewEncodingConverter(const char *from_charset, const char *to_charset, EncodingConverter** converter);
/* NLS_DeleteEncodingConverter
*
* Delete the encoding converter instance.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_DeleteEncodingConverter(EncodingConverter * converter);
/* NLS_ConvertStreamBuffer
*
* Converts the source buffer/size to the target buffer/size based on the
* source/target encoding information. The encoding names will be normalized
* by this function to resolve encoding aliases etc. Use NLS_GetResultBufferSize
* to calculate the best output buffer size based on the input encoding.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
* NLS_RESULT_TRUNCATED - Output buffer was too small,
* result was truncated
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_ConvertStreamBuffer(EncodingConverter * converter, const byte *inputBuffer, size_t inputBufferLength,
byte * outputBuffer, size_t outputBufferLength, size_t * convertedLength);
/* NLS_GetConversionOverflowSize
*
* If NLS_ConvertStreamBuffer returned NLS_RESULT_TRUNCATED, the size of the remaining
* converted text can be obtained by calling NLS_GetConversionOverflowSize.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_GetConversionOverflowSize(EncodingConverter * converter, size_t * size);
/* NLS_ConverterGetOverflow
*
* If NLS_ConvertStreamBuffer returned NLS_RESULT_TRUNCATED, the remaining
* converted text can be obtained by making consecutive calls to NLS_ConverterGetOverflow.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
* NLS_RESULT_TRUNCATED - Output buffer was too small,
* result was truncated
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_ConverterGetOverflow(EncodingConverter * converter,
byte * outputBuffer, size_t outputBufferLength, size_t * convertedLength);
/* NLS_ResetEncodingConverter
*
* Resets the converter, clearing any converted and/or unconverted
* text from the converter
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_ResetEncodingConverter(EncodingConverter * converter);
/* NLS_GetConversionRemSize
*
* When all input text has been converted, there may have been some
* characters which did not form a complete convertable group. The number
* of remaining bytes can optained by calling NLS_GetConversionRemSize.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_GetConversionRemSize(EncodingConverter * converter, size_t * size);
/* NLS_GetConversionRem
*
* When all input text has been converted, there may have been some
* characters which did not form a complete convertable group. The
* remaining bytes can optained by calling NLS_GetConversionRem.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_GetConversionRem(EncodingConverter * converter, byte * buffer, size_t bufferSize, size_t * size);
/* NLS_NewEncodingConverterEnumeration
*
* Create a new encoding converter enumeration instance. The encoding names will be
* normalized by this function to resolve encoding aliases etc. One or more of the
* encoding names may be spacified as NULL, resulting in all possible convertions being
* returned.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
* NLS_NO_FROM_ENCODING - No to encoding exists
* NLS_NO_TO_ENCODING - No from encoding exists
* NLS_NEW_CONVERTER_LIST_FAILED - No converter exists
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_NewEncodingConverterEnumeration(const char *from_charset, const char *to_charset,
EncondingConverterList ** converterList);
/* NLS_DeleteEncodingConverterEnumeration
*
* Delete the encoding converter enumeration instance.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_DeleteEncodingConverterEnumeration(EncondingConverterList * converterList);
/* NLS_CountEncodingConverters
*
* Get a count of the number of converters that exist.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_CountEncodingConverters(EncondingConverterList * converterList, size_t * count);
/* NLS_GetEncodingConverterListItem
*
* Caller must supply two char buffers of MAX_ENCODING_NAME_SIZE size, items are
* base 0 counted (0-n).
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_GetEncodingConverterListItem(EncondingConverterList * converterList, size_t itemNumber,
char *from_charset, char *to_charset);
/* NLS_GetResultBufferSize
*
* Returns an estimated buffer size in bytes for the target conversion of the
* input stream. The Estimate is garanteed to be larger than the target
* conversion will require.
*/
NLSCNVAPI_PUBLIC(size_t)
NLS_GetResultBufferSize(const byte *buffer, size_t length,
const char *from_charset, const char *to_charset);
/* NLS_GetNormalizedEncodingName
*
* Will return the normalized encoding name for known encodings,
* eg: UNICODE-1-1-UTF-8 -> UTF-8 etc.
*/
NLSCNVAPI_PUBLIC(const char*)
NLS_GetNormalizedEncodingName(const char* encoding);
/* NLS_GetEncodingNameFromJava
*
* Will return the normalized encoding name for a known java encoding name.
* eg: 8859_1 -> ISO_8859-1:1987 etc.
*/
NLSCNVAPI_PUBLIC(const char*)
NLS_GetEncodingNameFromJava(const char* javaName);
/* NLS_GetJavaEncodingName
*
* Will return the java encoding name from a normalized encoding name.
* eg: ISO_8859-1:1987 -> 8859_1 etc.
*/
NLSCNVAPI_PUBLIC(const char*)
NLS_GetJavaEncodingName(const char* encoding);
/************************ Detection ******************************/
/* NLS_DetectEncodingForBuffer
*
* Detects the encoding for a byte buffer, Will cycle through the
* known encoding converters trying to auto detect the encoding.
* Will create an ordered list of possible encodings for the input
* text.
*
* Status Returns
* NLS_SUCCESS
* NLS_AUTO_DETECTION_ERROR
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_DetectEncodingForBuffer(const byte *buffer, size_t length,
NLS_AUTO_DETECT_RESULT *results, size_t resultsCount, size_t* detectionCount);
/* NLS_DetectEncodingForUCS2
*
* Detects the best encoding to convert to from UCS2. Examins the
* contents of the UniChar buffer and attempts to find a target
* conversion which would generate the least loss.
*
* Status Returns
* NLS_SUCCESS
* NLS_AUTO_DETECTION_ERROR
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_DetectEncodingForUCS2(const UniChar *buffer, size_t length,
NLS_AUTO_DETECT_RESULT *results, size_t resultsCount, size_t* detectionCount);
/* NLS_RegisterStaticLibrary
*
* Adds registry entries for a statically-linked encoding converter
* library to the static link table, making them available for
* for creation with standard methods.
*
* Status Returns
* NLS_SUCCESS
* NLS_PARAM_ERROR - parameter verification failed
*/
NLSCNVAPI_PUBLIC(NLS_ErrorCode)
NLS_RegisterStaticLibrary(NLS_StaticConverterRegistry ImportStaticEntryList);
/************************ End ******************************/
NLS_END_PROTOS
#endif /* _NLSENC_H */