347 lines
12 KiB
C
347 lines
12 KiB
C
/*
|
|
**********************************************************************
|
|
* Copyright (C) 2005-2006, International Business Machines
|
|
* Corporation and others. All Rights Reserved.
|
|
**********************************************************************
|
|
* file name: ucsdet.h
|
|
* encoding: US-ASCII
|
|
* indentation:4
|
|
*
|
|
* created on: 2005Aug04
|
|
* created by: Andy Heninger
|
|
*
|
|
* ICU Character Set Detection, API for C
|
|
*
|
|
* Draft version 18 Oct 2005
|
|
*
|
|
*/
|
|
|
|
#ifndef __UCSDET_H
|
|
#define __UCSDET_H
|
|
|
|
#include "unicode/utypes.h"
|
|
#include "unicode/uenum.h"
|
|
|
|
/**
|
|
* \file
|
|
* \brief C API: Charset Detection API
|
|
*
|
|
* This API provides a facility for detecting the
|
|
* charset or encoding of character data in an unknown text format.
|
|
* The input data can be from an array of bytes.
|
|
* <p>
|
|
* Character set detection is at best an imprecise operation. The detection
|
|
* process will attempt to identify the charset that best matches the characteristics
|
|
* of the byte data, but the process is partly statistical in nature, and
|
|
* the results can not be guaranteed to always be correct.
|
|
* <p>
|
|
* For best accuracy in charset detection, the input data should be primarily
|
|
* in a single language, and a minimum of a few hundred bytes worth of plain text
|
|
* in the language are needed. The detection process will attempt to
|
|
* ignore html or xml style markup that could otherwise obscure the content.
|
|
*/
|
|
|
|
|
|
struct UCharsetDetector;
|
|
/**
|
|
* Structure representing a charset detector
|
|
* @draft ICU 3.6
|
|
*/
|
|
typedef struct UCharsetDetector UCharsetDetector;
|
|
|
|
struct UCharsetMatch;
|
|
/**
|
|
* Opaque structure representing a match that was identified
|
|
* from a charset detection operation.
|
|
* draft ICU 3.6
|
|
*/
|
|
typedef struct UCharsetMatch UCharsetMatch;
|
|
|
|
/**
|
|
* Open a charset detector.
|
|
*
|
|
* @param status Any error conditions occurring during the open
|
|
* operation are reported back in this variable.
|
|
* @return the newly opened charset detector.
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT UCharsetDetector * U_EXPORT2
|
|
ucsdet_open(UErrorCode *status);
|
|
|
|
/**
|
|
* Close a charset detector. All storage and any other resources
|
|
* owned by this charset detector will be released. Failure to
|
|
* close a charset detector when finished with it can result in
|
|
* memory leaks in the application.
|
|
*
|
|
* @param csd The charset detector to be closed.
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT void U_EXPORT2
|
|
ucsdet_close(UCharsetDetector *ucsd);
|
|
|
|
/**
|
|
* Set the input byte data whose charset is to detected.
|
|
*
|
|
* Ownership of the input text byte array remains with the caller.
|
|
* The input string must not be altered or deleted until the charset
|
|
* detector is either closed or reset to refer to different input text.
|
|
*
|
|
* @param csd the charset detector to be used.
|
|
* @param textIn the input text of unknown encoding. .
|
|
* @param len the length of the input text, or -1 if the text
|
|
* is NUL terminated.
|
|
* @param status any error conditions are reported back in this variable.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT void U_EXPORT2
|
|
ucsdet_setText(UCharsetDetector *ucsd, const char *textIn, int32_t len, UErrorCode *status);
|
|
|
|
|
|
/** Set the declared encoding for charset detection.
|
|
* The declared encoding of an input text is an encoding obtained
|
|
* by the user from an http header or xml declaration or similar source that
|
|
* can be provided as an additional hint to the charset detector.
|
|
*
|
|
* How and whether the declared encoding will be used during the
|
|
* detection process is TBD.
|
|
*
|
|
* @param csd the charset detector to be used.
|
|
* @param encoding an encoding for the current data obtained from
|
|
* a header or declaration or other source outside
|
|
* of the byte data itself.
|
|
* @param length the length of the encoding name, or -1 if the name string
|
|
* is NUL terminated.
|
|
* @param status any error conditions are reported back in this variable.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT void U_EXPORT2
|
|
ucsdet_setDeclaredEncoding(UCharsetDetector *ucsd, const char *encoding, int32_t length, UErrorCode *status);
|
|
|
|
|
|
/**
|
|
* Return the charset that best matches the supplied input data.
|
|
*
|
|
* Note though, that because the detection
|
|
* only looks at the start of the input data,
|
|
* there is a possibility that the returned charset will fail to handle
|
|
* the full set of input data.
|
|
* <p>
|
|
* The returned UCharsetMatch object is owned by the UCharsetDetector.
|
|
* It will remain valid until the detector input is reset, or until
|
|
* the detector is closed.
|
|
* <p>
|
|
* The function will fail if
|
|
* <ul>
|
|
* <li>no charset appears to match the data.</li>
|
|
* <li>no input text has been provided</li>
|
|
* </ul>
|
|
*
|
|
* @param csd the charset detector to be used.
|
|
* @param status any error conditions are reported back in this variable.
|
|
* @return a UCharsetMatch representing the best matching charset,
|
|
* or NULL if no charset matches the byte data.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT const UCharsetMatch * U_EXPORT2
|
|
ucsdet_detect(UCharsetDetector *ucsd, UErrorCode *status);
|
|
|
|
|
|
/**
|
|
* Find all charset matches that appear to be consistent with the input,
|
|
* returning an array of results. The results are ordered with the
|
|
* best quality match first.
|
|
*
|
|
* Because the detection only looks at a limited amount of the
|
|
* input byte data, some of the returned charsets may fail to handle
|
|
* the all of input data.
|
|
* <p>
|
|
* The returned UCharsetMatch objects are owned by the UCharsetDetector.
|
|
* They will remain valid until the detector is closed or modified
|
|
*
|
|
* <p>
|
|
* Return an error if
|
|
* <ul>
|
|
* <li>no charsets appear to match the input data.</li>
|
|
* <li>no input text has been provided</li>
|
|
* </ul>
|
|
*
|
|
* @param csd the charset detector to be used.
|
|
* @param matchesFound pointer to a variable that will be set to the
|
|
* number of charsets identified that are consistent with
|
|
* the input data. Output only.
|
|
* @param status any error conditions are reported back in this variable.
|
|
* @return A pointer to an array of pointers to UCharSetMatch objects.
|
|
* This array, and the UCharSetMatch instances to which it refers,
|
|
* are owned by the UCharsetDetector, and will remain valid until
|
|
* the detector is closed or modified.
|
|
* @draft ICU 3.4
|
|
*/
|
|
U_DRAFT const UCharsetMatch ** U_EXPORT2
|
|
ucsdet_detectAll(UCharsetDetector *ucsd, int32_t *matchesFound, UErrorCode *status);
|
|
|
|
|
|
|
|
/**
|
|
* Get the name of the charset represented by a UCharsetMatch.
|
|
*
|
|
* The storage for the returned name string is owned by the
|
|
* UCharsetMatch, and will remain valid while the UCharsetMatch
|
|
* is valid.
|
|
*
|
|
* The name returned is suitable for use with the ICU conversion APIs.
|
|
*
|
|
* @param csm The charset match object.
|
|
* @param status Any error conditions are reported back in this variable.
|
|
* @return The name of the matching charset.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT const char * U_EXPORT2
|
|
ucsdet_getName(const UCharsetMatch *ucsm, UErrorCode *status);
|
|
|
|
/**
|
|
* Get a confidence number for the quality of the match of the byte
|
|
* data with the charset. Confidence numbers range from zero to 100,
|
|
* with 100 representing complete confidence and zero representing
|
|
* no confidence.
|
|
*
|
|
* The confidence values are somewhat arbitrary. They define an
|
|
* an ordering within the results for any single detection operation
|
|
* but are not generally comparable between the results for different input.
|
|
*
|
|
* A confidence value of ten does have a general meaning - it is used
|
|
* for charsets that can represent the input data, but for which there
|
|
* is no other indication that suggests that the charset is the correct one.
|
|
* Pure 7 bit ASCII data, for example, is compatible with a
|
|
* great many charsets, most of which will appear as possible matches
|
|
* with a confidence of 10.
|
|
*
|
|
* @param csm The charset match object.
|
|
* @param status Any error conditions are reported back in this variable.
|
|
* @return A confidence number for the charset match.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT int32_t U_EXPORT2
|
|
ucsdet_getConfidence(const UCharsetMatch *ucsm, UErrorCode *status);
|
|
|
|
/**
|
|
* Get the RFC 3066 code for the language of the input data.
|
|
*
|
|
* The Charset Detection service is intended primarily for detecting
|
|
* charsets, not language. For some, but not all, charsets, a language is
|
|
* identified as a byproduct of the detection process, and that is what
|
|
* is returned by this function.
|
|
*
|
|
* CAUTION:
|
|
* 1. Language information is not available for input data encoded in
|
|
* all charsets. In particular, no language is identified
|
|
* for UTF-8 input data.
|
|
*
|
|
* 2. Closely related languages may sometimes be confused.
|
|
*
|
|
* If more accurate language detection is required, a linguistic
|
|
* analysis package should be used.
|
|
*
|
|
* The storage for the returned name string is owned by the
|
|
* UCharsetMatch, and will remain valid while the UCharsetMatch
|
|
* is valid.
|
|
*
|
|
* @param csm The charset match object.
|
|
* @param status Any error conditions are reported back in this variable.
|
|
* @return The RFC 3066 code for the language of the input data.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT const char * U_EXPORT2
|
|
ucsdet_getLanguage(const UCharsetMatch *ucsm, UErrorCode *status);
|
|
|
|
|
|
/**
|
|
* Get the entire input text as a UChar string, placing it into
|
|
* a caller-supplied buffer. A terminating
|
|
* NUL character will be appended to the buffer if space is available.
|
|
*
|
|
* The number of UChars in the output string, not including the terminating
|
|
* NUL, is returned.
|
|
*
|
|
* If the supplied buffer is smaller than required to hold the output,
|
|
* the contents of the buffer are undefined. The full output string length
|
|
* (in UChars) is returned as always, and can be used to allocate a buffer
|
|
* of the correct size.
|
|
*
|
|
*
|
|
* @param csm The charset match object.
|
|
* @param buf A UChar buffer to be filled with the converted text data.
|
|
* @param cap The capacity of the buffer in UChars.
|
|
* @param status Any error conditions are reported back in this variable.
|
|
* @return The number of UChars in the output string.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT int32_t U_EXPORT2
|
|
ucsdet_getUChars(const UCharsetMatch *ucsm,
|
|
UChar *buf, int32_t cap, UErrorCode *status);
|
|
|
|
|
|
|
|
/**
|
|
* Get an iterator over the set of all detectable charsets -
|
|
* over the charsets that are known to the charset detection
|
|
* service.
|
|
*
|
|
* The returned UEnumeration provides access to the names of
|
|
* the charsets.
|
|
*
|
|
* The state of the Charset detector that is passed in does not
|
|
* affect the result of this function, but requiring a valid, open
|
|
* charset detector as a parameter insures that the charset detection
|
|
* service has been safely initialized and that the required detection
|
|
* data is available.
|
|
*
|
|
* @param csd a Charset detector.
|
|
* @param status Any error conditions are reported back in this variable.
|
|
* @return an iterator providing access to the detectable charset names.
|
|
* @draft ICU 3.6
|
|
*/
|
|
|
|
U_DRAFT UEnumeration * U_EXPORT2
|
|
ucsdet_getAllDetectableCharsets(const UCharsetDetector *ucsd, UErrorCode *status);
|
|
|
|
|
|
/**
|
|
* Test whether input filtering is enabled for this charset detector.
|
|
* Input filtering removes text that appears to be HTML or xml
|
|
* markup from the input before applying the code page detection
|
|
* heuristics.
|
|
*
|
|
* @param csd The charset detector to check.
|
|
* @return TRUE if filtering is enabled.
|
|
* @draft ICU 3.4
|
|
*/
|
|
U_DRAFT UBool U_EXPORT2
|
|
ucsdet_isInputFilterEnabled(const UCharsetDetector *ucsd);
|
|
|
|
|
|
/**
|
|
* Enable filtering of input text. If filtering is enabled,
|
|
* text within angle brackets ("<" and ">") will be removed
|
|
* before detection, which will remove most HTML or xml markup.
|
|
*
|
|
* @param csd the charset detector to be modified.
|
|
* @param filter <code>true</code> to enable input text filtering.
|
|
* @return The previous setting.
|
|
*
|
|
* @draft ICU 3.6
|
|
*/
|
|
U_DRAFT UBool U_EXPORT2
|
|
ucsdet_enableInputFilter(UCharsetDetector *ucsd, UBool filter);
|
|
|
|
#endif /* __UCSDET_H */
|
|
|
|
|