Struct sd_id128::ID128

pub struct ID128 { /* fields omitted */ }

Wrapper for sd-id128 as offered in libsystemd.

ID128 fully implements translations to FFI calls to libsystemd and native Rust functionality to handle UUIDs.

FFI Constructors -> Result<ID128, Error>

• bood_id: get boot id
• boot_id_app_specific: get hashed boot id
• machine_id: get machine id
• machine_id_app_specific: get hashed machine id
• invocation_id: get service invocation id
• random_id: get a random id
• from_string_sd: parse string into id using libsystemd

Native Constructors -> Result<ID128, Error>

• from_string: parse string into id using native Rust
• from_string_lax: parse string into id using native Rust with lax rules

FFI Methods -> Result<T, Error>

• to_string_sd: format an id as String using libsystemd
• into_cstring_sd: format an id as CString using libsystemd

Native Method -> T

• to_string: format an id as String in default format using native Rust
• to_string_formatted: format an id as String using native Rust

Implemented Traits

• Display: provides to_string(&ID128) -> String and format!(..., &ID128)
• From -> String: provides into(ID128) -> String
• TryFrom -> ID128: provides try_into(String) -> ID128
• From<ffi::sd_id128> -> ID128: provides into(ffi::sd_id128) -> ID128
• From -> ffi::sd_id128: provides into(ID128) -> ffi::sd_id128
• AsRef<[u8; 16]>: provides as_ref(&ID128) -> &[u8; 16]
• Clone: provides clone(&ID128) -> ID128
• From -> [u8; 16]: provides into(ID128) -> [u8; 16]
• From<[u8; 16]> -> ID128: provides into([u8; 16]) -> ID128

Implementations

impl ID128

pub fn random_id() -> Result<Self, Error>

Generates a new randomized 128-bit ID (sd_id128_randomize).

Every invocation returns a new randomly generated ID. The libsystemd API uses the /dev/urandom kernel random number generator. Note that sd_id128_randomize() always returns a UUID v4-compatible ID.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::SDError(i32)): sd-id128 returned an error code

pub fn boot_id() -> Result<Self, Error>

Returns the boot ID of the executing kernel (sd_id128_get_boot).

libsystemd API reads and parses the /proc/sys/kernel/random/boot_id file exposed by the kernel. It is randomly generated early at boot and is unique for every running kernel instance. This function also internally caches the returned ID to make this call a cheap operation.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::SDError(i32)): sd-id128 returned an error code

pub fn boot_id_app_specific(app: ID128) -> Result<Self, Error>

Returns an app specific boot id (sd_id128_get_boot_app_specific).

It is recommended to use this function instead of boot_id when passing an ID to untrusted environments, in order to make sure that the original boot ID may not be determined externally. This way, the ID used by the application remains stable on a given machine, but cannot be easily correlated with IDs used in other applications on the same machine.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::SDError(i32)): sd-id128 returned an error code

pub fn machine_id() -> Result<Self, Error>

Returns the machine ID of the executing host (sd_id128_get_machine)

This reads and parses the machine-id file. This libsystemd API caches the machine ID internally to make retrieving the machine ID a cheap operation. This ID may be used wherever a unique identifier for the local system is needed.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::SDError(i32)): sd-id128 returned an error code

pub fn machine_id_app_specific(app: ID128) -> Result<Self, Error>

Returns an app specific machine id (sd_id128_get_machine_app_specific).

It is recommended to use this function instead of machine_id when passing an ID to untrusted environments, in order to make sure that the original machine ID may not be determined externally. This way, the ID used by the application remains stable on a given machine, but cannot be easily correlated with IDs used in other applications on the same machine.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::SDError(i32)): sd-id128 returned an error code

pub fn invocation_id() -> Result<Self, Error>

Returns the invocation ID of the service (sd_id128_get_invocation).

In its current implementation, this reads and parses the $INVOCATION_ID environment variable that the service manager sets when activating a service.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::SDError(i32)): sd-id128 returned an error code

pub fn from_str(string: &str) -> Result<Self, Error>

Parses a string into an ID applying strict rules using native Rust functionality (i.e. without any FFI call).

Takes a character string and tries to parse it into a valid ID. This method parses the string using native Rust functionality and strict formatting rules are applied to the source. There are two alternatives to this method:

• from_str_lax: allows some formatting errors on the source string
• from_str_sd: performs a FFI call to libsystemd in order to parse the source string

This method is strict with regards to the format of the source string:

• only dashes an hexadecimal numbers are allowed
• letter casing can be either upper or lower case
• dashes must conform precisely to any of the formats

Return Values

• Ok(ID128): success
• Err(Error::ParseStringError): the source string did not strictly comply with the expected format

pub fn from_str_lax(string: &str) -> Result<Self, Error>

Parses a string into an ID using native Rust functionality.

Takes a character string and tries to parse it into a valid ID. This method parses the string using native Rust functionality and lax formatting rules are applied to the source. There are two alternatives to this method:

• from_str: strict formatting rules are applied on the source string
• from_str_sd: performs a FFI call to libsystemd in order to parse the source string

This method reuses the strict parsing of from_string after pre-processing the source string as follows:

• trim
• remove all dashes: transform the string from any valid or invalid format into a libsystemd conforming format

Return Values

