Modulemd.ModuleStream: Modulemd Reference Manual

## Modulemd.ModuleStream Modulemd.ModuleStream — A parent class for all versions of ModulemdModuleStream objects. |

## Stability Level

Stable, unless otherwise indicated

## Functions

ModulemdModuleStream * | modulemd_module_stream_new ()
ModulemdModuleStream * | modulemd_module_stream_read_file ()
ModulemdModuleStream * | modulemd_module_stream_read_string ()
ModulemdModuleStream * | modulemd_module_stream_read_stream ()
gboolean | modulemd_module_stream_equals ()
ModulemdModuleStream * | modulemd_module_stream_copy ()
ModulemdModuleStream * | modulemd_module_stream_upgrade ()
ModulemdModule * | modulemd_module_stream_upgrade_ext ()
gboolean | modulemd_module_stream_validate ()
guint64 | modulemd_module_stream_get_mdversion ()
const gchar * | modulemd_module_stream_get_module_name ()
const gchar * | modulemd_module_stream_get_stream_name ()
void | modulemd_module_stream_set_version ()
guint64 | modulemd_module_stream_get_version ()
void | modulemd_module_stream_set_context ()
const gchar * | modulemd_module_stream_get_context ()
void | modulemd_module_stream_set_arch ()
const gchar * | modulemd_module_stream_get_arch ()
gchar * | modulemd_module_stream_get_nsvc_as_string ()
gchar * | modulemd_module_stream_get_NSVCA_as_string ()
gboolean | modulemd_module_stream_depends_on_stream ()
gboolean | modulemd_module_stream_build_depends_on_stream ()

## Properties

char * | module-name | Read / Write / Construct Only
char * | arch | Read / Write / Construct
char * | context | Read / Write / Construct
guint64 | mdversion | Read
char * | module-name | Read / Write / Construct Only
char * | stream-name | Read / Write / Construct Only
guint64 | version | Read / Write / Construct

## Types and Values

#define | MMD_MAXCONTEXTLEN
enum | ModulemdModuleStreamVersionEnum
#define | MODULEMD_TYPE_MODULE_STREAM
struct | ModulemdModuleStreamClass
| ModulemdModule
| ModulemdModuleStream

## Object Hierarchy

        GEnum
        ╰── ModulemdModuleStreamVersionEnum
        GObject
        ├── ModulemdModule
        ╰── ModulemdModuleStream
            ├── ModulemdModuleStreamV1
            ╰── ModulemdModuleStreamV2

## Description

## Functions

### modulemd_module_stream_new ()

    ModulemdModuleStream *
    modulemd_module_stream_new (guint64 mdversion,
                                const gchar *module_name,
                                const gchar *module_stream);

#### Parameters

mdversion | The metadata version of ModulemdModuleStream to create. | [in]
module_name | The name of the module. | [in][nullable]
module_stream | The name of this stream. Optional. | [in][nullable]

#### Returns

A newly-allocated ModulemdModuleStream object of the requested metadata version.

[transfer full]

Since: 2.0

### modulemd_module_stream_read_file ()

    ModulemdModuleStream *
    modulemd_module_stream_read_file (const gchar *path,
                                      gboolean strict,
                                      const gchar *module_name,
                                      const gchar *module_stream,
                                      GError **error);

`modulemd_module_stream_read_file` has been deprecated since version 2.11 and should not be used in newly-written code.

Use `modulemd_read_packager_file()` instead.

Create a ModulemdModuleStream object from a YAML file.

Note: This function also reads modulemd-packager v2 and v3 documents, which are transparently returned as ModulemdModuleStream (V2) objects. However, if a modulemd-packager v3 document (ModulemdPackagerV3) is encountered and it uses buildopts (ModulemdBuildopts) in one or more build configurations, only the buildopts present in the first listed configuration (if any) will be applied to the returned ModulemdModuleStreamV2 object.

#### Parameters

path | The path to a YAML document containing a module stream definition. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
module_name | An optional module name to override the document on disk. Mostly useful in cases where the name is being auto-detected from git. | [in][nullable]
module_stream | An optional module stream name to override the document on disk. Mostly useful in cases where the name is being auto-detected from git. | [in][nullable]
error | A GError that will return the reason for a failed read. | [out]

#### Returns

A newly-allocated ModulemdModuleStream object if the YAML file was valid and contained exactly one `document: modulemd` subdocument. NULL if the document fails validation or multiple documents are encountered and sets `error` appropriately. See ModulemdModuleIndex for functions to read in multiple-subdocument YAML.

[transfer full]

Since: 2.0

