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.

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