Modulemd.ModuleIndex: Modulemd Reference Manual

## Modulemd.ModuleIndex Modulemd.ModuleIndex — The primary interface to dealing with repodata in the module metadata format. |

## Stability Level

Stable, unless otherwise indicated

## Functions

gint | (*ModulemdReadHandler) ()
gint | (*ModulemdWriteHandler) ()
ModulemdModuleIndex * | modulemd_module_index_new ()
gboolean | modulemd_module_index_update_from_file ()
gboolean | modulemd_module_index_update_from_string ()
gboolean | modulemd_module_index_update_from_stream ()
gboolean | modulemd_module_index_update_from_custom ()
gboolean | modulemd_module_index_update_from_defaults_directory ()
gchar * | modulemd_module_index_dump_to_string ()
gboolean | modulemd_module_index_dump_to_stream ()
gboolean | modulemd_module_index_dump_to_custom ()
GStrv | modulemd_module_index_get_module_names_as_strv ()
ModulemdModule * | modulemd_module_index_get_module ()
GPtrArray * | modulemd_module_index_search_streams ()
GPtrArray * | modulemd_module_index_search_streams_by_nsvca_glob ()
GPtrArray * | modulemd_module_index_search_rpms ()
gboolean | modulemd_module_index_remove_module ()
gboolean | modulemd_module_index_add_module_stream ()
gboolean | modulemd_module_index_add_defaults ()
gboolean | modulemd_module_index_add_obsoletes ()
GHashTable * | modulemd_module_index_get_default_streams_as_hash_table ()
gboolean | modulemd_module_index_add_translation ()
ModulemdDefaultsVersionEnum | modulemd_module_index_get_defaults_mdversion ()
ModulemdModuleStreamVersionEnum | modulemd_module_index_get_stream_mdversion ()
gboolean | modulemd_module_index_upgrade_streams ()
gboolean | modulemd_module_index_upgrade_defaults ()
void | modulemd_module_index_clear_xmds ()

## Types and Values

#define | MODULEMD_TYPE_MODULE_INDEX
| ModulemdModuleIndex

## Object Hierarchy

        GObject
        ╰── ModulemdModuleIndex

## Description

This object provides an interface to the complete metadata read from a repository or manually added to this object.

NOTE: When adding or updating this object from YAML, all objects imported will be automatically upgraded to match the highest version of that object that is seen. This means that if the repository has a mix of ModulemdModuleStreamV1 and ModulemdModuleStreamV2 objects, the index will contain only ModulemdModuleStreamV2. You can check the versions the index upgraded to with the `modulemd_module_index_get_stream_mdversion()` and `modulemd_module_index_get_defaults_mdversion()`. If your application would prefer to always work with a particular stream or defaults version (such as to avoid extra branching logic), the `modulemd_module_index_upgrade_streams()` and `modulemd_module_index_upgrade_defaults()` functions can be used to force the contents of the index to upgrade to those versions.

Interacting with ModulemdModuleIndex is relatively simple. A common Python example for working with Fedora repodata might be (assuming the metadata has already been read into strings):

    1
    2
    3
    4
    5
    6
    7
    8
    fedora_repo_index = Modulemd.ModuleIndex.new()
    fedora_repo_index.update_from_string(fedora_modulemd, True)

    # Get the list of all module names in the index
    module_names = fedora_repo_index.get_module_names()

    # Retrieve information about a particular module from the index
    module = fedora_repo_index.get_module('module_name')

See the ModulemdModule documentation for details on retrieving information about specific modules, including how to get ModulemdDefaults information and retrieve individual ModulemdModuleStream objects.

See the ModulemdModuleIndexMerger documentation for details on merging ModulemdModuleIndex objects from separate repositories together.

## Functions

### ModulemdReadHandler ()

    gint
    (*ModulemdReadHandler) (void *data,
                            unsigned char *buffer,
                            size_t size,
                            size_t *size_read);

The prototype of a read handler.

The read handler is called when the parser needs to read more bytes from the source. The handler should write not more than `size` bytes to the `buffer` . The number of written bytes should be set to the `size_read` variable.

This handler is identical to a yaml_read_handler_t in yaml.h header of libyaml but is included here to avoid depending on yaml.h in modulemd headers.

#### Parameters

data | A private pointer to the data being read. | [inout]
buffer | The buffer to write the data from the source. | [out]
size | The size of the buffer. | [in]
size_read | The actual number of bytes read from the source. | [out]