### modulemd_module_stream_read_string ()

    ModulemdModuleStream *
    modulemd_module_stream_read_string (const gchar *yaml_string,
                                        gboolean strict,
                                        const gchar *module_name,
                                        const gchar *module_stream,
                                        GError **error);

`modulemd_module_stream_read_string` has been deprecated since version 2.11 and should not be used in newly-written code.

Use `modulemd_read_packager_string()` instead.

Create a ModulemdModuleStream object from a YAML string.

Note: This function also reads modulemd-packager v2 and v3 documents, which are transparently returned as ModulemdModuleStream (V2) objects. However, if a modulemd-packager v3 document (ModulemdPackagerV3) is encountered and it uses buildopts (ModulemdBuildopts) in one or more build configurations, only the buildopts present in the first listed configuration (if any) will be applied to the returned ModulemdModuleStreamV2 object.

#### Parameters

yaml_string | A YAML document string containing a module stream definition. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
module_name | An optional module name to override the document on disk. Mostly useful in cases where the name is being auto-detected from git. | [in][nullable]
module_stream | An optional module stream name to override the document on disk. Mostly useful in cases where the name is being auto-detected from git. | [in][nullable]
error | A GError that will return the reason for a failed read. | [out]

#### Returns

A newly-allocated ModulemdModuleStream object if the YAML string was valid and contained exactly one `document: modulemd` subdocument. NULL if the document fails validation or multiple documents are encountered and sets `error` appropriately. See ModulemdModuleIndex for functions to read in multiple-subdocument YAML.

[transfer full]

Since: 2.0

### modulemd_module_stream_read_stream ()

    ModulemdModuleStream *
    modulemd_module_stream_read_stream (FILE *stream,
                                        gboolean strict,
                                        const gchar *module_name,
                                        const gchar *module_stream,
                                        GError **error);

Create a ModulemdModuleStream object from a YAML file.

[skip]

#### Parameters

stream | A YAML document as a FILE * containing a module stream definition. | [in]
strict | Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it. | [in]
module_name | An optional module name to override the document on disk. Mostly useful in cases where the name is being auto-detected from git. | [in][nullable]
module_stream | An optional module stream name to override the document on disk. Mostly useful in cases where the name is being auto-detected from git. | [in][nullable]
error | A GError that will return the reason for a failed read. | [out]

#### Returns

A newly-allocated ModulemdModuleStream object if the YAML file was valid and contained exactly one `document: modulemd` subdocument. NULL if the document fails validation or multiple documents are encountered and sets NULL appropriately. See ModulemdModuleIndex for functions to read in multiple-subdocument YAML.

[transfer full]

Since: 2.0

### modulemd_module_stream_equals ()

    gboolean
    modulemd_module_stream_equals (ModulemdModuleStream *self_1,
                                   ModulemdModuleStream *self_2);

Checks if `self_1` and `self_2` are identical objects.

#### Parameters

self_1 | A ModulemdModuleStream object. | [in]
self_2 | A ModulemdModuleStream object. | [in]

#### Returns

TRUE, If both objects are equal. FALSE, otherwise.

Since: 2.3

### modulemd_module_stream_copy ()

    ModulemdModuleStream *
    modulemd_module_stream_copy (ModulemdModuleStream *self,
                                 const gchar *module_name,
                                 const gchar *module_stream);

Copies a ModulemdModuleStream, optionally assigning it a new stream name in the process.

#### Parameters

self | This ModulemdModuleStream object. | [in]
module_name | An optional new name for the module of the copied stream. | [in][nullable]
module_stream | An optional new name for the copied stream. | [in][nullable]

#### Returns

A newly-allocated ModulemdModuleStream object that is a complete copy of `self` , optionally with a new stream name.

[transfer full]

Since: 2.0

### modulemd_module_stream_upgrade ()

    ModulemdModuleStream *
    modulemd_module_stream_upgrade (ModulemdModuleStream *self,
                                    guint64 mdversion,
                                    GError **error);

`modulemd_module_stream_upgrade` has been deprecated since version 2.10 and should not be used in newly-written code.

Use `modulemd_module_stream_upgrade_ext()` instead.

Return an upgraded copy of this object. Does not modify the original.

#### Parameters

self | This ModulemdModuleStream object. | [in]
mdversion | The metadata version to upgrade to. If zero, upgrades to the highest-supported version. | [in]
error | A GError that will return the reason for an upgrade error. | [out]

#### Returns

A newly-allocated ModulemdModuleStream copy of this object upgraded to the requested version. Returns NULL and sets `error` appropriately if the upgrade could not be completed automatically.

[transfer full]

Since: 2.0

