michael@0: /* michael@0: ********************************************************************** michael@0: * Copyright (C) 2005-2013, International Business Machines michael@0: * Corporation and others. All Rights Reserved. michael@0: ********************************************************************** michael@0: * file name: ucsdet.h michael@0: * encoding: US-ASCII michael@0: * indentation:4 michael@0: * michael@0: * created on: 2005Aug04 michael@0: * created by: Andy Heninger michael@0: * michael@0: * ICU Character Set Detection, API for C michael@0: * michael@0: * Draft version 18 Oct 2005 michael@0: * michael@0: */ michael@0: michael@0: #ifndef __UCSDET_H michael@0: #define __UCSDET_H michael@0: michael@0: #include "unicode/utypes.h" michael@0: michael@0: #if !UCONFIG_NO_CONVERSION michael@0: michael@0: #include "unicode/localpointer.h" michael@0: #include "unicode/uenum.h" michael@0: michael@0: /** michael@0: * \file michael@0: * \brief C API: Charset Detection API michael@0: * michael@0: * This API provides a facility for detecting the michael@0: * charset or encoding of character data in an unknown text format. michael@0: * The input data can be from an array of bytes. michael@0: *

michael@0: * Character set detection is at best an imprecise operation. The detection michael@0: * process will attempt to identify the charset that best matches the characteristics michael@0: * of the byte data, but the process is partly statistical in nature, and michael@0: * the results can not be guaranteed to always be correct. michael@0: *