#### Returns

On success, the handler must return 1. If the handler failed, the returned value must be 0. On EOF, the handler must set the `size_read` to 0 and return 1.

Since: 2.3

### ModulemdWriteHandler ()

    gint
    (*ModulemdWriteHandler) (void *data,
                             unsigned char *buffer,
                             size_t size);

The prototype of a write handler.

The write handler is called when the emitter needs to flush the accumulated characters to the output. The handler should write `size` bytes of the `buffer` to the output.

This handler is identical to a yaml_write_handler_t in yaml.h header of libyaml but is included here to avoid depending on yaml.h in modulemd headers.

#### Parameters

data | A private pointer that includes the data source. | [inout]
buffer | The buffer with bytes to be written. | [out]
size | The size of the buffer. | [in]

#### Returns

On success, the handler must return 1. If the handler failed, the returned value must be 0.

Since: 2.3

### modulemd_module_index_new ()

    ModulemdModuleIndex *
    modulemd_module_index_new (void);

#### Returns

A newly-allocated ModulemdModuleIndex object.

[transfer full]

Since: 2.0

### modulemd_module_index_update_from_file ()

    gboolean
    modulemd_module_index_update_from_file
                                   (ModulemdModuleIndex *self,
                                    const gchar *yaml_file,
                                    gboolean strict,
                                    GPtrArray **failures,
                                    GError **error);

#### Parameters

self | This ModulemdModuleIndex object. |
yaml_file | A name of a YAML file containing the module metadata and other related information such as default streams. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
failures | On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array. | [out][element-type ModulemdSubdocumentInfo][transfer container]
error | A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured. | [out]

#### Returns

`TRUE` if the update was successful. Returns `FALSE` and sets `failures` appropriately if any of the YAML subdocuments were invalid or sets `error` if there was a fatal parse error.

Since: 2.0

### modulemd_module_index_update_from_string ()

    gboolean
    modulemd_module_index_update_from_string
                                   (ModulemdModuleIndex *self,
                                    const gchar *yaml_string,
                                    gboolean strict,
                                    GPtrArray **failures,
                                    GError **error);

#### Parameters

self | This ModulemdModuleIndex object. |
yaml_string | A YAML string containing the module metadata and other related information such as default streams. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
failures | On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array. | [out][element-type ModulemdSubdocumentInfo][transfer container]
error | A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured. | [out]

#### Returns

`TRUE` if the update was successful. Returns `FALSE` and sets `failures` appropriately if any of the YAML subdocuments were invalid or sets `error` if there was a fatal parse error.

Since: 2.0

### modulemd_module_index_update_from_stream ()

    gboolean
    modulemd_module_index_update_from_stream
                                   (ModulemdModuleIndex *self,
                                    FILE *yaml_stream,
                                    gboolean strict,
                                    GPtrArray **failures,
                                    GError **error);

[skip]

#### Parameters

self | This ModulemdModuleIndex object. |
yaml_stream | A YAML stream containing the module metadata and other related information such as default streams. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
failures | On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array. | [out][element-type ModulemdSubdocumentInfo][transfer container]
error | A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured. | [out]

#### Returns

`TRUE` if the update was successful. Returns `FALSE` and sets `failures` appropriately if any of the YAML subdocuments were invalid or sets `error` if there was a fatal parse error.

Since: 2.0

### modulemd_module_index_update_from_custom ()

    gboolean
    modulemd_module_index_update_from_custom
                                   (ModulemdModuleIndex *self,
                                    ModulemdReadHandler custom_read_fn,
                                    void *custom_pvt_data,
                                    gboolean strict,
                                    GPtrArray **failures,
                                    GError **error);

[skip]

#### Parameters

self | This ModulemdModuleIndex object. |
custom_read_fn | A ModulemdReadHandler. | [in]
custom_pvt_data | The private data needed by the ModulemdReadHandler. | [inout]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
failures | On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array. | [out][element-type ModulemdSubdocumentInfo][transfer container]
error | A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured. | [out]

#### Returns

`TRUE` if the update was successful. Returns `FALSE` and sets `failures` appropriately if any of the YAML subdocuments were invalid or sets `error` if there was a fatal parse error.

Since: 2.3

