/* ********************************************************************** * Copyright (C) 2005-2007, 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" #if !UCONFIG_NO_CONVERSION #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. *

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

* 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 * @stable ICU 3.6 */ typedef struct UCharsetDetector UCharsetDetector; struct UCharsetMatch; /** * Opaque structure representing a match that was identified * from a charset detection operation. * @stable 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. * @stable ICU 3.6 */ U_STABLE 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 ucsd The charset detector to be closed. * @stable ICU 3.6 */ U_STABLE 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 ucsd 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. * * @stable ICU 3.6 */ U_STABLE 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 ucsd 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. * * @stable ICU 3.6 */ U_STABLE 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. *

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

* The function will fail if *

* * @param ucsd 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. * * @stable ICU 3.6 */ U_STABLE 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. *

* The returned UCharsetMatch objects are owned by the UCharsetDetector. * They will remain valid until the detector is closed or modified * *

* Return an error if *

* * @param ucsd 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. * @stable ICU 3.6 */ U_STABLE 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 ucsm The charset match object. * @param status Any error conditions are reported back in this variable. * @return The name of the matching charset. * * @stable ICU 3.6 */ U_STABLE 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 ucsm The charset match object. * @param status Any error conditions are reported back in this variable. * @return A confidence number for the charset match. * * @stable ICU 3.6 */ U_STABLE 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 ucsm 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, or * an empty string if the language could not be determined. * * @stable ICU 3.6 */ U_STABLE 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 ucsm 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. * * @stable ICU 3.6 */ U_STABLE 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 ucsd a Charset detector. * @param status Any error conditions are reported back in this variable. * @return an iterator providing access to the detectable charset names. * @stable ICU 3.6 */ U_STABLE 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 ucsd The charset detector to check. * @return TRUE if filtering is enabled. * @stable ICU 3.6 */ U_STABLE 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 ucsd the charset detector to be modified. * @param filter true to enable input text filtering. * @return The previous setting. * * @stable ICU 3.6 */ U_STABLE UBool U_EXPORT2 ucsdet_enableInputFilter(UCharsetDetector *ucsd, UBool filter); #endif #endif /* __UCSDET_H */