[apple/icu.git] / icuSources / test / intltest / idnaref.h

/*
 *******************************************************************************
 *
 *   Copyright (C) 2003-2004, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 *
 *******************************************************************************
 *   file name:  idnaref.h
 *   encoding:   US-ASCII
 *   tab size:   8 (not used)
 *   indentation:4
 *
 *   created on: 2003feb1
 *   created by: Ram Viswanadha
 */

#ifndef __IDNAREF_H__
#define __IDNAREF_H__

#include "unicode/utypes.h"

#if !UCONFIG_NO_IDNA

#include "unicode/parseerr.h"

#define IDNAREF_DEFAULT          0x0000
#define IDNAREF_ALLOW_UNASSIGNED 0x0001
#define IDNAREF_USE_STD3_RULES   0x0002
    
/**
 * This function implements the ToASCII operation as defined in the IDNA draft.
 * This operation is done on <b>single labels</b> before sending it to something that expects
 * ASCII names. A label is an individual part of a domain name. Labels are usually
 * separated by dots; for e.g." "www.example.com" is composed of 3 labels 
 * "www","example", and "com".
 *
 *
 * @param src               Input Unicode label.
 * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 * @param dest              Output Unicode array with ACE encoded ASCII label.
 * @param destCapacity      Size of dest.
 * @param options           A bit set of options:
 *  
 *  - idnaref_UNASSIGNED        Unassigned values can be converted to ASCII for query operations
 *                          If TRUE unassigned values are treated as normal Unicode code points.
 *                          If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
 *  - idnaref_USE_STD3_RULES    Use STD3 ASCII rules for host name syntax restrictions
 *                          If TRUE and the input does not statisfy STD3 rules, the operation 
 *                          will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 *
 * @param parseError        Pointer to UParseError struct to recieve information on position 
 *                          of error if an error is encountered. Can be NULL.
 * @param status            ICU in/out error code parameter.
 *                          U_INVALID_CHAR_FOUND if src contains
 *                          unmatched single surrogates.
 *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 *                          too many code points.
 *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 * @return                  Number of ASCII characters converted.
 * @draft ICU 2.6
 */
U_CFUNC int32_t U_EXPORT2
idnaref_toASCII(const UChar* src, int32_t srcLength, 
              UChar* dest, int32_t destCapacity,
              int32_t options,
              UParseError* parseError,
              UErrorCode* status);


/**
 * This function implements the ToUnicode operation as defined in the IDNA draft.
 * This operation is done on <b>single labels</b> before sending it to something that expects
 * ASCII names. A label is an individual part of a domain name. Labels are usually
 * separated by dots; for e.g." "www.example.com" is composed of 3 labels 
 * "www","example", and "com".
 *
 * @param src               Input ASCII (ACE encoded) label.
 * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 * @param dest Output       Converted Unicode array.
 * @param destCapacity      Size of dest.
 * @param options           A bit set of options:
 *  
 *  - idnaref_UNASSIGNED        Unassigned values can be converted to ASCII for query operations
 *                          If TRUE unassigned values are treated as normal Unicode code points.
 *                          If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
 *  - idnaref_USE_STD3_RULES    Use STD3 ASCII rules for host name syntax restrictions
 *                          If TRUE and the input does not statisfy STD3 rules, the operation 
 *                          will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 *
 * @param parseError        Pointer to UParseError struct to recieve information on position 
 *                          of error if an error is encountered. Can be NULL.
 * @param status            ICU in/out error code parameter.
 *                          U_INVALID_CHAR_FOUND if src contains
 *                          unmatched single surrogates.
 *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 *                          too many code points.
 *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 * @return                  Number of Unicode characters converted.
 * @draft ICU 2.6
 */
U_CFUNC int32_t U_EXPORT2
idnaref_toUnicode(const UChar* src, int32_t srcLength,
                UChar* dest, int32_t destCapacity,
                int32_t options,
                UParseError* parseError,
                UErrorCode* status);


