Back to home page

EIC code displayed by LXR

 
 

    


Warning, file /include/xkbcommon/xkbregistry.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 /*
0002  * Copyright © 2020 Red Hat, Inc.
0003  *
0004  * Permission is hereby granted, free of charge, to any person obtaining a
0005  * copy of this software and associated documentation files (the "Software"),
0006  * to deal in the Software without restriction, including without limitation
0007  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
0008  * and/or sell copies of the Software, and to permit persons to whom the
0009  * Software is furnished to do so, subject to the following conditions:
0010  *
0011  * The above copyright notice and this permission notice (including the next
0012  * paragraph) shall be included in all copies or substantial portions of the
0013  * Software.
0014  *
0015  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0016  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0017  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
0018  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
0019  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
0020  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
0021  * DEALINGS IN THE SOFTWARE.
0022  */
0023 
0024 
0025 #ifndef _XKBREGISTRY_H_
0026 #define _XKBREGISTRY_H_
0027 
0028 #include <stdarg.h>
0029 #include <stdbool.h>
0030 
0031 /**
0032  * @file
0033  * @brief Query for available RMLVO
0034  *
0035  */
0036 
0037 #ifdef __cplusplus
0038 extern "C" {
0039 #endif
0040 
0041 /**
0042  * @defgroup registry Query for available RMLVO
0043  *
0044  * The libxkbregistry API to query for available rules, models, layouts,
0045  * variants and options (RMLVO). libxkbregistry is a separate library to
0046  * libxkbcommon.
0047  *
0048  * This library is the replacement for clients currently parsing evdev.xml
0049  * directly. The library is intended to provide easy access to the set of
0050  * **possible** MLVO configurations for a given ruleset. It is not a library to
0051  * apply these configurations, merely to enumerate them. The intended users of
0052  * this library are the configuration UIs that allow a user to select their
0053  * keyboard layout of choice.
0054  *
0055  * @{
0056  */
0057 
0058 /**
0059  * @struct rxkb_context
0060  *
0061  * Opaque top level library context object.
0062  *
0063  * The context contains general library state, like include paths and parsed
0064  * data. Objects are created in a specific context, and multiple contexts
0065  * may coexist simultaneously. Objects from different contexts are
0066  * completely separated and do not share any memory or state.
0067  */
0068 struct rxkb_context;
0069 
0070 /**
0071  * @struct rxkb_model
0072  *
0073  * Opaque struct representing an XKB model.
0074  */
0075 struct rxkb_model;
0076 
0077 /**
0078  * @struct rxkb_layout
0079  *
0080  * Opaque struct representing an XKB layout, including an optional variant.
0081  * Where the variant is NULL, the layout is the base layout.
0082  *
0083  * For example, "us" is the base layout, "us(intl)" is the "intl" variant of the
0084  * layout "us".
0085  */
0086 struct rxkb_layout;
0087 
0088 /**
0089  * @struct rxkb_option_group
0090  *
0091  * Opaque struct representing an option group. Option groups divide the
0092  * individual options into logical groups. Their main purpose is to indicate
0093  * whether some options are mutually exclusive or not.
0094  */
0095 struct rxkb_option_group;
0096 
0097 /**
0098  * @struct rxkb_option
0099  *
0100  * Opaque struct representing an XKB option. Options are grouped inside an @ref
0101  * rxkb_option_group.
0102  */
0103 struct rxkb_option;
0104 
0105 /**
0106  *
0107  * @struct rxkb_iso639_code
0108  *
0109  * Opaque struct representing an ISO 639-3 code (e.g. "eng", "fra"). There
0110  * is no guarantee that two identical ISO codes share the same struct. You
0111  * must not rely on the pointer value of this struct.
0112  *
0113  * See https://iso639-3.sil.org/code_tables/639/data for a list of codes.
0114  */
0115 struct rxkb_iso639_code;
0116 
0117 /**
0118  *
0119  * @struct rxkb_iso3166_code
0120  *
0121  * Opaque struct representing an ISO 3166 Alpha 2 code (e.g. "US", "FR").
0122  * There is no guarantee that two identical ISO codes share the same struct.
0123  * You must not rely on the pointer value of this struct.
0124  *
0125  * See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes for a list
0126  * of codes.
0127  */
0128 struct rxkb_iso3166_code;
0129 
0130 /**
0131  * Describes the popularity of an item. Historically, some highly specialized or
0132  * experimental definitions are excluded from the default list and shipped in
0133  * separate files. If these extra definitions are loaded (see @ref
0134  * RXKB_CONTEXT_LOAD_EXOTIC_RULES), the popularity of the item is set
0135  * accordingly.
0136  *
0137  * If the exotic items are not loaded, all items will have the standard
0138  * popularity.
0139  */
0140 enum rxkb_popularity {
0141     RXKB_POPULARITY_STANDARD = 1,
0142     RXKB_POPULARITY_EXOTIC,
0143 };
0144 
0145 /**
0146  * Flags for context creation.
0147  */
0148 enum rxkb_context_flags {
0149     RXKB_CONTEXT_NO_FLAGS = 0,
0150     /**
0151      * Skip the default include paths. This requires the caller to call
0152      * rxkb_context_include_path_append() or
0153      * rxkb_context_include_path_append_default().
0154      */
0155     RXKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
0156     /**
0157      * Load the extra items that are considered too exotic for the default list.
0158      *
0159      * For historical reasons, xkeyboard-config ships those exotic rules in a
0160      * separate file (e.g. `evdev.extras.xml`). Where the exotic rules are
0161      * requested, libxkbregistry will look for and load `$ruleset.extras.xml`
0162      * in the include paths, see rxkb_context_include_path_append() for details
0163      * on the lookup behavior.
0164      */
0165     RXKB_CONTEXT_LOAD_EXOTIC_RULES = (1 << 1),
0166     /**
0167      * Disable the use of secure_getenv for this context, so that privileged
0168      * processes can use environment variables. Client uses at their own risk.
0169      *
0170      * @since 1.5.0
0171      */
0172     RXKB_CONTEXT_NO_SECURE_GETENV = (1 << 2)
0173 };
0174 
0175 /**
0176  * Create a new xkb registry context.
0177  *
0178  * The context has an initial refcount of 1. Use rxkb_context_unref() to release
0179  * memory associated with this context.
0180  *
0181  * Creating a context does not parse the files yet, use
0182  * rxkb_context_parse().
0183  *
0184  * @param flags Flags affecting context behavior
0185  * @return A new xkb registry context or NULL on failure
0186  */
0187 struct rxkb_context *
0188 rxkb_context_new(enum rxkb_context_flags flags);
0189 
0190 /** Specifies a logging level. */
0191 enum rxkb_log_level {
0192     RXKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
0193     RXKB_LOG_LEVEL_ERROR = 20,    /**< Log all errors. */
0194     RXKB_LOG_LEVEL_WARNING = 30,  /**< Log warnings and errors. */
0195     RXKB_LOG_LEVEL_INFO = 40,     /**< Log information, warnings, and errors. */
0196     RXKB_LOG_LEVEL_DEBUG = 50     /**< Log everything. */
0197 };
0198 
0199 /**
0200  * Set the current logging level.
0201  *
0202  * @param ctx     The context in which to set the logging level.
0203  * @param level   The logging level to use.  Only messages from this level
0204  * and below will be logged.
0205  *
0206  * The default level is RXKB_LOG_LEVEL_ERROR.  The environment variable
0207  * RXKB_LOG_LEVEL, if set at the time the context was created, overrides the
0208  * default value.  It may be specified as a level number or name.
0209  */
0210 void
0211 rxkb_context_set_log_level(struct rxkb_context *ctx,
0212                            enum rxkb_log_level level);
0213 
0214 /**
0215  * Get the current logging level.
0216  */
0217 enum rxkb_log_level
0218 rxkb_context_get_log_level(struct rxkb_context *ctx);
0219 
0220 /**
0221  * Set a custom function to handle logging messages.
0222  *
0223  * @param ctx     The context in which to use the set logging function.
0224  * @param log_fn  The function that will be called for logging messages.
0225  * Passing NULL restores the default function, which logs to stderr.
0226  *
0227  * By default, log messages from this library are printed to stderr.  This
0228  * function allows you to replace the default behavior with a custom
0229  * handler.  The handler is only called with messages which match the
0230  * current logging level and verbosity settings for the context.
0231  * level is the logging level of the message.  @a format and @a args are
0232  * the same as in the vprintf(3) function.
0233  *
0234  * You may use rxkb_context_set_user_data() on the context, and then call
0235  * rxkb_context_get_user_data() from within the logging function to provide
0236  * it with additional private context.
0237  */
0238 void
0239 rxkb_context_set_log_fn(struct rxkb_context *ctx,
0240                         void (*log_fn)(struct rxkb_context *ctx,
0241                                        enum rxkb_log_level level,
0242                                        const char *format, va_list args));
0243 
0244 
0245 /**
0246  * Parse the given ruleset. This can only be called once per context and once
0247  * parsed the data in the context is considered constant and will never
0248  * change.
0249  *
0250  * This function parses all files with the given ruleset name. See
0251  * rxkb_context_include_path_append() for details.
0252  *
0253  * If this function returns false, libxkbregistry failed to parse the xml files.
0254  * This is usually caused by invalid files on the host and should be debugged by
0255  * the host's administrator using external tools. Callers should reduce the
0256  * include paths to known good paths and/or fall back to a default RMLVO set.
0257  *
0258  * If this function returns false, the context should be be considered dead and
0259  * must be released with rxkb_context_unref().
0260  *
0261  * @param ctx The xkb registry context
0262  * @param ruleset The ruleset to parse, e.g. "evdev"
0263  * @return true on success or false on failure
0264  */
0265 bool
0266 rxkb_context_parse(struct rxkb_context *ctx, const char *ruleset);
0267 
0268 /**
0269  * Parse the default ruleset as configured at build time. See
0270  * rxkb_context_parse() for details.
0271  */
0272 bool
0273 rxkb_context_parse_default_ruleset(struct rxkb_context *ctx);
0274 
0275 /**
0276  * Increases the refcount of this object by one and returns the object.
0277  *
0278  * @param ctx The xkb registry context
0279  * @return The passed in object
0280  */
0281 struct rxkb_context*
0282 rxkb_context_ref(struct rxkb_context *ctx);
0283 
0284 /**
0285  * Decreases the refcount of this object by one. Where the refcount of an
0286  * object hits zero, associated resources will be freed.
0287  *
0288  * @param ctx The xkb registry context
0289  * @return always NULL
0290  */
0291 struct rxkb_context*
0292 rxkb_context_unref(struct rxkb_context *ctx);
0293 
0294 /**
0295  * Assign user-specific data. libxkbregistry will not look at or modify the
0296  * data, it will merely return the same pointer in
0297  * rxkb_context_get_user_data().
0298  *
0299  * @param ctx The xkb registry context
0300  * @param user_data User-specific data pointer
0301  */
0302 void
0303 rxkb_context_set_user_data(struct rxkb_context *ctx, void *user_data);
0304 
0305 /**
0306  * Return the pointer passed into rxkb_context_get_user_data().
0307  *
0308  * @param ctx The xkb registry context
0309  * @return User-specific data pointer
0310  */
0311 void *
0312 rxkb_context_get_user_data(struct rxkb_context *ctx);
0313 
0314 /**
0315  * Append a new entry to the context's include path.
0316  *
0317  * The include path handling is optimized for the most common use-case: a set of
0318  * system files that provide a complete set of MLVO and some
0319  * custom MLVO provided by a user **in addition** to the system set.
0320  *
0321  * The include paths should be given so that the least complete path is
0322  * specified first and the most complete path is appended last. For example:
0323  *
0324  * @code
0325  *    ctx = rxkb_context_new(RXKB_CONTEXT_NO_DEFAULT_INCLUDES);
0326  *    rxkb_context_include_path_append(ctx, "/home/user/.config/xkb");
0327  *    rxkb_context_include_path_append(ctx, "/usr/share/X11/xkb");
0328  *    rxkb_context_parse(ctx, "evdev");
0329  * @endcode
0330  *
0331  * The above example reflects the default behavior unless @ref
0332  * RXKB_CONTEXT_NO_DEFAULT_INCLUDES is provided.
0333  *
0334  * Loading of the files is in **reverse order**, i.e. the last path appended is
0335  * loaded first - in this case the ``/usr/share/X11/xkb`` path.
0336  * Any models, layouts, variants and options defined in the "evdev" ruleset
0337  * are loaded into the context. Then, any RMLVO found in the "evdev" ruleset of
0338  * the user's path (``/home/user/.config/xkb`` in this example) are **appended**
0339  * to the existing set.
0340  *
0341  * Note that data from previously loaded include paths is never overwritten,
0342  * only appended to. It is not not possible to change the system-provided data,
0343  * only to append new models, layouts, variants and options to it.
0344  *
0345  * In other words, to define a new variant of the "us" layout called "banana",
0346  * the following XML is sufficient.
0347  *
0348  * @verbatim
0349  * <xkbConfigRegistry version="1.1">
0350  * <layoutList>
0351  *   <layout>
0352  *     <configItem>
0353  *       <name>us</name>
0354  *     </configItem>
0355  *     <variantList>
0356  *       <variant>
0357  *         <configItem>
0358  *          <name>banana</name>
0359  *          <description>English (Banana)</description>
0360  *        </configItem>
0361  *      </variant>
0362  *    </layout>
0363  * </layoutList>
0364  * </xkbConfigRegistry>
0365  * @endverbatim
0366  *
0367  * The list of models, options and all other layouts (including "us" and its
0368  * variants) is taken from the system files. The resulting list of layouts will
0369  * thus have a "us" keyboard layout with the variant "banana" and all other
0370  * system-provided variants (dvorak, colemak, intl, etc.)
0371  *
0372  * This function must be called before rxkb_context_parse() or
0373  * rxkb_context_parse_default_ruleset().
0374  *
0375  * @returns true on success, or false if the include path could not be added
0376  * or is inaccessible.
0377  */
0378 bool
0379 rxkb_context_include_path_append(struct rxkb_context *ctx, const char *path);
0380 
0381 /**
0382  * Append the default include paths to the context's include path.
0383  * See rxkb_context_include_path_append() for details about the merge order.
0384  *
0385  * This function must be called before rxkb_context_parse() or
0386  * rxkb_context_parse_default_ruleset().
0387  *
0388  * @returns true on success, or false if the include path could not be added
0389  * or is inaccessible.
0390  */
0391 bool
0392 rxkb_context_include_path_append_default(struct rxkb_context *ctx);
0393 
0394 /**
0395  * Return the first model for this context. Use this to start iterating over
0396  * the models, followed by calls to rxkb_model_next(). Models are not sorted.
0397  *
0398  * The refcount of the returned model is not increased. Use rxkb_model_ref() if
0399  * you need to keep this struct outside the immediate scope.
0400  *
0401  * @return The first model in the model list.
0402  */
0403 struct rxkb_model *
0404 rxkb_model_first(struct rxkb_context *ctx);
0405 
0406 /**
0407  * Return the next model for this context. Returns NULL when no more models
0408  * are available.
0409  *
0410  * The refcount of the returned model is not increased. Use rxkb_model_ref() if
0411  * you need to keep this struct outside the immediate scope.
0412  *
0413  * @return the next model or NULL at the end of the list
0414  */
0415 struct rxkb_model *
0416 rxkb_model_next(struct rxkb_model *m);
0417 
0418 /**
0419  * Increase the refcount of the argument by one.
0420  *
0421  * @returns The argument passed in to this function.
0422  */
0423 struct rxkb_model *
0424 rxkb_model_ref(struct rxkb_model *m);
0425 
0426 /**
0427  * Decrease the refcount of the argument by one. When the refcount hits zero,
0428  * all memory associated with this struct is freed.
0429  *
0430  * @returns always NULL
0431  */
0432 struct rxkb_model *
0433 rxkb_model_unref(struct rxkb_model *m);
0434 
0435 /**
0436  * Return the name of this model. This is the value for M in RMLVO, to be used
0437  * with libxkbcommon.
0438  */
0439 const char *
0440 rxkb_model_get_name(struct rxkb_model *m);
0441 
0442 /**
0443  * Return a human-readable description of this model. This function may return
0444  * NULL.
0445  */
0446 const char *
0447 rxkb_model_get_description(struct rxkb_model *m);
0448 
0449 /**
0450  * Return the vendor name for this model. This function may return NULL.
0451  */
0452 const char *
0453 rxkb_model_get_vendor(struct rxkb_model *m);
0454 
0455 /**
0456  * Return the popularity for this model.
0457  */
0458 enum rxkb_popularity
0459 rxkb_model_get_popularity(struct rxkb_model *m);
0460 
0461 /**
0462  * Return the first layout for this context. Use this to start iterating over
0463  * the layouts, followed by calls to rxkb_layout_next(). Layouts are not sorted.
0464  *
0465  * The refcount of the returned layout is not increased. Use rxkb_layout_ref() if
0466  * you need to keep this struct outside the immediate scope.
0467  *
0468  * @return The first layout in the layout list.
0469  */
0470 struct rxkb_layout *
0471 rxkb_layout_first(struct rxkb_context *ctx);
0472 
0473 /**
0474  * Return the next layout for this context. Returns NULL when no more layouts
0475  * are available.
0476  *
0477  * The refcount of the returned layout is not increased. Use rxkb_layout_ref()
0478  * if you need to keep this struct outside the immediate scope.
0479  *
0480  * @return the next layout or NULL at the end of the list
0481  */
0482 struct rxkb_layout *
0483 rxkb_layout_next(struct rxkb_layout *l);
0484 
0485 /**
0486  * Increase the refcount of the argument by one.
0487  *
0488  * @returns The argument passed in to this function.
0489  */
0490 struct rxkb_layout *
0491 rxkb_layout_ref(struct rxkb_layout *l);
0492 
0493 /**
0494  * Decrease the refcount of the argument by one. When the refcount hits zero,
0495  * all memory associated with this struct is freed.
0496  *
0497  * @returns always NULL
0498  */
0499 struct rxkb_layout *
0500 rxkb_layout_unref(struct rxkb_layout *l);
0501 
0502 /**
0503  * Return the name of this layout. This is the value for L in RMLVO, to be used
0504  * with libxkbcommon.
0505  */
0506 const char *
0507 rxkb_layout_get_name(struct rxkb_layout *l);
0508 
0509 /**
0510  * Return the variant of this layout. This is the value for V in RMLVO, to be
0511  * used with libxkbcommon.
0512  *
0513  * A variant does not stand on its own, it always depends on the base layout.
0514  * e.g. there may be multiple variants called "intl" but there is only one
0515  * "us(intl)".
0516  *
0517  * Where the variant is NULL, the layout is the base layout (e.g. "us").
0518  */
0519 const char *
0520 rxkb_layout_get_variant(struct rxkb_layout *l);
0521 
0522 /**
0523  * Return a short (one-word) description of this layout. This function may
0524  * return NULL.
0525  */
0526 const char *
0527 rxkb_layout_get_brief(struct rxkb_layout *l);
0528 
0529 /**
0530  * Return a human-readable description of this layout. This function may return
0531  * NULL.
0532  */
0533 const char *
0534 rxkb_layout_get_description(struct rxkb_layout *l);
0535 
0536 /**
0537  * Return the popularity for this layout.
0538  */
0539 enum rxkb_popularity
0540 rxkb_layout_get_popularity(struct rxkb_layout *l);
0541 
0542 /**
0543  * Return the first option group for this context. Use this to start iterating
0544  * over the option groups, followed by calls to rxkb_option_group_next().
0545  * Option groups are not sorted.
0546  *
0547  * The refcount of the returned option group is not increased. Use
0548  * rxkb_option_group_ref() if you need to keep this struct outside the immediate
0549  * scope.
0550  *
0551  * @return The first option group in the option group list.
0552  */
0553 struct rxkb_option_group *
0554 rxkb_option_group_first(struct rxkb_context *ctx);
0555 
0556 /**
0557  * Return the next option group for this context. Returns NULL when no more
0558  * option groups are available.
0559  *
0560  * The refcount of the returned option group is not increased. Use
0561  * rxkb_option_group_ref() if you need to keep this struct outside the immediate
0562  * scope.
0563  *
0564  * @return the next option group or NULL at the end of the list
0565  */
0566 struct rxkb_option_group *
0567 rxkb_option_group_next(struct rxkb_option_group *g);
0568 
0569 /**
0570  * Increase the refcount of the argument by one.
0571  *
0572  * @returns The argument passed in to this function.
0573  */
0574 struct rxkb_option_group *
0575 rxkb_option_group_ref(struct rxkb_option_group *g);
0576 
0577 /**
0578  * Decrease the refcount of the argument by one. When the refcount hits zero,
0579  * all memory associated with this struct is freed.
0580  *
0581  * @returns always NULL
0582  */
0583 struct rxkb_option_group *
0584 rxkb_option_group_unref(struct rxkb_option_group *g);
0585 
0586 /**
0587  * Return the name of this option group. This is **not** the value for O in
0588  * RMLVO, the name can be used for internal sorting in the caller. This function
0589  * may return NULL.
0590  */
0591 const char *
0592 rxkb_option_group_get_name(struct rxkb_option_group *m);
0593 
0594 /**
0595  * Return a human-readable description of this option group. This function may
0596  * return NULL.
0597  */
0598 const char *
0599 rxkb_option_group_get_description(struct rxkb_option_group *m);
0600 
0601 /**
0602  * @return true if multiple options within this option group can be selected
0603  *              simultaneously, false if all options within this option group
0604  *              are mutually exclusive.
0605  */
0606 bool
0607 rxkb_option_group_allows_multiple(struct rxkb_option_group *g);
0608 
0609 /**
0610  * Return the popularity for this option group.
0611  */
0612 enum rxkb_popularity
0613 rxkb_option_group_get_popularity(struct rxkb_option_group *g);
0614 
0615 /**
0616  * Return the first option for this option group. Use this to start iterating
0617  * over the options, followed by calls to rxkb_option_next(). Options are not
0618  * sorted.
0619  *
0620  * The refcount of the returned option is not increased. Use rxkb_option_ref()
0621  * if you need to keep this struct outside the immediate scope.
0622  *
0623  * @return The first option in the option list.
0624  */
0625 struct rxkb_option *
0626 rxkb_option_first(struct rxkb_option_group *group);
0627 
0628 /**
0629  * Return the next option for this option group. Returns NULL when no more
0630  * options are available.
0631  *
0632  * The refcount of the returned options is not increased. Use rxkb_option_ref()
0633  * if you need to keep this struct outside the immediate scope.
0634  *
0635  * @returns The next option or NULL at the end of the list
0636  */
0637 struct rxkb_option *
0638 rxkb_option_next(struct rxkb_option *o);
0639 
0640 /**
0641  * Increase the refcount of the argument by one.
0642  *
0643  * @returns The argument passed in to this function.
0644  */
0645 struct rxkb_option *
0646 rxkb_option_ref(struct rxkb_option *o);
0647 
0648 /**
0649  * Decrease the refcount of the argument by one. When the refcount hits zero,
0650  * all memory associated with this struct is freed.
0651  *
0652  * @returns always NULL
0653  */
0654 struct rxkb_option *
0655 rxkb_option_unref(struct rxkb_option *o);
0656 
0657 /**
0658  * Return the name of this option. This is the value for O in RMLVO, to be used
0659  * with libxkbcommon.
0660  */
0661 const char *
0662 rxkb_option_get_name(struct rxkb_option *o);
0663 
0664 /**
0665  * Return a short (one-word) description of this option. This function may
0666  * return NULL.
0667  */
0668 const char *
0669 rxkb_option_get_brief(struct rxkb_option *o);
0670 
0671 /**
0672  * Return a human-readable description of this option. This function may return
0673  * NULL.
0674  */
0675 const char *
0676 rxkb_option_get_description(struct rxkb_option *o);
0677 
0678 /**
0679  * Return the popularity for this option.
0680  */
0681 enum rxkb_popularity
0682 rxkb_option_get_popularity(struct rxkb_option *o);
0683 
0684 /**
0685  * Increase the refcount of the argument by one.
0686  *
0687  * @returns The argument passed in to this function.
0688  */
0689 struct rxkb_iso639_code *
0690 rxkb_iso639_code_ref(struct rxkb_iso639_code *iso639);
0691 
0692 /**
0693  * Decrease the refcount of the argument by one. When the refcount hits zero,
0694  * all memory associated with this struct is freed.
0695  *
0696  * @returns always NULL
0697  */
0698 struct rxkb_iso639_code *
0699 rxkb_iso639_code_unref(struct rxkb_iso639_code *iso639);
0700 
0701 /**
0702  * Return the ISO 639-3 code for this code (e.g. "eng", "fra").
0703  */
0704 const char *
0705 rxkb_iso639_code_get_code(struct rxkb_iso639_code *iso639);
0706 
0707 /**
0708  * Return the first ISO 639 for this layout. Use this to start iterating over
0709  * the codes, followed by calls to rxkb_iso639_code_next(). Codes are not
0710  * sorted.
0711  *
0712  * The refcount of the returned code is not increased. Use rxkb_iso639_code_ref()
0713  * if you need to keep this struct outside the immediate scope.
0714  *
0715  * @return The first code in the code list.
0716  */
0717 struct rxkb_iso639_code *
0718 rxkb_layout_get_iso639_first(struct rxkb_layout *layout);
0719 
0720 /**
0721  * Return the next code in the list. Returns NULL when no more codes
0722  * are available.
0723  *
0724  * The refcount of the returned codes is not increased. Use
0725  * rxkb_iso639_code_ref() if you need to keep this struct outside the immediate
0726  * scope.
0727  *
0728  * @returns The next code or NULL at the end of the list
0729  */
0730 struct rxkb_iso639_code *
0731 rxkb_iso639_code_next(struct rxkb_iso639_code *iso639);
0732 
0733 /**
0734  * Increase the refcount of the argument by one.
0735  *
0736  * @returns The argument passed in to this function.
0737  */
0738 struct rxkb_iso3166_code *
0739 rxkb_iso3166_code_ref(struct rxkb_iso3166_code *iso3166);
0740 
0741 /**
0742  * Decrease the refcount of the argument by one. When the refcount hits zero,
0743  * all memory associated with this struct is freed.
0744  *
0745  * @returns always NULL
0746  */
0747 struct rxkb_iso3166_code *
0748 rxkb_iso3166_code_unref(struct rxkb_iso3166_code *iso3166);
0749 
0750 /**
0751  * Return the ISO 3166 Alpha 2 code for this code (e.g. "US", "FR").
0752  */
0753 const char *
0754 rxkb_iso3166_code_get_code(struct rxkb_iso3166_code *iso3166);
0755 
0756 /**
0757  * Return the first ISO 3166 for this layout. Use this to start iterating over
0758  * the codes, followed by calls to rxkb_iso3166_code_next(). Codes are not
0759  * sorted.
0760  *
0761  * The refcount of the returned code is not increased. Use
0762  * rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate
0763  * scope.
0764  *
0765  * @return The first code in the code list.
0766  */
0767 struct rxkb_iso3166_code *
0768 rxkb_layout_get_iso3166_first(struct rxkb_layout *layout);
0769 
0770 /**
0771  * Return the next code in the list. Returns NULL when no more codes
0772  * are available.
0773  *
0774  * The refcount of the returned codes is not increased. Use
0775  * rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate
0776  * scope.
0777  *
0778  * @returns The next code or NULL at the end of the list
0779  */
0780 struct rxkb_iso3166_code *
0781 rxkb_iso3166_code_next(struct rxkb_iso3166_code *iso3166);
0782 
0783 /** @} */
0784 
0785 #ifdef __cplusplus
0786 } /* extern "C" */
0787 #endif
0788 
0789 #endif /* _XKBREGISTRY_H_ */