### modulemd_module_index_update_from_defaults_directory ()

    gboolean
    modulemd_module_index_update_from_defaults_directory
                                   (ModulemdModuleIndex *self,
                                    const gchar *path,
                                    gboolean strict,
                                    const gchar *overrides_path,
                                    GError **error);

This function will open the directory at `path` and iterate through it, adding any files with the suffix ".yaml" to `self` . If `overrides_path` is non-`NULL`, it will also open any files with the suffix ".yaml" in that location and import them, overriding any conflicts with the existing defaults.

Note: If you need detailed information about what failed and why, it is better to implement the directory traversal yourself and use the `modulemd_module_index_update_from_file()` function, as it will return the failures information.

#### Parameters

self | This ModulemdModuleIndex object. |
path | The path to a directory containing defaults documents. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or a conflict in module default streams. | [in]
overrides_path | If non-`NULL`, the path to a directory containing defaults documents that should override those in `path` . | [in][nullable]
error | A GError indicating why this function failed. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured. | [out]

#### Returns

`TRUE` if all ".yaml" files in the directory were imported successfully (this includes if no ".yaml" files were present). `FALSE` if one or more files could not be read successfully and sets `error` appropriately.

Since: 2.8

### modulemd_module_index_dump_to_string ()

    gchar *
    modulemd_module_index_dump_to_string (ModulemdModuleIndex *self,
                                          GError **error);

#### Parameters

self | This ModulemdModuleIndex object. |
error | A GError containing the reason the function failed, NULL if the function succeeded. | [out]

#### Returns

A YAML representation of the index as a string. In the event of an error, sets `error` appropriately and returns NULL.

[transfer full]

Since: 2.0

### modulemd_module_index_dump_to_stream ()

    gboolean
    modulemd_module_index_dump_to_stream (ModulemdModuleIndex *self,
                                          FILE *yaml_stream,
                                          GError **error);

[skip]

#### Parameters

self | This ModulemdModuleIndex object. |
yaml_stream | A stream to write the module metadata and other related information to. | [in]
error | A GError containing the reason the function failed, NULL if the function succeeded. | [out]

#### Returns

TRUE if written successfully, FALSE and sets `error` appropriately in the event of an error.

Since: 2.0

### modulemd_module_index_dump_to_custom ()

    gboolean
    modulemd_module_index_dump_to_custom (ModulemdModuleIndex *self,
                                          ModulemdWriteHandler custom_write_fn,
                                          void *custom_pvt_data,
                                          GError **error);

[skip]

#### Parameters

self | This ModulemdModuleIndex object. |
custom_write_fn | A ModulemdWriteHandler. | [in]
custom_pvt_data | The private data needed by the ModulemdWriteHandler. | [inout]
error | A GError containing the reason the function failed, NULL if the function succeeded. | [out]

#### Returns

TRUE if written successfully, FALSE and sets `error` appropriately in the event of an error.

Since: 2.3

### modulemd_module_index_get_module_names_as_strv ()

    GStrv
    modulemd_module_index_get_module_names_as_strv
                                   (ModulemdModuleIndex *self);

[rename-to modulemd_module_index_get_module_names]

#### Parameters

self | This ModulemdModuleIndex object. |

#### Returns

An ordered list of string keys in this index.

[transfer full]

Since: 2.0

### modulemd_module_index_get_module ()

    ModulemdModule *
    modulemd_module_index_get_module (ModulemdModuleIndex *self,
                                      const gchar *module_name);

#### Parameters

self | This ModulemdModuleIndex object. |
module_name | The module name to look up in the index. |

#### Returns

The ModulemdModule object matching the provided module name or NULL if the key was not present in the index.

[transfer none]

Since: 2.0

### modulemd_module_index_search_streams ()

    GPtrArray *
    modulemd_module_index_search_streams (ModulemdModuleIndex *self,
                                          const gchar *module_name,
                                          const gchar *stream_name,
                                          const gchar *version,
                                          const gchar *context,
                                          const gchar *arch);

All arguments to this method will be compared using fnmatch(3).

#### Parameters

self | This ModulemdModuleIndex object. |
module_name | The name of the module to retrieve. If NULL, will search all modules in the index. | [nullable]
stream_name | The name of the stream to retrieve. If NULL, will search all streams in a module. | [nullable]
version | The version of the stream to retrieve. If NULL, will search all versions. | [nullable]
context | The context of the stream to retrieve. If NULL, will search all contexts. | [nullable]
arch | The processor architecture of the stream to retrieve. If NULL, the architecture is not included in the search. | [nullable]

