Class StreamsFactory

• Defined in File libCZI_StreamsLib.h

Nested Relationships

Nested Types

• Struct StreamsFactory::CreateStreamInfo

• Struct StreamsFactory::Property

• Struct StreamsFactory::StreamClassInfo

• Class StreamsFactory::StreamProperties

• Struct StreamsFactory::StreamPropertyBagPropertyInfo

Class Documentation

class StreamsFactory

A factory object for creating streams objects. libCZI is operating on abstractions (IStream for an input stream, IOutputStream for an output stream and IInputOutputStream for and input-output-stream) for accessing the CZI-data. In this class factory we gather implementations provided by libCZI and provide functionality to enumerate available classes. At this point, we can find two variants here - for operating on a file in a file-system and for operating on an http- or https-stream. The http-stream class is based on cURL (https://curl.se/libcurl/), and it needs to be configured in when building libCZI.

Public Static Functions

static const StreamPropertyBagPropertyInfo *GetStreamPropertyBagPropertyInfo(int *count)

Gets a (static) list of all properties which can be used for the property bag when creating a stream object. This list is terminated by an entry with a null property_name. The list is static and will not change during the lifetime of the application, the returned pointer is valid until the application terminates. It is pointing to static memory and must not be freed.

Parameters:

count – [out] If non-null, the number of valid elements (not including the terminal element) is put here.

Returns:

A pointer to an array containing property-bag information.

static void Initialize()

Perform one-time initialization of the streams objects. Some stream objects may require some one-time initialization for being operational (this is e.g. the case with the libcurl-based ones). It is considered good practice to call this function before using any of the other methods. Calling it multiple times is not a problem (and subsequent calls after the first are ignored).

static std::shared_ptr<libCZI::IStream> CreateStream(const CreateStreamInfo &stream_info, const std::string &file_identifier)

Creates and initializes a new instance of the specified stream class. If the specified class is not known, then this function will return nullptr. In case of an error when initializing the stream, an exception will be thrown.

Parameters:

• stream_info – Information describing the stream.

• file_identifier – The filename (or, more generally, a URI of some sort) identifying the file to be opened in UTF8-encoding.

Returns:

The newly created and initialized stream.

static std::shared_ptr<libCZI::IStream> CreateStream(const CreateStreamInfo &stream_info, const std::wstring &file_identifier)

Creates and initializes a new instance of the specified stream class. If the specified class is not known, then this function will return nullptr. In case of an error when initializing the stream, an exception will be thrown.

Parameters:

• stream_info – Information describing the stream.

• file_identifier – The filename (or, more generally, a URI of some sort) identifying the file to be opened.

Returns:

The newly created and initialized stream.

static bool GetStreamInfoForClass(int index, StreamClassInfo &stream_info)

Gets information about a stream class available in the factory. The function returns false if the index is out of range. The function is idempotent, the information returned from it will not change during the lifetime of the application.

Parameters:

• index – Zero-based index of the class for which information is to be retrieved.

• stream_info – [out] Information describing the stream class.

Returns:

True if it succeeds; false otherwise.

static int GetStreamClassesCount()

Gets the number of stream classes available in the factory.

Returns:

The number of available stream classes.

static std::shared_ptr<libCZI::IStream> CreateDefaultStreamForFile(const char *filename)

Creates an instance of the default streams-objects for reading from the file-system.

Parameters:

filename – Filename of the file to open (in UTF-8 encoding).

Returns:

A new instance of a streams-objects for reading the specified file from the file-system.

static std::shared_ptr<libCZI::IStream> CreateDefaultStreamForFile(const wchar_t *filename)

Creates an instance of the default streams-objects for reading from the file-system.

Parameters:

filename – Filename of the file to open.

Returns:

A new instance of a streams-objects for reading the specified file from the file-system.

Public Static Attributes

static const char *kStreamClassInfoProperty_CurlHttp_CaInfo

A static string for the property_name for the get_property-function of the StreamClassInfo identifying the build-time configured file holding one or more certificates to verify the peer with. C.f. https://curl.se/libcurl/c/curl_version_info.html, this property gives the value of the “cainfo”-field. If it is null, then an invalid property is returned.

static const char *kStreamClassInfoProperty_CurlHttp_CaPath

A static string for the property_name for the get_property-function of the StreamClassInfo identifying the build-time configured directory holding CA certificates. C.f. https://curl.se/libcurl/c/curl_version_info.html, this property gives the value of the “capath”-field. If it is null, then an invalid property is returned.

struct CreateStreamInfo

The parameters for creating an instance of a stream object.

Public Members

std::string class_name

Name of the class (this uniquely identifies the class).

std::map<int, Property> property_bag

A property-bag with options for creating the stream-object.

struct Property

This declares a variant type (to be used with the property bag in the streams factory).

Public Types

enum class Type

Values that represent the type represented by this variant.

Values:

enumerator Invalid

An enum constant representing the ‘invalid’ type (would throw an invalid-argument-exception).

enumerator Int32

An enum constant representing the ‘signed 32-bit integer’ type.

enumerator Float

An enum constant representing the ‘float’ type.

enumerator Double

An enum constant representing the ‘double’ type.

enumerator Boolean

An enum constant representing the ‘boolean’ type.

enumerator String

An enum constant representing the ‘string’ type.

Public Functions

inline Property()

Default constructor - setting the variant to ‘invalid’.

inline explicit Property(std::int32_t v)

Constructor for initializing the ‘int32’ type.

Parameters:

v – The value to set the variant to.

inline explicit Property(double v)

Constructor for initializing the ‘double’ type.

Parameters:

v – The value to set the variant to.

inline explicit Property(float v)

Constructor for initializing the ‘float’ type.

Parameters:

v – The value to set the variant to.

inline explicit Property(bool v)

Constructor for initializing the ‘bool’ type.

Parameters:

v – The value to set the variant to.

inline explicit Property(const std::string &v)

Constructor for initializing the ‘string’ type.

Parameters:

v – The value to set the variant to.

inline explicit Property(const char *string)

Constructor for initializing the ‘string’ type.

Parameters:

string – The value to set the variant to.

inline void SetInt32(std::int32_t v)

Sets the type of the variant to “Int32” and the value to the specified value.

Parameters:

v – The value to be set.

inline void SetDouble(double v)

Sets the type of the variant to “Double” and the value to the specified value.

Parameters:

v – The value to be set.

inline void SetFloat(float v)

Sets the type of the variant to “Float” and the value to the specified value.

Parameters:

v – The value to be set.

inline void SetBool(bool v)

Sets the type of the variant to “Boolean” and the value to the specified value.

Parameters:

v – The value to be set.

inline void SetString(const std::string &v)

Sets the type of the variant to “String” and the value to the specified value.

Parameters:

v – The value to be set.

inline std::int32_t GetAsInt32OrThrow() const

Returns integer value if ValueType is int, otherwise throws a RuntimeError.

inline double GetAsDoubleOrThrow() const

Returns double value if ValueType is double, otherwise throws a RuntimeError.

inline float GetAsFloatOrThrow() const

Returns float value if ValueType is ‘Float’, otherwise throws a RuntimeError.

inline bool GetAsBoolOrThrow() const

Returns boolean value if ValueType is boolean, otherwise throws a RuntimeError.

inline std::string GetAsStringOrThrow() const

Returns string value if ValueType is string, otherwise throws a RuntimeError.

inline Type GetType() const

Returns ValueType.

Public Members

std::int32_t int32Value

float floatValue

double doubleValue

bool boolValue

struct StreamClassInfo

This structure gathers information about a stream class.

Public Members

std::string class_name

Name of the class (this uniquely identifies the class).

std::string short_description

A short and informal description of the class.

std::function<std::string()> get_build_info

A function which returns a string with build information for the class (e.g. version information). Note that this field may be null, in which case no information is available.

std::function<Property(const char *property_name)> get_property

A function which returns a class-specific property about the class. This is e.g. intended for providing information about build-time options for a specific class. Currently, it is used for the libcurl-based stream-class to provide information about the build-time configured paths for the CA certificates. Note that this field may be null, in which case no information is available.

class StreamProperties

Here the keys for the property-bag with options for creating a stream-object are gathered.

Public Types

Values that identify properties in the property-bag for constructing a stream-object.

Values:

enumerator kCurlHttp_Proxy

For CurlHttpInputStream, type string: gives the proxy to use, c.f. https://curl.se/libcurl/c/CURLOPT_PROXY.html for more information.

enumerator kCurlHttp_UserAgent

For CurlHttpInputStream, type string: gives the user agent to use, c.f. https://curl.se/libcurl/c/CURLOPT_USERAGENT.html for more information.

enumerator kCurlHttp_Timeout

For CurlHttpInputStream, type int32: gives the timeout in seconds, c.f. https://curl.se/libcurl/c/CURLOPT_TIMEOUT.html for more information.

enumerator kCurlHttp_ConnectTimeout

For CurlHttpInputStream, type int32: gives the timeout in seconds for the connection phase, c.f. https://curl.se/libcurl/c/CURLOPT_CONNECTTIMEOUT.html for more information.

enumerator kCurlHttp_Xoauth2Bearer

For CurlHttpInputStream, type string: gives an OAuth2.0 access token, c.f. https://curl.se/libcurl/c/CURLOPT_XOAUTH2_BEARER.html for more information.

enumerator kCurlHttp_Cookie

For CurlHttpInputStream, type string: gives a cookie, c.f. https://curl.se/libcurl/c/CURLOPT_COOKIE.html for more information.

enumerator kCurlHttp_SslVerifyPeer

For CurlHttpInputStream, type bool: a boolean indicating whether the SSL-certificate of the remote host is to be verified, c.f. https://curl.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html for more information.

enumerator kCurlHttp_SslVerifyHost

For CurlHttpInputStream, type bool: a boolean indicating whether the SSL-certificate’s name is to be verified against host, c.f. https://curl.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html for more information.

enumerator kCurlHttp_FollowLocation

For CurlHttpInputStream, type bool: a boolean indicating whether redirects are to be followed, c.f. https://curl.se/libcurl/c/CURLOPT_FOLLOWLOCATION.html for more information.

enumerator kCurlHttp_MaxRedirs

For CurlHttpInputStream, type int32: gives the maximum number of redirects to follow, c.f. https://curl.se/libcurl/c/CURLOPT_MAXREDIRS.html for more information.

enumerator kCurlHttp_CaInfo

For CurlHttpInputStream, type string: gives the directory to check for CA certificate bundle , c.f. https://curl.se/libcurl/c/CURLOPT_CAINFO.html for more information.

enumerator kCurlHttp_CaInfoBlob

For CurlHttpInputStream, type string: give PEM encoded content holding one or more certificates to verify the HTTPS server with, c.f. https://curl.se/libcurl/c/CURLOPT_CAINFO_BLOB.html for more information.

enumerator kAzureBlob_AuthenticationMode

For AzureBlobInputStream, type string: specifies how authentication is to be done (c.f. https://learn.microsoft.com/en-us/azure/storage/blobs/quickstart-blobs-c-plus-plus?tabs=managed-identity%2Croles-azure-portal#authenticate-to-azure-and-authorize-access-to-blob-data). Possible values are: “DefaultAzureCredential”, “EnvironmentCredential”, “AzureCliCredential”, “ManagedIdentityCredential”, “WorkloadIdentityCredential”, “ConnectionString”. The default is: “DefaultAzureCredential”.

struct StreamPropertyBagPropertyInfo

Information about a property for the property bag when creating a stream object.

Public Members

const char *property_name

(Proposed) name of the property. This is a null-terminated static string. It is enum name with the initial “k” removed.

int property_id

The numerical identifier for the property.

Property::Type property_type

Type of the property.