### modulemd_module_stream_upgrade_ext ()

    ModulemdModule *
    modulemd_module_stream_upgrade_ext (ModulemdModuleStream *self,
                                        guint64 mdversion,
                                        GError **error);

Does not modify the original ModulemdModuleStream object, `from` .

#### Parameters

self | This ModulemdModuleStream object. | [in]
mdversion | The metadata version to upgrade to. If zero, upgrades to the highest-supported version. | [in]
error | A GError that will return the reason for an upgrade error. | [out]

#### Returns

A newly-allocated ModulemdModule containing a copy of this object upgraded to the requested version, possibly with multiple streams. Returns NULL and sets `error` appropriately if the upgrade could not be completed automatically.

[transfer full]

Since: 2.10

### modulemd_module_stream_validate ()

    gboolean
    modulemd_module_stream_validate (ModulemdModuleStream *self,
                                     GError **error);

Verifies that all stored values are internally consistent and that the module is sufficiently-complete for emitting. This function is called implicitly before attempting to emit the contents.

#### Parameters

self | This ModulemdModuleStream object. | [in]
error | A GError that will return the reason for a validation error. | [out]

#### Returns

TRUE if the ModulemdModuleStream passed validation. FALSE and sets `error` appropriately if validation fails.

Since: 2.0

### modulemd_module_stream_get_mdversion ()

    guint64
    modulemd_module_stream_get_mdversion (ModulemdModuleStream *self);

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

The metadata version of this ModulemdModuleStream.

Since: 2.0

### modulemd_module_stream_get_module_name ()

    const gchar *
    modulemd_module_stream_get_module_name
                                   (ModulemdModuleStream *self);

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

The name of the module.

[transfer none]

Since: 2.0

### modulemd_module_stream_get_stream_name ()

    const gchar *
    modulemd_module_stream_get_stream_name
                                   (ModulemdModuleStream *self);

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

The name of this stream.

[transfer none]

Since: 2.0

### modulemd_module_stream_set_version ()

    void
    modulemd_module_stream_set_version (ModulemdModuleStream *self,
                                        guint64 version);

#### Parameters

self | This ModulemdModuleStream object. | [in]
version | The version of this ModulemdModuleStream. | [in]

Since: 2.0

### modulemd_module_stream_get_version ()

    guint64
    modulemd_module_stream_get_version (ModulemdModuleStream *self);

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

The version of this ModulemdModuleStream.

### modulemd_module_stream_set_context ()

    void
    modulemd_module_stream_set_context (ModulemdModuleStream *self,
                                        const gchar *context);

#### Parameters

self | This ModulemdModuleStream object. | [in]
context | Module context flag. The context flag serves to distinguish module builds with the same name, stream and version and plays an important role in automatic module stream name expansion. | [in][nullable]

Since: 2.0

### modulemd_module_stream_get_context ()

    const gchar *
    modulemd_module_stream_get_context (ModulemdModuleStream *self);

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

Module context flag. The context flag serves to distinguish module builds with the same name, stream and version and plays an important role in automatic module stream name expansion.

[transfer none]

Since: 2.0

### modulemd_module_stream_set_arch ()

    void
    modulemd_module_stream_set_arch (ModulemdModuleStream *self,
                                     const gchar *arch);

#### Parameters

self | This ModulemdModuleStream object. | [in]
arch | Module architecture. Indicates to which processor architecture this ModulemdModuleStream applies. | [in][nullable]

Since: 2.2

### modulemd_module_stream_get_arch ()

    const gchar *
    modulemd_module_stream_get_arch (ModulemdModuleStream *self);

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

Module architecture object. Indicates to which processor architecture this ModulemdModuleStream applies.

[transfer none]

Since: 2.2

### modulemd_module_stream_get_nsvc_as_string ()

    gchar *
    modulemd_module_stream_get_nsvc_as_string
                                   (ModulemdModuleStream *self);

Retrieves a representation of the module name, stream name, version and context of this ModulemdModuleStream in the form `module_name:stream_name:version:context`. Note that this excludes the architecture of the module stream and as such is not guaranteed to be unique within a repository.

[rename-to modulemd_module_stream_get_nsvc]

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

The NSVC (name:stream:version[:context]) of this module stream. NULL if module name or stream stream is unknown.

[transfer full]

Since: 2.0

### modulemd_module_stream_get_NSVCA_as_string ()

    gchar *
    modulemd_module_stream_get_NSVCA_as_string
                                   (ModulemdModuleStream *self);

[rename-to modulemd_module_stream_get_NSVCA]

#### Parameters

self | This ModulemdModuleStream object. | [in]

#### Returns

The NSVCA of this module stream. The returned format is described here. NULL if module name or stream stream is unknown.