/**
 * Convenience function that implements the IDNToASCII operation as defined in the IDNA draft.
 * This operation is done on complete domain names, e.g: "www.example.com". 
 * It is important to note that this operation can fail. If it fails, then the input 
 * domain name cannot be used as an Internationalized Domain Name and the application
 * should have methods defined to deal with the failure.
 * 
 * <b>Note:</b> IDNA draft specifies that a conformant application should divide a domain name
 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 
 * and then convert. This function does not offer that level of granularity. The options once  
 * set will apply to all labels in the domain name
 *
 * @param src               Input ASCII IDN.
 * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 * @param dest Output       Unicode array.
 * @param destCapacity      Size of dest.
 * @param options           A bit set of options:
 *  
 *  - idnaref_UNASSIGNED        Unassigned values can be converted to ASCII for query operations
 *                          If TRUE unassigned values are treated as normal Unicode code points.
 *                          If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
 *  - idnaref_USE_STD3_RULES    Use STD3 ASCII rules for host name syntax restrictions
 *                          If TRUE and the input does not statisfy STD3 rules, the operation 
 *                          will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 * 
 * @param parseError        Pointer to UParseError struct to recieve information on position 
 *                          of error if an error is encountered. Can be NULL.
 * @param status            ICU in/out error code parameter.
 *                          U_INVALID_CHAR_FOUND if src contains
 *                          unmatched single surrogates.
 *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 *                          too many code points.
 *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 * @return                  Number of ASCII characters converted.
 * @draft ICU 2.6
 */
U_CFUNC int32_t U_EXPORT2
idnaref_IDNToASCII(  const UChar* src, int32_t srcLength,
                   UChar* dest, int32_t destCapacity,
                   int32_t options,
                   UParseError* parseError,
                   UErrorCode* status);

/**
 * Convenience function that implements the IDNToUnicode operation as defined in the IDNA draft.
 * This operation is done on complete domain names, e.g: "www.example.com". 
 *
 * <b>Note:</b> IDNA draft specifies that a conformant application should divide a domain name
 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 
 * and then convert. This function does not offer that level of granularity. The options once  
 * set will apply to all labels in the domain name
 *
 * @param src               Input Unicode IDN.
 * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 * @param dest Output       ASCII array.
 * @param destCapacity      Size of dest.
 * @param options           A bit set of options:
 *  
 *  - idnaref_UNASSIGNED        Unassigned values can be converted to ASCII for query operations
 *                          If TRUE unassigned values are treated as normal Unicode code points.
 *                          If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
 *  - idnaref_USE_STD3_RULES    Use STD3 ASCII rules for host name syntax restrictions
 *                          If TRUE and the input does not statisfy STD3 rules, the operation 
 *                          will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 *
 * @param parseError        Pointer to UParseError struct to recieve information on position 
 *                          of error if an error is encountered. Can be NULL.
 * @param status            ICU in/out error code parameter.
 *                          U_INVALID_CHAR_FOUND if src contains
 *                          unmatched single surrogates.
 *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 *                          too many code points.
 *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 * @return                  Number of ASCII characters converted.
 * @draft ICU 2.6
 */
U_CFUNC int32_t U_EXPORT2
idnaref_IDNToUnicode(  const UChar* src, int32_t srcLength,
                     UChar* dest, int32_t destCapacity,
                     int32_t options,
                     UParseError* parseError,
                     UErrorCode* status);

