fs_stream_cr_api.h File Reference

Composition Root API for wiring the fs_stream adapter into the stream factory. More...

#include "fs_stream/cr/fs_stream_types.h"
#include "stream/borrowers/stream_types.h"
#include "stream/adapters/stream_key_type.h"
#include "stream/adapters/stream_install.h"
#include "stream/adapters/stream_adapters_api.h"
#include "osal/mem/osal_mem_ops.h"

Include dependency graph for fs_stream_cr_api.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
fs_stream_cfg_t	fs_stream_default_cfg (void)
	Return a default configuration for the fs_stream adapter.
fs_stream_env_t	fs_stream_default_env (const osal_file_env_t *file_env, const osal_file_ops_t *file_ops, const stream_env_t *port_env)
	Build a default environment for the fs_stream adapter.
stream_status_t	fs_stream_create_stream (stream_t **out, const fs_stream_args_t *args, const fs_stream_cfg_t *cfg, const fs_stream_env_t *env)
	Create a file-backed stream instance.
stream_status_t	fs_stream_create_desc (stream_adapter_desc_t *out, stream_key_t key, const fs_stream_cfg_t *cfg, const fs_stream_env_t *env, const osal_mem_ops_t *mem)
	Build an adapter descriptor for registering fs_stream in a factory.

Detailed Description

This header exposes the CR-facing entry points used to:

• build default fs_stream configuration and environment values,
• create a file-backed stream instance,
• build an adapter descriptor suitable for registration in the stream factory.

Definition in file fs_stream_cr_api.h.

Function Documentation

fs_stream_create_desc()

stream_status_t fs_stream_create_desc	(	stream_adapter_desc_t *	out,
		stream_key_t	key,
		const fs_stream_cfg_t *	cfg,
		const fs_stream_env_t *	env,
		const osal_mem_ops_t *	mem
	)

The Composition Root uses this function to build a stream_adapter_desc_t suitable for registration into the stream factory, for example via stream_factory_add_adapter().

Memory policy:

• mem must be the allocator that will later be used to destroy the descriptor-owned user data through ud_dtor.

Parameters

[out]

out

Descriptor to initialize. Must not be NULL.

On failure, if out != NULL, *out is reset to an empty descriptor.

Parameters

[in]	key	Adapter key used by the factory to select this adapter. Must not be NULL and must not be an empty string.
[in]	cfg	Adapter configuration to bind into the descriptor. Must not be NULL.
[in]	env	Adapter environment to bind into the descriptor. Must not be NULL.
[in]	mem	Memory operations used to allocate descriptor-owned user data. Must not be NULL.

Return values

STREAM_STATUS_OK	Descriptor successfully created.
STREAM_STATUS_INVALID	One or more arguments are invalid.
STREAM_STATUS_OOM	Allocation of descriptor-owned user data failed.

Definition at line 256 of file fs_stream.c.

fs_stream_create_stream()

stream_status_t fs_stream_create_stream	(	stream_t **	out,
		const fs_stream_args_t *	args,
		const fs_stream_cfg_t *	cfg,
		const fs_stream_env_t *	env
	)

This function allocates and initializes a public stream_t whose backend is an OSAL file opened according to the parameters provided in fs_stream_args_t.

The underlying OSAL file is opened through the file operations injected in the adapter environment.

Ownership:

• On success, a newly allocated stream is returned in *out.
• The caller becomes responsible for destroying it via stream_destroy().
• On failure, *out is left unchanged.

Parameters

[out]	out	Receives the created stream handle. Must not be NULL.
[in]	args	Creation arguments describing the file to open. Must not be NULL.

Contract:

• args->path must not be NULL and must not be an empty string.
• args->flags must not be zero.

Parameters

[in]	cfg	Adapter configuration. Must not be NULL.
[in]	env	Adapter environment containing injected dependencies. Must not be NULL.

Return values

STREAM_STATUS_OK	Stream successfully created.
STREAM_STATUS_INVALID	One or more arguments are invalid.
STREAM_STATUS_OOM	Memory allocation failed.
STREAM_STATUS_IO_ERROR	The underlying OSAL file operation failed.

Definition at line 208 of file fs_stream.c.

fs_stream_default_cfg()

fs_stream_cfg_t fs_stream_default_cfg

(

void

)

This helper provides a value-initialized baseline configuration that the Composition Root may override.

Returns

A well-formed default fs_stream_cfg_t.

Definition at line 294 of file fs_stream.c.

fs_stream_default_env()

fs_stream_env_t fs_stream_default_env	(	const osal_file_env_t *	file_env,
		const osal_file_ops_t *	file_ops,
		const stream_env_t *	port_env
	)

This helper packages borrowed dependencies into a value-initialized fs_stream_env_t.

The returned environment does not take ownership of any pointer passed as argument.

Parameters

[in]	file_env	Borrowed OSAL file environment.
[in]	file_ops	Borrowed OSAL file operations table.
[in]	port_env	Borrowed stream port environment.

Returns

A well-formed fs_stream_env_t aggregating the provided dependencies.

Definition at line 298 of file fs_stream.c.