• Ok(ID128): success
• Err(Error::ParseStringError): the source string did not comply with the expected format

pub fn from_str_sd(string: &str) -> Result<Self, Error>

Parses a string into an ID using libsystemd (sd_id128_from_string).

Takes a character string with 32 hexadecimal digits (either lowercase or uppercase) and parses them back into a 128-bit ID.

Return Values

• Ok(ID128): initialized ID128 struct
• Err(Error::NulError): the source string did contain a 0-byte
• Err(Error::SDError): sd-id128 returned an error code

pub fn into_cstring_sd(self) -> Result<CString, Error>

Formats an ID as CString using libsystemd (sd_id128_to_string).

This function performs a FFI call to libsystemd to transform an ID into a string. There are some alternative methods available:

• ID128 implements fmt::Display using native Rust functionality, thus the following becomes available:
  • to_string method and format!() will use a default format
  • to_string_formatted offers formatting an ID in multiple variants
• to_string_sd: is a convinience wrapper around into_string_sd

This function is supposed to always be successful. Since there are some rather theoretical errors possible, the return value is a Result<>.

Return Values

• Ok(String): a 128-bit ID as a character string. The ID will be formatted as 32 lowercase hexadecimal digits and be terminated by a NUL byte.
• Err(Error::NullError): If this error is reported, it indicates an error in this library.
• Err(Error::SDError): If this error is reported, it indicates an error in libsystemd and/or in this library. The error code is always 0 and thus won't reveal any further information.

pub fn to_string_sd(&self) -> Result<String, Error>

Formats an ID as String using libsystemd (sd_id128_to_string).

This function performs a FFI call to libsystemd to transform an ID into a string. There are some alternative methods available:

• ID128 implements fmt::Display using native Rust functionality, thus the following becomes available:
  • to_string method and format!() will use a default format
  • to_string_formatted offers formatting an ID in multiple variants
• into_string_sd: to_string_sd is a convinience wrapper around into_string_sd

This function is supposed to always be successful. Since there are some rather theoretical errors possible, the return value is a Result<>.

Return Values

• Ok(String): a 128-bit ID as a character string. The ID will be formatted as 32 lowercase hexadecimal digits and be terminated by a NUL byte.
• Err(Error::NullError): If this error is reported, it indicates an error in this library.
• Err(Error::SDError): If this error is reported, it indicates an error in libsystemd and/or in this library. The error code is always 0 and thus won't reveal any further information.

pub fn to_string_formatted(&self, format: Format, case: Case) -> String

Formats an ID as String using Rust native functionality.

This function transforms an ID into a String using native Rust functionality. As an alternative the methods into_cstring_sd and to_string_sd perform a FFI call to transform an ID into string. This Rust native function offers the possibility to apply the same format tho: choose format "LibSystemD" and lower case.

The formatting default is in Rust native function to_string is RFC: 01234567-89ab-cdef-0123-456789abcdef. This is the official defined standard in RFC 4122.

Return Values

• String: text representation of the id

pub fn into_ffi(self) -> sd_id128

Transform an ID128 into a FFI binding sd_id128.

The FFI binding struct sd_id128 is only required for direct FFI calls.

pub fn as_ffi(&self) -> &sd_id128

Returns a reference to the inner FFI binding sd_id128.

The FFI binding struct sd_id128 is only required for direct FFI calls.

pub fn from_ffi(ffi: sd_id128) -> ID128

Constructs an ID128 from a FFI binding sd_id128.

The FFI binding struct sd_id128 retrieved from a direct FFI call may be used to construct a full ID128.

pub fn as_raw_value(&self) -> &[u8; 16]

Returns a slice of the raw ID.

pub fn as_mut_raw_value(&mut self) -> &mut [u8; 16]

Returns a mutable slice of the raw ID.

pub fn into_raw_value(self) -> [u8; 16]

Transforms the ID128 into a raw value slice.

pub fn from_raw_value(value: [u8; 16]) -> ID128

Constructs an ID128 from a raw value slice.

Trait Implementations

impl AsRef<[u8; 16]> for ID128

pub fn as_ref(&self) -> &[u8; 16]

Performs the conversion.

impl Clone for ID128

pub fn clone(&self) -> ID128

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ID128

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ID128

pub fn default() -> ID128

Returns the "default value" for a type.

impl Display for ID128

pub fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for ID128

impl From<[u8; 16]> for ID128

pub fn from(value: [u8; 16]) -> ID128

Performs the conversion.

impl From<ID128> for String

pub fn from(id128: ID128) -> String

Performs the conversion.

impl From<ID128> for sd_id128

pub fn from(id128: ID128) -> sd_id128

Performs the conversion.

impl From<ID128> for [u8; 16]

pub fn from(id128: ID128) -> [u8; 16]

Performs the conversion.

impl From<sd_id128> for ID128

pub fn from(sd_id128: sd_id128) -> ID128

Performs the conversion.

impl PartialEq<ID128> for ID128

pub fn eq(&self, other: &ID128) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &ID128) -> bool

This method tests for !=.

impl StructuralEq for ID128

impl StructuralPartialEq for ID128

impl TryFrom<&'_ str> for ID128

type Error = Error

The type returned in the event of a conversion error.

pub fn try_from(value: &str) -> Result<Self, Error>

Performs the conversion.