ppapi/api/trusted/ppb_char_set_trusted.idl

   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 /*
   7  * This file defines the <code>PPB_CharSet_Trusted</code> interface.
   8  */
   9
  10 label Chrome {
  11   M18 = 1.0
  12 };
  13
  14 [assert_size(4)] enum PP_CharSet_Trusted_ConversionError {
  15   /**
  16    * Causes the entire conversion to fail if an error is encountered. The
  17    * conversion function will return NULL.
  18    */
  19   PP_CHARSET_TRUSTED_CONVERSIONERROR_FAIL,
  20
  21   /**
  22    * Silently skips over errors. Unrepresentable characters and input encoding
  23    * errors will be removed from the output.
  24    */
  25   PP_CHARSET_TRUSTED_CONVERSIONERROR_SKIP,
  26
  27   /**
  28    * Replaces the error or unrepresentable character with a substitution
  29    * character. When converting to a Unicode character set (UTF-8 or UTF-16) it
  30    * will use the unicode "substitution character" U+FFFD. When converting to
  31    * another character set, the character will be charset-specific. For many
  32    * languages this will be the representation of the '?' character.
  33    */
  34   PP_CHARSET_TRUSTED_CONVERSIONERROR_SUBSTITUTE
  35 };
  36
  37 /**
  38  * The <code>PPB_CharSet_Trusted</code> interface provides functions for
  39  * converting between character sets.
  40  *
  41  * This inteface is provided for trusted plugins only since in Native Client it
  42  * would require an expensive out-of-process IPC call for each conversion,
  43  * which makes performance unacceptable. Native Client plugins should include
  44  * ICU or some other library if they need this feature.
  45  */
  46 interface PPB_CharSet_Trusted {
  47   /**
  48    * Converts the UTF-16 string pointed to by |*utf16| to an 8-bit string in
  49    * the specified code page. |utf16_len| is measured in UTF-16 units, not
  50    * bytes. This value may not be NULL.
  51    *
  52    * The given output buffer will be filled up to output_length bytes with the
  53    * result. output_length will be updated with the number of bytes required
  54    * for the given string. The output buffer may be null to just retrieve the
  55    * required buffer length.
  56    *
  57    * This function will return PP_FALSE if there was an error converting the
  58    * string and you requested PP_CHARSET_CONVERSIONERROR_FAIL, or the output
  59    * character set was unknown. Otherwise, it will return PP_TRUE.
  60    */
  61   PP_Bool UTF16ToCharSet([in, size_as=utf16_len] uint16_t[] utf16,
  62                          [in] uint32_t utf16_len,
  63                          [in] str_t output_char_set,
  64                          [in] PP_CharSet_Trusted_ConversionError on_error,
  65                          [out] str_t output_buffer,
  66                          [inout] uint32_t output_length);
  67
  68   /**
  69    * Same as UTF16ToCharSet except converts in the other direction. The input
  70    * is in the given charset, and the |input_len| is the number of bytes in
  71    * the |input| string.
  72    *
  73    * Note that the output_utf16_length is measured in UTF-16 characters.
  74    *
  75    * Since UTF16 can represent every Unicode character, the only time the
  76    * replacement character will be used is if the encoding in the input string
  77    * is incorrect.
  78    */
  79   PP_Bool CharSetToUTF16([in] str_t input,
  80                          [in] uint32_t input_len,
  81                          [in] str_t input_char_set,
  82                          [in] PP_CharSet_Trusted_ConversionError on_error,
  83                          [out] uint16_t output_buffer,
  84                          [inout] uint32_t output_utf16_length);
  85
  86   /**
  87    * Returns a string var representing the current multi-byte character set of
  88    * the current system.
  89    *
  90    * WARNING: You really shouldn't be using this function unless you're dealing
  91    * with legacy data. You should be using UTF-8 or UTF-16 and you don't have
  92    * to worry about the character sets.
  93    */
  94   PP_Var GetDefaultCharSet([in] PP_Instance instance);
  95 };