/****************************************************************************

 *

 * ftsnames.h

 *

 *   Simple interface to access SFNT 'name' tables (which are used

 *   to hold font names, copyright info, notices, etc.) (specification).

 *

 *   This is _not_ used to retrieve glyph names!

 *

 * Copyright (C) 1996-2019 by

 * David Turner, Robert Wilhelm, and Werner Lemberg.

 *

 * This file is part of the FreeType project, and may only be used,

 * modified, and distributed under the terms of the FreeType project

 * license, LICENSE.TXT.  By continuing to use, modify, or distribute

 * this file you indicate that you have read the license and

 * understand and accept it fully.

 *

 */

  /**************************************************************************

   *

   * @section:

   *   sfnt_names

   *

   * @title:

   *   SFNT Names

   *

   * @abstract:

   *   Access the names embedded in TrueType and OpenType files.

   *

   * @description:

   *   The TrueType and OpenType specifications allow the inclusion of a

   *   special names table ('name') in font files.  This table contains

   *   textual (and internationalized) information regarding the font, like

   *   family name, copyright, version, etc.

   *

   *   The definitions below are used to access them if available.

   *

   *   Note that this has nothing to do with glyph names!

   *

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_SfntName

   *

   * @description:

   *   A structure used to model an SFNT 'name' table entry.

   *

   * @fields:

   *   platform_id ::

   *     The platform ID for `string`.  See @TT_PLATFORM_XXX for possible

   *     values.

   *

   *   encoding_id ::

   *     The encoding ID for `string`.  See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX,

   *     @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX for possible

   *     values.

   *

   *   language_id ::

   *     The language ID for `string`.  See @TT_MAC_LANGID_XXX and

   *     @TT_MS_LANGID_XXX for possible values.

   *

   *     Registered OpenType values for `language_id` are always smaller than

   *     0x8000; values equal or larger than 0x8000 usually indicate a

   *     language tag string (introduced in OpenType version 1.6).  Use

   *     function @FT_Get_Sfnt_LangTag with `language_id` as its argument to

   *     retrieve the associated language tag.

   *

   *   name_id ::

   *     An identifier for `string`.  See @TT_NAME_ID_XXX for possible

   *     values.

   *

   *   string ::

   *     The 'name' string.  Note that its format differs depending on the

   *     (platform,encoding) pair, being either a string of bytes (without a

   *     terminating `NULL` byte) or containing UTF-16BE entities.

   *

   *   string_len ::

   *     The length of `string` in bytes.

   *

   * @note:

   *   Please refer to the TrueType or OpenType specification for more

   *   details.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_Sfnt_Name_Count

   *

   * @description:

   *   Retrieve the number of name strings in the SFNT 'name' table.

   *

   * @input:

   *   face ::

   *     A handle to the source face.

   *

   * @return:

   *   The number of strings in the 'name' table.

   *

   * @note:

   *   This function always returns an error if the config macro

   *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_Sfnt_Name

   *

   * @description:

   *   Retrieve a string of the SFNT 'name' table for a given index.

   *

   * @input:

   *   face ::

   *     A handle to the source face.

   *

   *   idx ::

   *     The index of the 'name' string.

   *

   * @output:

   *   aname ::

   *     The indexed @FT_SfntName structure.

   *

   * @return:

   *   FreeType error code.  0~means success.

   *

   * @note:

   *   The `string` array returned in the `aname` structure is not

   *   null-terminated.  Note that you don't have to deallocate `string` by

   *   yourself; FreeType takes care of it if you call @FT_Done_Face.

   *

   *   Use @FT_Get_Sfnt_Name_Count to get the total number of available

   *   'name' table entries, then do a loop until you get the right platform,

   *   encoding, and name ID.

   *

   *   'name' table format~1 entries can use language tags also, see

   *   @FT_Get_Sfnt_LangTag.

   *

   *   This function always returns an error if the config macro

   *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_SfntLangTag

   *

   * @description:

   *   A structure to model a language tag entry from an SFNT 'name' table.

   *

   * @fields:

   *   string ::

   *     The language tag string, encoded in UTF-16BE (without trailing

   *     `NULL` bytes).

   *

   *   string_len ::

   *     The length of `string` in **bytes**.

   *

   * @note:

   *   Please refer to the TrueType or OpenType specification for more

   *   details.

   *

   * @since:

   *   2.8

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_Sfnt_LangTag

   *

   * @description:

   *   Retrieve the language tag associated with a language ID of an SFNT

   *   'name' table entry.

   *

   * @input:

   *   face ::

   *     A handle to the source face.

   *

   *   langID ::

   *     The language ID, as returned by @FT_Get_Sfnt_Name.  This is always a

   *     value larger than 0x8000.

   *

   * @output:

   *   alangTag ::

   *     The language tag associated with the 'name' table entry's language

   *     ID.

   *

   * @return:

   *   FreeType error code.  0~means success.

   *

   * @note:

   *   The `string` array returned in the `alangTag` structure is not

   *   null-terminated.  Note that you don't have to deallocate `string` by

   *   yourself; FreeType takes care of it if you call @FT_Done_Face.

   *

   *   Only 'name' table format~1 supports language tags.  For format~0

   *   tables, this function always returns FT_Err_Invalid_Table.  For

   *   invalid format~1 language ID values, FT_Err_Invalid_Argument is

   *   returned.

   *

   *   This function always returns an error if the config macro

   *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.

   *

   * @since:

   *   2.8

   */