/**
 * Compare two strings for IDNs for equivalence.
 * This function splits the domain names into labels and compares them.
 * According to IDN draft, whenever two labels are compared, they are 
 * considered equal if and only if their ASCII forms (obtained by 
 * applying toASCII) match using an case-insensitive ASCII comparison.
 * Two domain names are considered a match if and only if all labels 
 * match regardless of whether label separators match.
 *
 * @param s1                First source string.
 * @param length1           Length of first source string, or -1 if NUL-terminated.
 *
 * @param s2                Second source string.
 * @param length2           Length of second source string, or -1 if NUL-terminated.
 * @param options           A bit set of options:
 *  
 *  - idnaref_UNASSIGNED        Unassigned values can be converted to ASCII for query operations
 *                          If TRUE unassigned values are treated as normal Unicode code points.
 *                          If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
 *  - idnaref_USE_STD3_RULES    Use STD3 ASCII rules for host name syntax restrictions
 *                          If TRUE and the input does not statisfy STD3 rules, the operation 
 *                          will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 *
 * @param status            ICU error code in/out parameter.
 *                          Must fulfill U_SUCCESS before the function call.
 * @return <0 or 0 or >0 as usual for string comparisons
 * @draft ICU 2.6
 */
U_CFUNC int32_t U_EXPORT2
idnaref_compare(  const UChar *s1, int32_t length1,
                const UChar *s2, int32_t length2,
                int32_t options,
                UErrorCode* status);

#endif /* #if !UCONFIG_NO_IDNA */

#endif
Commit	Line	Data
b75a7d8f A	1	/*
	2	*******************************************************************************
	3	*
374ca955	4	* Copyright (C) 2003-2004, International Business Machines
b75a7d8f A	5	* Corporation and others. All Rights Reserved.
	6	*
	7	*******************************************************************************
	8	* file name: idnaref.h
	9	* encoding: US-ASCII
	10	* tab size: 8 (not used)
	11	* indentation:4
	12	*
	13	* created on: 2003feb1
	14	* created by: Ram Viswanadha
	15	*/
	16
	17	#ifndef __IDNAREF_H__
	18	#define __IDNAREF_H__
	19
	20	#include "unicode/utypes.h"
	21
	22	#if !UCONFIG_NO_IDNA
	23
	24	#include "unicode/parseerr.h"
	25
	26	#define IDNAREF_DEFAULT 0x0000
	27	#define IDNAREF_ALLOW_UNASSIGNED 0x0001
	28	#define IDNAREF_USE_STD3_RULES 0x0002
	29
	30	/**
	31	* This function implements the ToASCII operation as defined in the IDNA draft.
	32	* This operation is done on <b>single labels</b> before sending it to something that expects
	33	* ASCII names. A label is an individual part of a domain name. Labels are usually
	34	* separated by dots; for e.g." "www.example.com" is composed of 3 labels
	35	* "www","example", and "com".
	36	*
	37	*
	38	* @param src Input Unicode label.
	39	* @param srcLength Number of UChars in src, or -1 if NUL-terminated.
	40	* @param dest Output Unicode array with ACE encoded ASCII label.
	41	* @param destCapacity Size of dest.
	42	* @param options A bit set of options:
	43	*
	44	* - idnaref_UNASSIGNED Unassigned values can be converted to ASCII for query operations
	45	* If TRUE unassigned values are treated as normal Unicode code points.
	46	* If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
	47	* - idnaref_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions
	48	* If TRUE and the input does not statisfy STD3 rules, the operation
	49	* will fail with U_IDNA_STD3_ASCII_RULES_ERROR
	50	*
	51	* @param parseError Pointer to UParseError struct to recieve information on position
	52	* of error if an error is encountered. Can be NULL.
	53	* @param status ICU in/out error code parameter.
	54	* U_INVALID_CHAR_FOUND if src contains
	55	* unmatched single surrogates.
	56	* U_INDEX_OUTOFBOUNDS_ERROR if src contains
	57	* too many code points.
	58	* U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
	59	* @return Number of ASCII characters converted.
	60	* @draft ICU 2.6
	61	*/
