include/xkbcommon/xkbregistry.h

   1 /*
   2  * Copyright © 2020 Red Hat, Inc.
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the "Software"),
   6  * to deal in the Software without restriction, including without limitation
   7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8  * and/or sell copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice (including the next
  12  * paragraph) shall be included in all copies or substantial portions of the
  13  * Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21  * DEALINGS IN THE SOFTWARE.
  22  */
  23
  24
  25 #ifndef _XKBREGISTRY_H_
  26 #define _XKBREGISTRY_H_
  27
  28 #include <stdarg.h>
  29 #include <stdbool.h>
  30
  31 /**
  32  * @file
  33  * @brief Query for available RMLVO
  34  *
  35  */
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /**
  42  * @defgroup registry Query for available RMLVO
  43  *
  44  * The libxkbregistry API to query for available rules, models, layouts,
  45  * variants and options (RMLVO). libxkbregistry is a separate library to
  46  * libxkbcommon.
  47  *
  48  * This library is the replacement for clients currently parsing evdev.xml
  49  * directly. The library is intended to provide easy access to the set of
  50  * **possible** MLVO configurations for a given ruleset. It is not a library to
  51  * apply these configurations, merely to enumerate them. The intended users of
  52  * this library are the configuration UIs that allow a user to select their
  53  * keyboard layout of choice.
  54  *
  55  * @{
  56  */
  57
  58 /**
  59  * @struct rxkb_context
  60  *
  61  * Opaque top level library context object.
  62  *
  63  * The context contains general library state, like include paths and parsed
  64  * data. Objects are created in a specific context, and multiple contexts
  65  * may coexist simultaneously. Objects from different contexts are
  66  * completely separated and do not share any memory or state.
  67  */
  68 struct rxkb_context;
  69
  70 /**
  71  * @struct rxkb_model
  72  *
  73  * Opaque struct representing an XKB model.
  74  */
  75 struct rxkb_model;
  76
  77 /**
  78  * @struct rxkb_layout
  79  *
  80  * Opaque struct representing an XKB layout, including an optional variant.
  81  * Where the variant is NULL, the layout is the base layout.
  82  *
  83  * For example, "us" is the base layout, "us(intl)" is the "intl" variant of the
  84  * layout "us".
  85  */
  86 struct rxkb_layout;
  87
  88 /**
  89  * @struct rxkb_option_group
  90  *
  91  * Opaque struct representing an option group. Option groups divide the
  92  * individual options into logical groups. Their main purpose is to indicate
  93  * whether some options are mutually exclusive or not.
  94  */
  95 struct rxkb_option_group;
  96
  97 /**
  98  * @struct rxkb_option
  99  *
 100  * Opaque struct representing an XKB option. Options are grouped inside an @ref
 101  * rxkb_option_group.
 102  */
 103 struct rxkb_option;
 104
 105 /**
 106  *
 107  * @struct rxkb_iso639_code
 108  *
 109  * Opaque struct representing an ISO 639-3 code (e.g. "eng", "fra"). There
 110  * is no guarantee that two identical ISO codes share the same struct. You
 111  * must not rely on the pointer value of this struct.
 112  *
 113  * See https://iso639-3.sil.org/code_tables/639/data for a list of codes.
 114  */
 115 struct rxkb_iso639_code;
 116
 117 /**
 118  *
 119  * @struct rxkb_iso3166_code
 120  *
 121  * Opaque struct representing an ISO 3166 Alpha 2 code (e.g. "US", "FR").
 122  * There is no guarantee that two identical ISO codes share the same struct.
 123  * You must not rely on the pointer value of this struct.
 124  *
 125  * See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes for a list
 126  * of codes.
 127  */
 128 struct rxkb_iso3166_code;
 129
 130 /**
 131  * Describes the popularity of an item. Historically, some highly specialized or
 132  * experimental definitions are excluded from the default list and shipped in
 133  * separate files. If these extra definitions are loaded (see @ref
 134  * RXKB_CONTEXT_LOAD_EXOTIC_RULES), the popularity of the item is set
 135  * accordingly.
 136  *
 137  * If the exotic items are not loaded, all items will have the standard
 138  * popularity.
 139  */
 140 enum rxkb_popularity {
 141     RXKB_POPULARITY_STANDARD = 1,
 142     RXKB_POPULARITY_EXOTIC,
 143 };
 144
 145 /**
 146  * Flags for context creation.
 147  */
 148 enum rxkb_context_flags {
 149     RXKB_CONTEXT_NO_FLAGS = 0,
 150     /**
 151      * Skip the default include paths. This requires the caller to call
 152      * rxkb_context_include_path_append() or
 153      * rxkb_context_include_path_append_default().
 154      */
 155     RXKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
 156     /**
 157      * Load the extra items that are considered too exotic for the default list.
 158      *
 159      * For historical reasons, xkeyboard-config ships those exotic rules in a
 160      * separate file (e.g. `evdev.extras.xml`). Where the exotic rules are
 161      * requested, libxkbregistry will look for and load `$ruleset.extras.xml`
 162      * in the include paths, see rxkb_context_include_path_append() for details
 163      * on the lookup behavior.
 164      */
 165     RXKB_CONTEXT_LOAD_EXOTIC_RULES = (1 << 1),
 166     /**
 167      * Disable the use of secure_getenv for this context, so that privileged
 168      * processes can use environment variables. Client uses at their own risk.
 169      *
 170      * @since 1.5.0
 171      */
 172     RXKB_CONTEXT_NO_SECURE_GETENV = (1 << 2)
 173 };
 174
 175 /**
 176  * Create a new xkb registry context.
 177  *
 178  * The context has an initial refcount of 1. Use rxkb_context_unref() to release
 179  * memory associated with this context.
 180  *
 181  * Creating a context does not parse the files yet, use
 182  * rxkb_context_parse().
 183  *
 184  * @param flags Flags affecting context behavior
 185  * @return A new xkb registry context or NULL on failure
 186  */
 187 struct rxkb_context *
 188 rxkb_context_new(enum rxkb_context_flags flags);
 189
 190 /** Specifies a logging level. */
 191 enum rxkb_log_level {
 192     RXKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
 193     RXKB_LOG_LEVEL_ERROR = 20,    /**< Log all errors. */
 194     RXKB_LOG_LEVEL_WARNING = 30,  /**< Log warnings and errors. */
 195     RXKB_LOG_LEVEL_INFO = 40,     /**< Log information, warnings, and errors. */
 196     RXKB_LOG_LEVEL_DEBUG = 50     /**< Log everything. */
 197 };
 198
 199 /**
 200  * Set the current logging level.
 201  *
 202  * @param ctx     The context in which to set the logging level.
 203  * @param level   The logging level to use.  Only messages from this level
 204  * and below will be logged.
 205  *
 206  * The default level is RXKB_LOG_LEVEL_ERROR.  The environment variable
 207  * RXKB_LOG_LEVEL, if set at the time the context was created, overrides the
 208  * default value.  It may be specified as a level number or name.
 209  */
 210 void
 211 rxkb_context_set_log_level(struct rxkb_context *ctx,
 212                            enum rxkb_log_level level);
 213
 214 /**
 215  * Get the current logging level.
 216  */
 217 enum rxkb_log_level
 218 rxkb_context_get_log_level(struct rxkb_context *ctx);
 219
 220 /**
 221  * Set a custom function to handle logging messages.
 222  *
 223  * @param ctx     The context in which to use the set logging function.
 224  * @param log_fn  The function that will be called for logging messages.
 225  * Passing NULL restores the default function, which logs to stderr.
 226  *
 227  * By default, log messages from this library are printed to stderr.  This
 228  * function allows you to replace the default behavior with a custom
 229  * handler.  The handler is only called with messages which match the
 230  * current logging level and verbosity settings for the context.
 231  * level is the logging level of the message.  @a format and @a args are
 232  * the same as in the vprintf(3) function.
 233  *
 234  * You may use rxkb_context_set_user_data() on the context, and then call
 235  * rxkb_context_get_user_data() from within the logging function to provide
 236  * it with additional private context.
 237  */
 238 void
 239 rxkb_context_set_log_fn(struct rxkb_context *ctx,
 240                         void (*log_fn)(struct rxkb_context *ctx,
 241                                        enum rxkb_log_level level,
 242                                        const char *format, va_list args));
 243
 244
 245 /**
 246  * Parse the given ruleset. This can only be called once per context and once
 247  * parsed the data in the context is considered constant and will never
 248  * change.
 249  *
 250  * This function parses all files with the given ruleset name. See
 251  * rxkb_context_include_path_append() for details.
 252  *
 253  * If this function returns false, libxkbregistry failed to parse the xml files.
 254  * This is usually caused by invalid files on the host and should be debugged by
 255  * the host's administrator using external tools. Callers should reduce the
 256  * include paths to known good paths and/or fall back to a default RMLVO set.
 257  *
 258  * If this function returns false, the context should be be considered dead and
 259  * must be released with rxkb_context_unref().
 260  *
 261  * @param ctx The xkb registry context
 262  * @param ruleset The ruleset to parse, e.g. "evdev"
 263  * @return true on success or false on failure
 264  */
 265 bool
 266 rxkb_context_parse(struct rxkb_context *ctx, const char *ruleset);
 267
 268 /**
 269  * Parse the default ruleset as configured at build time. See
 270  * rxkb_context_parse() for details.
 271  */
 272 bool
 273 rxkb_context_parse_default_ruleset(struct rxkb_context *ctx);
 274
 275 /**
 276  * Increases the refcount of this object by one and returns the object.
 277  *
 278  * @param ctx The xkb registry context
 279  * @return The passed in object
 280  */
 281 struct rxkb_context*
 282 rxkb_context_ref(struct rxkb_context *ctx);
 283
 284 /**
 285  * Decreases the refcount of this object by one. Where the refcount of an
 286  * object hits zero, associated resources will be freed.
 287  *
 288  * @param ctx The xkb registry context
 289  * @return always NULL
 290  */
 291 struct rxkb_context*
 292 rxkb_context_unref(struct rxkb_context *ctx);
 293
 294 /**
 295  * Assign user-specific data. libxkbregistry will not look at or modify the
 296  * data, it will merely return the same pointer in
 297  * rxkb_context_get_user_data().
 298  *
 299  * @param ctx The xkb registry context
 300  * @param user_data User-specific data pointer
 301  */
 302 void
 303 rxkb_context_set_user_data(struct rxkb_context *ctx, void *user_data);
 304
 305 /**
 306  * Return the pointer passed into rxkb_context_get_user_data().
 307  *
 308  * @param ctx The xkb registry context
 309  * @return User-specific data pointer
 310  */
 311 void *
 312 rxkb_context_get_user_data(struct rxkb_context *ctx);
 313
 314 /**
 315  * Append a new entry to the context's include path.
 316  *
 317  * The include path handling is optimized for the most common use-case: a set of
 318  * system files that provide a complete set of MLVO and some
 319  * custom MLVO provided by a user **in addition** to the system set.
 320  *
 321  * The include paths should be given so that the least complete path is
 322  * specified first and the most complete path is appended last. For example:
 323  *
 324  * @code
 325  *    ctx = rxkb_context_new(RXKB_CONTEXT_NO_DEFAULT_INCLUDES);
 326  *    rxkb_context_include_path_append(ctx, "/home/user/.config/xkb");
 327  *    rxkb_context_include_path_append(ctx, "/usr/share/X11/xkb");
 328  *    rxkb_context_parse(ctx, "evdev");
 329  * @endcode
 330  *
 331  * The above example reflects the default behavior unless @ref
 332  * RXKB_CONTEXT_NO_DEFAULT_INCLUDES is provided.
 333  *
 334  * Loading of the files is in **reverse order**, i.e. the last path appended is
 335  * loaded first - in this case the ``/usr/share/X11/xkb`` path.
 336  * Any models, layouts, variants and options defined in the "evdev" ruleset
 337  * are loaded into the context. Then, any RMLVO found in the "evdev" ruleset of
 338  * the user's path (``/home/user/.config/xkb`` in this example) are **appended**
 339  * to the existing set.
 340  *
 341  * Note that data from previously loaded include paths is never overwritten,
 342  * only appended to. It is not not possible to change the system-provided data,
 343  * only to append new models, layouts, variants and options to it.
 344  *
 345  * In other words, to define a new variant of the "us" layout called "banana",
 346  * the following XML is sufficient.
 347  *
 348  * @verbatim
 349  * <xkbConfigRegistry version="1.1">
 350  * <layoutList>
 351  *   <layout>
 352  *     <configItem>
 353  *       <name>us</name>
 354  *     </configItem>
 355  *     <variantList>
 356  *       <variant>
 357  *         <configItem>
 358  *          <name>banana</name>
 359  *          <description>English (Banana)</description>
 360  *        </configItem>
 361  *      </variant>
 362  *    </layout>
 363  * </layoutList>
 364  * </xkbConfigRegistry>
 365  * @endverbatim
 366  *
 367  * The list of models, options and all other layouts (including "us" and its
 368  * variants) is taken from the system files. The resulting list of layouts will
 369  * thus have a "us" keyboard layout with the variant "banana" and all other
 370  * system-provided variants (dvorak, colemak, intl, etc.)
 371  *
 372  * This function must be called before rxkb_context_parse() or
 373  * rxkb_context_parse_default_ruleset().
 374  *
 375  * @returns true on success, or false if the include path could not be added
 376  * or is inaccessible.
 377  */
 378 bool
 379 rxkb_context_include_path_append(struct rxkb_context *ctx, const char *path);
 380
 381 /**
 382  * Append the default include paths to the context's include path.
 383  * See rxkb_context_include_path_append() for details about the merge order.
 384  *
 385  * This function must be called before rxkb_context_parse() or
 386  * rxkb_context_parse_default_ruleset().
 387  *
 388  * @returns true on success, or false if the include path could not be added
 389  * or is inaccessible.
 390  */
 391 bool
 392 rxkb_context_include_path_append_default(struct rxkb_context *ctx);
 393
 394 /**
 395  * Return the first model for this context. Use this to start iterating over
 396  * the models, followed by calls to rxkb_model_next(). Models are not sorted.
 397  *
 398  * The refcount of the returned model is not increased. Use rxkb_model_ref() if
 399  * you need to keep this struct outside the immediate scope.
 400  *
 401  * @return The first model in the model list.
 402  */
 403 struct rxkb_model *
 404 rxkb_model_first(struct rxkb_context *ctx);
 405
 406 /**
 407  * Return the next model for this context. Returns NULL when no more models
 408  * are available.
 409  *
 410  * The refcount of the returned model is not increased. Use rxkb_model_ref() if
 411  * you need to keep this struct outside the immediate scope.
 412  *
 413  * @return the next model or NULL at the end of the list
 414  */
 415 struct rxkb_model *
 416 rxkb_model_next(struct rxkb_model *m);
 417
 418 /**
 419  * Increase the refcount of the argument by one.
 420  *
 421  * @returns The argument passed in to this function.
 422  */
 423 struct rxkb_model *
 424 rxkb_model_ref(struct rxkb_model *m);
 425
 426 /**
 427  * Decrease the refcount of the argument by one. When the refcount hits zero,
 428  * all memory associated with this struct is freed.
 429  *
 430  * @returns always NULL
 431  */
 432 struct rxkb_model *
 433 rxkb_model_unref(struct rxkb_model *m);
 434
 435 /**
 436  * Return the name of this model. This is the value for M in RMLVO, to be used
 437  * with libxkbcommon.
 438  */
 439 const char *
 440 rxkb_model_get_name(struct rxkb_model *m);
 441
 442 /**
 443  * Return a human-readable description of this model. This function may return
 444  * NULL.
 445  */
 446 const char *
 447 rxkb_model_get_description(struct rxkb_model *m);
 448
 449 /**
 450  * Return the vendor name for this model. This function may return NULL.
 451  */
 452 const char *
 453 rxkb_model_get_vendor(struct rxkb_model *m);
 454
 455 /**
 456  * Return the popularity for this model.
 457  */
 458 enum rxkb_popularity
 459 rxkb_model_get_popularity(struct rxkb_model *m);
 460
 461 /**
 462  * Return the first layout for this context. Use this to start iterating over
 463  * the layouts, followed by calls to rxkb_layout_next(). Layouts are not sorted.
 464  *
 465  * The refcount of the returned layout is not increased. Use rxkb_layout_ref() if
 466  * you need to keep this struct outside the immediate scope.
 467  *
 468  * @return The first layout in the layout list.
 469  */
 470 struct rxkb_layout *
 471 rxkb_layout_first(struct rxkb_context *ctx);
 472
 473 /**
 474  * Return the next layout for this context. Returns NULL when no more layouts
 475  * are available.
 476  *
 477  * The refcount of the returned layout is not increased. Use rxkb_layout_ref()
 478  * if you need to keep this struct outside the immediate scope.
 479  *
 480  * @return the next layout or NULL at the end of the list
 481  */
 482 struct rxkb_layout *
 483 rxkb_layout_next(struct rxkb_layout *l);
 484
 485 /**
 486  * Increase the refcount of the argument by one.
 487  *
 488  * @returns The argument passed in to this function.
 489  */
 490 struct rxkb_layout *
 491 rxkb_layout_ref(struct rxkb_layout *l);
 492
 493 /**
 494  * Decrease the refcount of the argument by one. When the refcount hits zero,
 495  * all memory associated with this struct is freed.
 496  *
 497  * @returns always NULL
 498  */
 499 struct rxkb_layout *
 500 rxkb_layout_unref(struct rxkb_layout *l);
 501
 502 /**
 503  * Return the name of this layout. This is the value for L in RMLVO, to be used
 504  * with libxkbcommon.
 505  */
 506 const char *
 507 rxkb_layout_get_name(struct rxkb_layout *l);
 508
 509 /**
 510  * Return the variant of this layout. This is the value for V in RMLVO, to be
 511  * used with libxkbcommon.
 512  *
 513  * A variant does not stand on its own, it always depends on the base layout.
 514  * e.g. there may be multiple variants called "intl" but there is only one
 515  * "us(intl)".
 516  *
 517  * Where the variant is NULL, the layout is the base layout (e.g. "us").
 518  */
 519 const char *
 520 rxkb_layout_get_variant(struct rxkb_layout *l);
 521
 522 /**
 523  * Return a short (one-word) description of this layout. This function may
 524  * return NULL.
 525  */
 526 const char *
 527 rxkb_layout_get_brief(struct rxkb_layout *l);
 528
 529 /**
 530  * Return a human-readable description of this layout. This function may return
 531  * NULL.
 532  */
 533 const char *
 534 rxkb_layout_get_description(struct rxkb_layout *l);
 535
 536 /**
 537  * Return the popularity for this layout.
 538  */
 539 enum rxkb_popularity
 540 rxkb_layout_get_popularity(struct rxkb_layout *l);
 541
 542 /**
 543  * Return the first option group for this context. Use this to start iterating
 544  * over the option groups, followed by calls to rxkb_option_group_next().
 545  * Option groups are not sorted.
 546  *
 547  * The refcount of the returned option group is not increased. Use
 548  * rxkb_option_group_ref() if you need to keep this struct outside the immediate
 549  * scope.
 550  *
 551  * @return The first option group in the option group list.
 552  */
 553 struct rxkb_option_group *
 554 rxkb_option_group_first(struct rxkb_context *ctx);
 555
 556 /**
 557  * Return the next option group for this context. Returns NULL when no more
 558  * option groups are available.
 559  *
 560  * The refcount of the returned option group is not increased. Use
 561  * rxkb_option_group_ref() if you need to keep this struct outside the immediate
 562  * scope.
 563  *
 564  * @return the next option group or NULL at the end of the list
 565  */
 566 struct rxkb_option_group *
 567 rxkb_option_group_next(struct rxkb_option_group *g);
 568
 569 /**
 570  * Increase the refcount of the argument by one.
 571  *
 572  * @returns The argument passed in to this function.
 573  */
 574 struct rxkb_option_group *
 575 rxkb_option_group_ref(struct rxkb_option_group *g);
 576
 577 /**
 578  * Decrease the refcount of the argument by one. When the refcount hits zero,
 579  * all memory associated with this struct is freed.
 580  *
 581  * @returns always NULL
 582  */
 583 struct rxkb_option_group *
 584 rxkb_option_group_unref(struct rxkb_option_group *g);
 585
 586 /**
 587  * Return the name of this option group. This is **not** the value for O in
 588  * RMLVO, the name can be used for internal sorting in the caller. This function
 589  * may return NULL.
 590  */
 591 const char *
 592 rxkb_option_group_get_name(struct rxkb_option_group *m);
 593
 594 /**
 595  * Return a human-readable description of this option group. This function may
 596  * return NULL.
 597  */
 598 const char *
 599 rxkb_option_group_get_description(struct rxkb_option_group *m);
 600
 601 /**
 602  * @return true if multiple options within this option group can be selected
 603  *              simultaneously, false if all options within this option group
 604  *              are mutually exclusive.
 605  */
 606 bool
 607 rxkb_option_group_allows_multiple(struct rxkb_option_group *g);
 608
 609 /**
 610  * Return the popularity for this option group.
 611  */
 612 enum rxkb_popularity
 613 rxkb_option_group_get_popularity(struct rxkb_option_group *g);
 614
 615 /**
 616  * Return the first option for this option group. Use this to start iterating
 617  * over the options, followed by calls to rxkb_option_next(). Options are not
 618  * sorted.
 619  *
 620  * The refcount of the returned option is not increased. Use rxkb_option_ref()
 621  * if you need to keep this struct outside the immediate scope.
 622  *
 623  * @return The first option in the option list.
 624  */
 625 struct rxkb_option *
 626 rxkb_option_first(struct rxkb_option_group *group);
 627
 628 /**
 629  * Return the next option for this option group. Returns NULL when no more
 630  * options are available.
 631  *
 632  * The refcount of the returned options is not increased. Use rxkb_option_ref()
 633  * if you need to keep this struct outside the immediate scope.
 634  *
 635  * @returns The next option or NULL at the end of the list
 636  */
 637 struct rxkb_option *
 638 rxkb_option_next(struct rxkb_option *o);
 639
 640 /**
 641  * Increase the refcount of the argument by one.
 642  *
 643  * @returns The argument passed in to this function.
 644  */
 645 struct rxkb_option *
 646 rxkb_option_ref(struct rxkb_option *o);
 647
 648 /**
 649  * Decrease the refcount of the argument by one. When the refcount hits zero,
 650  * all memory associated with this struct is freed.
 651  *
 652  * @returns always NULL
 653  */
 654 struct rxkb_option *
 655 rxkb_option_unref(struct rxkb_option *o);
 656
 657 /**
 658  * Return the name of this option. This is the value for O in RMLVO, to be used
 659  * with libxkbcommon.
 660  */
 661 const char *
 662 rxkb_option_get_name(struct rxkb_option *o);
 663
 664 /**
 665  * Return a short (one-word) description of this option. This function may
 666  * return NULL.
 667  */
 668 const char *
 669 rxkb_option_get_brief(struct rxkb_option *o);
 670
 671 /**
 672  * Return a human-readable description of this option. This function may return
 673  * NULL.
 674  */
 675 const char *
 676 rxkb_option_get_description(struct rxkb_option *o);
 677
 678 /**
 679  * Return the popularity for this option.
 680  */
 681 enum rxkb_popularity
 682 rxkb_option_get_popularity(struct rxkb_option *o);
 683
 684 /**
 685  * Increase the refcount of the argument by one.
 686  *
 687  * @returns The argument passed in to this function.
 688  */
 689 struct rxkb_iso639_code *
 690 rxkb_iso639_code_ref(struct rxkb_iso639_code *iso639);
 691
 692 /**
 693  * Decrease the refcount of the argument by one. When the refcount hits zero,
 694  * all memory associated with this struct is freed.
 695  *
 696  * @returns always NULL
 697  */
 698 struct rxkb_iso639_code *
 699 rxkb_iso639_code_unref(struct rxkb_iso639_code *iso639);
 700
 701 /**
 702  * Return the ISO 639-3 code for this code (e.g. "eng", "fra").
 703  */
 704 const char *
 705 rxkb_iso639_code_get_code(struct rxkb_iso639_code *iso639);
 706
 707 /**
 708  * Return the first ISO 639 for this layout. Use this to start iterating over
 709  * the codes, followed by calls to rxkb_iso639_code_next(). Codes are not
 710  * sorted.
 711  *
 712  * The refcount of the returned code is not increased. Use rxkb_iso639_code_ref()
 713  * if you need to keep this struct outside the immediate scope.
 714  *
 715  * @return The first code in the code list.
 716  */
 717 struct rxkb_iso639_code *
 718 rxkb_layout_get_iso639_first(struct rxkb_layout *layout);
 719
 720 /**
 721  * Return the next code in the list. Returns NULL when no more codes
 722  * are available.
 723  *
 724  * The refcount of the returned codes is not increased. Use
 725  * rxkb_iso639_code_ref() if you need to keep this struct outside the immediate
 726  * scope.
 727  *
 728  * @returns The next code or NULL at the end of the list
 729  */
 730 struct rxkb_iso639_code *
 731 rxkb_iso639_code_next(struct rxkb_iso639_code *iso639);
 732
 733 /**
 734  * Increase the refcount of the argument by one.
 735  *
 736  * @returns The argument passed in to this function.
 737  */
 738 struct rxkb_iso3166_code *
 739 rxkb_iso3166_code_ref(struct rxkb_iso3166_code *iso3166);
 740
 741 /**
 742  * Decrease the refcount of the argument by one. When the refcount hits zero,
 743  * all memory associated with this struct is freed.
 744  *
 745  * @returns always NULL
 746  */
 747 struct rxkb_iso3166_code *
 748 rxkb_iso3166_code_unref(struct rxkb_iso3166_code *iso3166);
 749
 750 /**
 751  * Return the ISO 3166 Alpha 2 code for this code (e.g. "US", "FR").
 752  */
 753 const char *
 754 rxkb_iso3166_code_get_code(struct rxkb_iso3166_code *iso3166);
 755
 756 /**
 757  * Return the first ISO 3166 for this layout. Use this to start iterating over
 758  * the codes, followed by calls to rxkb_iso3166_code_next(). Codes are not
 759  * sorted.
 760  *
 761  * The refcount of the returned code is not increased. Use
 762  * rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate
 763  * scope.
 764  *
 765  * @return The first code in the code list.
 766  */
 767 struct rxkb_iso3166_code *
 768 rxkb_layout_get_iso3166_first(struct rxkb_layout *layout);
 769
 770 /**
 771  * Return the next code in the list. Returns NULL when no more codes
 772  * are available.
 773  *
 774  * The refcount of the returned codes is not increased. Use
 775  * rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate
 776  * scope.
 777  *
 778  * @returns The next code or NULL at the end of the list
 779  */
 780 struct rxkb_iso3166_code *
 781 rxkb_iso3166_code_next(struct rxkb_iso3166_code *iso3166);
 782
 783 /** @} */
 784
 785 #ifdef __cplusplus
 786 } /* extern "C" */
 787 #endif
 788
 789 #endif /* _XKBREGISTRY_H_ */