#### Returns

The list of stream objects matching all of the requested parameters. This function cannot fail, but it may return a zero-length list if no matches were found. The returned streams will be in a predictable order, sorted first by module name, then stream name, then by version (highest first), then by context and finally by architecture.

[transfer container][element-type ModulemdModuleStream]

Since: 2.9

### modulemd_module_index_search_streams_by_nsvca_glob ()

    GPtrArray *
    modulemd_module_index_search_streams_by_nsvca_glob
                                   (ModulemdModuleIndex *self,
                                    const gchar *nsvca_pattern);

#### Parameters

self | This ModulemdModuleIndex object. |
nsvca_pattern | A glob pattern to match against the NSVCA strings of the ModulemdModuleStream objects in this module. If NULL, this will match all NSVCAs. | [nullable]

#### Returns

The list of stream objects matching all of the requested parameters. This function cannot fail, but it may return a zero-length list if no matches were found. The returned streams will be in a predictable order, sorted first by module name, then stream name, then by version (highest first), then by context and finally by architecture.

[transfer container][element-type ModulemdModuleStream]

Since: 2.9

### modulemd_module_index_search_rpms ()

    GPtrArray *
    modulemd_module_index_search_rpms (ModulemdModuleIndex *self,
                                       const gchar *nevra_pattern);

All arguments to this method will be compared using fnmatch(3).

#### Parameters

self | This ModulemdModuleIndex object. |
nevra_pattern | A glob pattern to match against the NEVRA strings of the rpm artifacts in the ModulemdModuleStream objects in this module. | [not nullable]

#### Returns

The list of stream objects containing an RPM that matches the `nevra_pattern` . This function cannot fail, but it may return a zero-length list if no matches were found. The returned streams will be in a predictable order, sorted first by module name, then stream name, then by version (highest first), then by context and finally by architecture.

[transfer container][element-type ModulemdModuleStream]

Since: 2.9

### modulemd_module_index_remove_module ()

    gboolean
    modulemd_module_index_remove_module (ModulemdModuleIndex *self,
                                         const gchar *module_name);

Remove a module, including all of its streams, its defaults and its translations from a ModulemdModuleIndex.

#### Parameters

self | This ModulemdModuleIndex object. |
module_name | The name of the module to remove from the index. |

#### Returns

TRUE if the module name was present in the index. FALSE if it was not.

Since: 2.2

### modulemd_module_index_add_module_stream ()

    gboolean
    modulemd_module_index_add_module_stream
                                   (ModulemdModuleIndex *self,
                                    ModulemdModuleStream *stream,
                                    GError **error);

Add a ModulemdModuleStream to the ModulemdModuleIndex. While being added, the ModulemdModuleStream will be upgraded to `MD_MODULESTREAM_VERSION_LATEST` to ensure that merges done with ModulemdModuleIndexMerger will always occur between streams of the same version. If this upgrade cannot be performed, the function will return `error` set appropriately.

#### Parameters

self | This ModulemdModuleIndex object. |
stream | The ModulemdModuleStream to add to the index. The stream added must have a module name and stream name set on it or it will be rejected. |
error | A GError containing the reason the ModulemdModuleStream object could not be added or NULL if the function succeeded. | [out]

#### Returns

TRUE if the ModulemdModuleStream was added successfully. If the stream already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets `error` appropriately.

Since: 2.0

### modulemd_module_index_add_defaults ()

    gboolean
    modulemd_module_index_add_defaults (ModulemdModuleIndex *self,
                                        ModulemdDefaults *defaults,
                                        GError **error);

#### Parameters

self | This ModulemdModuleIndex object. |
defaults | The ModulemdDefaults object to add to the index. |
error | A GError containing the reason the ModulemdDefaults object could not be added or NULL if the function succeeded. | [out]

#### Returns

TRUE if the ModulemdDefaults was added successfully. If the defaults already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets `error` appropriately.

Since: 2.0

### modulemd_module_index_add_obsoletes ()

    gboolean
    modulemd_module_index_add_obsoletes (ModulemdModuleIndex *self,
                                         ModulemdObsoletes *obsoletes,
                                         GError **error);

#### Parameters

self | This ModulemdModuleIndex object. |
obsoletes | The ModulemdObsoletes object to add to the index. | [in]
error | A GError containing the reason the ModulemdObsoletes object could not be added or NULL if the function succeeded. | [out]

