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_ */ 783