ppapi/c/trusted/ppb_char_set_trusted.h

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /* From trusted/ppb_char_set_trusted.idl modified Wed Feb  8 16:34:25 2012. */
   7
   8 #ifndef PPAPI_C_TRUSTED_PPB_CHAR_SET_TRUSTED_H_
   9 #define PPAPI_C_TRUSTED_PPB_CHAR_SET_TRUSTED_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_instance.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_stdint.h"
  15 #include "ppapi/c/pp_var.h"
  16
  17 #define PPB_CHARSET_TRUSTED_INTERFACE_1_0 "PPB_CharSet_Trusted;1.0"
  18 #define PPB_CHARSET_TRUSTED_INTERFACE PPB_CHARSET_TRUSTED_INTERFACE_1_0
  19
  20 /**
  21  * @file
  22  *
  23  * This file defines the <code>PPB_CharSet_Trusted</code> interface.
  24  */
  25
  26
  27 /**
  28  * @addtogroup Enums
  29  * @{
  30  */
  31 typedef enum {
  32   /**
  33    * Causes the entire conversion to fail if an error is encountered. The
  34    * conversion function will return NULL.
  35    */
  36   PP_CHARSET_TRUSTED_CONVERSIONERROR_FAIL,
  37   /**
  38    * Silently skips over errors. Unrepresentable characters and input encoding
  39    * errors will be removed from the output.
  40    */
  41   PP_CHARSET_TRUSTED_CONVERSIONERROR_SKIP,
  42   /**
  43    * Replaces the error or unrepresentable character with a substitution
  44    * character. When converting to a Unicode character set (UTF-8 or UTF-16) it
  45    * will use the unicode "substitution character" U+FFFD. When converting to
  46    * another character set, the character will be charset-specific. For many
  47    * languages this will be the representation of the '?' character.
  48    */
  49   PP_CHARSET_TRUSTED_CONVERSIONERROR_SUBSTITUTE
  50 } PP_CharSet_Trusted_ConversionError;
  51 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CharSet_Trusted_ConversionError, 4);
  52 /**
  53  * @}
  54  */
  55
  56 /**
  57  * @addtogroup Interfaces
  58  * @{
  59  */
  60 /**
  61  * The <code>PPB_CharSet_Trusted</code> interface provides functions for
  62  * converting between character sets.
  63  *
  64  * This inteface is provided for trusted plugins only since in Native Client it
  65  * would require an expensive out-of-process IPC call for each conversion,
  66  * which makes performance unacceptable. Native Client plugins should include
  67  * ICU or some other library if they need this feature.
  68  */
  69 struct PPB_CharSet_Trusted_1_0 {
  70   /**
  71    * Converts the UTF-16 string pointed to by |*utf16| to an 8-bit string in
  72    * the specified code page. |utf16_len| is measured in UTF-16 units, not
  73    * bytes. This value may not be NULL.
  74    *
  75    * The given output buffer will be filled up to output_length bytes with the
  76    * result. output_length will be updated with the number of bytes required
  77    * for the given string. The output buffer may be null to just retrieve the
  78    * required buffer length.
  79    *
  80    * This function will return PP_FALSE if there was an error converting the
  81    * string and you requested PP_CHARSET_CONVERSIONERROR_FAIL, or the output
  82    * character set was unknown. Otherwise, it will return PP_TRUE.
  83    */
  84   PP_Bool (*UTF16ToCharSet)(const uint16_t utf16[],
  85                             uint32_t utf16_len,
  86                             const char* output_char_set,
  87                             PP_CharSet_Trusted_ConversionError on_error,
  88                             char* output_buffer,
  89                             uint32_t* output_length);
  90   /**
  91    * Same as UTF16ToCharSet except converts in the other direction. The input
  92    * is in the given charset, and the |input_len| is the number of bytes in
  93    * the |input| string.
  94    *
  95    * Note that the output_utf16_length is measured in UTF-16 characters.
  96    *
  97    * Since UTF16 can represent every Unicode character, the only time the
  98    * replacement character will be used is if the encoding in the input string
  99    * is incorrect.
 100    */
 101   PP_Bool (*CharSetToUTF16)(const char* input,
 102                             uint32_t input_len,
 103                             const char* input_char_set,
 104                             PP_CharSet_Trusted_ConversionError on_error,
 105                             uint16_t* output_buffer,
 106                             uint32_t* output_utf16_length);
 107   /**
 108    * Returns a string var representing the current multi-byte character set of
 109    * the current system.
 110    *
 111    * WARNING: You really shouldn't be using this function unless you're dealing
 112    * with legacy data. You should be using UTF-8 or UTF-16 and you don't have
 113    * to worry about the character sets.
 114    */
 115   struct PP_Var (*GetDefaultCharSet)(PP_Instance instance);
 116 };
 117
 118 typedef struct PPB_CharSet_Trusted_1_0 PPB_CharSet_Trusted;
 119 /**
 120  * @}
 121  */
 122
 123 #endif  /* PPAPI_C_TRUSTED_PPB_CHAR_SET_TRUSTED_H_ */
 124