[transfer full]

Since: 2.2

### modulemd_module_stream_depends_on_stream ()

    gboolean
    modulemd_module_stream_depends_on_stream
                                   (ModulemdModuleStream *self,
                                    const gchar *module_name,
                                    const gchar *stream_name);

#### Parameters

self | This ModulemdModuleStream object. | [not nullable]
module_name | A module name. | [not nullable]
stream_name | The stream of the module. | [not nullable]

#### Returns

TRUE if any of the ModulemdDependencies objects associated with this module applies to the provided module name and stream in the runtime dependencies.

Since: 2.1

Stability Level: Unstable

### modulemd_module_stream_build_depends_on_stream ()

    gboolean
    modulemd_module_stream_build_depends_on_stream
                                   (ModulemdModuleStream *self,
                                    const gchar *module_name,
                                    const gchar *stream_name);

#### Parameters

self | This ModulemdModuleStream object. | [not nullable]
module_name | A module name. | [not nullable]
stream_name | The stream of the module. | [not nullable]

#### Returns

TRUE if any of the ModulemdDependencies objects associated with this module applies to the provided module name and stream in the build-time dependencies.

Since: 2.1

Stability Level: Unstable

## Types and Values

### MMD_MAXCONTEXTLEN

    #define MMD_MAXCONTEXTLEN 10

The ModuleStream v3 specification defines the maximum lenth of the context field.

Since: 2.10

### enum ModulemdModuleStreamVersionEnum

#### Members

MD_MODULESTREAM_VERSION_ERROR | Represents an error handling module stream version. |
MD_MODULESTREAM_VERSION_UNSET | Represents an unset module stream version. |
MD_MODULESTREAM_VERSION_ONE | Represents v1 of the ModulemdModuleStream metadata format. |
MD_MODULESTREAM_VERSION_TWO | Represents v2 of the ModulemdModuleStream metadata format. |
MD_MODULESTREAM_VERSION_LATEST | Represents the highest-supported version of the ModulemdModuleStream metadata format. |

Since: 2.0

### MODULEMD_TYPE_MODULE_STREAM

    #define MODULEMD_TYPE_MODULE_STREAM (modulemd_module_stream_get_type ())

### struct ModulemdModuleStreamClass

    struct ModulemdModuleStreamClass {
      GObjectClass parent_class;

      ModulemdModuleStream *(*copy) (ModulemdModuleStream *self,
                                     const gchar *module_name,
                                     const gchar *module_stream);

      gboolean (*validate) (ModulemdModuleStream *self, GError **error);

      guint64 (*get_mdversion) (ModulemdModuleStream *self);

      gboolean (*depends_on_stream) (ModulemdModuleStream *self,
                                     const gchar *module_name,
                                     const gchar *stream_name);

      gboolean (*build_depends_on_stream) (ModulemdModuleStream *self,
                                           const gchar *module_name,
                                           const gchar *stream_name);

      gboolean (*equals) (ModulemdModuleStream *self_1,
                          ModulemdModuleStream *self_2);

      /* Padding to allow adding up to 7 new virtual functions without
       * breaking ABI. */
      gpointer padding[7];
    };

### ModulemdModule

    typedef struct _ModulemdModule ModulemdModule;

### ModulemdModuleStream

    typedef struct _ModulemdModuleStream ModulemdModuleStream;

## Property Details

### The `“module-name”` property

      “module-name”              char *

The name of this module.

Owner: ModulemdModule

Flags: Read / Write / Construct Only

Default value: NULL

### The `“arch”` property

      “arch”                     char *

The processor architecture of this module stream.

Owner: ModulemdModuleStream

Flags: Read / Write / Construct

Default value: NULL

### The `“context”` property

      “context”                  char *

The context of this module stream. Distinguishes between streams with the same version but different dependencies due to module stream expansion.

Owner: ModulemdModuleStream

Flags: Read / Write / Construct

Default value: NULL

### The `“mdversion”` property

      “mdversion”                guint64

The metadata version of this ModuleStream object. Read-only.

Owner: ModulemdModuleStream

Flags: Read

Allowed values: <= 2

Default value: 0

### The `“module-name”` property

      “module-name”              char *

The name of the module providing this stream.

Owner: ModulemdModuleStream

Flags: Read / Write / Construct Only

Default value: NULL

### The `“stream-name”` property

      “stream-name”              char *

The name of this module stream.

Owner: ModulemdModuleStream

Flags: Read / Write / Construct Only

Default value: NULL

### The `“version”` property

      “version”                  guint64

The version of this module stream.

Owner: ModulemdModuleStream

Flags: Read / Write / Construct

Default value: 0