#### Returns

TRUE if the ModulemdObsoletes was added successfully. If the obsoletes already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets `error` appropriately.

Since: 2.10

### modulemd_module_index_get_default_streams_as_hash_table ()

    GHashTable *
    modulemd_module_index_get_default_streams_as_hash_table
                                   (ModulemdModuleIndex *self,
                                    const gchar *intent);

Get a dictionary of all modules in the index that have a default stream.

This function cannot fail, but may return an empty (non-NULL) GHashTable.

[rename-to modulemd_module_index_get_default_streams]

#### Parameters

self | This ModulemdModuleIndex object. | [in]
intent | The name of the system intent whose default stream will be retrieved. If left NULL or the specified intent has no separate default, it will return the generic default stream for this module. System intents are deprecated and this argument will be ignored in the future. | [in][nullable]

#### Returns

A GHashTable with the module name as the key and the default stream as the value for all modules with a default stream in the index. Modules without a default stream will not appear in this table.

[transfer container][element-type utf8 utf8]

Since: 2.5

### modulemd_module_index_add_translation ()

    gboolean
    modulemd_module_index_add_translation (ModulemdModuleIndex *self,
                                           ModulemdTranslation *translation,
                                           GError **error);

#### Parameters

self | This ModulemdModuleIndex object. |
translation | The ModulemdTranslation object to add to the index. |
error | A GError containing the reason the ModulemdTranslation object could not be added or NULL if the function succeeded. | [out]

#### Returns

TRUE if the ModulemdTranslation was added successfully. If the translation already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets `error` appropriately.

Since: 2.0

### modulemd_module_index_get_defaults_mdversion ()

    ModulemdDefaultsVersionEnum
    modulemd_module_index_get_defaults_mdversion
                                   (ModulemdModuleIndex *self);

#### Parameters

self | This ModulemdModuleIndex object. |

#### Returns

The metadata version of ModulemdDefaults in use for this index.

Since: 2.0

### modulemd_module_index_get_stream_mdversion ()

    ModulemdModuleStreamVersionEnum
    modulemd_module_index_get_stream_mdversion
                                   (ModulemdModuleIndex *self);

#### Parameters

self | This ModulemdModuleIndex object. |

#### Returns

The metadata version of ModulemdModuleStream in use for this index.

Since: 2.0

### modulemd_module_index_upgrade_streams ()

    gboolean
    modulemd_module_index_upgrade_streams (ModulemdModuleIndex *self,
                                           ModulemdModuleStreamVersionEnum mdversion,
                                           GError **error);

Upgrades all ModulemdModuleStream objects in this index to `mdversion` if they are not already at that version.

#### Parameters

self | This ModulemdModuleIndex object. |
mdversion | The ModulemdModuleStream metadata version to upgrade to. |
error | A GError that contains information on why the index could not be upgraded in the event of an error. | [out]

Since: 2.0

### modulemd_module_index_upgrade_defaults ()

    gboolean
    modulemd_module_index_upgrade_defaults
                                   (ModulemdModuleIndex *self,
                                    ModulemdDefaultsVersionEnum mdversion,
                                    GError **error);

Upgrades all ModulemdDefaults objects in this index to `mdversion` if they are not already at that version. An attempt to downgrade or an attempt to upgrade beyond the latest supported version will report an error. In the case of a failure to upgrade a particular ModulemdDefaults object of the index, an error will be reported and the index will be left in an undefined state.

#### Parameters

self | This ModulemdModuleIndex object. |
mdversion | The ModulemdDefaults metadata version to upgrade to. |
error | A GError that contains information on why the index could not be upgraded in the event of an error. | [out][optional]

Since: 2.0

### modulemd_module_index_clear_xmds ()

    void
    modulemd_module_index_clear_xmds (ModulemdModuleIndex *self);

Iterates through all ModulemdModuleStream entries in this ModulemdModuleIndex and removes any XMD sections that are present. This is generally done to trim down the metadata to only the portions that are useful to the package manager.

#### Parameters

self | This ModulemdModuleIndex object. |

Since: 2.14

## Types and Values

### MODULEMD_TYPE_MODULE_INDEX

    #define MODULEMD_TYPE_MODULE_INDEX (modulemd_module_index_get_type ())

### ModulemdModuleIndex

    typedef struct _ModulemdModuleIndex ModulemdModuleIndex;