374ca955	62	U_CFUNC int32_t U_EXPORT2
b75a7d8f A	63	idnaref_toASCII(const UChar* src, int32_t srcLength,
	64	UChar* dest, int32_t destCapacity,
	65	int32_t options,
	66	UParseError* parseError,
	67	UErrorCode* status);
	68
	69
	70	/**
	71	* This function implements the ToUnicode operation as defined in the IDNA draft.
	72	* This operation is done on <b>single labels</b> before sending it to something that expects
	73	* ASCII names. A label is an individual part of a domain name. Labels are usually
	74	* separated by dots; for e.g." "www.example.com" is composed of 3 labels
	75	* "www","example", and "com".
	76	*
	77	* @param src Input ASCII (ACE encoded) label.
	78	* @param srcLength Number of UChars in src, or -1 if NUL-terminated.
	79	* @param dest Output Converted Unicode array.
	80	* @param destCapacity Size of dest.
	81	* @param options A bit set of options:
	82	*
	83	* - idnaref_UNASSIGNED Unassigned values can be converted to ASCII for query operations
	84	* If TRUE unassigned values are treated as normal Unicode code points.
	85	* If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
	86	* - idnaref_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions
	87	* If TRUE and the input does not statisfy STD3 rules, the operation
	88	* will fail with U_IDNA_STD3_ASCII_RULES_ERROR
	89	*
	90	* @param parseError Pointer to UParseError struct to recieve information on position
	91	* of error if an error is encountered. Can be NULL.
	92	* @param status ICU in/out error code parameter.
	93	* U_INVALID_CHAR_FOUND if src contains
	94	* unmatched single surrogates.
	95	* U_INDEX_OUTOFBOUNDS_ERROR if src contains
	96	* too many code points.
	97	* U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
	98	* @return Number of Unicode characters converted.
	99	* @draft ICU 2.6
	100	*/
374ca955	101	U_CFUNC int32_t U_EXPORT2
b75a7d8f A	102	idnaref_toUnicode(const UChar* src, int32_t srcLength,
	103	UChar* dest, int32_t destCapacity,
	104	int32_t options,
	105	UParseError* parseError,
	106	UErrorCode* status);
	107
	108
	109	/**
	110	* Convenience function that implements the IDNToASCII operation as defined in the IDNA draft.
	111	* This operation is done on complete domain names, e.g: "www.example.com".
	112	* It is important to note that this operation can fail. If it fails, then the input
	113	* domain name cannot be used as an Internationalized Domain Name and the application
	114	* should have methods defined to deal with the failure.
	115	*
	116	* <b>Note:</b> IDNA draft specifies that a conformant application should divide a domain name
	117	* into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each,
	118	* and then convert. This function does not offer that level of granularity. The options once
	119	* set will apply to all labels in the domain name
	120	*
	121	* @param src Input ASCII IDN.
	122	* @param srcLength Number of UChars in src, or -1 if NUL-terminated.
	123	* @param dest Output Unicode array.
	124	* @param destCapacity Size of dest.
	125	* @param options A bit set of options:
	126	*
	127	* - idnaref_UNASSIGNED Unassigned values can be converted to ASCII for query operations
	128	* If TRUE unassigned values are treated as normal Unicode code points.
	129	* If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
	130	* - idnaref_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions
	131	* If TRUE and the input does not statisfy STD3 rules, the operation
	132	* will fail with U_IDNA_STD3_ASCII_RULES_ERROR
	133	*
	134	* @param parseError Pointer to UParseError struct to recieve information on position
	135	* of error if an error is encountered. Can be NULL.
	136	* @param status ICU in/out error code parameter.
	137	* U_INVALID_CHAR_FOUND if src contains
	138	* unmatched single surrogates.
	139	* U_INDEX_OUTOFBOUNDS_ERROR if src contains
	140	* too many code points.
	141	* U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
	142	* @return Number of ASCII characters converted.
	143	* @draft ICU 2.6
	144	*/
374ca955	145	U_CFUNC int32_t U_EXPORT2
b75a7d8f A	146	idnaref_IDNToASCII( const UChar* src, int32_t srcLength,
	147	UChar* dest, int32_t destCapacity,
	148	int32_t options,
	149	UParseError* parseError,
	150	UErrorCode* status);
	151
	152	/**
	153	* Convenience function that implements the IDNToUnicode operation as defined in the IDNA draft.
	154	* This operation is done on complete domain names, e.g: "www.example.com".
	155	*
	156	* <b>Note:</b> IDNA draft specifies that a conformant application should divide a domain name
	157	* into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each,
	158	* and then convert. This function does not offer that level of granularity. The options once
	159	* set will apply to all labels in the domain name
	160	*
	161	* @param src Input Unicode IDN.
	162	* @param srcLength Number of UChars in src, or -1 if NUL-terminated.
	163	* @param dest Output ASCII array.
	164	* @param destCapacity Size of dest.
	165	* @param options A bit set of options:
	166	*
	167	* - idnaref_UNASSIGNED Unassigned values can be converted to ASCII for query operations
	168	* If TRUE unassigned values are treated as normal Unicode code points.
	169	* If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
	170	* - idnaref_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions
	171	* If TRUE and the input does not statisfy STD3 rules, the operation
	172	* will fail with U_IDNA_STD3_ASCII_RULES_ERROR
	173	*
	174	* @param parseError Pointer to UParseError struct to recieve information on position
	175	* of error if an error is encountered. Can be NULL.
	176	* @param status ICU in/out error code parameter.
	177	* U_INVALID_CHAR_FOUND if src contains
	178	* unmatched single surrogates.
	179	* U_INDEX_OUTOFBOUNDS_ERROR if src contains
	180	* too many code points.
	181	* U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
	182	* @return Number of ASCII characters converted.
	183	* @draft ICU 2.6
	184	*/
374ca955	185	U_CFUNC int32_t U_EXPORT2
b75a7d8f A	186	idnaref_IDNToUnicode( const UChar* src, int32_t srcLength,
	187	UChar* dest, int32_t destCapacity,
	188	int32_t options,
	189	UParseError* parseError,
	190	UErrorCode* status);
	191
	192	/**
	193	* Compare two strings for IDNs for equivalence.
	194	* This function splits the domain names into labels and compares them.
	195	* According to IDN draft, whenever two labels are compared, they are
	196	* considered equal if and only if their ASCII forms (obtained by
	197	* applying toASCII) match using an case-insensitive ASCII comparison.
	198	* Two domain names are considered a match if and only if all labels
	199	* match regardless of whether label separators match.
	200	*
	201	* @param s1 First source string.
	202	* @param length1 Length of first source string, or -1 if NUL-terminated.
	203	*
	204	* @param s2 Second source string.
	205	* @param length2 Length of second source string, or -1 if NUL-terminated.
	206	* @param options A bit set of options:
	207	*
	208	* - idnaref_UNASSIGNED Unassigned values can be converted to ASCII for query operations
	209	* If TRUE unassigned values are treated as normal Unicode code points.
	210	* If FALSE the operation fails with U_UNASSIGNED_CODE_POINT_FOUND error code.
	211	* - idnaref_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions
	212	* If TRUE and the input does not statisfy STD3 rules, the operation
	213	* will fail with U_IDNA_STD3_ASCII_RULES_ERROR
	214	*
	215	* @param status ICU error code in/out parameter.
	216	* Must fulfill U_SUCCESS before the function call.
	217	* @return <0 or 0 or >0 as usual for string comparisons
	218	* @draft ICU 2.6
	219	*/
374ca955	220	U_CFUNC int32_t U_EXPORT2
b75a7d8f A	221	idnaref_compare( const UChar *s1, int32_t length1,
	222	const UChar *s2, int32_t length2,
	223	int32_t options,
	224	UErrorCode* status);
	225
	226	#endif /* #if !UCONFIG_NO_IDNA */
	227
	228	#endif