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
 168 /**
 169  * Create a new xkb registry context.
 170  *
 171  * The context has an initial refcount of 1. Use rxkb_context_unref() to release
 172  * memory associated with this context.
 173  *
 174  * Creating a context does not parse the files yet, use
 175  * rxkb_context_parse().
 176  *
 177  * @param flags Flags affecting context behavior
 178  * @return A new xkb registry context or NULL on failure
 179  */
 180 struct rxkb_context *
 181 rxkb_context_new(enum rxkb_context_flags flags);
 182
 183 /** Specifies a logging level. */
 184 enum rxkb_log_level {
 185     RXKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
 186     RXKB_LOG_LEVEL_ERROR = 20,    /**< Log all errors. */
 187     RXKB_LOG_LEVEL_WARNING = 30,  /**< Log warnings and errors. */
 188     RXKB_LOG_LEVEL_INFO = 40,     /**< Log information, warnings, and errors. */
 189     RXKB_LOG_LEVEL_DEBUG = 50     /**< Log everything. */
 190 };
 191
 192 /**
 193  * Set the current logging level.
 194  *
 195  * @param ctx     The context in which to set the logging level.
 196  * @param level   The logging level to use.  Only messages from this level
 197  * and below will be logged.
 198  *
 199  * The default level is RXKB_LOG_LEVEL_ERROR.  The environment variable
 200  * RXKB_LOG_LEVEL, if set at the time the context was created, overrides the
 201  * default value.  It may be specified as a level number or name.
 202  */
 203 void
 204 rxkb_context_set_log_level(struct rxkb_context *ctx,
 205                            enum rxkb_log_level level);
 206
 207 /**
 208  * Get the current logging level.
 209  */
 210 enum rxkb_log_level
 211 rxkb_context_get_log_level(struct rxkb_context *ctx);
 212
 213 /**
 214  * Set a custom function to handle logging messages.
 215  *
 216  * @param ctx     The context in which to use the set logging function.
 217  * @param log_fn  The function that will be called for logging messages.
 218  * Passing NULL restores the default function, which logs to stderr.
 219  *
 220  * By default, log messages from this library are printed to stderr.  This
 221  * function allows you to replace the default behavior with a custom
 222  * handler.  The handler is only called with messages which match the
 223  * current logging level and verbosity settings for the context.
 224  * level is the logging level of the message.  @a format and @a args are
 225  * the same as in the vprintf(3) function.
 226  *
 227  * You may use rxkb_context_set_user_data() on the context, and then call
 228  * rxkb_context_get_user_data() from within the logging function to provide
 229  * it with additional private context.
 230  */
 231 void
 232 rxkb_context_set_log_fn(struct rxkb_context *ctx,
 233                         void (*log_fn)(struct rxkb_context *ctx,
 234                                        enum rxkb_log_level level,
 235                                        const char *format, va_list args));
 236
 237
 238 /**
 239  * Parse the given ruleset. This can only be called once per context and once
 240  * parsed the data in the context is considered constant and will never
 241  * change.
 242  *
 243  * This function parses all files with the given ruleset name. See
 244  * rxkb_context_include_path_append() for details.
 245  *
 246  * If this function returns false, libxkbregistry failed to parse the xml files.
 247  * This is usually caused by invalid files on the host and should be debugged by
 248  * the host's administrator using external tools. Callers should reduce the
 249  * include paths to known good paths and/or fall back to a default RMLVO set.
 250  *
 251  * If this function returns false, the context should be be considered dead and
 252  * must be released with rxkb_context_unref().
 253  *
 254  * @param ctx The xkb registry context
 255  * @param ruleset The ruleset to parse, e.g. "evdev"
 256  * @return true on success or false on failure
 257  */
 258 bool
 259 rxkb_context_parse(struct rxkb_context *ctx, const char *ruleset);
 260
 261 /**
 262  * Parse the default ruleset as configured at build time. See
 263  * rxkb_context_parse() for details.
 264  */
 265 bool
 266 rxkb_context_parse_default_ruleset(struct rxkb_context *ctx);
 267
 268 /**
 269  * Increases the refcount of this object by one and returns the object.
 270  *
 271  * @param ctx The xkb registry context
 272  * @return The passed in object
 273  */
 274 struct rxkb_context*
 275 rxkb_context_ref(struct rxkb_context *ctx);
 276
 277 /**
 278  * Decreases the refcount of this object by one. Where the refcount of an
 279  * object hits zero, associated resources will be freed.
 280  *
 281  * @param ctx The xkb registry context
 282  * @return always NULL
 283  */
 284 struct rxkb_context*
 285 rxkb_context_unref(struct rxkb_context *ctx);
 286
 287 /**
 288  * Assign user-specific data. libxkbregistry will not look at or modify the
 289  * data, it will merely return the same pointer in
 290  * rxkb_context_get_user_data().
 291  *
 292  * @param ctx The xkb registry context
 293  * @param user_data User-specific data pointer
 294  */
 295 void
 296 rxkb_context_set_user_data(struct rxkb_context *ctx, void *user_data);
 297
 298 /**
 299  * Return the pointer passed into rxkb_context_get_user_data().
 300  *
 301  * @param ctx The xkb registry context
 302  * @return User-specific data pointer
 303  */
 304 void *
 305 rxkb_context_get_user_data(struct rxkb_context *ctx);
 306
 307 /**
 308  * Append a new entry to the context's include path.
 309  *
 310  * The include path handling is optimized for the most common use-case: a set of
 311  * system files that provide a complete set of MLVO and some
 312  * custom MLVO provided by a user **in addition** to the system set.
 313  *
 314  * The include paths should be given so that the least complete path is
 315  * specified first and the most complete path is appended last. For example:
 316  *
 317  * @code
 318  *    ctx = rxkb_context_new(RXKB_CONTEXT_NO_DEFAULT_INCLUDES);
 319  *    rxkb_context_include_path_append(ctx, "/home/user/.config/xkb");
 320  *    rxkb_context_include_path_append(ctx, "/usr/share/X11/xkb");
 321  *    rxkb_context_parse(ctx, "evdev");
 322  * @endcode
 323  *
 324  * The above example reflects the default behavior unless @ref
 325  * RXKB_CONTEXT_NO_DEFAULT_INCLUDES is provided.
 326  *
 327  * Loading of the files is in **reverse order**, i.e. the last path appended is
 328  * loaded first - in this case the ``/usr/share/X11/xkb`` path.
 329  * Any models, layouts, variants and options defined in the "evdev" ruleset
 330  * are loaded into the context. Then, any RMLVO found in the "evdev" ruleset of
 331  * the user's path (``/home/user/.config/xkb`` in this example) are **appended**
 332  * to the existing set.
 333  *
 334  * Note that data from previously loaded include paths is never overwritten,
 335  * only appended to. It is not not possible to change the system-provided data,
 336  * only to append new models, layouts, variants and options to it.
 337  *
 338  * In other words, to define a new variant of the "us" layout called "banana",
 339  * the following XML is sufficient.
 340  *
 341  * @verbatim
 342  * <xkbConfigRegistry version="1.1">
 343  * <layoutList>
 344  *   <layout>
 345  *     <configItem>
 346  *       <name>us</name>
 347  *     </configItem>
 348  *     <variantList>
 349  *       <variant>
 350  *         <configItem>
 351  *          <name>banana</name>
 352  *          <description>English (Banana)</description>
 353  *        </configItem>
 354  *      </variant>
 355  *    </layout>
 356  * </layoutList>
 357  * </xkbConfigRegistry>
 358  * @endverbatim
 359  *
 360  * The list of models, options and all other layouts (including "us" and its
 361  * variants) is taken from the system files. The resulting list of layouts will
 362  * thus have a "us" keyboard layout with the variant "banana" and all other
 363  * system-provided variants (dvorak, colemak, intl, etc.)
 364  *
 365  * This function must be called before rxkb_context_parse() or
 366  * rxkb_context_parse_default_ruleset().
 367  *
 368  * @returns true on success, or false if the include path could not be added
 369  * or is inaccessible.
 370  */
 371 bool
 372 rxkb_context_include_path_append(struct rxkb_context *ctx, const char *path);
 373
 374 /**
 375  * Append the default include paths to the context's include path.
 376  * See rxkb_context_include_path_append() for details about the merge order.
 377  *
 378  * This function must be called before rxkb_context_parse() or
 379  * rxkb_context_parse_default_ruleset().
 380  *
 381  * @returns true on success, or false if the include path could not be added
 382  * or is inaccessible.
 383  */
 384 bool
 385 rxkb_context_include_path_append_default(struct rxkb_context *ctx);
 386
 387 /**
 388  * Return the first model for this context. Use this to start iterating over
 389  * the models, followed by calls to rxkb_model_next(). Models are not sorted.
 390  *
 391  * The refcount of the returned model is not increased. Use rxkb_model_ref() if
 392  * you need to keep this struct outside the immediate scope.
 393  *
 394  * @return The first model in the model list.
 395  */
 396 struct rxkb_model *
 397 rxkb_model_first(struct rxkb_context *ctx);
 398
 399 /**
 400  * Return the next model for this context. Returns NULL when no more models
 401  * are available.
 402  *
 403  * The refcount of the returned model is not increased. Use rxkb_model_ref() if
 404  * you need to keep this struct outside the immediate scope.
 405  *
 406  * @return the next model or NULL at the end of the list
 407  */
 408 struct rxkb_model *
 409 rxkb_model_next(struct rxkb_model *m);
 410
 411 /**
 412  * Increase the refcount of the argument by one.
 413  *
 414  * @returns The argument passed in to this function.
 415  */
 416 struct rxkb_model *
 417 rxkb_model_ref(struct rxkb_model *m);
 418
 419 /**
 420  * Decrease the refcount of the argument by one. When the refcount hits zero,
 421  * all memory associated with this struct is freed.
 422  *
 423  * @returns always NULL
 424  */
 425 struct rxkb_model *
 426 rxkb_model_unref(struct rxkb_model *m);
 427
 428 /**
 429  * Return the name of this model. This is the value for M in RMLVO, to be used
 430  * with libxkbcommon.
 431  */
 432 const char *
 433 rxkb_model_get_name(struct rxkb_model *m);
 434
 435 /**
 436  * Return a human-readable description of this model. This function may return
 437  * NULL.
 438  */
 439 const char *
 440 rxkb_model_get_description(struct rxkb_model *m);
 441
 442 /**
 443  * Return the vendor name for this model. This function may return NULL.
 444  */
 445 const char *
 446 rxkb_model_get_vendor(struct rxkb_model *m);
 447
 448 /**
 449  * Return the popularity for this model.
 450  */
 451 enum rxkb_popularity
 452 rxkb_model_get_popularity(struct rxkb_model *m);
 453
 454 /**
 455  * Return the first layout for this context. Use this to start iterating over
 456  * the layouts, followed by calls to rxkb_layout_next(). Layouts are not sorted.
 457  *
 458  * The refcount of the returned layout is not increased. Use rxkb_layout_ref() if
 459  * you need to keep this struct outside the immediate scope.
 460  *
 461  * @return The first layout in the layout list.
 462  */
 463 struct rxkb_layout *
 464 rxkb_layout_first(struct rxkb_context *ctx);
 465
 466 /**
 467  * Return the next layout for this context. Returns NULL when no more layouts
 468  * are available.
 469  *
 470  * The refcount of the returned layout is not increased. Use rxkb_layout_ref()
 471  * if you need to keep this struct outside the immediate scope.
 472  *
 473  * @return the next layout or NULL at the end of the list
 474  */
 475 struct rxkb_layout *
 476 rxkb_layout_next(struct rxkb_layout *l);
 477
 478 /**
 479  * Increase the refcount of the argument by one.
 480  *
 481  * @returns The argument passed in to this function.
 482  */
 483 struct rxkb_layout *
 484 rxkb_layout_ref(struct rxkb_layout *l);
 485
 486 /**
 487  * Decrease the refcount of the argument by one. When the refcount hits zero,
 488  * all memory associated with this struct is freed.
 489  *
 490  * @returns always NULL
 491  */
 492 struct rxkb_layout *
 493 rxkb_layout_unref(struct rxkb_layout *l);
 494
 495 /**
 496  * Return the name of this layout. This is the value for L in RMLVO, to be used
 497  * with libxkbcommon.
 498  */
 499 const char *
 500 rxkb_layout_get_name(struct rxkb_layout *l);
 501
 502 /**
 503  * Return the variant of this layout. This is the value for V in RMLVO, to be
 504  * used with libxkbcommon.
 505  *
 506  * A variant does not stand on its own, it always depends on the base layout.
 507  * e.g. there may be multiple variants called "intl" but there is only one
 508  * "us(intl)".
 509  *
 510  * Where the variant is NULL, the layout is the base layout (e.g. "us").
 511  */
 512 const char *
 513 rxkb_layout_get_variant(struct rxkb_layout *l);
 514
 515 /**
 516  * Return a short (one-word) description of this layout. This function may
 517  * return NULL.
 518  */
 519 const char *
 520 rxkb_layout_get_brief(struct rxkb_layout *l);
 521
 522 /**
 523  * Return a human-readable description of this layout. This function may return
 524  * NULL.
 525  */
 526 const char *
 527 rxkb_layout_get_description(struct rxkb_layout *l);
 528
 529 /**
 530  * Return the popularity for this layout.
 531  */
 532 enum rxkb_popularity
 533 rxkb_layout_get_popularity(struct rxkb_layout *l);
 534
 535 /**
 536  * Return the first option group for this context. Use this to start iterating
 537  * over the option groups, followed by calls to rxkb_option_group_next().
 538  * Option groups are not sorted.
 539  *
 540  * The refcount of the returned option group is not increased. Use
 541  * rxkb_option_group_ref() if you need to keep this struct outside the immediate
 542  * scope.
 543  *
 544  * @return The first option group in the option group list.
 545  */
 546 struct rxkb_option_group *
 547 rxkb_option_group_first(struct rxkb_context *ctx);
 548
 549 /**
 550  * Return the next option group for this context. Returns NULL when no more
 551  * option groups are available.
 552  *
 553  * The refcount of the returned option group is not increased. Use
 554  * rxkb_option_group_ref() if you need to keep this struct outside the immediate
 555  * scope.
 556  *
 557  * @return the next option group or NULL at the end of the list
 558  */
 559 struct rxkb_option_group *
 560 rxkb_option_group_next(struct rxkb_option_group *g);
 561
 562 /**
 563  * Increase the refcount of the argument by one.
 564  *
 565  * @returns The argument passed in to this function.
 566  */
 567 struct rxkb_option_group *
 568 rxkb_option_group_ref(struct rxkb_option_group *g);
 569
 570 /**
 571  * Decrease the refcount of the argument by one. When the refcount hits zero,
 572  * all memory associated with this struct is freed.
 573  *
 574  * @returns always NULL
 575  */
 576 struct rxkb_option_group *
 577 rxkb_option_group_unref(struct rxkb_option_group *g);
 578
 579 /**
 580  * Return the name of this option group. This is **not** the value for O in
 581  * RMLVO, the name can be used for internal sorting in the caller. This function
 582  * may return NULL.
 583  */
 584 const char *
 585 rxkb_option_group_get_name(struct rxkb_option_group *m);
 586
 587 /**
 588  * Return a human-readable description of this option group. This function may
 589  * return NULL.
 590  */
 591 const char *
 592 rxkb_option_group_get_description(struct rxkb_option_group *m);
 593
 594 /**
 595  * @return true if multiple options within this option group can be selected
 596  *              simultaneously, false if all options within this option group
 597  *              are mutually exclusive.
 598  */
 599 bool
 600 rxkb_option_group_allows_multiple(struct rxkb_option_group *g);
 601
 602 /**
 603  * Return the popularity for this option group.
 604  */
 605 enum rxkb_popularity
 606 rxkb_option_group_get_popularity(struct rxkb_option_group *g);
 607
 608 /**
 609  * Return the first option for this option group. Use this to start iterating
 610  * over the options, followed by calls to rxkb_option_next(). Options are not
 611  * sorted.
 612  *
 613  * The refcount of the returned option is not increased. Use rxkb_option_ref()
 614  * if you need to keep this struct outside the immediate scope.
 615  *
 616  * @return The first option in the option list.
 617  */
 618 struct rxkb_option *
 619 rxkb_option_first(struct rxkb_option_group *group);
 620
 621 /**
 622  * Return the next option for this option group. Returns NULL when no more
 623  * options are available.
 624  *
 625  * The refcount of the returned options is not increased. Use rxkb_option_ref()
 626  * if you need to keep this struct outside the immediate scope.
 627  *
 628  * @returns The next option or NULL at the end of the list
 629  */
 630 struct rxkb_option *
 631 rxkb_option_next(struct rxkb_option *o);
 632
 633 /**
 634  * Increase the refcount of the argument by one.
 635  *
 636  * @returns The argument passed in to this function.
 637  */
 638 struct rxkb_option *
 639 rxkb_option_ref(struct rxkb_option *o);
 640
 641 /**
 642  * Decrease the refcount of the argument by one. When the refcount hits zero,
 643  * all memory associated with this struct is freed.
 644  *
 645  * @returns always NULL
 646  */
 647 struct rxkb_option *
 648 rxkb_option_unref(struct rxkb_option *o);
 649
 650 /**
 651  * Return the name of this option. This is the value for O in RMLVO, to be used
 652  * with libxkbcommon.
 653  */
 654 const char *
 655 rxkb_option_get_name(struct rxkb_option *o);
 656
 657 /**
 658  * Return a short (one-word) description of this option. This function may
 659  * return NULL.
 660  */
 661 const char *
 662 rxkb_option_get_brief(struct rxkb_option *o);
 663
 664 /**
 665  * Return a human-readable description of this option. This function may return
 666  * NULL.
 667  */
 668 const char *
 669 rxkb_option_get_description(struct rxkb_option *o);
 670
 671 /**
 672  * Return the popularity for this option.
 673  */
 674 enum rxkb_popularity
 675 rxkb_option_get_popularity(struct rxkb_option *o);
 676
 677 /**
 678  * Increase the refcount of the argument by one.
 679  *
 680  * @returns The argument passed in to this function.
 681  */
 682 struct rxkb_iso639_code *
 683 rxkb_iso639_code_ref(struct rxkb_iso639_code *iso639);
 684
 685 /**
 686  * Decrease the refcount of the argument by one. When the refcount hits zero,
 687  * all memory associated with this struct is freed.
 688  *
 689  * @returns always NULL
 690  */
 691 struct rxkb_iso639_code *
 692 rxkb_iso639_code_unref(struct rxkb_iso639_code *iso639);
 693
 694 /**
 695  * Return the ISO 639-3 code for this code (e.g. "eng", "fra").
 696  */
 697 const char *
 698 rxkb_iso639_code_get_code(struct rxkb_iso639_code *iso639);
 699
 700 /**
 701  * Return the first ISO 639 for this layout. Use this to start iterating over
 702  * the codes, followed by calls to rxkb_iso639_code_next(). Codes are not
 703  * sorted.
 704  *
 705  * The refcount of the returned code is not increased. Use rxkb_iso639_code_ref()
 706  * if you need to keep this struct outside the immediate scope.
 707  *
 708  * @return The first code in the code list.
 709  */
 710 struct rxkb_iso639_code *
 711 rxkb_layout_get_iso639_first(struct rxkb_layout *layout);
 712
 713 /**
 714  * Return the next code in the list. Returns NULL when no more codes
 715  * are available.
 716  *
 717  * The refcount of the returned codes is not increased. Use
 718  * rxkb_iso639_code_ref() if you need to keep this struct outside the immediate
 719  * scope.
 720  *
 721  * @returns The next code or NULL at the end of the list
 722  */
 723 struct rxkb_iso639_code *
 724 rxkb_iso639_code_next(struct rxkb_iso639_code *iso639);
 725
 726 /**
 727  * Increase the refcount of the argument by one.
 728  *
 729  * @returns The argument passed in to this function.
 730  */
 731 struct rxkb_iso3166_code *
 732 rxkb_iso3166_code_ref(struct rxkb_iso3166_code *iso3166);
 733
 734 /**
 735  * Decrease the refcount of the argument by one. When the refcount hits zero,
 736  * all memory associated with this struct is freed.
 737  *
 738  * @returns always NULL
 739  */
 740 struct rxkb_iso3166_code *
 741 rxkb_iso3166_code_unref(struct rxkb_iso3166_code *iso3166);
 742
 743 /**
 744  * Return the ISO 3166 Alpha 2 code for this code (e.g. "US", "FR").
 745  */
 746 const char *
 747 rxkb_iso3166_code_get_code(struct rxkb_iso3166_code *iso3166);
 748
 749 /**
 750  * Return the first ISO 3166 for this layout. Use this to start iterating over
 751  * the codes, followed by calls to rxkb_iso3166_code_next(). Codes are not
 752  * sorted.
 753  *
 754  * The refcount of the returned code is not increased. Use
 755  * rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate
 756  * scope.
 757  *
 758  * @return The first code in the code list.
 759  */
 760 struct rxkb_iso3166_code *
 761 rxkb_layout_get_iso3166_first(struct rxkb_layout *layout);
 762
 763 /**
 764  * Return the next code in the list. Returns NULL when no more codes
 765  * are available.
 766  *
 767  * The refcount of the returned codes is not increased. Use
 768  * rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate
 769  * scope.
 770  *
 771  * @returns The next code or NULL at the end of the list
 772  */
 773 struct rxkb_iso3166_code *
 774 rxkb_iso3166_code_next(struct rxkb_iso3166_code *iso3166);
 775
 776 /** @} */
 777
 778 #ifdef __cplusplus
 779 } /* extern "C" */
 780 #endif
 781
 782 #endif /* _XKBREGISTRY_H_ */