michael@0: * For best accuracy in charset detection, the input data should be primarily michael@0: * in a single language, and a minimum of a few hundred bytes worth of plain text michael@0: * in the language are needed. The detection process will attempt to michael@0: * ignore html or xml style markup that could otherwise obscure the content. michael@0: */ michael@0: michael@0: michael@0: struct UCharsetDetector; michael@0: /** michael@0: * Structure representing a charset detector michael@0: * @stable ICU 3.6 michael@0: */ michael@0: typedef struct UCharsetDetector UCharsetDetector; michael@0: michael@0: struct UCharsetMatch; michael@0: /** michael@0: * Opaque structure representing a match that was identified michael@0: * from a charset detection operation. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: typedef struct UCharsetMatch UCharsetMatch; michael@0: michael@0: /** michael@0: * Open a charset detector. michael@0: * michael@0: * @param status Any error conditions occurring during the open michael@0: * operation are reported back in this variable. michael@0: * @return the newly opened charset detector. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE UCharsetDetector * U_EXPORT2 michael@0: ucsdet_open(UErrorCode *status); michael@0: michael@0: /** michael@0: * Close a charset detector. All storage and any other resources michael@0: * owned by this charset detector will be released. Failure to michael@0: * close a charset detector when finished with it can result in michael@0: * memory leaks in the application. michael@0: * michael@0: * @param ucsd The charset detector to be closed. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucsdet_close(UCharsetDetector *ucsd); michael@0: michael@0: #if U_SHOW_CPLUSPLUS_API michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: /** michael@0: * \class LocalUCharsetDetectorPointer michael@0: * "Smart pointer" class, closes a UCharsetDetector via ucsdet_close(). michael@0: * For most methods see the LocalPointerBase base class. michael@0: * michael@0: * @see LocalPointerBase michael@0: * @see LocalPointer michael@0: * @stable ICU 4.4 michael@0: */ michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUCharsetDetectorPointer, UCharsetDetector, ucsdet_close); michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif michael@0: michael@0: /** michael@0: * Set the input byte data whose charset is to detected. michael@0: * michael@0: * Ownership of the input text byte array remains with the caller. michael@0: * The input string must not be altered or deleted until the charset michael@0: * detector is either closed or reset to refer to different input text. michael@0: * michael@0: * @param ucsd the charset detector to be used. michael@0: * @param textIn the input text of unknown encoding. . michael@0: * @param len the length of the input text, or -1 if the text michael@0: * is NUL terminated. michael@0: * @param status any error conditions are reported back in this variable. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucsdet_setText(UCharsetDetector *ucsd, const char *textIn, int32_t len, UErrorCode *status); michael@0: michael@0: michael@0: /** Set the declared encoding for charset detection. michael@0: * The declared encoding of an input text is an encoding obtained michael@0: * by the user from an http header or xml declaration or similar source that michael@0: * can be provided as an additional hint to the charset detector. michael@0: * michael@0: * How and whether the declared encoding will be used during the michael@0: * detection process is TBD. michael@0: * michael@0: * @param ucsd the charset detector to be used. michael@0: * @param encoding an encoding for the current data obtained from michael@0: * a header or declaration or other source outside michael@0: * of the byte data itself. michael@0: * @param length the length of the encoding name, or -1 if the name string michael@0: * is NUL terminated. michael@0: * @param status any error conditions are reported back in this variable. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucsdet_setDeclaredEncoding(UCharsetDetector *ucsd, const char *encoding, int32_t length, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Return the charset that best matches the supplied input data. michael@0: * michael@0: * Note though, that because the detection michael@0: * only looks at the start of the input data, michael@0: * there is a possibility that the returned charset will fail to handle michael@0: * the full set of input data. michael@0: *

michael@0: * The returned UCharsetMatch object is owned by the UCharsetDetector. michael@0: * It will remain valid until the detector input is reset, or until michael@0: * the detector is closed. michael@0: *

michael@0: * The function will fail if michael@0: *

michael@0: * michael@0: * @param ucsd the charset detector to be used. michael@0: * @param status any error conditions are reported back in this variable. michael@0: * @return a UCharsetMatch representing the best matching charset, michael@0: * or NULL if no charset matches the byte data. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE const UCharsetMatch * U_EXPORT2 michael@0: ucsdet_detect(UCharsetDetector *ucsd, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Find all charset matches that appear to be consistent with the input, michael@0: * returning an array of results. The results are ordered with the michael@0: * best quality match first. michael@0: * michael@0: * Because the detection only looks at a limited amount of the michael@0: * input byte data, some of the returned charsets may fail to handle michael@0: * the all of input data. michael@0: *

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

michael@0: * Return an error if michael@0: *

michael@0: * michael@0: * @param ucsd the charset detector to be used. michael@0: * @param matchesFound pointer to a variable that will be set to the michael@0: * number of charsets identified that are consistent with michael@0: * the input data. Output only. michael@0: * @param status any error conditions are reported back in this variable. michael@0: * @return A pointer to an array of pointers to UCharSetMatch objects. michael@0: * This array, and the UCharSetMatch instances to which it refers, michael@0: * are owned by the UCharsetDetector, and will remain valid until michael@0: * the detector is closed or modified. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE const UCharsetMatch ** U_EXPORT2 michael@0: ucsdet_detectAll(UCharsetDetector *ucsd, int32_t *matchesFound, UErrorCode *status); michael@0: michael@0: michael@0: michael@0: /** michael@0: * Get the name of the charset represented by a UCharsetMatch. michael@0: * michael@0: * The storage for the returned name string is owned by the michael@0: * UCharsetMatch, and will remain valid while the UCharsetMatch michael@0: * is valid. michael@0: * michael@0: * The name returned is suitable for use with the ICU conversion APIs. michael@0: * michael@0: * @param ucsm The charset match object. michael@0: * @param status Any error conditions are reported back in this variable. michael@0: * @return The name of the matching charset. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE const char * U_EXPORT2 michael@0: ucsdet_getName(const UCharsetMatch *ucsm, UErrorCode *status); michael@0: michael@0: /** michael@0: * Get a confidence number for the quality of the match of the byte michael@0: * data with the charset. Confidence numbers range from zero to 100, michael@0: * with 100 representing complete confidence and zero representing michael@0: * no confidence. michael@0: * michael@0: * The confidence values are somewhat arbitrary. They define an michael@0: * an ordering within the results for any single detection operation michael@0: * but are not generally comparable between the results for different input. michael@0: * michael@0: * A confidence value of ten does have a general meaning - it is used michael@0: * for charsets that can represent the input data, but for which there michael@0: * is no other indication that suggests that the charset is the correct one. michael@0: * Pure 7 bit ASCII data, for example, is compatible with a michael@0: * great many charsets, most of which will appear as possible matches michael@0: * with a confidence of 10. michael@0: * michael@0: * @param ucsm The charset match object. michael@0: * @param status Any error conditions are reported back in this variable. michael@0: * @return A confidence number for the charset match. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: ucsdet_getConfidence(const UCharsetMatch *ucsm, UErrorCode *status); michael@0: michael@0: /** michael@0: * Get the RFC 3066 code for the language of the input data. michael@0: * michael@0: * The Charset Detection service is intended primarily for detecting michael@0: * charsets, not language. For some, but not all, charsets, a language is michael@0: * identified as a byproduct of the detection process, and that is what michael@0: * is returned by this function. michael@0: * michael@0: * CAUTION: michael@0: * 1. Language information is not available for input data encoded in michael@0: * all charsets. In particular, no language is identified michael@0: * for UTF-8 input data. michael@0: * michael@0: * 2. Closely related languages may sometimes be confused. michael@0: * michael@0: * If more accurate language detection is required, a linguistic michael@0: * analysis package should be used. michael@0: * michael@0: * The storage for the returned name string is owned by the michael@0: * UCharsetMatch, and will remain valid while the UCharsetMatch michael@0: * is valid. michael@0: * michael@0: * @param ucsm The charset match object. michael@0: * @param status Any error conditions are reported back in this variable. michael@0: * @return The RFC 3066 code for the language of the input data, or michael@0: * an empty string if the language could not be determined. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE const char * U_EXPORT2 michael@0: ucsdet_getLanguage(const UCharsetMatch *ucsm, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Get the entire input text as a UChar string, placing it into michael@0: * a caller-supplied buffer. A terminating michael@0: * NUL character will be appended to the buffer if space is available. michael@0: * michael@0: * The number of UChars in the output string, not including the terminating michael@0: * NUL, is returned. michael@0: * michael@0: * If the supplied buffer is smaller than required to hold the output, michael@0: * the contents of the buffer are undefined. The full output string length michael@0: * (in UChars) is returned as always, and can be used to allocate a buffer michael@0: * of the correct size. michael@0: * michael@0: * michael@0: * @param ucsm The charset match object. michael@0: * @param buf A UChar buffer to be filled with the converted text data. michael@0: * @param cap The capacity of the buffer in UChars. michael@0: * @param status Any error conditions are reported back in this variable. michael@0: * @return The number of UChars in the output string. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: ucsdet_getUChars(const UCharsetMatch *ucsm, michael@0: UChar *buf, int32_t cap, UErrorCode *status); michael@0: michael@0: michael@0: michael@0: /** michael@0: * Get an iterator over the set of all detectable charsets - michael@0: * over the charsets that are known to the charset detection michael@0: * service. michael@0: * michael@0: * The returned UEnumeration provides access to the names of michael@0: * the charsets. michael@0: * michael@0: *

michael@0: * The state of the Charset detector that is passed in does not michael@0: * affect the result of this function, but requiring a valid, open michael@0: * charset detector as a parameter insures that the charset detection michael@0: * service has been safely initialized and that the required detection michael@0: * data is available. michael@0: * michael@0: *

michael@0: * Note: Multiple different charset encodings in a same family may use michael@0: * a single shared name in this implementation. For example, this method returns michael@0: * an array including "ISO-8859-1" (ISO Latin 1), but not including "windows-1252" michael@0: * (Windows Latin 1). However, actual detection result could be "windows-1252" michael@0: * when the input data matches Latin 1 code points with any points only available michael@0: * in "windows-1252". michael@0: * michael@0: * @param ucsd a Charset detector. michael@0: * @param status Any error conditions are reported back in this variable. michael@0: * @return an iterator providing access to the detectable charset names. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE UEnumeration * U_EXPORT2 michael@0: ucsdet_getAllDetectableCharsets(const UCharsetDetector *ucsd, UErrorCode *status); michael@0: michael@0: /** michael@0: * Test whether input filtering is enabled for this charset detector. michael@0: * Input filtering removes text that appears to be HTML or xml michael@0: * markup from the input before applying the code page detection michael@0: * heuristics. michael@0: * michael@0: * @param ucsd The charset detector to check. michael@0: * @return TRUE if filtering is enabled. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: michael@0: U_STABLE UBool U_EXPORT2 michael@0: ucsdet_isInputFilterEnabled(const UCharsetDetector *ucsd); michael@0: michael@0: michael@0: /** michael@0: * Enable filtering of input text. If filtering is enabled, michael@0: * text within angle brackets ("<" and ">") will be removed michael@0: * before detection, which will remove most HTML or xml markup. michael@0: * michael@0: * @param ucsd the charset detector to be modified. michael@0: * @param filter true to enable input text filtering. michael@0: * @return The previous setting. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: ucsdet_enableInputFilter(UCharsetDetector *ucsd, UBool filter); michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Get an iterator over the set of detectable charsets - michael@0: * over the charsets that are enabled by the specified charset detector. michael@0: * michael@0: * The returned UEnumeration provides access to the names of michael@0: * the charsets. michael@0: * michael@0: * @param ucsd a Charset detector. michael@0: * @param status Any error conditions are reported back in this variable. michael@0: * @return an iterator providing access to the detectable charset names by michael@0: * the specified charset detector. michael@0: * @internal michael@0: */ michael@0: U_INTERNAL UEnumeration * U_EXPORT2 michael@0: ucsdet_getDetectableCharsets(const UCharsetDetector *ucsd, UErrorCode *status); michael@0: michael@0: /** michael@0: * Enable or disable individual charset encoding. michael@0: * A name of charset encoding must be included in the names returned by michael@0: * {@link #getAllDetectableCharsets()}. michael@0: * michael@0: * @param ucsd a Charset detector. michael@0: * @param encoding encoding the name of charset encoding. michael@0: * @param enabled TRUE to enable, or FALSE to disable the michael@0: * charset encoding. michael@0: * @param status receives the return status. When the name of charset encoding michael@0: * is not supported, U_ILLEGAL_ARGUMENT_ERROR is set. michael@0: * @internal michael@0: */ michael@0: U_INTERNAL void U_EXPORT2 michael@0: ucsdet_setDetectableCharset(UCharsetDetector *ucsd, const char *encoding, UBool enabled, UErrorCode *status); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: #endif michael@0: #endif /* __UCSDET_H */ michael@0: michael@0: