1. Correct coding comments.
[efi/edk2/.git] / edk2 / EdkCompatibilityPkg / Compatibility / Include / Library / LanguageLib.h
1 /** @file\r
2   Provides functions for language conversion between ISO 639-2 and RFC 4646 styles.\r
3 \r
4 Copyright (c) 2009 - 2010, Intel Corporation<BR>\r
5 All rights reserved. This program and the accompanying materials\r
6 are licensed and made available under the terms and conditions of the BSD License\r
7 which accompanies this distribution.  The full text of the license may be found at\r
8 http://opensource.org/licenses/bsd-license.php\r
9 \r
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
12 \r
13 **/\r
14 \r
15 #ifndef __LANGUAGE_LIB__\r
16 #define __LANGUAGE_LIB__\r
17 \r
18 /**\r
19   Converts an ISO 639-2 language code to an RFC 4646 language code.\r
20   If the ISO 639-2 language code has a corresponding ISO 639-1 code, then that ISO 639-1\r
21   code is returned in the out parameter. Else the original ISO 639-2 code is returned. The returned RFC 4646\r
22   language code is composed of only a primary language subtag.\r
23 \r
24   If Iso639Language is NULL, then ASSERT().\r
25   If Rfc4646Language is NULL, then ASSERT().\r
26 \r
27   @param[out] Rfc4646Language  Pointers to a buffer large enough for an ASCII string\r
28                                representing an RFC 4646 language code containing only\r
29                                either a ISO 639-1 or ISO 639-2 primary language subtag.\r
30                                This string is Null-terminated.\r
31   @param[in]  Iso639Language   Pointer to a 3-letter ASCII string that represents\r
32                                an ISO 639-2 language code. This string is not required\r
33                                to be Null-terminated.\r
34 \r
35   @retval TRUE                 The ISO 639-2 language code was converted to an ISO 639-1 code.\r
36   @retval FALSE                The language code does not have a corresponding ISO 639-1 code.\r
37 \r
38 **/\r
39 BOOLEAN\r
40 EFIAPI\r
41 ConvertIso639ToRfc4646 (\r
42   OUT CHAR8        *Rfc4646Language,\r
43   IN  CONST CHAR8  *Iso639Language\r
44   );\r
45 \r
46 /**\r
47   Converts an RFC 4646 language code to an ISO 639-2 language code. The primary language\r
48   subtag of the RFC 4646 code must be either an ISO 639-1 or 639-2 code. If the primary\r
49   language subtag is an ISO 639-1 code, then it is converted to its corresponding ISO 639-2\r
50   code (T code if applies). Else the ISO 639-2 code is returned.\r
51 \r
52   If Rfc4646Language is NULL, then ASSERT().\r
53   If Iso639Language is NULL, then ASSERT().\r
54 \r
55   @param[out] Iso639Language   Pointers to a buffer large enough for a 3-letter ASCII string\r
56                                representing an ISO 639-2 language code. The string is Null-terminated.\r
57   @param[in]  Rfc4646Language  Pointer to a RFC 4646 language code string. This string is terminated\r
58                                by a NULL or a ';' character.\r
59 \r
60   @retval TRUE                 Language code converted successfully.\r
61   @retval FALSE                The RFC 4646 language code is invalid or unsupported.\r
62 \r
63 **/\r
64 BOOLEAN\r
65 EFIAPI\r
66 ConvertRfc4646ToIso639 (\r
67   OUT CHAR8        *Iso639Language,\r
68   IN  CONST CHAR8  *Rfc4646Language\r
69   );\r
70 \r
71 /**\r
72   Converts ISO 639-2 language codes to RFC 4646 codes and returns the converted codes.\r
73   Caller is responsible for freeing the allocated buffer.\r
74 \r
75   If Iso639Languages is NULL, then ASSERT.\r
76 \r
77   @param[in] Iso639Languages  Pointers to Null-terminated ISO 639-2 language code strings containing\r
78                               one or more ISO 639-2 3-letter language codes.\r
79   \r
80   @retval NULL                Invalid ISO 639-2 language code found.\r
81   @retval NULL                Out of memory.\r
82   @return                     Pointer to the allocate buffer containing the Null-terminated converted language codes string.\r
83                               This string is composed of one or more RFC4646 language codes each of which has only\r
84                               ISO 639-1 2-letter primary language subtag.\r
85 \r
86 **/\r
87 CHAR8 *\r
88 EFIAPI\r
89 ConvertLanguagesIso639ToRfc4646 (\r
90   IN CONST CHAR8  *Iso639Languages\r
91   );\r
92 \r
93 /**\r
94   Converts RFC 4646 language codes to ISO 639-2 codes and returns the converted codes.\r
95   The primary language subtag of the RFC 4646 code must be either an ISO 639-1 or 639-2 code.\r
96   Caller is responsible for freeing the allocated buffer.\r
97 \r
98   If Rfc4646Languages is NULL, then ASSERT.\r
99 \r
100   @param[in] Rfc4646Languages  Pointers to a Null-terminated RFC 4646 language codes string containing\r
101                                one or more RFC 4646 language codes.\r
102   \r
103   @retval NULL                 Invalid or unsupported RFC 4646 language code found.\r
104   @retval NULL                 Out of memory.\r
105   @return                      Pointer to the allocate buffer containing the Null-terminated converted language codes string.\r
106                                This string is composed of one or more ISO 639-2 language codes.\r
107 \r
108 **/\r
109 CHAR8 *\r
110 EFIAPI\r
111 ConvertLanguagesRfc4646ToIso639 (\r
112   IN CONST CHAR8  *Rfc4646Languages\r
113   );\r
114 \r
115 \r
116 #endif\r